@monster-orange/den 0.3.0 → 0.4.1

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

@@ -0,0 +1,294 @@
+/**
+ * `<cli> agents list|start|stop|resume|personas` (AG-2a, AG spec §5c):
+ * an agent is a persona and a workspace, run by a runtime in a session of
+ * the AG-3a host. This is the CLI's front: it parses the arguments and
+ * prints; what each operation does is agent-ops.ts, which the Workspaces
+ * page's routes (server/agent-routes.ts) call too.
+ *
+ *   start   resolves the persona (Den's default pack, then
+ *           agents.persona_packs) and the runtime, 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
+ *           agent record (<stateDir>/agents/<id>.json, 0600; no env, no argv).
+ *           The agent's env is an allowlist plus what its runtime declares,
+ *           less every runtime's scrubEnv (sessions/env.ts), never the
+ *           caller's whole environment; no --keep-env. A
+ *           session that exits non-zero in its first moments (exitWatchMs)
+ *           is reported with its last lines, exit 1.
+ *   list    the workspace's agents (sessions with an agent record), with
+ *           persona, runtime and model; a record whose session is gone is
+ *           listed as stopped or ended. A plain session is not an agent.
+ *   stop    ends its session (TERM) and marks the record stopped.
+ *   resume  only when its runtime declares resume and its session is not
+ *           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).
+ *
+ * Nothing here takes a grant: grants come from the org config only. The
+ * host enforces agents.max_concurrent on every start.
+ */
+import { DEFAULT_RUNTIME_ID } from "../../shared/agents/runtimes.js";
+import { HostError } from "../../shared/sessions/client.js";
+import {
+  AgentError,
+  listAgents,
+  listPersonas as personaList,
+  loadAgentWorkspaces,
+  resolveAgentsDeps,
+  resumeAgent,
+  startAgent,
+  stopAgent,
+  type AgentsDeps,
+  type AgentsResolved,
+  type EarlyExit,
+  type Started,
+} from "./agent-ops.js";
+import {
+  columns,
+  guarded,
+  noExtra,
+  parseArgs,
+  UsageError,
+  workspaceFlag,
+} from "./sessions-command.js";
+
+export {
+  agentMcp,
+  agentRows,
+  EXIT_WATCH_MS,
+  plainLines,
+  type AgentRow,
+  type AgentsDeps,
+} from "./agent-ops.js";
+
+export const AGENTS_HELP = {
+  usage: "agents <list|start|stop|resume|personas> ...",
+  lines: [
+    "Agents: a persona and a workspace, run by a runtime in a session that",
+    "outlives the web server (see `{cli} sessions`).",
+    "",
+    "{cli} agents list -w <ws> [--json]",
+    "{cli} agents start -w <ws> --persona <p> [--runtime <r>] [--model <m>] [--id <id>]",
+    "    runs in the workspace's dir as <dist>-<ws>:<id>; its MCP is pinned to <ws>",
+    "    (plus agents.<id>.grants); capped by agents.max_concurrent",
+    "{cli} agents stop <id> [-w <ws>]",
+    "{cli} agents resume <id> [-w <ws>]",
+    "    only when its runtime declares resume and its session has ended;",
+    "    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)",
+    "",
+    "Runtimes: den-claude (default; needs claude on PATH) and generic (the",
+    "persona's argv template). Attach with `{cli} sessions attach <ws>:<id>`.",
+    "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.",
+  ],
+};
+
+async function list(args: string[], d: AgentsResolved): Promise<number> {
+  const where = "agents list";
+  const p = parseArgs(where, args, { "--workspace": true, "--json": false });
+  noExtra(where, p);
+  const ws = workspaceFlag(where, p);
+  if (!ws) throw new UsageError(`${where} needs -w <workspace>`);
+  const rows = await listAgents(d, ws);
+  if (p.flags["--json"]) {
+    d.out(JSON.stringify(rows, null, 2));
+    return 0;
+  }
+  if (!rows.length) {
+    d.out(`no agents in ${ws}`);
+    return 0;
+  }
+  for (const l of columns([
+    [
+      "AGENT",
+      "PERSONA",
+      "RUNTIME",
+      "STATE",
+      "MODEL",
+      "PID",
+      "STARTED",
+      "SESSION",
+    ],
+    ...rows.map((r) => [
+      r.agent,
+      r.persona ?? "-",
+      r.runtime ?? "-",
+      r.state,
+      r.model ?? "-",
+      r.session && !r.session.exited ? String(r.session.pid) : "-",
+      r.session?.startedAt ?? "-",
+      r.session?.name ?? "-",
+    ]),
+  ]))
+    d.out(l);
+  return 0;
+}
+
+/** An early exit, as the terminal shows it: its code and last lines. */
+function printEarlyExit(d: AgentsResolved, id: string, e: EarlyExit): void {
+  const code = e.exitCode === undefined ? "" : ` (exit ${e.exitCode})`;
+  d.err(`✗ agent ${id} exited at once${code}`);
+  if (e.tail.length) {
+    d.err(`  its last ${e.tail.length === 1 ? "line" : "lines"}:`);
+    for (const l of e.tail) d.err(`  | ${l}`);
+  }
+  d.err(`  All of it: ${d.cli} sessions attach ${e.sessionName}`);
+}
+
+/** A start's or resume's warnings and outcome; its exit code. */
+function report(d: AgentsResolved, s: Started, line: string): number {
+  for (const w of s.warnings) d.err(w);
+  if (s.early) {
+    printEarlyExit(d, s.rec.id, s.early);
+    return 1;
+  }
+  d.out(line);
+  d.out(`  attach: ${d.cli} sessions attach ${s.rec.sessionName}`);
+  return 0;
+}
+
+/** A flag's string value, or undefined. */
+function str(
+  p: ReturnType<typeof parseArgs>,
+  flag: string,
+): string | undefined {
+  const v = p.flags[flag];
+  return typeof v === "string" ? v : undefined;
+}
+
+async function start(args: string[], d: AgentsResolved): Promise<number> {
+  const where = "agents start";
+  const p = parseArgs(where, args, {
+    "--workspace": true,
+    "--persona": true,
+    "--runtime": true,
+    "--model": true,
+    "--id": true,
+  });
+  noExtra(where, p);
+  const ws = workspaceFlag(where, p);
+  if (!ws) throw new UsageError(`${where} needs -w <workspace>`);
+  const persona = str(p, "--persona");
+  if (!persona) throw new UsageError(`${where} needs --persona <p>`);
+  const s = await startAgent(d, {
+    workspace: ws,
+    persona,
+    runtime: str(p, "--runtime"),
+    model: str(p, "--model"),
+    id: str(p, "--id"),
+  });
+  return report(
+    d,
+    s,
+    `started agent ${s.rec.id} (${s.rec.persona}, ${s.rec.runtime}) as ${s.rec.sessionName} in ${s.rec.cwd}`,
+  );
+}
+
+/** `<id> [-w <ws>]`. */
+function idAndWorkspace(
+  where: string,
+  args: string[],
+): { id: string; ws?: string } {
+  const p = parseArgs(where, args, { "--workspace": true });
+  noExtra(where, p, 1);
+  const id = p.positional[0];
+  if (!id) throw new UsageError(`${where} needs <id>`);
+  return { id, ws: workspaceFlag(where, p) };
+}
+
+async function stop(args: string[], d: AgentsResolved): Promise<number> {
+  const { id, ws } = idAndWorkspace("agents stop", args);
+  const { rec, session: s } = await stopAgent(d, id, ws);
+  d.out(
+    s
+      ? `stopped agent ${rec.id} (sent TERM to ${s.name}, pid ${s.pid})`
+      : `agent ${rec.id} was not running; marked stopped`,
+  );
+  return 0;
+}
+
+async function resume(args: string[], d: AgentsResolved): Promise<number> {
+  const { id, ws } = idAndWorkspace("agents resume", args);
+  const s = await resumeAgent(d, id, ws);
+  if (s.fresh)
+    d.out(
+      `agent ${s.rec.id}: starting fresh: it was never prompted, so there is no conversation to resume`,
+    );
+  return report(
+    d,
+    s,
+    `${s.fresh ? "started" : "resumed"} agent ${s.rec.id} as ${s.rec.sessionName} in ${s.rec.cwd}`,
+  );
+}
+
+async function listPersonas(
+  args: string[],
+  d: AgentsResolved,
+): Promise<number> {
+  const where = "agents personas";
+  const p = parseArgs(where, args, { "--json": false });
+  noExtra(where, p);
+  const all = personaList(d);
+  if (p.flags["--json"]) {
+    d.out(JSON.stringify(all, null, 2));
+    return 0;
+  }
+  for (const l of columns([
+    ["PERSONA", "STANDING", "RUNTIME", "MODEL", "ROLE"],
+    ...all.map((x) => [
+      x.id,
+      x.standing ? "yes" : "-",
+      x.runtime ?? DEFAULT_RUNTIME_ID,
+      x.model ?? "-",
+      x.role,
+    ]),
+  ]))
+    d.out(l);
+  return 0;
+}
+
+/** `<cli> agents ...`; returns the exit code. */
+export async function cmdAgents(
+  args: string[],
+  deps: AgentsDeps = {},
+): Promise<number> {
+  const d = resolveAgentsDeps(deps);
+  const sub =
+    args[0] === undefined || args[0].startsWith("-") ? "list" : args[0];
+  const rest = sub === args[0] ? args.slice(1) : args;
+  return guarded(d, AGENTS_HELP, "agents", async () => {
+    try {
+      switch (sub) {
+        case "list":
+          return await list(rest, d);
+        case "start":
+          await loadAgentWorkspaces(deps);
+          return await start(rest, d);
+        case "stop":
+          return await stop(rest, d);
+        case "resume":
+          await loadAgentWorkspaces(deps);
+          return await resume(rest, d);
+        case "personas":
+          return await listPersonas(rest, d);
+        default:
+          throw new UsageError(`unknown agents command "${sub}"`);
+      }
+    } catch (e) {
+      if (e instanceof AgentError) {
+        if (e.usage) throw new UsageError(e.message);
+        d.err(`✗ ${e.message}`);
+        for (const h of e.hints) d.err(`  ${h}`);
+        return 1;
+      }
+      if (e instanceof HostError) {
+        d.err(`✗ ${e.message}`);
+        return 1;
+      }
+      throw e;
+    }
+  });
+}

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;
 }