@monster-orange/den 0.3.0 → 0.4.0

package/src/shared/agents/den-claude.ts

@@ -0,0 +1,173 @@
+/**
+ * den-claude: Den's built-in runtime for Claude Code (AG spec §4).
+ *
+ *   claude --session-id <uuid> --mcp-config <filesDir>/mcp.json
+ *          --strict-mcp-config --permission-mode <mode> [--model <m>]
+ *          --append-system-prompt <role prompt>
+ *
+ * - The MCP config (0600) holds one server, Den's, scoped to the agent's
+ *   workspace; --strict-mcp-config keeps any other MCP server out, so the
+ *   agent acts only through Den (§1).
+ * - The role prompt is appended to Claude Code's own system prompt.
+ * - Each launch picks a fresh conversation id (--session-id); resume
+ *   continues it with --resume <id>, in the same cwd, with the same MCP.
+ * - Permission prompts stay in the terminal (approvals: "terminal"):
+ *   --permission-mode default, unless the persona's `permission_mode` sets
+ *   one of Claude Code's modes; bypassPermissions warns at every start. The
+ *   Notification hook comes with agent states (AG-6a).
+ * - Its environment is the allowlist (sessions/env.ts) plus
+ *   CLAUDE_CONFIG_DIR, where a user keeps Claude Code's config when not in
+ *   HOME. Claude Code reads its own credentials from there; no token is
+ *   passed. Its scrubEnv, CLAUDECODE and CLAUDE_CODE_*, never reaches any
+ *   session Den starts (an agent is not a child of the session that
+ *   started it).
+ *
+ * detect runs nothing: `claude` on PATH, and its version read from where it
+ * is installed (a native install's versions/<version>, or the npm package's
+ * package.json).
+ */
+import { randomUUID } from "crypto";
+import * as fs from "fs";
+import * as path from "path";
+import { rolePrompt } from "./personas.js";
+import {
+  LaunchError,
+  mcpConfigJson,
+  mcpConfigPath,
+  whichBin,
+  type LaunchInput,
+  type LaunchOutput,
+  type Runtime,
+  type RuntimeDetect,
+} from "./runtime.js";
+
+export const DEN_CLAUDE_ID = "den-claude";
+const BIN = "claude";
+const PACKAGE = "@anthropic-ai/claude-code";
+const SEMVER = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/;
+
+/** Claude Code's permission modes (`claude --permission-mode`). */
+export const PERMISSION_MODES = [
+  "default",
+  "acceptEdits",
+  "plan",
+  "bypassPermissions",
+] as const;
+export const DEFAULT_PERMISSION_MODE = "default";
+
+/** The persona's permission mode, checked; a bad one names the key. */
+function permissionMode(input: LaunchInput): string {
+  const m = input.persona.permissionMode ?? DEFAULT_PERMISSION_MODE;
+  if (!(PERMISSION_MODES as readonly string[]).includes(m))
+    throw new LaunchError(
+      `${input.persona.source}: permission_mode "${m.replace(/[^\x20-\x7e]/g, "?").slice(0, 40)}" must be one of ${PERMISSION_MODES.join(", ")}`,
+    );
+  return m;
+}
+
+/** The installed version, from the install's own files; undefined when unknown. */
+export function installedVersion(bin: string): string | undefined {
+  let real: string;
+  try {
+    real = fs.realpathSync(bin);
+  } catch {
+    return undefined;
+  }
+  if (SEMVER.test(path.basename(real))) return path.basename(real);
+  for (let dir = path.dirname(real), i = 0; i < 6; i++) {
+    try {
+      const pkg = JSON.parse(
+        fs.readFileSync(path.join(dir, "package.json"), "utf-8"),
+      ) as { name?: unknown; version?: unknown };
+      if (pkg.name === PACKAGE && typeof pkg.version === "string")
+        return pkg.version;
+    } catch {
+      /* not here */
+    }
+    const up = path.dirname(dir);
+    if (up === dir) break;
+    dir = up;
+  }
+  return undefined;
+}
+
+function detect(env: NodeJS.ProcessEnv = process.env): RuntimeDetect {
+  const bin = whichBin(BIN, env);
+  if (!bin) return { available: false, why: `${BIN} is not on PATH` };
+  const version = installedVersion(bin);
+  return version ? { available: true, version } : { available: true };
+}
+
+/** The flags every run shares: Den's MCP only, the model, the role prompt. */
+function common(input: LaunchInput): {
+  argv: string[];
+  files: Record<string, string>;
+  warnings: string[];
+} {
+  const file = mcpConfigPath(input);
+  const mode = permissionMode(input);
+  return {
+    argv: [
+      "--mcp-config",
+      file,
+      "--strict-mcp-config",
+      "--permission-mode",
+      mode,
+      ...(input.model ? ["--model", input.model] : []),
+      "--append-system-prompt",
+      rolePrompt(
+        input.persona,
+        input.agentId,
+        input.workspace.name,
+        input.mcp.name,
+      ),
+    ],
+    files: { [file]: mcpConfigJson(input.mcp) },
+    warnings:
+      mode === "bypassPermissions"
+        ? [
+            `⚠ persona ${input.persona.id} sets permission_mode: bypassPermissions: Claude Code will not ask before running any tool`,
+          ]
+        : [],
+  };
+}
+
+function binFor(input: LaunchInput): string {
+  const bin = whichBin(BIN, input.env);
+  if (!bin) throw new LaunchError(`${DEN_CLAUDE_ID}: ${BIN} is not on PATH`);
+  return bin;
+}
+
+export const denClaude: Runtime = {
+  id: DEN_CLAUDE_ID,
+  detect,
+  launch(input): LaunchOutput {
+    const bin = binFor(input);
+    const id = input.resumeToken ?? randomUUID();
+    const c = common(input);
+    return {
+      argv: [bin, "--session-id", id, ...c.argv],
+      env: {},
+      files: c.files,
+      resumeToken: id,
+      warnings: c.warnings,
+    };
+  },
+  resume(input) {
+    if (!input.resumeToken) return null;
+    const bin = binFor(input);
+    const c = common(input);
+    return {
+      argv: [bin, "--resume", input.resumeToken, ...c.argv],
+      env: {},
+      files: c.files,
+      warnings: c.warnings,
+    };
+  },
+  approvals: "terminal",
+  envPassthrough: ["CLAUDE_CONFIG_DIR"],
+  // Claude Code's session plumbing: the session id, its messaging socket and
+  // token, the child-session marker (which turns transcripts off). An agent
+  // is not part of the session that started it.
+  scrubEnv: ["CLAUDECODE", "CLAUDE_CODE_*"],
+};

