@monster-orange/den 0.3.0 → 0.4.0

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

@@ -1,13 +1,26 @@
 /**
- * `doctor`: every strategy kind in the registry (secrets, tls), the
- * strategy this distribution selects for it, whether nothing chose it
- * (implicit), and its detect() result with the reason.
+ * `doctor`: every strategy kind in the registry (secrets, tls,
+ * session-backend, runtime), the strategy this distribution selects for it, whether
+ * nothing chose it (implicit), and its detect() result with the reason.
  *
- * Read-only: detect() is a PATH check, so doctor never spawns a backend
- * CLI, never prompts, and never prints a secret value. Exit 1 when a
- * strategy that will be used is unavailable or its config is invalid.
+ * Read-only: detect() is a PATH check (session-backend loads the optional
+ * PTY module, which runs nothing; runtime reads a CLI's version from its
+ * install, never by running it), so doctor never spawns a backend CLI,
+ * never prompts, and never prints a secret value. Exit 1 when a strategy
+ * that will be used is unavailable or its config is invalid. When agents
+ * are configured, a note says to run `<cli> doctor --probe`.
+ *
+ * `--probe` (opt-in, AG spec §5a-env) is the one exception to never
+ * spawning: it runs a short probe session through the session host for a
+ * plain session and each available runtime's agent env (env-probe.ts), and
+ * exits 1 when a runtime's scrubEnv name or a credential-shaped variable
+ * reaches one. Without the PTY module the probe is unavailable, not failed.
  */
 import chalk from "chalk";
+import { readDenConfig, type DenConfig } from "../../shared/den-config.js";
+import { getStateDir } from "../../shared/paths.js";
+import { product } from "../../shared/product.js";
+import { listRecords } from "../../shared/agents/records.js";
 import { readBrand } from "../../shared/brand.js";
 import { hasEdgeBlock, readEdgeConfig } from "../../shared/edge/config.js";
 import { edgeTlsWarnings, tlsStrategyFor } from "../../shared/edge/tls.js";
@@ -15,7 +28,18 @@ import {
   readSecretsConfig,
   secretsStatus,
 } from "../../shared/secrets/index.js";
-import { strategyKinds } from "../../shared/strategies/registry.js";
+import {
+  DEN_PTY_ID,
+  SESSION_BACKEND_KIND,
+} from "../../shared/sessions/den-pty.js";
+import {
+  getStrategy,
+  strategyKinds,
+} from "../../shared/strategies/registry.js";
+import {
+  DEFAULT_RUNTIME_ID,
+  RUNTIME_KIND,
+} from "../../shared/agents/runtimes.js";
 
 export interface DoctorRow {
   kind: string;
@@ -80,6 +104,42 @@ const SELECTORS: Record<string, Selector> = {
       };
     }
   },
