@monster-orange/den 0.4.1 → 0.4.3

package/src/shared/agents/runtime-search.ts

@@ -0,0 +1,416 @@
+/**
+ * Where a runtime's CLI is found (AG-0.1): the way the person's terminal
+ * would find it, not only on the server's own PATH. A web server run as a
+ * launchd service gets a short PATH that leaves out `~/.local/bin`, where
+ * Claude Code's native installer puts `claude`.
+ *
+ * The search, first match wins:
+ *   1. setting      `agents.runtimes.<id>.bin` in config/local/user.yml
+ *                   (per machine, so never in the distribution's config):
+ *                   an absolute path to an executable file; a bad one is
+ *                   refused with its reason, never skipped.
+ *   2. login-shell  the login shell's PATH (`$SHELL -lc`), resolved once
+ *                   at server start, async, under a 3-second timeout; on
+ *                   any failure it is left out (the current PATH remains).
+ *   3. PATH         the caller's own PATH.
+ *   4. well-known   the runtime's install directories (its `find.dirs`:
+ *                   for den-claude ~/.local/bin, ~/.claude/local,
+ *                   /opt/homebrew/bin, /usr/local/bin and npm's global
+ *                   bin, derived from npm_config_prefix and node's own
+ *                   directory, never by running npm).
+ *
+ * Sessions and agents Den starts get the same directories on their PATH
+ * (sessionPath), so the runtime's own tools are found too.
+ *
+ * Two engine overrides, for tests and diagnosis (names only, never
+ * secrets), read from the env given, else this process's: DEN_LOGIN_SHELL,
+ * the shell to ask instead of $SHELL ("off": none), and DEN_RUNTIME_DIRS,
+ * a PATH-style list that replaces every runtime's well-known directories
+ * (empty: none).
+ */
+import { spawn } from "child_process";
+import * as fs from "fs";
+import * as path from "path";
+
+export type BinSource = "setting" | "login-shell" | "well-known" | "PATH";
+
+/** The shell asked for the login PATH instead of $SHELL; "off" for none. */
+export const LOGIN_SHELL_ENV = "DEN_LOGIN_SHELL";
+/** A PATH-style list replacing every runtime's well-known directories. */
+export const RUNTIME_DIRS_ENV = "DEN_RUNTIME_DIRS";
+export const LOGIN_PATH_TIMEOUT_MS = 3000;
+
+/** How a runtime's CLI is found and its version asked (catalog-shaped). */
+export interface RuntimeFind {
+  /** Executable names, in order ("claude"). */
+  bins: readonly string[];
+  /** Its well-known install directories, from HOME and the env. */
+  dirs?: (home: string | undefined, env: NodeJS.ProcessEnv) => string[];
+  /** The arguments that print its version ("--version"). */
+  versionArgs?: readonly string[];
+}
+
+export interface SearchDir {
+  dir: string;
+  source: Exclude<BinSource, "setting">;
+}
+
+export interface Located {
+  available: boolean;
+  path?: string;
+  source?: BinSource;
+  /** Why it is unavailable. */
+  why?: string;
+  /** The directories searched, in order (none when a setting decided). */
+  searched: string[];
+}
+
+/**
+ * An engine override: the env given, else this process's (a test run sets
+ * them once for every env it builds).
+ */
+function engineOverride(
+  name: string,
+  env: NodeJS.ProcessEnv,
+): string | undefined {
+  return env[name] ?? process.env[name];
+}
+
+// ── the login shell's PATH ──────────────────────────────────────────────────
+
+let loginDirs: string[] | null = null;
+
+/** The login shell's PATH as resolved at start, or undefined. */
+export function loginPath(): string | undefined {
+  return loginDirs ? loginDirs.join(path.delimiter) : undefined;
+}
+
+/** Set (or, with undefined, forget) the resolved login PATH. */
+export function setLoginPath(p: string | undefined): void {
+  loginDirs = p ? absoluteDirs(p) : null;
+}
+
+const BEGIN = "__DEN_PATH_BEGIN__";
+const END = "__DEN_PATH_END__";
+
+export interface LoginPathOptions {
+  env?: NodeJS.ProcessEnv;
+  timeoutMs?: number;
+}
+
+/**
+ * Ask the login shell for its PATH: `<shell> -lc 'printf …"$PATH"…'`,
+ * between markers so anything a startup file prints is ignored. Resolves
+ * undefined on no shell, a timeout (the shell is killed), a non-absolute
+ * shell, or nothing between the markers. Never throws, never blocks.
+ */
+export function resolveLoginPath(
+  o: LoginPathOptions = {},
+): Promise<string | undefined> {
+  const env = o.env ?? process.env;
+  const shell = (
+    engineOverride(LOGIN_SHELL_ENV, env) ??
+    env.SHELL ??
+    ""
+  ).trim();
+  if (!shell || shell === "off" || !path.isAbsolute(shell))
+    return Promise.resolve(undefined);
+  const timeoutMs = o.timeoutMs ?? LOGIN_PATH_TIMEOUT_MS;
+  return new Promise((resolve) => {
+    let out = "";
+    let done = false;
+    const finish = (v: string | undefined) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      resolve(v);
+    };
+    let child: ReturnType<typeof spawn>;
+    try {
+      child = spawn(shell, ["-lc", `printf '${BEGIN}%s${END}' "$PATH"`], {
+        env,
+        stdio: ["ignore", "pipe", "ignore"],
+      });
+    } catch {
+      resolve(undefined);
+      return;
+    }
+    const timer = setTimeout(() => {
+      try {
+        child.kill("SIGKILL");
+      } catch {
+        /* gone */
+      }
+      finish(undefined);
+    }, timeoutMs);
+    timer.unref?.();
+    child.on("error", () => finish(undefined));
+    child.stdout?.on("data", (d: Buffer) => {
+      out += d.toString("utf-8");
+      if (out.length > 256 * 1024) out = out.slice(-128 * 1024);
+      const m = new RegExp(`${BEGIN}([^]*?)${END}`).exec(out);
+      if (m) {
+        const dirs = absoluteDirs(m[1]);
+        finish(dirs.length ? dirs.join(path.delimiter) : undefined);
+      }
+    });
+    child.on("close", () => finish(undefined));
+  });
+}
+
+/**
+ * Resolve the login PATH once and keep it (the server's start, `agents
+ * doctor`). Never throws; on failure the current PATH stays the search.
+ */
+export async function initLoginPath(o: LoginPathOptions = {}): Promise<void> {
+  const p = await resolveLoginPath(o);
+  if (p) setLoginPath(p);
+}
+
+// ── the directories ─────────────────────────────────────────────────────────
+
+/** A PATH-style list's absolute entries, in order, once each. */
+function absoluteDirs(list: string): string[] {
+  const out: string[] = [];
+  for (const d of list.split(path.delimiter)) {
+    const dir = d.trim();
+    if (dir && path.isAbsolute(dir) && !out.includes(dir)) out.push(dir);
+  }
+  return out;
+}
+
+/**
+ * npm's global bin, without running npm: `$npm_config_prefix/bin`, then
+ * the directory of the node binary (npm's default global prefix puts its
+ * bin there).
+ */
+export function npmGlobalBins(
+  env: NodeJS.ProcessEnv,
+  execPath: string = process.execPath,
+): string[] {
+  const out: string[] = [];
+  const prefix = env.npm_config_prefix ?? env.NPM_CONFIG_PREFIX;
+  if (prefix && path.isAbsolute(prefix)) out.push(path.join(prefix, "bin"));
+  if (execPath && path.isAbsolute(execPath)) out.push(path.dirname(execPath));
+  return out;
+}
+
+/** The common install directories: Homebrew's, /usr/local's, npm's. */
+export function systemBinDirs(env: NodeJS.ProcessEnv): string[] {
+  return ["/opt/homebrew/bin", "/usr/local/bin", ...npmGlobalBins(env)];
+}
+
+/** A runtime's well-known directories, or DEN_RUNTIME_DIRS when set. */
+export function wellKnownDirs(
+  find: RuntimeFind | undefined,
+  env: NodeJS.ProcessEnv,
+): string[] {
+  const override = engineOverride(RUNTIME_DIRS_ENV, env);
+  if (override !== undefined) return absoluteDirs(override);
+  const home = env.HOME && path.isAbsolute(env.HOME) ? env.HOME : undefined;
+  return find?.dirs
+    ? absoluteDirs(find.dirs(home, env).join(path.delimiter))
+    : [];
+}
+
+/** Where a runtime is looked for, in order: login shell, PATH, well-known. */
+export function searchDirs(
+  find: RuntimeFind | undefined,
+  env: NodeJS.ProcessEnv,
+): SearchDir[] {
+  const out: SearchDir[] = [];
+  const add = (dirs: string[], source: SearchDir["source"]) => {
+    for (const dir of dirs)
+      if (!out.some((x) => x.dir === dir)) out.push({ dir, source });
+  };
+  add(loginDirs ?? [], "login-shell");
+  add(absoluteDirs(env.PATH ?? ""), "PATH");
+  add(wellKnownDirs(find, env), "well-known");
+  return out;
+}
+
+function isExecutableFile(file: string): boolean {
+  try {
+    fs.accessSync(file, fs.constants.X_OK);
+    return fs.statSync(file).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/** The setting's key for runtime `id`. */
+export const binSettingKey = (id: string) => `agents.runtimes.${id}.bin`;
+
+/**
+ * A configured bin, checked: an absolute path to an executable file.
+ * Returns its path, or why it is refused (naming the key, never guessing).
+ */
+export function checkBinSetting(
+  id: string,
+  value: unknown,
+): { path: string } | { why: string } {
+  const key = binSettingKey(id);
+  if (
+    value &&
+    typeof value === "object" &&
+    typeof (value as { why?: unknown }).why === "string"
+  )
+    return { why: (value as { why: string }).why };
+  if (typeof value !== "string" || !value.trim())
+    return { why: `${key} must be an absolute path (got ${typeof value})` };
+  const p = value.trim();
+  const shown = p.replace(/[^\x20-\x7e]/g, "?").slice(0, 200);
+  if (!path.isAbsolute(p))
+    return { why: `${key}: "${shown}" is not an absolute path` };
+  if (!fs.existsSync(p)) return { why: `${key}: ${shown} does not exist` };
+  if (!isExecutableFile(p))
+    return { why: `${key}: ${shown} is not an executable file` };
+  return { path: p };
+}
+
+/**
+ * Find runtime `id`'s CLI: the setting when there is one (refused with its
+ * reason when bad), else the first of `find.bins` in searchDirs. Runs
+ * nothing.
+ */
+export function locateRuntime(
+  id: string,
+  find: RuntimeFind,
+  env: NodeJS.ProcessEnv,
+  setting?: unknown,
+): Located {
+  if (setting !== undefined && setting !== null) {
+    const c = checkBinSetting(id, setting);
+    return "path" in c
+      ? { available: true, path: c.path, source: "setting", searched: [] }
+      : { available: false, why: c.why, source: "setting", searched: [] };
+  }
+  const dirs = searchDirs(find, env);
+  for (const { dir, source } of dirs)
+    for (const bin of find.bins) {
+      const file = path.join(dir, bin);
+      if (isExecutableFile(file))
+        return {
+          available: true,
+          path: file,
+          source,
+          searched: dirs.map((d) => d.dir),
+        };
+    }
+  return {
+    available: false,
+    why: `${find.bins.join(" or ")} not found (searched ${dirs.length} ${dirs.length === 1 ? "directory" : "directories"})`,
+    searched: dirs.map((d) => d.dir),
+  };
+}
+
+/**
+ * The PATH a session Den starts gets: the login shell's, the caller's,
+ * then each runtime's well-known directories that exist, and `extra` (a
+ * configured bin's directory). The caller's PATH is kept as it is when
+ * nothing is added.
+ */
+export function sessionPath(
+  env: NodeJS.ProcessEnv,
+  finds: readonly (RuntimeFind | undefined)[],
+  extra: readonly string[] = [],
+): string | undefined {
+  const own = env.PATH;
+  const ownDirs = absoluteDirs(own ?? "");
+  const before = (loginDirs ?? []).filter((d) => !ownDirs.includes(d));
+  const after: string[] = [];
+  const seen = new Set([...before, ...ownDirs]);
+  const candidates = [
+    ...finds.flatMap((f) => wellKnownDirs(f, env)),
+    ...extra.filter((d) => path.isAbsolute(d)),
+  ];
+  for (const d of candidates) {
+    if (seen.has(d)) continue;
+    seen.add(d);
+    try {
+      if (fs.statSync(d).isDirectory()) after.push(d);
+    } catch {
+      /* not on this machine */
+    }
+  }
+  if (!before.length && !after.length) return own;
+  return [...before, ...(own ? [own] : []), ...after].join(path.delimiter);
+}
+
+// ── the version ─────────────────────────────────────────────────────────────
+
+const VERSION_TIMEOUT_MS = 3000;
+const versions = new Map<string, Promise<string | undefined>>();
+
+/** The first version-shaped token of a CLI's `--version` output. */
+export function parseVersion(out: string): string | undefined {
+  const m = /\bv?(\d+\.\d+(?:\.\d+)?(?:[-+][0-9A-Za-z.-]+)?)\b/.exec(out);
+  return m?.[1];
+}
+
+/**
+ * Run `<bin> <versionArgs>` once (under a timeout; stdin closed, the env
+ * as given) and keep the answer, per path and file identity, so a page
+ * asking again runs nothing. Undefined when it fails or prints none.
+ */
+export function runtimeVersion(
+  bin: string,
+  args: readonly string[],
+  env: NodeJS.ProcessEnv,
+  timeoutMs: number = VERSION_TIMEOUT_MS,
+): Promise<string | undefined> {
+  let key: string;
+  try {
+    const st = fs.statSync(bin);
+    key = `${bin}\0${st.ino}\0${st.size}\0${st.mtimeMs}\0${args.join(" ")}`;
+  } catch {
+    return Promise.resolve(undefined);
+  }
+  const known = versions.get(key);
+  if (known) return known;
+  const p = new Promise<string | undefined>((resolve) => {
+    let out = "";
+    let done = false;
+    const finish = (v: string | undefined) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      resolve(v);
+    };
+    let child: ReturnType<typeof spawn>;
+    try {
+      child = spawn(bin, [...args], {
+        env,
+        stdio: ["ignore", "pipe", "pipe"],
+      });
+    } catch {
+      resolve(undefined);
+      return;
+    }
+    const timer = setTimeout(() => {
+      try {
+        child.kill("SIGKILL");
+      } catch {
+        /* gone */
+      }
+      finish(undefined);
+    }, timeoutMs);
+    timer.unref?.();
+    const take = (d: Buffer) => {
+      if (out.length < 4096) out += d.toString("utf-8");
+    };
+    child.stdout?.on("data", take);
+    child.stderr?.on("data", take);
+    child.on("error", () => finish(undefined));
+    child.on("close", (code) =>
+      finish(code === 0 ? parseVersion(out) : undefined),
+    );
+  });
+  versions.set(key, p);
+  return p;
+}
+
+/** Forget every version asked (tests). */
+export function clearVersionCache(): void {
+  versions.clear();
+}

package/src/shared/agents/runtime.ts

@@ -16,6 +16,7 @@ import {
   type StrategyEntry,
 } from "../strategies/registry.js";
 import type { Persona } from "./personas.js";
+import type { BinSource, RuntimeFind } from "./runtime-search.js";
 
 export const RUNTIME_KIND = "runtime";
 
@@ -27,6 +28,20 @@ export interface RuntimeDetect {
   version?: string;
   /** Why it is unavailable. */
   why?: string;
+  /** The CLI it runs, when found (AG-0.1). */
+  path?: string;
+  /** Where that path came from. */
+  source?: BinSource;
+  /** The directories searched, in order (names only, never values). */
+  searched?: string[];
+}
+
+export interface DetectOptions {
+  /**
+   * `agents.runtimes.<id>.bin` as configured in user.yml (undefined:
+   * read it there; null: none).
+   */
+  bin?: unknown;
 }
 
 /** The MCP server an agent acts through: Den's, scoped to its workspace. */
@@ -69,6 +84,8 @@ export interface LaunchInput {
    * run that was never prompted starts afresh with the id it had.
    */
   resumeToken?: string;
+  /** The CLI detect found (a setting, the login PATH, …); else searched again. */
+  bin?: string;
 }
 
 export interface LaunchOutput {
@@ -88,7 +105,15 @@ export type ResumeInput = LaunchInput;
 export interface Runtime {
   /** "den-claude", "generic". */
   id: string;
-  detect(env?: NodeJS.ProcessEnv): RuntimeDetect;
+  /** Its name for people ("Claude Code"), in the Start agent form. */
+  label?: string;
+  /**
+   * How its CLI is found and its version asked (AG-0.1): the search's
+   * binary names and install directories, per runtime, so a catalog can
+   * supply them (AG-0.5). None: nothing to find (generic).
+   */
+  find?: RuntimeFind;
+  detect(env?: NodeJS.ProcessEnv, opts?: DetectOptions): 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. */

package/src/shared/agents/runtimes.ts

@@ -4,7 +4,14 @@
  */
 import { denClaude } from "./den-claude.js";
 import { generic } from "./generic.js";
-import { allScrubEnv, registerRuntime, type Runtime } from "./runtime.js";
+import {
+  allScrubEnv,
+  getRuntime,
+  registerRuntime,
+  runtimeIds,
+  type Runtime,
+} from "./runtime.js";
+import { sessionPath, type RuntimeFind } from "./runtime-search.js";
 import { ACTOR_TOKEN_ENV } from "../actor-token.js";
 import { AGENT_ACTOR_ENV, buildSessionEnv } from "../sessions/env.js";
 
@@ -25,9 +32,27 @@ export {
   type Runtime,
 } from "./runtime.js";
 
+/** Every registered runtime's find (its well-known directories). */
+export function allRuntimeFinds(): (RuntimeFind | undefined)[] {
+  return runtimeIds().map((id) => getRuntime(id)?.find);
+}
+
+/**
+ * The caller's env with the PATH a session gets (AG-0.1): the login
+ * shell's PATH, the caller's, then every runtime's install directories
+ * that exist, and `extraDirs` (a configured CLI's directory).
+ */
+export function withSessionPath(
+  caller: NodeJS.ProcessEnv,
+  extraDirs: readonly string[] = [],
+): NodeJS.ProcessEnv {
+  const PATH = sessionPath(caller, allRuntimeFinds(), extraDirs);
+  return PATH === caller.PATH ? caller : { ...caller, PATH };
+}
+
 /**
  * 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
+ * checks it: the allowlist (its PATH the search's, withSessionPath), the runtime's passthrough and launch env, Den's
  * markers (DEN_AGENT=agent:<id>, and SEC-1c's DEN_ACTOR_TOKEN when one was
  * minted), then every runtime's scrubEnv and any person credential.
  */
@@ -38,9 +63,11 @@ export function agentSessionEnv(
   agentId: string,
   /** SEC-1c: the agent's actor token (`agents start` mints it; the probe has none). */
   actorToken?: string,
+  /** Added to its PATH: the directory of the CLI it runs. */
+  extraDirs: readonly string[] = [],
 ): Record<string, string> {
   return buildSessionEnv({
-    caller,
+    caller: withSessionPath(caller, extraDirs),
     passthrough: rt.envPassthrough,
     launch,
     // The seam for a persona's or runtime's declared env: none yet.

package/src/shared/den-config.ts

@@ -244,10 +244,16 @@ export interface DenConfig {
    */
   mcp?: McpConfig;
   /**
-   * Agents: `max_concurrent` caps the sessions running at once in this
-   * distribution (default 4). See readAgentsConfig.
+   * Agents: `max_concurrent` caps the agents running at once in this
+   * distribution (default 4); plain sessions never count. See
+   * readAgentsConfig.
    */
   agents?: AgentsConfig;
+  /**
+   * Plain sessions (`<cli> sessions start`): `max_concurrent` caps those
+   * running at once (default 8); agents never count. See readSessionsConfig.
+   */
+  sessions?: SessionsConfig;
   /**
    * The web UI: `port` (read by edge/config.ts readWebPort) and `service`,
    * the launchd service `<cli> service` installs. See readWebServiceConfig.
@@ -373,6 +379,13 @@ export interface UserConfig {
    * src/shared/environment-manager/scope.ts.
    */
   view?: { scope?: string };
+  /**
+   * Agents on this machine (AG-0.1): `runtimes.<id>.bin`, the absolute path
+   * of a runtime's CLI, which wins over the search (login shell PATH, PATH,
+   * install directories). Per machine, so user.yml only: the distribution's
+   * config never sets a path. See shared/agents/runtime-search.ts.
+   */
+  agents?: { runtimes?: Record<string, { bin?: unknown } | null> };
 }
 
 const ALL_ENVIRONMENTS: Environment[] = [
@@ -394,6 +407,35 @@ const DEFAULT_CONFIG: DenConfig = {
   environments: ALL_ENVIRONMENTS,
 };
 
+/** The per-engineer user config's path (config/local/user.yml), absolute. */
+export function userConfigPath(): string {
+  return USER_CONFIG_PATH;
+}
+
+/**
+ * `agents.runtimes.<id>.bin` from user.yml, as written (checked where it is
+ * used: runtime-search.ts checkBinSetting; a block that is no mapping is
+ * `{ why }`); undefined when unset or when user.yml can't be read.
+ */
+export function configuredRuntimeBin(
+  id: string,
+  read: () => UserConfig = readUserConfig,
+): unknown {
+  try {
+    const rts = read().agents?.runtimes;
+    if (!rts || typeof rts !== "object") return undefined;
+    const block = (rts as Record<string, unknown>)[id];
+    if (block === undefined || block === null) return undefined;
+    if (typeof block !== "object" || Array.isArray(block))
+      return {
+        why: `agents.runtimes.${id} must be a mapping ({ bin: <absolute path> })`,
+      };
+    return (block as { bin?: unknown }).bin;
+  } catch {
+    return undefined;
+  }
+}
+
 /** Read the per-engineer user config (config/local/user.yml). Returns {} if absent. */
 export function readUserConfig(): UserConfig {
   try {
@@ -558,6 +600,7 @@ export function readDenConfig(): DenConfig {
       security: parsed?.security,
       mcp: parsed?.mcp,
       agents: parsed?.agents,
+      sessions: parsed?.sessions,
       web: parsed?.web,
       test_accounts: parsed?.test_accounts,
       defaults: parsed?.defaults,
@@ -739,7 +782,7 @@ export function readMcpConfig(
 
 /** `agents:` in the org config. */
 export interface AgentsConfig {
-  /** Sessions that may run at once (default 4). */
+  /** Agents that may run at once (default 4); plain sessions never count. */
   max_concurrent?: number;
   /**
    * Persona packs (AG-2a): directories of persona files, relative to the
@@ -845,6 +888,48 @@ export function readAgentsConfig(
   return out;
 }
 
+/** `sessions:` in the org config: plain sessions (`<cli> sessions start`). */
+export interface SessionsConfig {
+  /** Plain sessions that may run at once (default 8); agents never count. */
+  max_concurrent?: number;
+}
+
+export const DEFAULT_SESSIONS_MAX_CONCURRENT = 8;
+
+/** `sessions:` with its defaults applied. */
+export interface ResolvedSessionsConfig {
+  maxConcurrent: number;
+}
+
+/**
+ * The effective sessions config. Anything malformed throws, naming the key,
+ * as readAgentsConfig does: a typo must not lift the cap.
+ */
+export function readSessionsConfig(
+  config: DenConfig = readDenConfig(),
+): ResolvedSessionsConfig {
+  const raw = (config.sessions ?? {}) as unknown;
+  if (!isMapping(raw))
+    throw new Error(`sessions: must be a mapping (got ${JSON.stringify(raw)})`);
+  for (const k of Object.keys(raw))
+    if (k !== "max_concurrent")
+      throw new Error(
+        `sessions.${k}: unknown key (sessions: takes max_concurrent)`,
+      );
+  const out: ResolvedSessionsConfig = {
+    maxConcurrent: DEFAULT_SESSIONS_MAX_CONCURRENT,
+  };
+  const max = raw.max_concurrent;
+  if (max !== undefined) {
+    if (typeof max !== "number" || !Number.isInteger(max) || max < 1)
+      throw new Error(
+        `sessions.max_concurrent: must be a whole number of at least 1 (got ${JSON.stringify(max)})`,
+      );
+    out.maxConcurrent = max;
+  }
+  return out;
+}
+
 // ── Web UI service (`<cli> service`) ──────────────────────────────────────────
 
 /** `web:` in the org config. */

package/src/shared/edge/render.ts

@@ -70,6 +70,37 @@ export function routeUrl(
   return `https://${routeHost(name, domain)}${p === 443 ? "" : `:${p}`}`;
 }
 
+/**
+ * The edge routes to a web server on one of `ports` (an upstream on the
+ * docker host or loopback), under every edge domain: `{ host, url }`, the
+ * hostname (lowercase) and the URL a browser uses there.
+ */
+export function webRouteHosts(
+  cfg: EdgeConfig,
+  ports: ReadonlySet<number>,
+): { host: string; url: string }[] {
+  return Object.entries(cfg.routes)
+    .filter(([, upstream]) => {
+      try {
+        const u = new URL(upstream);
+        return (
+          ports.has(Number(u.port || (u.protocol === "https:" ? 443 : 80))) &&
+          ["host.docker.internal", "localhost", "127.0.0.1"].includes(
+            u.hostname,
+          )
+        );
+      } catch {
+        return false;
+      }
+    })
+    .flatMap(([name]) =>
+      edgeDomains(cfg).map((d) => ({
+        host: routeHost(name, d).toLowerCase(),
+        url: routeUrl(name, cfg, d),
+      })),
+    );
+}
+
 /** Names that go on the org's certificate. */
 export function certNames(cfg: EdgeConfig): string[] {
   const zones = [...cfg.workspaces, ...(cfg.subzones ?? [])];