@monster-orange/den 0.3.0 → 0.4.0

package/src/shared/agents/runtime.ts

@@ -0,0 +1,192 @@
+/**
+ * The runtime contract (strategy kind `runtime`, AG spec §4): which CLI an
+ * agent runs. A runtime turns a persona and a workspace into argv, env and
+ * files (a per-agent MCP config), and says how to resume. It knows nothing
+ * about sessions, tmux or the browser; Den joins it to a session backend.
+ *
+ * Built-ins register here exactly as a runtime plugin would (AG-8a):
+ * den-claude and generic.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import {
+  getStrategy,
+  registerStrategy,
+  strategyIds,
+  type StrategyEntry,
+} from "../strategies/registry.js";
+import type { Persona } from "./personas.js";
+
+export const RUNTIME_KIND = "runtime";
+
+/** The runtime an agent gets when neither it nor its persona names one. */
+export const DEFAULT_RUNTIME_ID = "den-claude";
+
+export interface RuntimeDetect {
+  available: boolean;
+  version?: string;
+  /** Why it is unavailable. */
+  why?: string;
+}
+
+/** The MCP server an agent acts through: Den's, scoped to its workspace. */
+export interface AgentMcp {
+  /** The server's name in an MCP config (the distribution's CLI). */
+  name: string;
+  /** `<cli> mcp --workspace <ws> --actor agent:<id> [--grant <ws>…]`. */
+  command: string[];
+  /** The server's own environment (PATH pinned), never a secret. */
+  env: Record<string, string>;
+  /** The workspace it is pinned to. */
+  scope: string;
+}
+
+export interface LaunchInput {
+  persona: Persona;
+  workspace: { name: string; dir: string };
+  agentId: string;
+  /** Where the agent works: the workspace's dir (a worktree from AG-9a). */
+  worktree: string;
+  model?: string;
+  mcp: AgentMcp;
+  /** A directory of this agent's own (0700) for the files a runtime writes. */
+  filesDir: string;
+  /**
+   * The caller's environment, for finding the runtime's CLI on PATH. The
+   * agent does not get it: it starts from an allowlist (sessions/env.ts),
+   * plus envPassthrough and LaunchOutput.env.
+   */
+  env: NodeJS.ProcessEnv;
+  /**
+   * A conversation id to start under instead of a new one: a resume of a
+   * run that was never prompted starts afresh with the id it had.
+   */
+  resumeToken?: string;
+}
+
+export interface LaunchOutput {
+  argv: string[];
+  /** Added to the session's environment (after the allowlist). */
+  env: Record<string, string>;
+  /** Absolute path (inside filesDir) → content; Den writes each 0600. */
+  files?: Record<string, string>;
+  /** What resume needs to continue this run (kept in the agent record). */
+  resumeToken?: string;
+  /** One line each, printed when the agent starts (never secret). */
+  warnings?: string[];
+}
+
+export type ResumeInput = LaunchInput;
+
+export interface Runtime {
+  /** "den-claude", "generic". */
+  id: string;
+  detect(env?: NodeJS.ProcessEnv): RuntimeDetect;
+  /** 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. */
+  resume?(input: ResumeInput): Omit<LaunchOutput, "resumeToken"> | null;
+  /** Where permission prompts surface (Q-AG-2). */
+  approvals?: "terminal" | "hook";
+  /**
+   * Caller variables this runtime needs beyond the allowlist (PATH, HOME,
+   * USER, LOGNAME, SHELL, TERM, COLORTERM, LANG, LC_*, TZ, TMPDIR). Named
+   * one by one; Claude Code's session plumbing never passes.
+   */
+  envPassthrough?: readonly string[];
+  /**
+   * Names this runtime owns that must never reach a session Den starts
+   * (an exact name, or a prefix ending in `*`): den-claude's CLAUDECODE and
+   * CLAUDE_CODE_*. Den removes them after building any session's env,
+   * whatever put them there (sessions/env.ts).
+   */
+  scrubEnv: readonly string[];
+}
+
+/** A runtime cannot launch this agent here: a refusal, not a crash. */
+export class LaunchError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "LaunchError";
+  }
+}
+
+/** Register a runtime as strategy kind `runtime` (doctor lists it). */
+export function registerRuntime(rt: Runtime): void {
+  const entry: StrategyEntry<typeof RUNTIME_KIND, Runtime> = {
+    id: rt.id,
+    kind: RUNTIME_KIND,
+    detect(env) {
+      const d = rt.detect(env);
+      if (!d.available)
+        return { available: false, reason: d.why ?? "unavailable" };
+      return d.version
+        ? { available: true, reason: `version ${d.version}` }
+        : { available: true };
+    },
+    capabilities: rt,
+  };
+  registerStrategy(entry);
+}
+
+export function getRuntime(id: string): Runtime | undefined {
+  return getStrategy<typeof RUNTIME_KIND, Runtime>(RUNTIME_KIND, id)
+    ?.capabilities;
+}
+
+export function runtimeIds(): string[] {
+  return strategyIds(RUNTIME_KIND);
+}
+
+/** Every registered runtime's scrubEnv: applied to every session Den starts. */
+export function allScrubEnv(): string[] {
+  return [
+    ...new Set(runtimeIds().flatMap((id) => getRuntime(id)?.scrubEnv ?? [])),
+  ];
+}
+
+/** The first executable `bin` on `env.PATH`, or null. Runs nothing. */
+export function whichBin(
+  bin: string,
+  env: NodeJS.ProcessEnv = process.env,
+): string | null {
+  for (const dir of (env.PATH ?? "").split(path.delimiter)) {
+    if (!dir) continue;
+    const file = path.join(dir, bin);
+    try {
+      fs.accessSync(file, fs.constants.X_OK);
+      if (fs.statSync(file).isFile()) return file;
+    } catch {
+      /* not here */
+    }
+  }
+  return null;
+}
+
+/**
+ * A standard MCP config (`mcpServers`, the shape most MCP clients read)
+ * with Den's server as the only entry.
+ */
+export function mcpConfigJson(mcp: AgentMcp): string {
+  const [command, ...args] = mcp.command;
+  return (
+    JSON.stringify(
+      {
+        mcpServers: {
+          [mcp.name]: {
+            command,
+            args,
+            ...(Object.keys(mcp.env).length ? { env: mcp.env } : {}),
+          },
+        },
+      },
+      null,
+      2,
+    ) + "\n"
+  );
+}
+
+/** Where a runtime puts an agent's MCP config. */
+export function mcpConfigPath(input: Pick<LaunchInput, "filesDir">): string {
+  return path.join(input.filesDir, "mcp.json");
+}

