@monster-orange/den 0.2.8 → 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/auth/headless-login.ts

@@ -34,7 +34,7 @@ const PROJECT_ROOT = getDistRoot();
 const AUTH_DIR = path.resolve(PROJECT_ROOT, "playwright/.auth");
 
 // Per-engineer admin config — stores email + secret reference (no password)
-// Created by: make auth-configure [env=<env>]
+// Created by: make auth-configure [env=<env>] (secrets.provider: 1password)
 // Lookup order: config/local/admin-auth-{env}.json → config/local/admin-auth.json
 const LOCAL_CONFIG_DIR = path.resolve(PROJECT_ROOT, "config/local");
 

package/src/shared/auth/sudo-vault.ts

@@ -1,51 +1,56 @@
 /**
  * Secrets-backed persistence for the local-dev sudo password.
  *
- * Goes through the configured secrets strategy (Doppler, 1Password or env —
- * see src/shared/secrets), addressing the named ref `sudo` (default
- * OP_API_KEYS_VAULT / OP_DEV_KEYS_ITEM / OP_DEN_SUDO_FIELD; an org
- * moves it with `secrets.refs.sudo` in its config) — flat key
- * DEN_LOCAL_ADMIN_PWD for key/value backends.
+ * Goes through the configured secrets strategy (see src/shared/secrets),
+ * addressing the named ref `sudo`. There is no built-in location: a
+ * distribution that wants the saved password sets `secrets.refs.sudo` in its
+ * config. Without it, the vault path is "not configured" and only the
+ * interactive unlock is offered; nothing is spawned.
  *
  * All read helpers fail *soft*: if the backend isn't installed, the user isn't
- * signed in, or the value is missing, they return null/false so the server can
- * fall back to the manual unlock banner without surfacing CLI noise.
+ * signed in, the ref is not configured or the value is missing, they return
+ * null/false so the server can fall back to the manual unlock without
+ * surfacing CLI noise.
  */
 
-import {
-  OP_API_KEYS_VAULT,
-  OP_DEV_KEYS_ITEM,
-  OP_DEN_SUDO_FIELD,
-} from "../constants.js";
 import {
   getSecretsProvider,
   namedSecretRef,
+  notConfiguredMessage,
+  readSecretsConfig,
+  secretsStatus,
+  SecretsNotConfiguredError,
   type SecretRef,
+  type SecretsProviderName,
 } from "../secrets/index.js";
+import { product } from "../product.js";
 
-/** The built-in default for the `sudo` named ref. */
-export const SUDO_SECRET_REF: SecretRef = {
-  vault: OP_API_KEYS_VAULT,
-  item: OP_DEV_KEYS_ITEM,
-  field: OP_DEN_SUDO_FIELD,
-};
+/** Name of the sudo ref under `secrets.refs`. */
+export const SUDO_REF_NAME = "sudo";
 