+  // Agents' terminals (AG-3a). Only den-pty exists, so it is the implicit
+  // choice; unavailable is never a problem (nothing needs a session until
+  // one is started, and `sessions start` says why).
+  [SESSION_BACKEND_KIND](env) {
+    const d = getStrategy(SESSION_BACKEND_KIND, DEN_PTY_ID)?.detect(env) ?? {
+      available: false,
+      reason: "not registered",
+    };
+    return {
+      kind: SESSION_BACKEND_KIND,
+      selected: DEN_PTY_ID,
+      implicit: true,
+      available: d.available,
+      reason: d.reason,
+      problem: false,
+      warnings: [],
+    };
+  },
+  // Agents' CLIs (AG-2a): the default runtime, chosen per persona or agent,
+  // so it is implicit and its absence is never a problem (`agents start`
+  // says why it can't run).
+  [RUNTIME_KIND](env) {
+    const d = getStrategy(RUNTIME_KIND, DEFAULT_RUNTIME_ID)?.detect(env) ?? {
+      available: false,
+      reason: "not registered",
+    };
+    return {
+      kind: RUNTIME_KIND,
+      selected: DEFAULT_RUNTIME_ID,
+      implicit: true,
+      available: d.available,
+      reason: d.reason,
+      problem: false,
+      warnings: [],
+    };
+  },
 };
 
 /**
@@ -124,8 +184,77 @@ export function formatDoctor(rows: DoctorRow[], title: string): string[] {
   return lines;
 }
 
-export function cmdDoctor(_args: string[]): number {
+/**
+ * Whether agents are configured here: an `agents:` block with anything in
+ * it (max_concurrent, persona_packs, an agent id), or an agent record.
+ */
+export function agentsConfigured(
+  config: DenConfig | null,
+  stateDir: string,
+): boolean {
+  const raw = config?.agents as unknown;
+  if (raw && typeof raw === "object" && Object.keys(raw).length) return true;
+  try {
+    return listRecords(stateDir).length > 0;
+  } catch {
+    return false;
+  }
+}
+
+/** Informational lines after the rows: never a failure. */
+export function doctorNotes(cli: string, configured: boolean): string[] {
+  return configured
+    ? [
+        "",
+        `  ℹ agents are configured or have run here: run \`${cli} doctor --probe\` to verify agent env isolation`,
+      ]
+    : [];
+}
+
+function readConfigOrNull(): DenConfig | null {
+  try {
+    return readDenConfig();
+  } catch {
+    return null;
+  }
+}
+
+export async function cmdDoctor(args: string[]): Promise<number> {
+  const probe = args.includes("--probe");
+  const unknown = args.filter((a) => a !== "--probe");
+  if (unknown.length) {
+    console.error(
+      `✗ doctor: unknown argument ${unknown[0]} (doctor [--probe])`,
+    );
+    return 2;
+  }
   const rows = doctorRows();
   for (const l of formatDoctor(rows, readBrand().name)) console.log(l);
-  return rows.some((r) => r.problem) ? 1 : 0;
+  const cli = product().cli;
+  if (!probe) {
+    for (const l of doctorNotes(
+      cli,
+      agentsConfigured(readConfigOrNull(), getStateDir()),
+    ))
+      console.log(l);
+    return rows.some((r) => r.problem) ? 1 : 0;
+  }
+  const { runEnvProbe, formatProbe } = await import("./env-probe.js");
+  const { resolveDeps, plainSessionEnv } =
+    await import("./sessions-command.js");
+  const d = resolveDeps({});
+  const results = await runEnvProbe({
+    dist: d.dist,
+    cli: d.cli,
+    env: d.env,
+    pty: d.pty,
+    connect: d.connect,
+    plainEnv: (caller) => plainSessionEnv(caller),
+  });
+  console.log("");
+  console.log(chalk.bold(`${readBrand().name} doctor: session env probe`));
+  console.log("");
+  for (const l of formatProbe(results)) console.log(l);
+  const found = results.some((r) => r.findings.length);
+  return rows.some((r) => r.problem) || found ? 1 : 0;
 }

package/src/ui/cli/env-probe.ts

