@monster-orange/den 0.4.2 → 0.4.3

package/src/ui/cli/agent-ops.ts

@@ -7,7 +7,10 @@
  * what happened, or throws an AgentError saying why it didn't.
  *
  *   start   resolves the persona (Den's default pack, then
- *           agents.persona_packs) and the runtime, asks the runtime for argv,
+ *           agents.persona_packs) and the runtime (its CLI from
+ *           agents.runtimes.<id>.bin in user.yml, else the search:
+ *           runtime-search.ts, AG-0.1; unavailable, it is refused with the
+ *           fix), asks the runtime for argv,
  *           env and files (its MCP config: `<cli> mcp --workspace <ws>
  *           --actor agent:<id>`, plus a `--grant` per agents.<id>.grants),
  *           starts `<dist>-<ws>:<id>` in the workspace's dir, and writes the
@@ -38,7 +41,9 @@ import * as fs from "fs";
 import * as path from "path";
 import {
   AGENTS_RESERVED_KEYS,
+  configuredRuntimeBin,
   readAgentsConfig,
+  userConfigPath,
   type ResolvedAgentsConfig,
 } from "../../shared/den-config.js";
 import { cliEntrypoint } from "../../shared/engine.js";
@@ -69,6 +74,12 @@ import {
   type LaunchInput,
   type Runtime,
 } from "../../shared/agents/runtimes.js";
+import type { RuntimeDetect } from "../../shared/agents/runtime.js";
+import {
+  binSettingKey,
+  runtimeVersion,
+  type BinSource,
+} from "../../shared/agents/runtime-search.js";
 import { WORKSPACE_NAME_RE } from "../../shared/agent-actor.js";
 import {
   bindActorSession,
@@ -103,6 +114,10 @@ export interface AgentsDeps extends SessionsDeps {
    * exit (default 3000 ms; 0: not at all).
    */
   exitWatchMs?: number;
+  /** `agents.runtimes.<id>.bin` (default: user.yml's; undefined: unset). */
+  runtimeBin?: (id: string) => unknown;
+  /** The user.yml a person edits to set it (default: config/local/user.yml). */
+  userConfigFile?: () => string;
 }
 
 export interface AgentsResolved extends Resolved {
@@ -111,6 +126,8 @@ export interface AgentsResolved extends Resolved {
   workspaceDir: (ws: string) => string;
   mcpServer: () => { command: string[] | string; env: Record<string, string> };
   exitWatchMs: number;
+  runtimeBin: (id: string) => unknown;
+  userConfigFile: () => string;
 }
 
 /** The early-exit watch: at most this long, polling the host. */
@@ -199,6 +216,8 @@ export function resolveAgentsDeps(d: AgentsDeps): AgentsResolved {
       }),
     mcpServer: d.mcpServer ?? (() => defaultMcpServer(base.cli)),
     exitWatchMs: d.exitWatchMs ?? EXIT_WATCH_MS,
+    runtimeBin: d.runtimeBin ?? ((id) => configuredRuntimeBin(id)),
+    userConfigFile: d.userConfigFile ?? userConfigPath,
   };
 }
 
