@monster-orange/den 0.4.7 → 0.4.8

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
@@ -45,14 +52,18 @@ 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 { listRecords } from "../../shared/agents/records.js";
 import {
   AgentError,
   listAgents,
   listPersonas as personaList,
   listRuntimes,
   loadAgentWorkspaces,
+  removeAgent,
+  removeStopped,
   resolveAgentsDeps,
   resumeAgent,
+  resumeInterrupted,
   startAgent,
   stopAgent,
   type AgentsDeps,
@@ -80,19 +91,31 @@ 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|rm|personas|doctor|handback-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",
+    "{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]",
@@ -120,17 +143,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([
@@ -232,22 +265,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 +307,58 @@ async function resume(args: string[], d: AgentsResolved): Promise<number> {
   );
 }
 
+/** `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,
@@ -441,6 +544,9 @@ export async function cmdAgents(
         case "resume":
           await loadAgentWorkspaces(deps);
           return await resume(rest, d);
+        case "rm":
+          await loadAgentWorkspaces(deps);
+          return await rm(rest, d);
         case "personas":
           return await listPersonas(rest, d);
         case "doctor":

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(

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

@@ -0,0 +1,256 @@
+/**
+ * `<cli> usage` (den#6): how agents spend tokens and time, read from the
+ * runtimes' own transcripts on this machine (usage sources, plugin kind
+ * `usage`). Nothing is sent anywhere: it reads local files and writes
+ * local files.
+ *
+ *   agents [-w <ws>] [--json]    each agent's tokens and outcome (PR opened
+ *                                or merged, tests green, wall-clock), joined
+ *                                on its record's resumeToken, and kept in its
+ *                                record; the share attributed
+ *   report [--days N] [--json]   the week's numbers (default 7 days), written
+ *                                to <state dir>/usage/<date>.{json,md} and
+ *                                compared with the last report there
+ */
+import * as fs from "fs";
+import * as path from "path";
+import {
+  listRecords,
+  readRecord,
+  writeRecord,
+} from "../../shared/agents/records.js";
+import { getStateDir } from "../../shared/paths.js";
+import { product } from "../../shared/product.js";
+import {
+  agentUsage,
+  attributedPct,
+  renderReport,
+  weeklyMetrics,
+  type AgentUsageRow,
+  type UsageMetrics,
+} from "../../shared/usage/report.js";
+import { usageSources } from "../../shared/usage/sources.js";
+import type { TranscriptStats } from "../../shared/usage/transcript.js";
+import {
+  columns,
+  parseArgs,
+  noExtra,
+  UsageError,
+  workspaceFlag,
+} from "./sessions-command.js";
+
+export const USAGE_HELP = {
+  usage: "usage <agents|report> ...",
+  lines: [
+    "How agents spend tokens and time, from the runtimes' own transcripts on",
+    "this machine (Claude Code's: ~/.claude/projects). Read locally; nothing",
+    "is ever sent anywhere.",
+    "",
+    "{cli} usage agents [-w <ws>] [--json]",
+    "    each agent's tokens and outcome (pull request opened or merged, tests",
+    "    green, wall-clock), joined on its conversation id, and saved in its",
+    "    record; then the share of agents with both",
+    "{cli} usage report [--days <n>] [--json]",
+    "    the last n days (default 7): tokens, context re-reads, polling, denials,",
+    "    tool errors, corrections, subagents on Opus; written to",
+    "    <state dir>/usage/<date>.json and .md, compared with the last report",
+  ],
+};
+
+export interface UsageDeps {
+  stateDir?: () => string;
+  env?: NodeJS.ProcessEnv;
+  now?: () => Date;
+  out?: (line: string) => void;
+  err?: (line: string) => void;
+  cli?: string;
+}
+
+function resolve(d: UsageDeps) {
+  return {
+    stateDir: d.stateDir ?? (() => getStateDir()),
+    env: d.env ?? process.env,
+    now: d.now ?? (() => new Date()),
+    out: d.out ?? ((l: string) => console.log(l)),
+    err: d.err ?? ((l: string) => console.error(l)),
+    cli: d.cli ?? product().cli,
+  };
+}
+
+const k = (n: number) =>
+  n >= 1e9
+    ? `${(n / 1e9).toFixed(1)}B`
+    : n >= 1e6
+      ? `${(n / 1e6).toFixed(1)}M`
+      : n >= 1e3
+        ? `${Math.round(n / 1e3)}k`
+        : String(n);
+const mins = (ms?: number) =>
+  ms === undefined
+    ? "-"
+    : ms < 3_600_000
+      ? `${Math.round(ms / 60_000)}m`
+      : `${(ms / 3_600_000).toFixed(1)}h`;
+
+/** Save each attributed row's usage and outcome in its agent record. */
+function save(stateDir: string, rows: readonly AgentUsageRow[]): void {
+  for (const r of rows) {
+    if (!r.usage) continue;
+    const rec = readRecord(stateDir, r.agent);
+    if (!rec) continue;
+    writeRecord(stateDir, {
+      ...rec,
+      usage: r.usage,
+      ...(r.outcome ? { outcome: r.outcome } : {}),
+    });
+  }
+}
+
+async function agents(
+  args: string[],
+  d: ReturnType<typeof resolve>,
+): Promise<number> {
+  const where = "usage agents";
+  const p = parseArgs(where, args, { "--workspace": true, "--json": false });
+  noExtra(where, p);
+  const ws = workspaceFlag(where, p);
+  const recs = listRecords(d.stateDir()).filter(
+    (r) => !ws || r.workspace === ws,
+  );
+  const rows = await agentUsage(recs, { env: d.env });
+  save(d.stateDir(), rows);
+  const pct = attributedPct(rows);
+  if (p.flags["--json"]) {
+    d.out(JSON.stringify({ agents: rows, attributedPct: pct }, null, 2));
+    return 0;
+  }
+  if (!rows.length) {
+    d.out(`no agents${ws ? ` in ${ws}` : ""}`);
+    return 0;
+  }
+  for (const l of columns([
+    [
+      "AGENT",
+      "WORKSPACE",
+      "CALLS",
+      "OUTPUT",
+      "CACHE READ",
+      "WALL",
+      "TESTS",
+      "PR",
+    ],
+    ...rows.map((r) => [
+      r.agent,
+      r.workspace,
+      r.usage ? String(r.usage.calls) : "-",
+      r.usage ? k(r.usage.output) : "-",
+      r.usage ? k(r.usage.cacheRead) : "-",
+      mins(r.outcome?.wallClockMs),
+      r.outcome?.testsGreen === undefined
+        ? "-"
+        : r.outcome.testsGreen
+          ? "green"
+          : "red",
+      r.outcome?.prOpened
+        ? `${r.outcome.prOpened}${r.outcome.prMerged ? " (merged)" : ""}`
+        : "-",
+    ]),
+  ]))
+    d.out(l);
+  for (const r of rows) if (r.why) d.out(`  ${r.agent}: ${r.why}`);
+  d.out("");
+  d.out(
+    `${pct}% of agents have their tokens and outcome (${rows.filter((r) => r.attributed).length} of ${rows.length}). Read locally; nothing was sent.`,
+  );
+  return 0;
+}
+
+/** The newest report in `dir` dated before `date`, if any. */
+function previous(
+  dir: string,
+  date: string,
+): { date: string; metrics: Partial<UsageMetrics> } | undefined {
+  let names: string[];
+  try {
+    names = fs.readdirSync(dir);
+  } catch {
+    return undefined;
+  }
+  const older = names
+    .filter((n) => /^\d{4}-\d{2}-\d{2}\.json$/.test(n) && n < `${date}.json`)
+    .sort();
+  const last = older[older.length - 1];
+  if (!last) return undefined;
+  try {
+    return {
+      date: last.slice(0, -5),
+      metrics: JSON.parse(
+        fs.readFileSync(path.join(dir, last), "utf-8"),
+      ) as Partial<UsageMetrics>,
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+async function report(
+  args: string[],
+  d: ReturnType<typeof resolve>,
+): Promise<number> {
+  const where = "usage report";
+  const p = parseArgs(where, args, { "--days": true, "--json": false });
+  noExtra(where, p);
+  const days = p.flags["--days"] === undefined ? 7 : Number(p.flags["--days"]);
+  if (!Number.isFinite(days) || days <= 0 || days > 366)
+    throw new UsageError(`${where}: --days must be a number of days, 1 to 366`);
+  const now = d.now();
+  const since = now.getTime() - days * 86_400_000;
+  const stats: TranscriptStats[] = [];
+  for (const src of usageSources())
+    for (const f of src.files(since, d.env))
+      stats.push(await src.mine(f, { since }));
+  const rows = await agentUsage(listRecords(d.stateDir()), { env: d.env });
+  save(d.stateDir(), rows);
+  const m = weeklyMetrics(stats, rows);
+  const date = now.toISOString().slice(0, 10);
+  const dir = path.join(d.stateDir(), "usage");
+  const prev = previous(dir, date);
+  const md = renderReport(m, date, prev);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  fs.writeFileSync(
+    path.join(dir, `${date}.json`),
+    JSON.stringify(m, null, 1) + "\n",
+    { mode: 0o600 },
+  );
+  fs.writeFileSync(path.join(dir, `${date}.md`), md, { mode: 0o600 });
+  if (p.flags["--json"]) d.out(JSON.stringify(m, null, 2));
+  else {
+    for (const l of md.trimEnd().split("\n")) d.out(l);
+    d.out("");
+    d.out(
+      `Written to ${path.join(dir, `${date}.md`)} (${stats.length} transcripts, ${days} days).`,
+    );
+  }
+  return 0;
+}
+
+/** `<cli> usage ...`; returns the exit code. */
+export async function cmdUsage(
+  args: string[],
+  deps: UsageDeps = {},
+): Promise<number> {
+  const d = resolve(deps);
+  const sub = args[0] ?? "agents";
+  try {
+    if (sub === "agents") return await agents(args.slice(1), d);
+    if (sub === "report") return await report(args.slice(1), d);
+    throw new UsageError(`unknown usage command "${sub}"`);
+  } catch (e) {
+    if (e instanceof UsageError) {
+      d.err(`✗ ${e.message}`);
+      d.err(`Usage: ${d.cli} ${USAGE_HELP.usage}`);
+      return 2;
+    }
+    throw e;
+  }
+}

package/src/ui/mcp/api.ts

@@ -140,6 +140,14 @@ const ACTION_ROUTES: Record<string, string> = {
   "/api/workspace/sync": "POST",
 };
 
+/** Action routes with a parameter: an agent's resume (MCP agent_resume). */
+const ACTION_ROUTE_PATTERNS: { re: RegExp; method: string }[] = [
+  {
+    re: /^\/api\/workspaces\/[A-Za-z0-9._-]{1,64}\/agents\/[A-Za-z0-9._-]{1,64}\/resume$/,
+    method: "POST",
+  },
+];
+
 /**
  * Throws a Refusal unless (method, path) is an allowed route. Never reached:
  * sudo-password, aws/login, terminal/open, editor/open, workspace/exec,
@@ -155,7 +163,8 @@ export function assertAllowedRequest(
     (READ_ROUTES.has(path) &&
       (method === "GET" ||
         (method === "POST" && path === "/api/manifest/validate"))) ||
-    ACTION_ROUTES[path] === method;
+    ACTION_ROUTES[path] === method ||
+    ACTION_ROUTE_PATTERNS.some((r) => r.method === method && r.re.test(path));
   if (!ok) throw new Refusal(`${method} ${path} is not exposed to agents.`);
   if (path === "/api/service/exec") {
     const cmd = String(query.cmd ?? "");

package/src/ui/mcp/server.ts

@@ -179,6 +179,32 @@ export const MCP_USAGE = (cli: string): string =>
     `Register it with your agents: ${cli} mcp clients, then ${cli} mcp connect <client> (or --all).`,
   ].join("\n");
 
+/**
+ * The first argument `<cli> mcp` doesn't take (after the scope flags), or
+ * null. It takes --port <n> (or --port=<n>), --list, and --call <tool>
+ * ['<json>']; anything else fails closed (exit 2), never ignored.
+ */
+export function unknownMcpArg(argv: readonly string[]): string | null {
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--list") continue;
+    if (a === "--port") {
+      i++;
+      continue;
+    }
+    if (a.startsWith("--port=")) continue;
+    if (a === "--call") {
+      // The tool, then its JSON arguments when they aren't a flag.
+      i++;
+      const next = argv[i + 1];
+      if (next !== undefined && !next.startsWith("--")) i++;
+      continue;
+    }
+    return a;
+  }
+  return null;
+}
+
 /** A one-shot invocation: `--list`, or `--call <tool> [json]`. */
 export type OneShot =
   | { kind: "list" }
@@ -351,6 +377,14 @@ export async function runMcp(rawArgv: string[]): Promise<void> {
     process.exitCode = 2;
     return;
   }
+  const unknown = unknownMcpArg(argv);
+  if (unknown !== null) {
+    process.stderr.write(
+      `${cli} mcp: unknown argument "${unknown.replace(/[^\x20-\x7e]/g, "?").slice(0, 80)}"\n${MCP_USAGE(cli)}\n`,
+    );
+    process.exitCode = 2;
+    return;
+  }
   const refusedToken = actorTokenRefusal(scope, process.env, getStateDir());
   if (refusedToken) {
     process.stderr.write(`${cli} mcp: ${refusedToken}\n`);

package/src/ui/mcp/tools.ts

@@ -728,6 +728,54 @@ function lifecycleTool(cmd: LifecycleCmd): DenTool {
   };
 }
 
+/** An agent id or workspace name (WORKSPACE_NAME_RE). */
+const NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+
+/**
+ * MCP agent_resume (AG-14.4): resume a stopped or interrupted agent of this
+ * workspace (or a granted one) in its own conversation. Opt-in through
+ * mcp.actions; for orchestrators. The web server checks the scope again.
+ */
+const agentResumeTool: DenTool = {
+  name: "agent_resume",
+  title: "Resume an agent",
+  description:
+    "Resume a stopped or interrupted agent in the same conversation, persona, workspace and folder. Never starts a new conversation: an agent whose runtime can't resume is refused. Never the caller itself.",
+  action: true,
+  shape: {
+    agent: z.string().describe("The agent's id"),
+    workspace: workspaceArg,
+  },
+  async run(a, { api, scope }) {
+    const agent = str(a.agent);
+    if (!agent || !NAME_RE.test(agent))
+      throw new Refusal("agent_resume: agent must be an agent id");
+    let ws = str(a.workspace) ?? scope?.workspace;
+    if (!ws) {
+      const focused = (await api.get("/api/workspaces")) as {
+        focus?: unknown;
+      };
+      ws = typeof focused?.focus === "string" ? focused.focus : undefined;
+    }
+    if (!ws || !NAME_RE.test(ws))
+      throw new Refusal("agent_resume: name the agent's workspace");
+    // Scoped: callTool's scopeArgs pinned `workspace` to the scope (or a
+    // granted one, reported) before this runs.
+    if (scope && ws !== scope.workspace && !(scope.grants ?? []).includes(ws))
+      throw new ScopeRefusal(
+        `agent_resume: workspace "${ws}" is outside this agent's scope ("${scope.workspace}")`,
+      );
+    if (scope && `agent:${agent}` === scope.actor)
+      throw new Refusal("agent_resume: an agent can't resume itself");
+    return api.get(
+      `/api/workspaces/${encodeURIComponent(ws)}/agents/${encodeURIComponent(agent)}/resume`,
+      {},
+      "POST",
+      {},
+    );
+  },
+};
+
 const ACTION_TOOLS: Record<McpAction, DenTool> = {
   service_up: lifecycleTool("up"),
   service_down: lifecycleTool("down"),
@@ -816,6 +864,7 @@ const ACTION_TOOLS: Record<McpAction, DenTool> = {
       return actionResult(r, 300, { pillar, env });
     },
   },
+  agent_resume: agentResumeTool,
 };
 
 export const READ_TOOL_NAMES: readonly string[] = READ_TOOLS.map((t) => t.name);
@@ -853,6 +902,7 @@ const WORKSPACE_TOOLS = new Set([
   "service_restart",
   "workspace_sync",
   "run_tests",
+  "agent_resume",
 ]);
 
 /**