@@ -0,0 +1,266 @@
+/**
+ * `<cli> doctor --probe` (AG spec §5a-env): check, through the real session
+ * host and backend, what environment a session actually gets. Opt-in: plain
+ * `doctor` never spawns anything.
+ *
+ * For a plain session (as `sessions start` builds it, no --keep-env) and
+ * for each available runtime's agent env (as `agents start` builds it, the
+ * runtime's launch env included, but running the probe instead of the
+ * runtime's CLI), it starts a short session running a tiny node script that
+ * prints each key name and one flag: whether the name or value is
+ * credential-shaped (secret-env.ts, with the redactor's patterns). Values
+ * never leave the probe process.
+ *
+ * A finding is any runtime's scrubEnv name, or any credential-shaped
+ * variable, in either env.
+ */
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import {
+  agentSessionEnv,
+  allScrubEnv,
+  getRuntime,
+  LaunchError,
+  runtimeIds,
+  type LaunchInput,
+  type Runtime,
+} from "../../shared/agents/runtimes.js";
+import { credentialPatternData } from "../../shared/secret-env.js";
+import type { HostClient } from "../../shared/sessions/client.js";
+import { matchesScrub } from "../../shared/sessions/env.js";
+import { sessionName } from "../../shared/sessions/names.js";
+import type { PtyLoad } from "../../shared/sessions/pty.js";
+
+const MARK = "DENPROBE";
+const PROBE_ID = "env-probe";
+/** How long one probe session gets to print and exit. */
+const PROBE_TIMEOUT_MS = 10_000;
+
+/** The probe: key names and a 0/1 flag per key, then an end mark. No values. */
+export function probeScript(): string {
+  const p = JSON.stringify(credentialPatternData());
+  return [
+    `const P = ${p};`,
+    `const re = (l) => l.map((r) => new RegExp(r.source, r.flags));`,
+    `const N = re(P.name), V = re(P.value);`,
+    `for (const k of Object.keys(process.env).sort()) {`,
+    `  const v = process.env[k] || "";`,
+    `  const c = N.some((r) => r.test(k)) || (v !== "" && V.some((r) => r.test(v)));`,
+    `  process.stdout.write("${MARK} " + k + " " + (c ? 1 : 0) + "\\n");`,
+    `}`,
+    `process.stdout.write("${MARK}-END\\n");`,
+  ].join("\n");
+}
+
+export interface ProbeKey {
+  name: string;
+  credentialShaped: boolean;
+}
+
+/** The probe's report from its output; null when it did not finish. */
+export function parseProbe(output: string): ProbeKey[] | null {
+  const keys: ProbeKey[] = [];
+  let ended = false;
+  for (const raw of output.split(/\r?\n/)) {
+    const line = raw.replace(/\r/g, "").trim();
+    if (line === `${MARK}-END`) ended = true;
+    const m = new RegExp(`^${MARK} ([A-Za-z_][A-Za-z0-9_]*) ([01])$`).exec(
+      line,
+    );
+    if (m) keys.push({ name: m[1], credentialShaped: m[2] === "1" });
+  }
+  return ended ? keys : null;
+}
+
+export interface ProbeFinding {
+  key: string;
+  why: string;
+}
+
+export interface ProbeResult {
+  /** "plain session", or "agent (<runtime>)". */
+  target: string;
+  /** False: not probed (the reason says why); never a failure. */
+  ran: boolean;
+  reason?: string;
+  keys?: number;
+  findings: ProbeFinding[];
+}
+
+export interface ProbeDeps {
+  dist: string;
+  cli: string;
+  env: NodeJS.ProcessEnv;
+  pty: () => PtyLoad;
+  connect: () => Promise<HostClient>;
+  /** A plain session's env, as `sessions start` builds it. */
+  plainEnv: (caller: NodeJS.ProcessEnv) => Record<string, string>;
+  /** An agent's env, as `agents start` builds it. */
+  agentEnv?: (
+    caller: NodeJS.ProcessEnv,
+    rt: Runtime,
+    launch: Record<string, string>,
+    agentId: string,
+  ) => Record<string, string>;
+  /** Runtimes to probe (default: every registered one that is available). */
+  runtimes?: () => Runtime[];
+}
+
+/** A launch input for the probe: nothing is written, nothing it names runs. */
+function probeInput(d: ProbeDeps, dir: string): LaunchInput {
+  return {
+    persona: {
+      id: PROBE_ID,
+      role: "",
+      prompt: "",
+      standing: false,
+      tools: [],
+      context: [],
+      argv: [PROBE_ID],
+      source: "doctor --probe",
+    },
+    workspace: { name: "doctor", dir },
+    agentId: PROBE_ID,
+    worktree: dir,
+    mcp: { name: d.cli, command: [d.cli], env: {}, scope: "doctor" },
+    // Never written: the probe uses only the launch's env.
+    filesDir: path.join(dir, PROBE_ID),
+    env: d.env,
+  };
+}
+
+function findings(keys: ProbeKey[]): ProbeFinding[] {
+  const scrub = allScrubEnv();
+  const out: ProbeFinding[] = [];
+  for (const k of keys) {
+    if (matchesScrub(k.name, scrub))
+      out.push({ key: k.name, why: "a runtime's scrubEnv name" });
+    else if (k.credentialShaped)
+      out.push({ key: k.name, why: "credential-shaped" });
+  }
+  return out;
+}
+
+/** Run the probe in one session with `env`; its report, or why not. */
+async function probeOnce(
+  d: ProbeDeps,
+  c: HostClient,
+  target: string,
+  slug: string,
+  env: Record<string, string>,
+  cwd: string,
+): Promise<ProbeResult> {
+  const info = await c.start({
+    name: sessionName(d.dist, "doctor", `${PROBE_ID}-${slug}`),
+    cwd,
+    argv: [process.execPath, "-e", probeScript()],
+    env,
+    cols: 200,
+    rows: 24,
+  });
+  try {
+    const deadline = Date.now() + PROBE_TIMEOUT_MS;
+    for (;;) {
+      const s = (await c.list()).find((x) => x.ref.id === info.ref.id);
+      if (!s || s.exited) break;
+      if (Date.now() > deadline) {
+        await c.kill(info.ref.id, "KILL").catch(() => undefined);
+        await new Promise((r) => setTimeout(r, 200));
+        break;
+      }
+      await new Promise((r) => setTimeout(r, 50));
+    }
+    const keys = parseProbe(
+      (await c.scrollback(info.ref.id, 1024 * 1024)).toString("utf-8"),
+    );
+    if (!keys)
+      return {
+        target,
+        ran: true,
+        findings: [{ key: "-", why: "the probe did not finish" }],
+      };
+    return { target, ran: true, keys: keys.length, findings: findings(keys) };
+  } finally {
+    await c.forget(info.ref.id).catch(() => undefined);
+  }
+}
+
+/** Probe a plain session and each available runtime's agent env. */
+export async function runEnvProbe(d: ProbeDeps): Promise<ProbeResult[]> {
+  const pty = d.pty();
+  if (!pty.available)
+    return [
+      {
+        target: "sessions",
+        ran: false,
+        reason: `den-pty is unavailable: ${pty.reason}`,
+        findings: [],
+      },
+    ];
+  const runtimes =
+    d.runtimes?.() ??
+    runtimeIds()
+      .map((id) => getRuntime(id))
+      .filter((rt): rt is Runtime => !!rt);
+  const agentEnv = d.agentEnv ?? agentSessionEnv;
+  // The probe writes nothing: its cwd is the temp dir, as it is.
+  const dir = fs.realpathSync(os.tmpdir());
+  const c = await d.connect();
+  try {
+    const out: ProbeResult[] = [
+      await probeOnce(d, c, "plain session", "plain", d.plainEnv(d.env), dir),
+    ];
+    for (const rt of runtimes) {
+      const target = `agent (${rt.id})`;
+      const det = rt.detect(d.env);
+      if (!det.available) {
+        out.push({
+          target,
+          ran: false,
+          reason: `${rt.id} is unavailable: ${det.why ?? "unknown"}`,
+          findings: [],
+        });
+        continue;
+      }
+      let launch: Record<string, string>;
+      try {
+        launch = rt.launch(probeInput(d, dir)).env;
+      } catch (e) {
+        if (!(e instanceof LaunchError)) throw e;
+        out.push({ target, ran: false, reason: e.message, findings: [] });
+        continue;
+      }
+      out.push(
+        await probeOnce(
+          d,
+          c,
+          target,
+          rt.id,
+          agentEnv(d.env, rt, launch, PROBE_ID),
+          dir,
+        ),
+      );
+    }
+    return out;
+  } finally {
+    c.close();
+  }
+}
+
+/** One line per result, one per finding; key names only. */
+export function formatProbe(results: ProbeResult[]): string[] {
+  const lines: string[] = [];
+  const width = Math.max(...results.map((r) => r.target.length));
+  for (const r of results) {
+    const t = r.target.padEnd(width);
+    if (!r.ran)
+      lines.push(`  ${t}  - not probed: ${r.reason ?? "unavailable"}`);
+    else if (!r.findings.length)
+      lines.push(`  ${t}  ✓ clean (${r.keys ?? 0} variables)`);
+    else
+      for (const f of r.findings)
+        lines.push(`  ${t}  ✗ ${f.key} reaches it (${f.why})`);
+  }
+  return lines;
+}

