@monster-orange/den 0.4.7 → 0.4.9

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

@@ -0,0 +1,323 @@
+/**
+ * `<cli> usage` (den#6): how agents spend tokens and time, read from the
+ * runtimes' own transcripts on this machine (usage sources, plugin kind
+ * `usage`). None of it is sent anywhere: it reads local files and writes
+ * local files. The one question it asks outside: when an agent ran
+ * `gh pr merge`, `gh pr view <ref> --json state` confirms the merge
+ * (gh-pr-state.ts) before it counts.
+ *
+ *   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 {
+  agentFilesDir,
+  listRecords,
+  readRecord,
+  writeRecord,
+} from "../../shared/agents/records.js";
+import { markDue } from "../../shared/agents/rotation.js";
+import { ghPrState } from "../../shared/git/gh-pr-state.js";
+import { readAgentsConfig } from "../../shared/den-config.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), compactions and rotations, joined on its",
+    "    conversation id, and saved in its record; then the share of agents",
+    "    with both. A merged pull request makes the agent's rotation due",
+    "{cli} usage report [--days <n>] [--json]",
+    "    the last n days (default 7): tokens, context re-reads, polling, denials,",
+    "    tool errors, corrections, subagents on Opus, the longest session's context",
+    "    per call, the share of re-reads from never-ending sessions (more",
+    "    compactions than agents.rotate.after_compactions), rotations; 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;
+  /** agents.rotate (default: the org config's). */
+  rotateAfter?: () => { afterCompactions: number } | undefined;
+  /**
+   * A pull request's state, to confirm a `gh pr merge` the agent ran
+   * (default: `gh pr view <ref> --json state` in the agent's folder).
+   */
+  prState?: (
+    ref: string,
+    o: { repo?: string; cwd: string },
+  ) => Promise<string | undefined>;
+}
+
+/** The check, counting how often it asked (the summary line says so). */
+function counted(
+  f: NonNullable<UsageDeps["prState"]>,
+): NonNullable<UsageDeps["prState"]> & { asked: number } {
+  const g = Object.assign(
+    (ref: string, o: { repo?: string; cwd: string }) => {
+      g.asked++;
+      return f(ref, o);
+    },
+    { asked: 0 },
+  );
+  return g;
+}
+
+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,
+    rotateLimit: () => rotateLimit(d),
+    prState: counted(d.prState ?? ghPrState(d.env ?? process.env)),
+  };
+}
+
+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. An
+ * agent whose pull request merged has its rotation marked due (den#4): its
+ * Stop hook then asks it for its handoff.
+ */
+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 } : {}),
+    });
+    if (r.outcome?.prMerged)
+      markDue(agentFilesDir(stateDir, rec.id), "pr-merged", rec.resumeToken);
+  }
+}
+
+/** agents.rotate.after_compactions; the default when the config can't be read. */
+function rotateLimit(d: UsageDeps): number {
+  try {
+    return (
+      (d.rotateAfter ?? (() => readAgentsConfig().rotate))()
+        ?.afterCompactions ?? 3
+    );
+  } catch {
+    return 3;
+  }
+}
+
+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,
+    prState: d.prState,
+  });
+  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",
+      "COMPACTIONS",
+      "ROTATIONS",
+    ],
+    ...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)" : ""}`
+        : "-",
+      r.compactions === undefined ? "-" : String(r.compactions),
+      String(r.rotations),
+    ]),
+  ]))
+    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; none of this was sent.`,
+  );
+  if (d.prState.asked)
+    d.out(
+      `To confirm a merge, it asked GitHub for the state of ${d.prState.asked} pull request${d.prState.asked === 1 ? "" : "s"} (gh pr view).`,
+    );
+  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,
+    prState: d.prState,
+  });
+  save(d.stateDir(), rows);
+  const m = weeklyMetrics(stats, rows, d.rotateLimit());
+  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",
 ]);
 
 /**

package/src/ui/server/agent-resume-grant.ts

@@ -0,0 +1,53 @@
+/**
+ * MCP `agent_resume` (AG-14.4): the one agent route an agent's own token
+ * may reach, and only when all of these hold:
+ *
+ *   - the org config opts in: `mcp.actions` lists agent_resume (off by
+ *     default, like every MCP action);
+ *   - the agent to resume is in the caller's workspace, or one its
+ *     agents.<id>.grants gives it (the scope agent_spawn has, AG spec §5);
+ *   - it isn't the caller itself.
+ *
+ * The request checks (request-guard.ts agentRefusal) and the route
+ * (agent-routes.ts) both ask. Starting, stopping and removing agents stay a
+ * person's.
+ */
+export const AGENT_RESUME_ACTION = "agent_resume";
+
+/** POST /api/workspaces/<ws>/agents/<id>/resume. */
+export const AGENT_RESUME_ROUTE =
+  /^\/api\/workspaces\/([^/]+)\/agents\/([^/]+)\/resume$/;
+
+export interface ResumingAgent {
+  actor: string;
+  workspace: string;
+  grants: readonly string[];
+}
+
+/** Why this agent may not resume agent `id` of `ws`, or null when it may. */
+export function agentResumeRefusal(
+  p: ResumingAgent,
+  ws: string,
+  id: string,
+  actions: readonly string[],
+): string | null {
+  if (!actions.includes(AGENT_RESUME_ACTION))
+    return `${p.actor} can't resume agents: the org config's mcp.actions doesn't list ${AGENT_RESUME_ACTION}.`;
+  if (ws !== p.workspace && !p.grants.includes(ws))
+    return `${p.actor} can resume agents of workspace ${p.workspace} only${p.grants.length ? ` (or ${p.grants.join(", ")}, its grants)` : ""}, not ${ws}.`;
+  if (`agent:${id}` === p.actor) return `${p.actor} can't resume itself.`;
+  return null;
+}
+
+/** The route's workspace and agent id, decoded; null when it isn't it. */
+export function agentResumeTarget(
+  pathname: string,
+): { ws: string; id: string } | null {
+  const m = AGENT_RESUME_ROUTE.exec(pathname);
+  if (!m) return null;
+  try {
+    return { ws: decodeURIComponent(m[1]), id: decodeURIComponent(m[2]) };
+  } catch {
+    return null;
+  }
+}