-/** The effective sudo ref (`secrets.refs.sudo` over the default). */
-function sudoRef(): SecretRef {
-  return namedSecretRef("sudo", SUDO_SECRET_REF);
+/** The configured sudo ref, or null when `secrets.refs.sudo` is not set. */
+export function sudoRef(): SecretRef | null {
+  try {
+    return namedSecretRef(SUDO_REF_NAME, readSecretsConfig());
+  } catch {
+    return null;
+  }
 }
 
-/** True when the secrets backend is installed AND authenticated. */
+/** True when the sudo ref is configured AND its backend is ready. */
 export async function isSecretsBackendReady(): Promise<boolean> {
+  if (!sudoRef()) return false;
   return getSecretsProvider().isReady();
 }
 
 /** @deprecated use isSecretsBackendReady */
 export const isOpSignedIn = isSecretsBackendReady;
 
-/** Read the stored sudo password. Null when unavailable or empty. */
+/** Read the stored sudo password. Null when unavailable, unconfigured or empty. */
 export async function readSudoFromVault(): Promise<string | null> {
-  return getSecretsProvider().tryGet(sudoRef());
+  const ref = sudoRef();
+  if (!ref) return null;
+  return getSecretsProvider().tryGet(ref);
 }
 
 /** Whether a non-empty sudo password is stored (without returning it). */
@@ -55,15 +60,72 @@ export async function hasSudoInVault(): Promise<boolean> {
 
 /** Save (or overwrite) the sudo password. Throws on backend errors. */
 export async function saveSudoToVault(password: string): Promise<void> {
-  await getSecretsProvider().set(sudoRef(), password);
+  const ref = sudoRef();
+  if (!ref)
+    throw new SecretsNotConfiguredError(notConfiguredMessage(SUDO_REF_NAME));
+  await getSecretsProvider().set(ref, password);
+}
+
+/** What the UI's unlock form may offer: `/api/sudo-password/vault-status`. */
+export interface SudoVaultStatus {
+  /** The selected strategy id. */
+  backend: SecretsProviderName;
+  /** Name people see ("1Password"), for "Save to <label>". */
+  label: string;
+  /** `secrets.refs.sudo` is set for this backend. */
+  configured: boolean;
+  /**
+   * The backend can work here, whether or not a sudo ref is configured
+   * (`configured` says that). With no ref: detect() only (a PATH check,
+   * nothing spawned), and only for an explicitly chosen provider; an unset
+   * provider is never probed (it is not needed). With a ref: detect() and
+   * signed in.
+   */
+  backendAvailable: boolean;
+  /** Why it is not available (not configured, CLI not on PATH, signed out). */
+  reason?: string;
+  /** The distribution's org config file (e.g. config/acme.yml), for UI copy. */
+  configFile: string;
+  hasStored: boolean;
+  /** @deprecated alias of backendAvailable; removed in a later minor. */
+  opAvailable: boolean;
+}
+
+export async function sudoVaultStatus(): Promise<SudoVaultStatus> {
+  const cfg = readSecretsConfig();
+  const ref = sudoRef();
+  const pre = secretsStatus(cfg, process.env, { detect: false });
+  // Probe only what is needed or was chosen: a ref, or an explicit backend.
+  const probe = !!ref || (!pre.implicit && pre.backend !== "none");
+  const st = probe ? secretsStatus(cfg, process.env) : pre;
+  const out = (
+    backendAvailable: boolean,
+    hasStored: boolean,
+    reason?: string,
+  ): SudoVaultStatus => ({
+    backend: st.backend,
+    label: st.label,
+    configured: !!ref,
+    backendAvailable,
+    ...(reason ? { reason } : {}),
+    configFile: product().configFile,
+    hasStored,
+    opAvailable: backendAvailable,
+  });
+  if (!ref)
+    return out(
+      probe && st.detect.available,
+      false,
+      notConfiguredMessage(SUDO_REF_NAME),
+    );
+  if (!st.detect.available)
+    return out(false, false, `not available: ${st.detect.reason ?? ""}`.trim());
+  if (!(await getSecretsProvider().isReady()))
+    return out(false, false, `${st.label} is not signed in`);
+  return out(true, await hasSudoInVault());
 }
 
 /** Name of the active backend, for UI copy ("Save to Doppler"). */
 export function secretsBackendLabel(): string {
-  const n = getSecretsProvider().name;
-  return n === "1password"
-    ? "1Password"
-    : n === "doppler"
-      ? "Doppler"
-      : "environment";
+  return secretsStatus().label;
 }

package/src/shared/auth/token-providers/index.ts

@@ -115,9 +115,13 @@ const localJwtProvider: TokenProvider = {
     const l = cfg.auth?.localJwt;
     if (!l) throw new Error(`auth.localJwt is not set for ${cfg.name}`);
     const env = o.env ?? process.env;
+    // An explicit key the environment file names: not a default ref, so it
+    // resolves as it always has (env first, then the selected backend).
+    const fromEnv = env[l.secretKey];
+    const backend = fromEnv ? null : getSecretsProvider();
     const secret =
-      env[l.secretKey] ??
-      (await getSecretsProvider().tryGet({
+      fromEnv ??
+      (await backend!.tryGet({
         vault: "",
         item: "",
         field: l.secretKey,
@@ -125,7 +129,7 @@ const localJwtProvider: TokenProvider = {
       }));
     if (!secret) {
       throw new Error(
-        `local-jwt signing secret ${l.secretKey} not found in env or the secrets backend`,
+        `local-jwt signing secret ${l.secretKey} not found in env or the ${backend?.name ?? "configured"} secrets backend (secrets.provider)`,
       );
     }
     const ttl = l.ttlSeconds ?? 3600;

package/src/shared/brand.ts

@@ -8,6 +8,8 @@
  *     name: Acme Dev                 # shown in titles and the banner
  *     tagline: Acme local dev and E2E harness
  *     banner: [ "...", "..." ]       # optional ASCII art lines
+ *     theme: acme                    # the web UI's default theme (an id in
+ *                                    # plugins/<id>/, or den)
  */
 import * as fs from "fs";
 import * as path from "path";
@@ -19,6 +21,8 @@ export interface BrandConfig {
   name: string;
   tagline: string;
   banner?: string[];
+  /** The web UI's default theme id; the user's appearance.theme wins. */
+  theme?: string;
 }
 
 export function defaultBrand(): BrandConfig {
@@ -43,6 +47,9 @@ export function readBrand(root: string = getDistRoot()): BrandConfig {
     name: raw.name?.trim() || fallback.name,
     tagline: raw.tagline?.trim() || fallback.tagline,
     banner: Array.isArray(raw.banner) ? raw.banner.map(String) : undefined,
+    ...(typeof raw.theme === "string" && raw.theme.trim()
+      ? { theme: raw.theme.trim() }
+      : {}),
   };
   return cached;
 }

package/src/shared/config-error.ts

@@ -7,12 +7,36 @@
  * The message names config keys (`orgs.initech.repos`), never values a
  * secret could hide in.
  */
+/**
+ * One validation problem: the config file (as the distribution names it),
+ * the key path (`orgs.acme.sources[0].owner`) and what is wrong with it.
+ * `text` is the whole line after "<file>: ".
+ */
+export interface ConfigIssue {
+  file: string;
+  key: string;
+  message: string;
+  text: string;
+}
+
 export class ConfigError extends Error {
   readonly code = "config_invalid";
+  /** Every problem found (0.3.0-dev.40), in config order. */
+  readonly issues: ConfigIssue[];
 
-  constructor(message: string) {
-    super(message);
+  /**
+   * The message is one line per issue, "<file>: <text>". A plain string is
+   * one issue-less message.
+   */
+  constructor(issues: ConfigIssue[] | string) {
+    const list = typeof issues === "string" ? [] : issues;
+    super(
+      typeof issues === "string"
+        ? issues
+        : list.map((i) => `${i.file}: ${i.text}`).join("\n"),
+    );
     this.name = "ConfigError";
+    this.issues = list;
   }
 }
 
@@ -28,6 +52,12 @@ export function configErrorBody(e: ConfigError): {
   ok: false;
   error: string;
   code: "config_invalid";
+  issues: Array<{ file: string; key: string; message: string }>;
 } {
-  return { ok: false, error: e.message, code: e.code };
+  return {
+    ok: false,
+    error: e.message,
+    code: e.code,
+    issues: e.issues.map(({ file, key, message }) => ({ file, key, message })),
+  };
 }

package/src/shared/constants.ts

@@ -5,17 +5,7 @@
  * If it's specific to one module (e.g. a Playwright config timeout), keep it local.
  */
 
-import { envKey } from "./product.js";
-// ── 1Password strategy (only used when secrets.provider: 1password) ──────────────────────────────────────────────────────────────
-
-/**
- * Default 1Password account domain used by every `op` invocation across den.
- * Kept in sync with the `OP_ACCOUNT ?= …` default in the Makefile. Scripts that
- * may run outside `make` (setup-1password, auth-configure)
- * set `process.env.OP_ACCOUNT ||= OP_ACCOUNT_DEFAULT` at entry so op picks up
- * the right account even when invoked directly via `npx tsx`.
- */
-export const OP_ACCOUNT_DEFAULT = "example.1password.com";
+// ── Test accounts ─────────────────────────────────────────────────────────────
 
 /**
  * Default vault for shared test accounts. Deprecated: the vault is org data —
@@ -24,19 +14,8 @@ export const OP_ACCOUNT_DEFAULT = "example.1password.com";
  */
 export const OP_TEST_VAULT = "test-accounts";
 
-/** Vault containing per-engineer API keys (1Password's built-in personal vault). */
-export const OP_API_KEYS_VAULT = "Employee";
-
-/** Item within OP_API_KEYS_VAULT holding the developer's API keys. */
-export const OP_DEV_KEYS_ITEM = "Developer API Keys";
-
-/**
- * Field within OP_DEV_KEYS_ITEM where the user's local admin (sudo) password
- * is optionally stored. Populated when the user checks "Save to 1Password" on
- * the den local-dev unlock banner; read on server startup so subsequent
- * sessions unlock without prompting.
- */
-export const OP_DEN_SUDO_FIELD = `${envKey("LOCAL_ADMIN_PWD")}`;
+// No 1Password account, vault, item or field is built in: a distribution
+// names its own in `secrets` (src/shared/secrets).
 
 // ── Timeouts ─────────────────────────────────────────────────────────────────