package/src/ui/cli/flag-parser.ts

@@ -77,10 +77,18 @@ const WORKSPACE_COMMANDS = new Set([
 
 /**
  * Commands that read `-w`/`--workspace` themselves, so it is left in their
- * args: `setup --plan -w a -w b` takes several, and `mcp --workspace <ws>`
- * scopes the MCP server (it never sets the CLI's workspace override).
+ * args: `setup --plan -w a -w b` takes several, `mcp --workspace <ws>`
+ * scopes the MCP server, and `sessions`/`agents` name a session's
+ * workspace. None of them sets the CLI's workspace override.
  */
-const OWN_WORKSPACE_FLAG_COMMANDS = new Set(["setup", "mcp"]);
+const OWN_WORKSPACE_FLAG_COMMANDS = new Set([
+  "setup",
+  "mcp",
+  // A session's workspace is part of its name (AG-3a); -w never sets the
+  // CLI's workspace override here.
+  "sessions",
+  "agents",
+]);
 
 /** Whether `-w <name>` on this command requires `<name>` to be active. */
 export function workspaceFlagRequiresActive(command: string): boolean {

package/src/ui/cli/index.ts

@@ -193,6 +193,8 @@ import { cleanupStaleTabs } from "../../shared/cli-tabs.js";
 import { cmdConfig } from "./config-command.js";
 import { cmdEdge } from "./edge-command.js";
 import { cmdDoctor } from "./doctor-command.js";
+import { cmdSessions, SESSIONS_HELP } from "./sessions-command.js";
+import { AGENTS_HELP, cmdAgents } from "./agents-command.js";
 import { cmdService } from "./service-command.js";
 import { cmdStack } from "./stack-command.js";
 import { cmdTheme } from "./theme-command.js";
@@ -459,10 +461,14 @@ const COMMAND_HELP: Record<string, { usage: string; lines: string[] }> = {
     ],
   },
   doctor: {
-    usage: "doctor",
+    usage: "doctor [--probe]",
     lines: [
       "Each strategy kind (secrets, tls): the one selected, whether it was implicit,",
       "and whether it can work here (a PATH check; nothing is run or prompted).",
+      "--probe: start a short probe session (through the session host) for a",
+      "plain session and each available runtime's agent env; key names only.",
+      "Exit 1 when a runtime's scrubEnv name or a credential-shaped variable",
+      "reaches one. Without the PTY module it says unavailable, not failed.",
     ],
   },
   plugin: {
@@ -508,6 +514,8 @@ const COMMAND_HELP: Record<string, { usage: string; lines: string[] }> = {
     usage: "menu",
     lines: ["Open the interactive menu (pillar/module/env picker)."],
   },
+  sessions: SESSIONS_HELP,
+  agents: AGENTS_HELP,
 };
 
 function resolveCliBaseApiUrl(explicitBaseApiUrl?: string): string | undefined {
@@ -558,6 +566,8 @@ const TELEMETRY_COMMANDS = new Set<string>([
   "apps",
   "applications",
   "mcp",
+  "sessions",
+  "agents",
   "service",
   "theme",
   "plugin",
@@ -581,6 +591,10 @@ const CONFIG_FREE_COMMANDS = new Set<string>([
   "local-dev",
   "view-results",
   "down",
+  // The session host and its clients read no org data, and stopping or
+  // listing a session is never stranded by a config that fails (AG-3a).
+  "sessions",
+  "agents",
 ]);
 
 function configCheckedCommand(command: string): boolean {
@@ -964,7 +978,7 @@ class DenCLI {
           break;
 
         case "doctor":
-          process.exitCode = cmdDoctor(args.slice(1));
+          process.exitCode = await cmdDoctor(args.slice(1));
           break;
 
         case "service":
@@ -989,6 +1003,14 @@ class DenCLI {
           cmdApps(args.slice(1));
           break;
 
+        case "sessions":
+          process.exitCode = await cmdSessions(args.slice(1));
+          break;
+
+        case "agents":
+          process.exitCode = await cmdAgents(args.slice(1));
+          break;
+
         case "mcp": {
           // Setup subcommands: register the server with agents.
           const { MCP_CONNECT_SUBCOMMANDS, runMcpConnect } =
@@ -4805,6 +4827,16 @@ class DenCLI {
     console.log(
       "  plugin list          Local and added plugins, checked (validate, add, update, remove)",
     );
+    console.log(
+      "  sessions start -w <ws> --name <n> -- <argv…>  A terminal that outlives the web server",
+    );
+    console.log(
+      "  sessions list|attach|kill   List, attach to (ctrl-] detaches) or stop sessions",
+    );
+    console.log("  agents list -w <ws>  The workspace's agents");
+    console.log(
+      "  agents start -w <ws> --persona <p>  Run a persona in the workspace (stop, resume, personas)",
+    );
     console.log();
     console.log(
       "  workspace list           List workspaces (active set + focus)",