package/src/shared/agents/runtimes.ts

@@ -0,0 +1,47 @@
+/**
+ * Den's built-in runtimes, registered as strategy kind `runtime`: import
+ * this module to have them. den-claude first: it is the default.
+ */
+import { denClaude } from "./den-claude.js";
+import { generic } from "./generic.js";
+import { allScrubEnv, registerRuntime, type Runtime } from "./runtime.js";
+import { AGENT_ACTOR_ENV, buildSessionEnv } from "../sessions/env.js";
+
+registerRuntime(denClaude);
+registerRuntime(generic);
+
+export {
+  allScrubEnv,
+  DEFAULT_RUNTIME_ID,
+  getRuntime,
+  LaunchError,
+  RUNTIME_KIND,
+  runtimeIds,
+  type AgentMcp,
+  type LaunchInput,
+  type LaunchOutput,
+  type ResumeInput,
+  type Runtime,
+} from "./runtime.js";
+
+/**
+ * An agent's session env, as `agents start` builds it and `doctor --probe`
+ * checks it: the allowlist, the runtime's passthrough and launch env, Den's
+ * marker (DEN_AGENT=agent:<id>), then every runtime's scrubEnv.
+ */
+export function agentSessionEnv(
+  caller: NodeJS.ProcessEnv,
+  rt: Pick<Runtime, "envPassthrough">,
+  launch: Record<string, string>,
+  agentId: string,
+): Record<string, string> {
+  return buildSessionEnv({
+    caller,
+    passthrough: rt.envPassthrough,
+    launch,
+    // The seam for a persona's or runtime's declared env: none yet.
+    extra: {},
+    den: { [AGENT_ACTOR_ENV]: `agent:${agentId}` },
+    scrub: allScrubEnv(),
+  });
+}

package/src/shared/den-config.ts

