@monster-orange/den 0.4.7 → 0.4.9

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

@@ -20,10 +20,17 @@
  *           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;
+ *   resume  only when its runtime declares resume, its record holds the
+ *           runtime's resume token, and its session is not running: a new
+ *           session, in the same cwd and workspace with the grants it had,
+ *           continuing the last conversation (den-claude: --resume <token>);
  *           when that session was never prompted, a fresh start under the
  *           same conversation id (there is nothing to continue).
+ *           --all-interrupted (AG-14.3): every agent interrupted when Den or
+ *           the machine restarted that can resume.
+ *   rm      (AG-14.1b) forgets a stopped, interrupted or exited agent (never
+ *           a running one); --stopped forgets every one of -w <ws> (or of
+ *           every workspace). The runtime's own history stays.
  *   doctor  (AG-0.3, AG-0.5) each runtime of the catalog, installed
  *           first: its status, the CLI it runs and where that came from
  *           (workspace or user.yml setting, login shell, PATH, install
@@ -36,6 +43,14 @@
  *   handback-check <file|->  (den#5) the hand-back check (handback.ts) on a
  *           file or stdin: each problem on its own line, exit 1 when there
  *           is one, 0 when the hand-back is complete and plain.
+ *   relaunch (den#4, session rotation) once an agent's session rotated
+ *           (after agents.rotate.after_compactions compactions, or its pull
+ *           request merged) and its handoff.md passes the check: a fresh
+ *           conversation, same persona, workspace, folder and grants, whose
+ *           first prompt is the handoff. `resume` on a rotated agent
+ *           refuses (exit 1) and names relaunch.
+ *   handoff-check <id|file|->  (den#4) the handoff check (handoff.ts), like
+ *           handback-check.
  *
  * Nothing here takes a grant: grants come from the org config only. The
  * host enforces agents.max_concurrent on every start, counting agents only.
@@ -45,14 +60,25 @@ 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 { checkHandback } from "../../shared/agents/handback.js";
+import { checkHandoff } from "../../shared/agents/handoff.js";
+import { handoffFile, reasonText } from "../../shared/agents/rotation.js";
+import {
+  agentFilesDir,
+  listRecords,
+  readRecord,
+} from "../../shared/agents/records.js";
 import {
   AgentError,
   listAgents,
   listPersonas as personaList,
   listRuntimes,
   loadAgentWorkspaces,
+  relaunchAgent,
+  removeAgent,
+  removeStopped,
   resolveAgentsDeps,
   resumeAgent,
+  resumeInterrupted,
   startAgent,
   stopAgent,
   type AgentsDeps,
@@ -80,19 +106,37 @@ export {
 } from "./agent-ops.js";
 
 export const AGENTS_HELP = {
-  usage: "agents <list|start|stop|resume|personas|doctor|handback-check> ...",
+  usage:
+    "agents <list|start|stop|resume|relaunch|rm|personas|doctor|handback-check|handoff-check> ...",
   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 list -w <ws> [--stopped] [--json]",
+    "    --stopped: only the stopped, interrupted and exited ones",
     "{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 stop <id> [-w <ws>] [--no-wait]",
+    "    waits up to 5 s for the session to end (else: still stopping, exit 1);",
+    "    --no-wait: return once TERM is sent",
     "{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 resume --all-interrupted [-w <ws>]",
+    "    the same conversation, persona, workspace and folder, when its runtime",
+    "    can resume one and its session has ended; with nothing to resume yet,",
+    "    it starts fresh under the same conversation id. --all-interrupted: every",
+    "    agent interrupted when Den or the machine restarted. A rotated agent",
+    "    is not resumed: relaunch it",
+    "{cli} agents relaunch <id> [-w <ws>]",
+    "    session rotation: once a session ended after agents.rotate.after_compactions",
+    "    compactions (default 3) or its pull request merged, and its handoff.md",
+    "    passes the check, a fresh conversation (same persona, workspace, folder,",
+    "    grants) whose first prompt is the handoff",
+    "{cli} agents rm <id> [-w <ws>]",
+    "{cli} agents rm --stopped [-w <ws>]",
+    "    forget a stopped, interrupted or exited agent (never a running one);",
+    "    the runtime keeps its own history. agents.remove_stopped_after in",
+    "    user.yml (never, 1d, 7d) forgets stopped ones on its own",
     "{cli} agents personas [--json]",
     "    Den's default pack, then agents.persona_packs (a later pack wins by id)",
     "{cli} agents doctor [-w <ws>] [--json]",
@@ -103,6 +147,10 @@ export const AGENTS_HELP = {
     "    checks a hand-back to a person: URL, machine, branch, what changed, what",
     "    to click and decisions are all there, every ID is explained, and each",
     "    decision is a numbered yes/no question; exit 1 with what to fix",
+    "{cli} agents handoff-check <id|file|-> [--json]",
+    "    checks an agent's handoff.md (or a file, or stdin): Objective, State, Open items, How to QA and Next step",
+    "    are all there and filled in, and every ID is explained; exit 1 with what",
+    "    to fix",
     "",
     "Runtimes: den-claude (default; Claude Code's claude), codex (OpenAI's Codex",
     "CLI), gemini (Google's Gemini CLI), grok (xAI's Grok Build), and generic (the",
@@ -120,17 +168,27 @@ export const AGENTS_HELP = {
 
 async function list(args: string[], d: AgentsResolved): Promise<number> {
   const where = "agents list";
-  const p = parseArgs(where, args, { "--workspace": true, "--json": false });
+  const p = parseArgs(where, args, {
+    "--workspace": true,
+    "--json": false,
+    "--stopped": false,
+  });
   noExtra(where, p);
   const ws = workspaceFlag(where, p);
   if (!ws) throw new UsageError(`${where} needs -w <workspace>`);
-  const rows = await listAgents(d, ws);
+  const rows = await listAgents(d, ws, {
+    stopped: p.flags["--stopped"] === true,
+  });
   if (p.flags["--json"]) {
     d.out(JSON.stringify(rows, null, 2));
     return 0;
   }
   if (!rows.length) {
-    d.out(`no agents in ${ws}`);
+    d.out(
+      p.flags["--stopped"]
+        ? `no stopped agents in ${ws}`
+        : `no agents in ${ws}`,
+    );
     return 0;
   }
   for (const l of columns([
@@ -148,7 +206,9 @@ async function list(args: string[], d: AgentsResolved): Promise<number> {
       r.agent,
       r.persona ?? "-",
       r.runtime ?? "-",
-      r.state,
+      r.rotation?.due
+        ? `${r.state}, ${r.rotation.ready ? "ready to relaunch" : "handoff due"} (${reasonText(r.rotation.due, r.rotation.compactions)})`
+        : r.state,
       r.model ?? "-",
       r.session && !r.session.exited ? String(r.session.pid) : "-",
       r.session?.startedAt ?? "-",
@@ -232,22 +292,40 @@ function idAndWorkspace(
 }
 
 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);
+  // --no-wait: return once TERM is sent (before 0.4.8, always).
+  const wait = !args.includes("--no-wait");
+  const { id, ws } = idAndWorkspace(
+    "agents stop",
+    args.filter((a) => a !== "--no-wait"),
+  );
+  const {
+    rec,
+    session: s,
+    stillStopping,
+  } = await stopAgent(d, id, ws, {
+    wait,
+  });
+  if (stillStopping) {
+    d.err(
+      `${rec.id} is still stopping (sent TERM to ${s!.name}, pid ${s!.pid}; not ended after ${d.stopWaitMs / 1000} s)`,
+    );
+    return 1;
+  }
   d.out(
     s
-      ? `stopped agent ${rec.id} (sent TERM to ${s.name}, pid ${s.pid})`
+      ? `stopped agent ${rec.id} (sent TERM to ${s.name}, pid ${s.pid}${wait && d.stopWaitMs > 0 ? "; it has ended" : ""})`
       : `agent ${rec.id} was not running; marked stopped`,
   );
   return 0;
 }
 
 async function resume(args: string[], d: AgentsResolved): Promise<number> {
+  if (args.includes("--all-interrupted")) return resumeAll(args, d);
   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`,
+      `agent ${s.rec.id}: nothing to resume yet; started fresh (same conversation id, folder and scope)`,
     );
   return report(
     d,
@@ -256,6 +334,69 @@ async function resume(args: string[], d: AgentsResolved): Promise<number> {
   );
 }
 
+/** `agents relaunch <id> [-w <ws>]` (den#4). */
+async function relaunch(args: string[], d: AgentsResolved): Promise<number> {
+  const { id, ws } = idAndWorkspace("agents relaunch", args);
+  const s = await relaunchAgent(d, id, ws);
+  return report(
+    d,
+    s,
+    `relaunched agent ${s.rec.id} from its handoff (the last session ended after ${s.why}) as ${s.rec.sessionName} in ${s.rec.cwd}`,
+  );
+}
+
+/** `agents resume --all-interrupted [-w <ws>]` (AG-14.3). */
+async function resumeAll(args: string[], d: AgentsResolved): Promise<number> {
+  const where = "agents resume";
+  const p = parseArgs(where, args, {
+    "--workspace": true,
+    "--all-interrupted": false,
+  });
+  noExtra(where, p);
+  const ws = workspaceFlag(where, p);
+  const r = await resumeInterrupted(d, ws ? [ws] : undefined);
+  if (!r.resumed.length && !r.failed.length) {
+    d.out(`no interrupted agents${ws ? ` in ${ws}` : ""}`);
+    return 0;
+  }
+  for (const x of r.resumed)
+    d.out(
+      `${x.fresh ? "started" : "resumed"} agent ${x.rec.id} as ${x.rec.sessionName} in ${x.rec.cwd}`,
+    );
+  for (const f of r.failed) d.err(`✗ agent ${f.agent}: ${f.why}`);
+  return r.failed.length ? 1 : 0;
+}
+
+/** `agents rm <id> [-w <ws>]`, `agents rm --stopped [-w <ws>]` (AG-14.1b). */
+async function rm(args: string[], d: AgentsResolved): Promise<number> {
+  const where = "agents rm";
+  const p = parseArgs(where, args, { "--workspace": true, "--stopped": false });
+  noExtra(where, p, 1);
+  const ws = workspaceFlag(where, p);
+  const id = p.positional[0];
+  if (p.flags["--stopped"]) {
+    if (id) throw new UsageError(`${where}: give <id> or --stopped, not both`);
+    if (ws && !d.workspaceExists(ws))
+      throw new UsageError(`${where}: workspace "${ws}" does not exist`);
+    const wss = ws
+      ? [ws]
+      : [...new Set(listRecords(d.stateDir()).map((r) => r.workspace))];
+    const gone = await removeStopped(d, wss);
+    d.out(
+      gone.length
+        ? `removed ${gone.length} stopped ${gone.length === 1 ? "agent" : "agents"}: ${gone.map((g) => g.agent).join(", ")}`
+        : `no stopped agents${ws ? ` in ${ws}` : ""}`,
+    );
+    return 0;
+  }
+  if (!id) throw new UsageError(`${where} needs <id> or --stopped`);
+  const [gone] = await removeAgent(d, id, ws);
+  d.out(
+    `removed agent ${gone?.agent ?? id}; its conversation stays in the runtime's own history`,
+  );
+  return 0;
+}
+
 async function listPersonas(
   args: string[],
   d: AgentsResolved,
@@ -296,17 +437,37 @@ async function readFileOrStdin(src: string): Promise<string> {
   return text;
 }
 
-/** `agents handback-check <file|-> [--json]`. */
+/** `agents handback-check <file|-> [--json]`, or handoff-check (den#4). */
 async function handbackCheck(
   args: string[],
   d: AgentsResolved,
   deps: AgentsDoctorDeps,
+  kind: "handback" | "handoff" = "handback",
 ): Promise<number> {
-  const where = "agents handback-check";
+  const where = `agents ${kind}-check`;
   const p = parseArgs(where, args, { "--json": false });
   if (p.positional.length !== 1 || p.rest)
-    throw new UsageError(`${where} takes one file, or - for stdin`);
-  const src = p.positional[0];
+    throw new UsageError(
+      kind === "handoff"
+        ? `${where} takes an agent id, a file, or - for stdin`
+        : `${where} takes one file, or - for stdin`,
+    );
+  let src = p.positional[0];
+  // handoff-check <id>: that agent's handoff.md, when no such file is here.
+  if (
+    kind === "handoff" &&
+    src !== "-" &&
+    !fs.existsSync(src) &&
+    /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(src) &&
+    readRecord(d.stateDir(), src)
+  ) {
+    const file = handoffFile(agentFilesDir(d.stateDir(), src));
+    if (!fs.existsSync(file)) {
+      d.err(`✗ ${where}: no handoff.md yet for agent ${src} (${file})`);
+      return 1;
+    }
+    src = file;
+  }
   let text: string;
   try {
     text = await (deps.readHandback ?? readFileOrStdin)(src);
@@ -316,11 +477,12 @@ async function handbackCheck(
     );
     return 1;
   }
-  const r = checkHandback(text);
+  const r = kind === "handoff" ? checkHandoff(text) : checkHandback(text);
+  const what = kind === "handoff" ? "handoff" : "hand-back";
   if (p.flags["--json"]) d.out(JSON.stringify(r, null, 2));
-  else if (r.ok) d.out("✓ the hand-back is complete and plain");
+  else if (r.ok) d.out(`✓ the ${what} is complete and plain`);
   else {
-    d.out("✗ the hand-back is not ready:");
+    d.out(`✗ the ${what} is not ready:`);
     for (const l of r.problems) d.out(`  - ${l}`);
   }
   return r.ok ? 0 : 1;
@@ -441,6 +603,12 @@ export async function cmdAgents(
         case "resume":
           await loadAgentWorkspaces(deps);
           return await resume(rest, d);
+        case "relaunch":
+          await loadAgentWorkspaces(deps);
+          return await relaunch(rest, d);
+        case "rm":
+          await loadAgentWorkspaces(deps);
+          return await rm(rest, d);
         case "personas":
           return await listPersonas(rest, d);
         case "doctor":
@@ -449,6 +617,8 @@ export async function cmdAgents(
           return await doctor(rest, d, deps);
         case "handback-check":
           return await handbackCheck(rest, d, deps);
+        case "handoff-check":
+          return await handbackCheck(rest, d, deps, "handoff");
         default:
           throw new UsageError(`unknown agents command "${sub}"`);
       }

package/src/ui/cli/index.ts

@@ -196,6 +196,7 @@ 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 { USAGE_HELP, cmdUsage } from "./usage-command.js";
 import { cmdService } from "./service-command.js";
 import { cmdStack } from "./stack-command.js";
 import { cmdTheme } from "./theme-command.js";
@@ -536,6 +537,7 @@ const COMMAND_HELP: Record<string, { usage: string; lines: string[] }> = {
   },
   sessions: SESSIONS_HELP,
   agents: AGENTS_HELP,
+  usage: USAGE_HELP,
 };
 
 function resolveCliBaseApiUrl(explicitBaseApiUrl?: string): string | undefined {
@@ -588,6 +590,7 @@ const TELEMETRY_COMMANDS = new Set<string>([
   "mcp",
   "sessions",
   "agents",
+  "usage",
   "service",
   "theme",
   "plugin",
@@ -616,6 +619,8 @@ const CONFIG_FREE_COMMANDS = new Set<string>([
   // listing a session is never stranded by a config that fails (AG-3a).
   "sessions",
   "agents",
+  // den#6: reads local transcripts and agent records, no org data.
+  "usage",
 ]);
 
 function configCheckedCommand(command: string): boolean {
@@ -1082,6 +1087,10 @@ class DenCLI {
           process.exitCode = await cmdAgents(args.slice(1));
           break;
 
+        case "usage":
+          process.exitCode = await cmdUsage(args.slice(1));
+          break;
+
         case "mcp": {
           // Setup subcommands: register the server with agents.
           const { MCP_CONNECT_SUBCOMMANDS, runMcpConnect } =
@@ -5298,7 +5307,10 @@ class DenCLI {
     );
     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)",
+      "  agents start -w <ws> --persona <p>  Run a persona in the workspace (stop, resume, rm, personas)",
+    );
+    console.log(
+      "  usage agents|report      Agents' tokens and outcomes, from local transcripts (never sent)",
     );
     console.log();
     console.log(