@@ -394,29 +413,84 @@ export function listPersonas(d: AgentsResolved): ListedPersona[] {
 
 export interface RuntimeChoice {
   id: string;
+  /** Its name for people ("Claude Code"). */
+  label?: string;
   available: boolean;
   /** Why it is unavailable. */
   why?: string;
   version?: string;
+  /** The CLI it runs (AG-0.2). */
+  path?: string;
+  /** Where that path came from: setting, login-shell, well-known or PATH. */
+  source?: BinSource;
+  /** The directories searched, in order (a runtime with a CLI to find). */
+  searched?: string[];
+  /** The user.yml key that sets its path (a runtime with a CLI to find). */
+  setting?: string;
   /** It declares resume. */
   resume: boolean;
   default: boolean;
 }
 
-/** Every registered runtime, and whether it can run here (detect runs nothing). */
-export function listRuntimes(d: AgentsResolved): RuntimeChoice[] {
-  return runtimeIds().map((id) => {
-    const rt = getRuntime(id)!;
-    const det = rt.detect(d.env);
-    return {
-      id,
-      available: det.available,
-      ...(det.available ? {} : { why: det.why ?? "unavailable" }),
-      ...(det.version ? { version: det.version } : {}),
-      resume: Boolean(rt.resume),
-      default: id === DEFAULT_RUNTIME_ID,
-    };
-  });
+/**
+ * Whether runtime `rt` can run here (AG-0.1): its setting
+ * (`agents.runtimes.<id>.bin`, from d.runtimeBin), else the search. Runs
+ * nothing.
+ */
+export function detectRuntime(d: AgentsResolved, rt: Runtime): RuntimeDetect {
+  return rt.detect(d.env, { bin: d.runtimeBin(rt.id) ?? null });
+}
+
+/**
+ * Every registered runtime, and whether it can run here, with the path it
+ * runs and its version: its version command (`claude --version`), run once
+ * under a timeout and kept, else what its install says.
+ */
+export async function listRuntimes(
+  d: AgentsResolved,
+): Promise<RuntimeChoice[]> {
+  return Promise.all(
+    runtimeIds().map(async (id) => {
+      const rt = getRuntime(id)!;
+      const det = detectRuntime(d, rt);
+      const asked =
+        det.available && det.path && rt.find?.versionArgs
+          ? await runtimeVersion(det.path, rt.find.versionArgs, d.env)
+          : undefined;
+      const version = asked ?? det.version;
+      return {
+        id,
+        ...(rt.label ? { label: rt.label } : {}),
+        available: det.available,
+        ...(det.available ? {} : { why: det.why ?? "unavailable" }),
+        ...(version ? { version } : {}),
+        ...(det.path ? { path: det.path } : {}),
+        ...(det.source ? { source: det.source } : {}),
+        ...(rt.find
+          ? { searched: det.searched ?? [], setting: binSettingKey(id) }
+          : {}),
+        resume: Boolean(rt.resume),
+        default: id === DEFAULT_RUNTIME_ID,
+      };
+    }),
+  );
+}
+
+/** Refused unless `rt` can run here; its detect result when it can. */
+function availableOrRefuse(d: AgentsResolved, rt: Runtime): RuntimeDetect {
+  const det = detectRuntime(d, rt);
+  if (!det.available)
+    throw refused(
+      `${rt.id} is unavailable: ${det.why ?? "unknown"}`,
+      rt.find
+        ? [
+            `Install it, or set ${binSettingKey(rt.id)} to its absolute path in ${d.userConfigFile()}.`,
+            `\`${d.cli} agents doctor\` shows where it looked.`,
+          ]
+        : [],
+      503,
+    );
+  return det;
 }
 
 function runtimeFor(id: string): Runtime {
@@ -460,6 +534,15 @@ interface Launch {
   passthrough?: readonly string[];
   /** agents.<id>.grants, recorded with its actor token. */
   grants: readonly string[];
+  /** Added to the session's PATH: a configured CLI's own directory. */
+  binDir?: string;
+}
+
+/** A configured CLI's directory, for its session's PATH (its own tools). */
+function binDirOf(det: RuntimeDetect): { binDir?: string } {
+  return det.source === "setting" && det.path
+    ? { binDir: path.dirname(det.path) }
+    : {};
 }
 
 /** The host's cap refusal as an AgentError (its hint says what to do). */
@@ -511,6 +594,7 @@ async function startSession(
             launch.env,
             launch.rec.id,
             minted.token,
+            launch.binDir ? [launch.binDir] : [],
           ),
           cols: (tty && d.stdout.columns) || 80,
           rows: (tty && d.stdout.rows) || 24,
@@ -601,6 +685,7 @@ function launchInput(
   ws: string,
   id: string,
   model: string | undefined,
+  bin?: string,
 ): LaunchInput {
   const grants = cfg.agents[id]?.grants ?? [];
   for (const g of grants)
@@ -623,6 +708,7 @@ function launchInput(
     filesDir: agentFilesDir(d.stateDir(), id),
     stateDir: d.stateDir(),
     env: d.env,
+    ...(bin ? { bin } : {}),
   };
 }
 
@@ -681,9 +767,7 @@ export async function startAgent(
   const id = req.id ?? defaultId(d.stateDir(), persona.id, ws);
   checkId(where, id);
   const rt = runtimeFor(req.runtime ?? persona.runtime ?? DEFAULT_RUNTIME_ID);
-  const det = rt.detect(d.env);
-  if (!det.available)
-    throw refused(`${rt.id} is unavailable: ${det.why ?? "unknown"}`, [], 503);
+  const det = availableOrRefuse(d, rt);
   const model = req.model ?? persona.model;
 
   const prev = readRecord(d.stateDir(), id);
@@ -692,7 +776,7 @@ export async function startAgent(
       `agent ${id} belongs to workspace ${prev.workspace}; give this one another --id`,
     );
   ptyOrRefuse(d);
-  const input = launchInput(d, cfg, persona, ws, id, model);
+  const input = launchInput(d, cfg, persona, ws, id, model, det.path);
 
   return withClient(d, async (c) => {
     const sessions = await c.list();
@@ -721,6 +805,7 @@ export async function startAgent(
         env: out.env,
         passthrough: rt.envPassthrough,
         grants: cfg.agents[id]?.grants ?? [],
+        ...binDirOf(det),
       },
       old,
       {},
@@ -795,6 +880,7 @@ export async function resumeAgent(
   const persona = personas(d, cfg).get(rec.persona);
   if (!persona)
     throw refused(`agent ${rec.id}'s persona "${rec.persona}" is gone`);
+  const det = availableOrRefuse(d, rt);
   ptyOrRefuse(d);
   return withClient(d, async (c) => {
     const old = sessionOf(await c.list(), rec);
@@ -809,6 +895,7 @@ export async function resumeAgent(
       rec.workspace,
       rec.id,
       rec.model,
+      det.path,
     );
     // Resume in the cwd the agent had, wherever the workspace points now.
     const at = {
@@ -833,6 +920,7 @@ export async function resumeAgent(
         env: out.env,
         passthrough: rt.envPassthrough,
         grants: cfg.agents[rec.id]?.grants ?? [],
+        ...binDirOf(det),
       },
       old,
       fresh ? {} : { resumedAt: new Date().toISOString() },

package/src/ui/cli/agents-command.ts

@@ -24,16 +24,25 @@
  *           running: a new session, in the same cwd, continuing the last run;
  *           when that session was never prompted, a fresh start under the
  *           same conversation id (there is nothing to continue).
+ *   doctor  (AG-0.3) each runtime: its status, the CLI it runs and where
+ *           that came from (setting, login-shell, PATH, well-known), its
+ *           version (its version command, once, under a timeout), the
+ *           directories searched (names only, never an env value), and the
+ *           fix when it is missing. Exit 1 when the default runtime is
+ *           unavailable. It resolves the login shell's PATH first, as the
+ *           web server does at start.
  *
  * Nothing here takes a grant: grants come from the org config only. The
  * host enforces agents.max_concurrent on every start, counting agents only.
  */
 import { DEFAULT_RUNTIME_ID } from "../../shared/agents/runtimes.js";
+import { initLoginPath } from "../../shared/agents/runtime-search.js";
 import { HostError } from "../../shared/sessions/client.js";
 import {
   AgentError,
   listAgents,
   listPersonas as personaList,
+  listRuntimes,
   loadAgentWorkspaces,
   resolveAgentsDeps,
   resumeAgent,
@@ -42,6 +51,7 @@ import {
   type AgentsDeps,
   type AgentsResolved,
   type EarlyExit,
+  type RuntimeChoice,
   type Started,
 } from "./agent-ops.js";
 import {
@@ -63,7 +73,7 @@ export {
 } from "./agent-ops.js";
 
 export const AGENTS_HELP = {
-  usage: "agents <list|start|stop|resume|personas> ...",
+  usage: "agents <list|start|stop|resume|personas|doctor> ...",
   lines: [
     "Agents: a persona and a workspace, run by a runtime in a session that",
     "outlives the web server (see `{cli} sessions`).",
@@ -78,9 +88,16 @@ export const AGENTS_HELP = {
     "    a session never prompted starts fresh under the same conversation id",
     "{cli} agents personas [--json]",
     "    Den's default pack, then agents.persona_packs (a later pack wins by id)",
+    "{cli} agents doctor [--json]",
+    "    each runtime: status, the CLI it runs and where it came from, its version,",
+    "    the directories searched, and the fix; exit 1 when the default is missing",
     "",
-    "Runtimes: den-claude (default; needs claude on PATH) and generic (the",
+    "Runtimes: den-claude (default; Claude Code's claude) and generic (the",
     "persona's argv template). Attach with `{cli} sessions attach <ws>:<id>`.",
+    "A runtime's CLI is found as your terminal finds it: agents.runtimes.<id>.bin",
+    "in config/local/user.yml (an absolute path) wins, then the login shell's PATH,",
+    "this PATH, and its install directories (~/.local/bin, ~/.claude/local,",
+    "/opt/homebrew/bin, /usr/local/bin, npm's global bin).",
     "An agent's env is PATH, HOME, USER, LOGNAME, SHELL, TERM, COLORTERM, LANG,",
     "LC_*, TZ and TMPDIR, plus what its runtime declares: nothing else of yours.",
   ],
@@ -250,10 +267,87 @@ async function listPersonas(
   return 0;
 }
 
+export interface AgentsDoctorDeps {
+  /** Resolve the login shell's PATH first (default: initLoginPath). */
+  loginPath?: () => Promise<void>;
+}
+
+const SOURCE_WORD: Record<string, string> = {
+  setting: "agents.runtimes setting",
+  "login-shell": "login shell PATH",
+  PATH: "PATH",
+  "well-known": "install directory",
+};
+
+/** `agents doctor`'s lines for one runtime (names and paths, never env values). */
+export function doctorLines(
+  r: RuntimeChoice,
+  cli: string,
+  userConfig: string,
+): string[] {
+  const lines = [
+    `${r.id}${r.label ? ` (${r.label})` : ""}${r.default ? "  [default]" : ""}`,
+    r.available
+      ? "  status    ✓ available"
+      : `  status    ✗ unavailable: ${r.why ?? "unknown"}`,
+  ];
+  if (r.path)
+    lines.push(
+      `  path      ${r.path}${r.source ? ` (${SOURCE_WORD[r.source] ?? r.source})` : ""}`,
+    );
+  if (r.available && r.setting)
+    lines.push(`  version   ${r.version ?? "unknown"}`);
+  if (!r.setting) lines.push("  path      none to find (the persona's argv)");
+  else if (r.searched?.length)
+    r.searched.forEach((dir, i) =>
+      lines.push(`  ${i === 0 ? "searched  " : "          "}${dir}`),
+    );
+  else if (r.source !== "setting") lines.push("  searched  (no directories)");
+  if (!r.available && r.setting)
+    lines.push(
+      `  fix       install ${r.label ?? r.id}, or set ${r.setting} to its absolute path in ${userConfig}`,
+      `            then run \`${cli} agents doctor\` again`,
+    );
+  return lines;
+}
+
+async function doctor(
+  args: string[],
+  d: AgentsResolved,
+  deps: AgentsDoctorDeps,
+): Promise<number> {
+  const where = "agents doctor";
+  const p = parseArgs(where, args, { "--json": false });
+  noExtra(where, p);
+  await (deps.loginPath ?? (() => initLoginPath({ env: d.env })))();
+  const rts = await listRuntimes(d);
+  const def = rts.find((r) => r.default);
+  const code = def?.available ? 0 : 1;
+  if (p.flags["--json"]) {
+    d.out(
+      JSON.stringify(
+        { runtimes: rts, userConfig: d.userConfigFile() },
+        null,
+        2,
+      ),
+    );
+    return code;
+  }
+  rts.forEach((r, i) => {
+    if (i) d.out("");
+    for (const l of doctorLines(r, d.cli, d.userConfigFile())) d.out(l);
+  });
+  d.out("");
+  d.out(
+    `\`${d.cli} doctor --probe\` checks the env each runtime's session gets.`,
+  );
+  return code;
+}
+
 /** `<cli> agents ...`; returns the exit code. */
 export async function cmdAgents(
   args: string[],
-  deps: AgentsDeps = {},
+  deps: AgentsDeps & AgentsDoctorDeps = {},
 ): Promise<number> {
   const d = resolveAgentsDeps(deps);
   const sub =
@@ -274,6 +368,8 @@ export async function cmdAgents(
           return await resume(rest, d);
         case "personas":
           return await listPersonas(rest, d);
+        case "doctor":
+          return await doctor(rest, d, deps);
         default:
           throw new UsageError(`unknown agents command "${sub}"`);
       }

package/src/ui/cli/sessions-command.ts

@@ -27,7 +27,7 @@ import { cliEntrypoint } from "../../shared/engine.js";
 import { getDistRoot, getInvokeCwd, getStateDir } from "../../shared/paths.js";
 import { product } from "../../shared/product.js";
 import { ENV_NAME_RE, isCredentialShaped } from "../../shared/secret-env.js";
-import { allScrubEnv } from "../../shared/agents/runtimes.js";
+import { allScrubEnv, withSessionPath } from "../../shared/agents/runtimes.js";
 import {
   ensureHost,
   connectHost,
@@ -320,14 +320,19 @@ export function contractInfo(s: SessionInfo): SessionInfo {
 // ── subcommands ───────────────────────────────────────────────────────────────
 
 /**
- * A plain session's env (AG spec §5a-env): the allowlist, the names the
- * user kept, then every runtime's scrubEnv. `doctor --probe` checks it.
+ * A plain session's env (AG spec §5a-env): the allowlist (its PATH with
+ * the runtime search's directories, AG-0.1), the names the user kept, then
+ * every runtime's scrubEnv. `doctor --probe` checks it.
  */
 export function plainSessionEnv(
   caller: NodeJS.ProcessEnv,
   keep: readonly string[] = [],
 ): Record<string, string> {
-  return buildSessionEnv({ caller, keep, scrub: allScrubEnv() });
+  return buildSessionEnv({
+    caller: withSessionPath(caller),
+    keep,
+    scrub: allScrubEnv(),
+  });
 }
 
 /** Who ran the CLI, for an audit line: a login name, printable. */

package/src/ui/cli/web-command.ts

@@ -33,7 +33,8 @@ import {
 } from "../../shared/web-session.js";
 import { revokeAllActorTokens } from "../../shared/actor-token.js";
 import { engineBin, engineModuleFile } from "../../shared/engine.js";
-import { readWebPort } from "../../shared/edge/config.js";
+import { readEdgeConfig, readWebPort } from "../../shared/edge/config.js";
+import { webRouteHosts } from "../../shared/edge/render.js";
 import {
   ownServer,
   processCwd,
@@ -1081,7 +1082,7 @@ export function displayWebHelp(): void {
   console.log(`  ${product().cli} web --setup-browser-access`);
   console.log(`  ${product().cli} web token --print`);
   console.log(
-    `  ${product().cli} web login [--next <path>] [--origin <url>] [--port <port>]`,
+    `  ${product().cli} web login [--next <path>] [--host <name> | --origin <url>] [--port <port>]`,
   );
   console.log(`  ${product().cli} web sessions [--json] [--port <port>]`);
   console.log(
@@ -1392,20 +1393,24 @@ function takePort(args: string[]): { port: number; rest: string[] } {
 }
 
 /**
- * `<cli> web login [--next <path>] [--origin <url>]`: a fresh sign-in link
+ * `<cli> web login [--next <path>] [--host <name> | --origin <url>]`: a fresh sign-in link
  * on stdout, alone (the only place a login code is ever printed); a note on
- * stderr. `--origin` for the edge hostname or a LAN name, where the cookie
- * must be set (the signed-out page there says which).
+ * stderr. `--host` for an edge hostname (its URL from the edge config),
+ * `--origin` for any allowed origin (a LAN name), where the cookie must be
+ * set (the signed-out page there says which).
  */
 export function cmdWebLogin(args: string[], io: CliIo = stdIo): number {
-  const usage = `Usage: ${product().cli} web login [--next <path>] [--origin <url>] [--port <port>]\n`;
+  const usage = `Usage: ${product().cli} web login [--next <path>] [--host <name> | --origin <url>] [--port <port>]\n`;
   if (isHelp(args)) {
     io.out(
       usage +
         "  Prints a one-time sign-in link (it works once, within 60 s) for one browser.\n" +
         "  On localhost nothing asks for a sign-in; it is needed when this server is\n" +
-        "  reached beyond this machine (the edge, or a LAN address: pass its --origin).\n" +
+        "  reached from another machine (pass the edge hostname as --host, or a LAN\n" +
+        "  address as --origin).\n" +
         "  --next <path>   where the browser lands after signing in (same origin only)\n" +
+        "  --host <name>   an edge hostname that routes here (an edge domain or alias,\n" +
+        "                  a VPN name among them): the link uses its edge URL\n" +
         "  --origin <url>  the address the browser uses, http(s)://host[:port]\n",
     );
     return 0;
@@ -1430,8 +1435,16 @@ export function cmdWebLogin(args: string[], io: CliIo = stdIo): number {
           : undefined;
     const n = val("--next");
     const o = val("--origin");
+    const h = val("--host");
     if (n !== undefined) next = n;
-    else if (o !== undefined) {
+    else if (h !== undefined) {
+      const found = edgeOriginFor(h, port);
+      if (typeof found !== "string") {
+        io.err(found.error);
+        return 2;
+      }
+      origin = found;
+    } else if (o !== undefined) {
       origin = parseOrigin(o);
       if (!origin) {
         io.err(
@@ -1457,6 +1470,38 @@ export function cmdWebLogin(args: string[], io: CliIo = stdIo): number {
   return 0;
 }
 
+/**
+ * `web login --host <name>`: the origin a browser uses for an edge hostname
+ * that routes to this server (edge.routes under any edge domain or alias),
+ * or why there is none and what to add.
+ */
+export function edgeOriginFor(
+  name: string,
+  port: number,
+): string | { error: string } {
+  const want = name.trim().toLowerCase().replace(/\.$/, "");
+  let routes: { host: string; url: string }[] = [];
+  try {
+    routes = webRouteHosts(readEdgeConfig(), new Set([port, readWebPort()]));
+  } catch {
+    routes = [];
+  }
+  const hit = routes.find((r) => r.host === want);
+  if (hit) return hit.url;
+  const known = routes.map((r) => r.host);
+  return {
+    error:
+      `--host ${name} is not a hostname this server answers to` +
+      (known.length
+        ? ` (its edge hostnames: ${known.join(", ")}).\n`
+        : " (no edge route reaches this server).\n") +
+      "  Add it to the config's edge block: its domain to edge.aliases (a VPN\n" +
+      "  name), or a route to this server in edge.routes, then `edge up`. For a\n" +
+      "  LAN name (DEN_BIND_HOST and web.allow_plain_http_remote) pass\n" +
+      "  --origin http://<name>:<port> instead.\n",
+  };
+}
+
 interface SessionRow {
   id: string;
   createdAt: string;

package/src/ui/server/agent-routes.ts

@@ -1,7 +1,9 @@
 /**
  * The Workspaces page's Agents section (AG-4a, AG spec §5c), its routes:
  *
- *   GET  /api/personas                            personas and runtimes
+ *   GET  /api/personas                            personas and runtimes (each
+ *                                                 with its path, where it came
+ *                                                 from and its version: AG-0.2)
  *   GET  /api/workspaces/<ws>/agents              the workspace's agents
  *   POST /api/workspaces/<ws>/agents              start { persona, runtime?, model?, id? }
  *   POST /api/workspaces/<ws>/agents/<id>/stop
@@ -204,7 +206,12 @@ export async function handleAgentRoutes(
   if (!m) {
     if (method !== "GET") return methodNotAllowed(res, "GET");
     try {
-      sendJson(res, { personas: listPersonas(d), runtimes: listRuntimes(d) });
+      sendJson(res, {
+        personas: listPersonas(d),
+        runtimes: await listRuntimes(d),
+        // AG-0.2: the file a person edits to set a runtime's path.
+        userConfig: d.userConfigFile(),
+      });
     } catch (e) {
       sendError(res, e);
     }