package/src/shared/agents/generic.ts

@@ -0,0 +1,52 @@
+/**
+ * generic: any CLI, from the persona's argv template (AG spec §4):
+ *
+ *   argv: ["aider", "--model", "{model}", "--mcp-config", "{mcp_config}"]
+ *
+ * `{model}` is the agent's model; `{mcp_config}` is the path of a per-agent
+ * MCP config (0600) holding Den's scoped server, written only when the
+ * template references it. A CLI that speaks no MCP gets a terminal and no
+ * Den tools. generic declares no resume.
+ */
+import {
+  LaunchError,
+  mcpConfigJson,
+  mcpConfigPath,
+  type LaunchOutput,
+  type Runtime,
+} from "./runtime.js";
+
+export const GENERIC_ID = "generic";
+
+export const generic: Runtime = {
+  id: GENERIC_ID,
+  // The CLI is the persona's; there is nothing to look for until launch.
+  detect: () => ({ available: true }),
+  scrubEnv: [],
+  launch(input): LaunchOutput {
+    const template = input.persona.argv;
+    if (!template?.length)
+      throw new LaunchError(
+        `${GENERIC_ID}: persona ${input.persona.id} has no argv template (argv: [...] in its front matter)`,
+      );
+    const usesModel = template.some((a) => a.includes("{model}"));
+    if (usesModel && !input.model)
+      throw new LaunchError(
+        `${GENERIC_ID}: persona ${input.persona.id}'s argv uses {model}; give --model or set model in the persona`,
+      );
+    const file = mcpConfigPath(input);
+    const usesMcp = template.some((a) => a.includes("{mcp_config}"));
+    const argv = template.map((a) =>
+      a
+        .split("{model}")
+        .join(input.model ?? "")
+        .split("{mcp_config}")
+        .join(file),
+    );
+    return {
+      argv,
+      env: {},
+      ...(usesMcp ? { files: { [file]: mcpConfigJson(input.mcp) } } : {}),
+    };
+  },
+};