@@ -243,6 +243,11 @@ export interface DenConfig {
    * only; `actions` opts in to named actions. See readMcpConfig.
    */
   mcp?: McpConfig;
+  /**
+   * Agents: `max_concurrent` caps the sessions running at once in this
+   * distribution (default 4). See readAgentsConfig.
+   */
+  agents?: AgentsConfig;
   /**
    * The web UI: `port` (read by edge/config.ts readWebPort) and `service`,
    * the launchd service `<cli> service` installs. See readWebServiceConfig.
@@ -552,6 +557,7 @@ export function readDenConfig(): DenConfig {
       env_health_urls: parsed?.env_health_urls,
       security: parsed?.security,
       mcp: parsed?.mcp,
+      agents: parsed?.agents,
       web: parsed?.web,
       test_accounts: parsed?.test_accounts,
       defaults: parsed?.defaults,
@@ -729,6 +735,116 @@ export function readMcpConfig(
   };
 }
 
+// ── Agents (`<cli> sessions`, `<cli> agents`) ─────────────────────────────────
+
+/** `agents:` in the org config. */
+export interface AgentsConfig {
+  /** Sessions that may run at once (default 4). */
+  max_concurrent?: number;
+  /**
+   * 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_packs?: string[];
+  /**
+   * Any other key is an agent id: `agents.<id>.grants` widens that agent's
+   * MCP scope to other workspaces (AG spec §5b). Config only: an agent
+   * never grants itself one.
+   */
+  [agentId: string]: unknown;
+}
+
+export const DEFAULT_AGENTS_MAX_CONCURRENT = 4;
+
+/** The keys of `agents:` that are not an agent id. */
+export const AGENTS_RESERVED_KEYS = ["max_concurrent", "persona_packs"];
+
+/** One agent's own block, `agents.<id>`. */
+export interface AgentGrantsConfig {
+  /** Workspaces beyond its own that its MCP serves. */
+  grants: string[];
+}
+
+/** `agents:` with its defaults applied. */
+export interface ResolvedAgentsConfig {
+  maxConcurrent: number;
+  /** As configured (relative to the distribution root). */
+  personaPacks: string[];
+  /** `agents.<id>` blocks, by agent id. */
+  agents: Record<string, AgentGrantsConfig>;
+}
+
+/** An agent id or workspace name: what WORKSPACE_NAME_RE accepts. */
+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);
+
+/**
+ * The effective agents config. Anything malformed throws, naming the key:
+ * a typo must not lift the cap, drop a pack or widen a grant.
+ */
+export function readAgentsConfig(
+  config: DenConfig = readDenConfig(),
+): ResolvedAgentsConfig {
+  const raw = (config.agents ?? {}) as unknown;
+  if (!isMapping(raw))
+    throw new Error(`agents: must be a mapping (got ${JSON.stringify(raw)})`);
+  const out: ResolvedAgentsConfig = {
+    maxConcurrent: DEFAULT_AGENTS_MAX_CONCURRENT,
+    personaPacks: [],
+    agents: {},
+  };
+  const max = raw.max_concurrent;
+  if (max !== undefined) {
+    if (typeof max !== "number" || !Number.isInteger(max) || max < 1)
+      throw new Error(
+        `agents.max_concurrent: must be a whole number of at least 1 (got ${JSON.stringify(max)})`,
+      );
+    out.maxConcurrent = max;
+  }
+  const packs = raw.persona_packs;
+  if (packs !== undefined && packs !== null) {
+    if (!Array.isArray(packs))
+      throw new Error(
+        `agents.persona_packs: must be a list of paths (got ${JSON.stringify(packs)})`,
+      );
+    packs.forEach((p, i) => {
+      if (typeof p !== "string" || !p.trim())
+        throw new Error(
+          `agents.persona_packs[${i}]: must be a non-empty path (got ${JSON.stringify(p)})`,
+        );
+    });
+    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, ` +
+          `or an agent id mapping to { grants: [...] })`,
+      );
+    for (const k of Object.keys(block))
+      if (k !== "grants")
+        throw new Error(`${where}.${k}: unknown key (an agent takes grants)`);
+    const grants = block.grants ?? [];
+    if (!Array.isArray(grants))
+      throw new Error(
+        `${where}.grants: must be a list of workspace names (got ${JSON.stringify(grants)})`,
+      );
+    grants.forEach((g, i) => {
+      if (typeof g !== "string" || !AGENT_KEY_RE.test(g))
+        throw new Error(
+          `${where}.grants[${i}]: ${JSON.stringify(g)} is not a workspace name`,
+        );
+    });
+    out.agents[id] = { grants: [...new Set(grants as string[])] };
+  }
+  return out;
+}
+
 // ── Web UI service (`<cli> service`) ──────────────────────────────────────────
 
 /** `web:` in the org config. */

package/src/shared/engine.ts

@@ -13,6 +13,7 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { pathToFileURL } from "node:url";
 import { getDistRoot, getEngineRoot } from "./paths.js";
 
 /** An absolute path inside Den's own package. */
@@ -83,3 +84,25 @@ export function distPath(...parts: string[]): string {
 export function playwrightCommand(...args: string[]): EngineCommand {
   return { command: engineBin("playwright"), args };
 }
+
+/**
+ * How to run Den's CLI as a background process of its own, whatever process
+ * asks (the CLI, the web server): one node process, never the tsx CLI (a
+ * parent that relays signals). Live TypeScript source with tsx's loader in
+ * a checkout or a package install; the compiled build when tsx is absent,
+ * 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");
+  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");
+  if (loader && fs.existsSync(src))
+    return {
+      command: process.execPath,
+      args: ["--import", pathToFileURL(loader).href, src],
+    };
+  if (fs.existsSync(built)) return { command: process.execPath, args: [built] };
+  return { command: engineBin("tsx", engine), args: [src] };
+}

package/src/shared/environment-manager/workspaces.ts

@@ -325,6 +325,25 @@ export function writeWorkspacesFile(file: WorkspacesFile): void {
   }
 }
 
+/**
+ * A workspace's checkout directory: its `directory` (relative to the
+ * distribution root), else den-workspaces/<name>, else the legacy
+ * <reposRoot>/<name>, else the repos root itself. What /api/workspaces
+ * reports as resolvedDirs, and where an agent of the workspace runs.
+ */
+export function resolveWorkspaceDir(
+  name: string,
+  ws: Pick<WorkspaceConfig, "directory">,
+  reposRoot: string,
+): string {
+  if (ws.directory) return path.resolve(ROOT, ws.directory);
+  const gwDir = path.join(DEN_WORKSPACES_DIR, name);
+  if (fs.existsSync(gwDir)) return gwDir;
+  const legacyDir = path.join(reposRoot, name);
+  if (fs.existsSync(legacyDir)) return legacyDir;
+  return reposRoot;
+}
+
 export function getWorkspaceByName(name: string): {
   name: string;
   config: WorkspaceConfig;

package/src/shared/secret-env.ts

@@ -0,0 +1,70 @@
+/**
+ * Which environment variables are credentials, by name or by value. One
+ * set of patterns for everything that checks an environment: the test
+ * workers (tests/scrub-env.ts), the audit of `sessions start --keep-env`,
+ * and `<cli> doctor --probe` (with the text redactor's own patterns,
+ * redact.ts). They err on the side of flagging: a harmless variable called
+ * a credential costs less than a token called harmless.
+ *
+ * Nothing here returns or logs a value.
+ */
+
+import { redactSecrets, SECRET_PATTERNS } from "./redact.js";
+
+/** Variable names that hold credentials. */
+const SECRET_NAME =
+  /(TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIAL|API_?KEY|PRIVATE_KEY|ACCESS_KEY|AUTH)/i;
+
+/** Whole families of credential variables. */
+const SECRET_PREFIX = /^(OP_|DOPPLER_|AWS_|GH_|GITHUB_|NPM_|ANTHROPIC_)/i;
+
+/** Values shaped like well-known tokens, whatever the variable is called. */
+const SECRET_VALUE =
+  /(gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}|ops_[A-Za-z0-9]{20,}|sk-ant-[A-Za-z0-9_-]{20,}|dp\.(st|ct|sa|scim)\.[A-Za-z0-9]{20,}|npm_[A-Za-z0-9]{20,}|xox[abpr]-[A-Za-z0-9-]{10,})/;
+
+/** Whether a variable looks like a credential, by name or by value. */
+export function isCredentialEnv(
+  name: string,
+  value: string | undefined,
+): boolean {
+  return (
+    SECRET_NAME.test(name) ||
+    SECRET_PREFIX.test(name) ||
+    (value !== undefined && SECRET_VALUE.test(value))
+  );
+}
+
+/**
+ * Credential-shaped: by name or value (isCredentialEnv), or a value the
+ * text redactor would redact.
+ */
+export function isCredentialShaped(
+  name: string,
+  value: string | undefined,
+): boolean {
+  return (
+    isCredentialEnv(name, value) ||
+    (value !== undefined && value !== "" && redactSecrets(value) !== value)
+  );
+}
+
+/**
+ * Every pattern isCredentialShaped uses, as plain data (source and flags,
+ * global flag dropped), for a check run in another process (the probe).
+ */
+export function credentialPatternData(): {
+  name: { source: string; flags: string }[];
+  value: { source: string; flags: string }[];
+} {
+  const data = (re: RegExp) => ({
+    source: re.source,
+    flags: re.flags.replace("g", ""),
+  });
+  return {
+    name: [SECRET_NAME, SECRET_PREFIX].map(data),
+    value: [SECRET_VALUE, ...SECRET_PATTERNS.map((p) => p.re)].map(data),
+  };
+}
+
+/** An environment variable name (`--keep-env NAME`). */
+export const ENV_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;