package/src/shared/agents/personas.ts

@@ -0,0 +1,218 @@
+/**
+ * Personas (AG-2a, AG spec §4): who an agent is. A persona is a markdown
+ * file whose YAML front matter says what it is and whose body is its role
+ * prompt. A persona-pack is a directory of them.
+ *
+ * The format is Claude Code's agent file, read as it is, so a pack can
+ * point at a Claude Code plugin's agents/ directory without converting or
+ * forking it:
+ *
+ *   name         the id (Den's `id` wins when both are given)
+ *   description  the one-line role (Den's `role` wins)
+ *   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),
+ * `standing` (starts with its workspace, §5), `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
+ * Claude Code `color`) is ignored. A file without front matter (a pack's
+ * README) is not a persona.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import * as yaml from "yaml";
+import { WORKSPACE_NAME_RE } from "../agent-actor.js";
+import { enginePath } from "../engine.js";
+
+export interface Persona {
+  id: string;
+  /** One line: what it does. */
+  role: string;
+  /** The role prompt: the file's body. */
+  prompt: string;
+  /** The runtime it runs on unless an agent says otherwise. */
+  runtime?: string;
+  /** The model it runs unless an agent says otherwise. */
+  model?: string;
+  /** Started with its workspace (planner, orchestrator). */
+  standing: boolean;
+  /** Tool hints. */
+  tools: string[];
+  /** What to read first (specs, the design system, workspace config). */
+  context: string[];
+  /** The generic runtime's argv template ({model}, {mcp_config}). */
+  argv?: string[];
+  /** `permission_mode`: the runtime's permission mode (den-claude checks it). */
+  permissionMode?: string;
+  /** The file it came from. */
+  source: string;
+}
+
+/** A persona id: the same rules as an agent id or a workspace name. */
+export const PERSONA_ID_RE = WORKSPACE_NAME_RE;
+
+/** Den's own pack, shipped in the package (src/ ships whole). */
+export const DEFAULT_PACK_DIR = enginePath(
+  "src",
+  "shared",
+  "agents",
+  "default-pack",
+);
+
+const FRONT_MATTER = /^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/;
+
+function optString(
+  fm: Record<string, unknown>,
+  key: string,
+  where: string,
+): string | undefined {
+  const v = fm[key];
+  if (v === undefined || v === null) return undefined;
+  if (typeof v !== "string" && typeof v !== "number")
+    throw new Error(`${where}: ${key} must be a string`);
+  const s = String(v).trim();
+  return s || undefined;
+}
+
+/** `tools: Read, Grep` (Claude Code) or `tools: [read, grep]`. */
+function stringList(
+  fm: Record<string, unknown>,
+  key: string,
+  where: string,
+): string[] {
+  const v = fm[key];
+  if (v === undefined || v === null) return [];
+  if (typeof v === "string")
+    return v
+      .split(",")
+      .map((s) => s.trim())
+      .filter(Boolean);
+  if (Array.isArray(v) && v.every((x) => typeof x === "string"))
+    return (v as string[]).map((s) => s.trim()).filter(Boolean);
+  throw new Error(`${where}: ${key} must be a list of strings`);
+}
+
+/** One persona file, or null when it has no front matter. */
+export function parsePersona(text: string, file: string): Persona | null {
+  const m = FRONT_MATTER.exec(text);
+  if (!m) return null;
+  let fm: unknown;
+  try {
+    fm = yaml.parse(m[1]);
+  } catch (e) {
+    throw new Error(
+      `${file}: front matter is not YAML (${(e as Error).message.split("\n")[0]})`,
+    );
+  }
+  if (fm === null || fm === undefined) fm = {};
+  if (typeof fm !== "object" || Array.isArray(fm))
+    throw new Error(`${file}: front matter must be a mapping`);
+  const f = fm as Record<string, unknown>;
+  const id =
+    optString(f, "id", file) ??
+    optString(f, "name", file) ??
+    path.basename(file, path.extname(file));
+  if (!PERSONA_ID_RE.test(id))
+    throw new Error(
+      `${file}: id "${id}" must be letters, digits, ".", "_" or "-", 1-64 long, starting with a letter or digit`,
+    );
+  const standing = f.standing ?? false;
+  if (typeof standing !== "boolean")
+    throw new Error(`${file}: standing must be true or false`);
+  let argv: string[] | undefined;
+  if (f.argv !== undefined && f.argv !== null) {
+    if (
+      !Array.isArray(f.argv) ||
+      !f.argv.length ||
+      !f.argv.every((a) => typeof a === "string")
+    )
+      throw new Error(`${file}: argv must be a list of strings`);
+    argv = f.argv as string[];
+  }
+  const model = optString(f, "model", file);
+  const runtime = optString(f, "runtime", file);
+  const permissionMode = optString(f, "permission_mode", file);
+  return {
+    id,
+    role: optString(f, "role", file) ?? optString(f, "description", file) ?? "",
+    prompt: text.slice(m[0].length).trim(),
+    ...(runtime ? { runtime } : {}),
+    ...(model && model !== "inherit" ? { model } : {}),
+    standing,
+    tools: stringList(f, "tools", file),
+    context: stringList(f, "context", file),
+    ...(argv ? { argv } : {}),
+    ...(permissionMode ? { permissionMode } : {}),
+    source: file,
+  };
+}
+
+/**
+ * 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[] {
+  const agents = path.join(dir, "agents");
+  const from = fs.statSync(agents, { throwIfNoEntry: false })?.isDirectory()
+    ? agents
+    : dir;
+  const out: Persona[] = [];
+  const seen = new Map<string, string>();
+  for (const name of fs.readdirSync(from).sort()) {
+    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);
+    if (!p) continue;
+    const prev = seen.get(p.id);
+    if (prev) throw new Error(`${prev} and ${file} both define "${p.id}"`);
+    seen.set(p.id, file);
+    out.push(p);
+  }
+  return out;
+}
+
+/** `agents.persona_packs`, absolute; each must be a directory. */
+export function resolvePackDirs(packs: string[], distRoot: string): string[] {
+  return packs.map((p, i) => {
+    const abs = path.resolve(distRoot, p);
+    if (!fs.statSync(abs, { throwIfNoEntry: false })?.isDirectory())
+      throw new Error(`agents.persona_packs[${i}]: ${abs} is not a directory`);
+    return abs;
+  });
+}
+
+/**
+ * Every persona: Den's default pack, then each pack in order. A later
+ * pack's persona replaces an earlier one of the same id.
+ */
+export function loadPersonas(
+  packDirs: string[],
+  defaultPack: string = DEFAULT_PACK_DIR,
+): 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);
+  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
+ * chooses how to pass it in.
+ */
+export function rolePrompt(
+  persona: Persona,
+  agentId: string,
+  workspace: string,
+  mcpName: string,
+): string {
+  const lines = [
+    `You are agent ${agentId} in workspace ${workspace}, with the ${persona.id} persona.`,
+    `Act on services, logs and tests only through the ${mcpName} MCP server; it serves this workspace.`,
+  ];
+  if (persona.context.length)
+    lines.push(`Read first: ${persona.context.join("; ")}.`);
+  return `${lines.join("\n")}\n\n${persona.prompt}`;
+}

package/src/shared/agents/records.ts

@@ -0,0 +1,118 @@
+/**
+ * The agent record (AG-2a): what an agent is and where it runs, kept in the
+ * distribution's state dir so the CLI and the web server (AG-4a) see the
+ * 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
+ *
+ * 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.
+ */
+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";
+
+export interface AgentRecord {
+  id: string;
+  persona: string;
+  runtime: string;
+  model?: string;
+  workspace: string;
+  cwd: string;
+  /** The session it runs in now (or last ran in). */
+  session: SessionRef;
+  /** `<dist>-<ws>:<id>`. */
+  sessionName: string;
+  /** ISO 8601. */
+  startedAt: string;
+  /** Set by `agents stop`; cleared by a resume. */
+  stoppedAt?: string;
+  /** Set when a resume started its current session. */
+  resumedAt?: string;
+  /** The runtime's handle for resume (den-claude: the conversation id). */
+  resumeToken?: string;
+}
+
+/** An agent id: the same rules as a workspace or session name. */
+export const AGENT_ID_RE = WORKSPACE_NAME_RE;
+
+export function agentsDir(stateDir: string): string {
+  return path.join(stateDir, "agents");
+}
+
+export function agentFilesDir(stateDir: string, id: string): string {
+  return path.join(stateDir, "agent-files", id);
+}
+
+function ensureDir(dir: string): void {
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  fs.chmodSync(dir, 0o700);
+}
+
+/** Write `content` to `file`, owner-only from the start, atomically. */
+export function writePrivate(file: string, content: string): void {
+  ensureDir(path.dirname(file));
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, content, { mode: 0o600 });
+  fs.chmodSync(tmp, 0o600);
+  fs.renameSync(tmp, file);
+}
+
+function recordFile(stateDir: string, id: string): string {
+  if (!AGENT_ID_RE.test(id)) throw new Error(`"${id}" is not an agent id`);
+  return path.join(agentsDir(stateDir), `${id}.json`);
+}
+
+export function writeRecord(stateDir: string, rec: AgentRecord): void {
+  writePrivate(
+    recordFile(stateDir, rec.id),
+    JSON.stringify(rec, null, 2) + "\n",
+  );
+}
+
+export function readRecord(stateDir: string, id: string): AgentRecord | null {
+  if (!AGENT_ID_RE.test(id)) return null;
+  try {
+    return JSON.parse(
+      fs.readFileSync(recordFile(stateDir, id), "utf-8"),
+    ) as AgentRecord;
+  } catch (e) {
+    if ((e as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw e;
+  }
+}
+
+export function listRecords(stateDir: string): AgentRecord[] {
+  let names: string[];
+  try {
+    names = fs.readdirSync(agentsDir(stateDir));
+  } catch {
+    return [];
+  }
+  const out: AgentRecord[] = [];
+  for (const n of names.sort()) {
+    if (!n.endsWith(".json")) continue;
+    const rec = readRecord(stateDir, n.slice(0, -".json".length));
+    if (rec) out.push(rec);
+  }
+  return out;
+}
+
+/**
+ * Write a runtime's files, each 0600 and only inside `dir`: a runtime
+ * names where in its own directory, never elsewhere.
+ */
+export function writeRuntimeFiles(
+  dir: string,
+  files: Record<string, string> | undefined,
+): void {
+  for (const [file, content] of Object.entries(files ?? {})) {
+    const abs = path.resolve(file);
+    if (!abs.startsWith(path.resolve(dir) + path.sep))
+      throw new Error(`a runtime file must be inside ${dir}: ${file}`);
+    writePrivate(abs, content);
+  }
+}