@monster-orange/den 0.4.26 → 0.4.28

package/src/ui/cli/agent-ops.ts

@@ -50,6 +50,15 @@
  * Nothing here takes a grant: grants come from the org config only. The
  * host enforces agents.max_concurrent on every start, counting agents only.
  */
+import {
+  capHelpers,
+  HELPER_DEFAULTS,
+  HELPERS_READ_ONLY_NOTE,
+  helperCounts,
+  type Helper,
+  type HelperSettings,
+  type HelperTranscript,
+} from "../../shared/agents/helpers.js";
 import * as fs from "fs";
 import * as path from "path";
 import {
@@ -265,6 +274,8 @@ export interface AgentsDeps extends SessionsDeps {
     url: string;
     token: string;
     allowTools?: boolean;
+    /** HUB-1.7: Hub's MCP endpoint (default <url>/mcp). */
+    mcpUrl?: string;
   } | null>;
   /** HUB-1.5: workspace `ws`'s repos as owner/repo (X-Den-Repos). */
   workspaceRepos?: (ws: string) => string[];
@@ -288,6 +299,7 @@ export interface AgentsResolved extends Resolved {
     url: string;
     token: string;
     allowTools?: boolean;
+    mcpUrl?: string;
   } | null>;
   workspaceRepos: (ws: string) => string[];
 }
@@ -395,6 +407,7 @@ export async function agentHub(
   d: AgentsResolved,
   ws: string,
   name: string,
+  agentId?: string,
 ): Promise<AgentMcp["hub"] | undefined> {
   const h = await d.hub().catch(() => null);
   if (!h) return undefined;
@@ -407,10 +420,11 @@ export async function agentHub(
   }
   return {
     name: HUB_SERVER,
-    url: h.url,
+    url: h.mcpUrl || `${h.url}/mcp`,
     allowTools: h.allowTools !== false,
     headers: hubHeaders(h.token, {
       agent: name,
+      ...(agentId ? { agentId } : {}),
       session: crypto.randomUUID(),
       workspace: ws,
       repos,
@@ -480,6 +494,7 @@ async function defaultHub(): Promise<{
   url: string;
   token: string;
   allowTools: boolean;
+  mcpUrl: string;
 } | null> {
   const { readHubConfig, readHubToken } = await import("../../shared/hub.js");
   let cfg;
@@ -490,7 +505,9 @@ async function defaultHub(): Promise<{
   }
   if (!cfg) return null;
   const token = await readHubToken(cfg);
-  return token ? { url: cfg.url, token, allowTools: cfg.allowTools } : null;
+  return token
+    ? { url: cfg.url, token, allowTools: cfg.allowTools, mcpUrl: cfg.mcpUrl }
+    : null;
 }
 
 /**
@@ -630,6 +647,12 @@ export interface AgentRow {
   /** D28: the last one (when, why, the old conversation, by itself or not). */
   lastRotation?: RotationEntry;
   session?: SessionInfo;
+  /**
+   * D32: the helpers it started in its own session: how many, how many
+   * run now, and the ones worth showing under it (running, or ended
+   * within agents.helpers.collapse_done_minutes; at most 8).
+   */
+  helpers?: { running: number; total: number; recent: Helper[] };
 }
 
 /** Its state as a row shows it (AG-14.1: stopped, exited or interrupted). */
@@ -823,9 +846,138 @@ export async function listAgents(
   const records = listRecords(d.stateDir()).filter((r) => r.workspace === ws);
   noteEnded(d.stateDir(), sessions, records);
   const rows = agentRows(sessions, records, d.stateDir(), policyResolver(d));
+  addHelperCounts(d, rows, records);
   return opts.stopped ? rows.filter((r) => isStoppedState(r.state)) : rows;
 }
 
+/** At most this many helpers ride along on an agent's row. */
+const ROW_HELPERS = 8;
+
+/** D32: agents.helpers, or its defaults when the config can't be read. */
+function helperSettings(d: AgentsResolved): HelperSettings {
+  try {
+    return d.agentsConfig().helpers ?? HELPER_DEFAULTS;
+  } catch {
+    return HELPER_DEFAULTS;
+  }
+}
+
+/** D32: each row's helper counts and recent helpers (never fails a list). */
+function addHelperCounts(
+  d: AgentsResolved,
+  rows: AgentRow[],
+  records: AgentRecord[],
+): void {
+  const settings = helperSettings(d);
+  const byId = new Map(records.map((r) => [r.id, r]));
+  for (const row of rows) {
+    const rec = byId.get(row.agent);
+    if (!rec) continue;
+    const h = rowHelpers(rec, !isStoppedState(row.state), settings, d.env);
+    if (h) row.helpers = h;
+  }
+}
+
+/**
+ * D32: what an agent's row shows of its helpers: counts, and the ones
+ * worth showing (running, or this conversation's ended within
+ * collapse_done_minutes; at most 8). Undefined: none, or its runtime
+ * can't tell. Never throws.
+ */
+export function rowHelpers(
+  rec: AgentRecord,
+  live: boolean,
+  settings: HelperSettings = HELPER_DEFAULTS,
+  env: NodeJS.ProcessEnv = process.env,
+  now = Date.now(),
+): AgentRow["helpers"] {
+  const rt = getRuntime(rec.runtime);
+  if (!rt?.helpers) return undefined;
+  let hs: Helper[] = [];
+  try {
+    hs = rt.helpers(rec, { env, now, settings, agentLive: live });
+  } catch {
+    return undefined;
+  }
+  if (!hs.length) return undefined;
+  const keep = settings.collapseDoneMinutes * 60_000;
+  const shown = hs.filter(
+    (h) =>
+      h.status === "running" ||
+      (!h.earlier && now - (h.lastActivityAt ?? h.startedAt ?? 0) <= keep),
+  );
+  return { ...helperCounts(hs), recent: capHelpers(shown, ROW_HELPERS) };
+}
+
+/** D32: an agent's helpers, read-only, and whether its runtime can tell. */
+export async function agentHelpers(
+  d: AgentsResolved,
+  id: string,
+  ws?: string,
+): Promise<{
+  rec: AgentRecord;
+  supported: boolean;
+  live: boolean;
+  helpers: Helper[];
+  note: string;
+}> {
+  const rec = agentRecord(d, id, ws);
+  const rt = getRuntime(rec.runtime);
+  const live = await agentLive(d, rec);
+  const helpers =
+    rt?.helpers?.(rec, {
+      env: d.env,
+      settings: helperSettings(d),
+      agentLive: live,
+    }) ?? [];
+  return {
+    rec,
+    supported: !!rt?.helpers,
+    live,
+    helpers,
+    note: HELPERS_READ_ONLY_NOTE,
+  };
+}
+
+/** D32: one of agent `id`'s helpers' transcript; a 404 when there's none. */
+export async function agentHelperTranscript(
+  d: AgentsResolved,
+  id: string,
+  helperId: string,
+  ws?: string,
+  limit?: number,
+): Promise<HelperTranscript & { note: string }> {
+  const rec = agentRecord(d, id, ws);
+  const rt = getRuntime(rec.runtime);
+  const t = rt?.helperTranscript?.(rec, helperId, {
+    env: d.env,
+    settings: helperSettings(d),
+    agentLive: await agentLive(d, rec),
+    ...(limit ? { limit } : {}),
+  });
+  if (!t) throw refused(`agent ${id} has no helper "${helperId}"`, [], 404);
+  return { ...t, note: HELPERS_READ_ONLY_NOTE };
+}
+
+/** Whether agent `rec`'s session runs now (an unreachable host: no). */
+async function agentLive(
+  d: AgentsResolved,
+  rec: AgentRecord,
+): Promise<boolean> {
+  try {
+    const c = await d.connectExisting();
+    if (!c) return false;
+    try {
+      const s = sessionOf(await c.list(), rec);
+      return Boolean(s && !s.exited);
+    } finally {
+      c.close();
+    }
+  } catch {
+    return false;
+  }
+}
+
 // ── personas, runtimes ──────────────────────────────────────────────────────
 
 /** The agents config; an invalid one is a refusal naming the key. */
@@ -1901,6 +2053,7 @@ export async function startAgent(
     d,
     ws,
     given ?? prev?.displayName ?? persona.displayName ?? id,
+    id,
   );
   const input = {
     ...base,
@@ -2443,7 +2596,12 @@ export async function resumeAgent(
     // Resume in the cwd the agent had, wherever the workspace points now.
     // D24 (and D25: a rename since) the name peers see it by.
     const peerName = peerSessionName(d.cli, rec.workspace, rec);
-    const hub = await agentHub(d, rec.workspace, rec.displayName ?? rec.id);
+    const hub = await agentHub(
+      d,
+      rec.workspace,
+      rec.displayName ?? rec.id,
+      rec.id,
+    );
     const at = {
       ...input,
       ...(hub ? { mcp: { ...input.mcp, hub } } : {}),

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

@@ -70,6 +70,7 @@ 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 { shownDepths } from "../../shared/agents/helpers.js";
 import {
   parseRotateValue,
   type OverrideScope,
@@ -84,6 +85,8 @@ import {
   importAgent,
   changePersona,
   listAgents,
+  agentHelpers,
+  agentHelperTranscript,
   listConversations,
   listPersonas as personaList,
   listRuntimes,
@@ -129,7 +132,7 @@ export {
 
 export const AGENTS_HELP = {
   usage:
-    "agents <list|start|stop|resume|relaunch|rotate|keep|handoff|import|persona|rename|rm|personas|doctor|handback-check|handoff-check> ...",
+    "agents <list|start|stop|resume|relaunch|rotate|keep|handoff|import|persona|helpers|rename|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`).",
@@ -167,6 +170,13 @@ export const AGENTS_HELP = {
     "    agent never rotates. A person's only",
     "{cli} agents handoff <id> [-w <ws>]",
     "    ask a running agent, at idle, to write its handoff",
+    "{cli} agents helpers <id> [-w <ws>] [--all] [--json]",
+    "    the helpers it started in its own session (Claude Code's Agent and",
+    "    Workflow subagents): what each does, its type, model, branch, state and",
+    "    times; running first. --all: its earlier conversations' too. Read-only:",
+    "    they belong to the agent's session, so Den can't stop or steer them",
+    "{cli} agents helpers <id> <helper> [-w <ws>] [--limit <n>] [--json]",
+    "    one helper's transcript, tool calls summarized (the last 500 lines)",
     "{cli} agents import -w <ws> [--runtime <r>] [--json]",
     "{cli} agents import -w <ws> --session <id> --persona <p> [--runtime <r>] [--id <id>] [--model <m>]",
     "    bring in a conversation started outside Den: the first lists the runtime's",
@@ -456,6 +466,120 @@ async function persona(args: string[], d: AgentsResolved): Promise<number> {
 }
 
 /** `<id> [-w <ws>]`. */
+/** D32: `agents helpers <id> [<helper>]`, read-only. */
+async function helpers(args: string[], d: AgentsResolved): Promise<number> {
+  const where = "agents helpers";
+  const p = parseArgs(where, args, {
+    "--workspace": true,
+    "--json": false,
+    "--all": false,
+    "--limit": true,
+  });
+  noExtra(where, p, 2);
+  const [id, helperId] = p.positional;
+  if (!id) throw new UsageError(`${where} needs <id>`);
+  const ws = workspaceFlag(where, p);
+  const ago = (ms?: number) =>
+    ms === undefined ? "-" : `${duration(Date.now() - ms)} ago`;
+  if (helperId) {
+    const raw = p.flags["--limit"];
+    const limit = raw === undefined ? undefined : Number(raw);
+    if (limit !== undefined && (!Number.isInteger(limit) || limit < 1))
+      throw new UsageError(
+        `${where}: --limit must be a whole number of at least 1`,
+      );
+    const t = await agentHelperTranscript(d, id, helperId, ws, limit);
+    if (p.flags["--json"]) {
+      d.out(JSON.stringify(t, null, 2));
+      return 0;
+    }
+    d.out(
+      `${t.helper.description ?? t.helper.id} (${t.helper.status}, ${t.helper.type ?? "helper"})`,
+    );
+    if (t.omitted) d.out(`… ${t.omitted} earlier lines`);
+    for (const i of t.items) {
+      const lead =
+        i.kind === "tool"
+          ? `→ ${i.tool}: `
+          : i.kind === "result"
+            ? i.error
+              ? "  ✗ "
+              : "  ← "
+            : i.kind === "prompt"
+              ? "asked: "
+              : i.kind === "note"
+                ? "… "
+                : "";
+      d.out(`${lead}${i.text}`);
+    }
+    d.out("");
+    d.out(t.note);
+    return 0;
+  }
+  const r = await agentHelpers(d, id, ws);
+  const shown = p.flags["--all"]
+    ? r.helpers
+    : r.helpers.filter((h) => !h.earlier);
+  if (p.flags["--json"]) {
+    d.out(
+      JSON.stringify(
+        {
+          agent: r.rec.id,
+          supported: r.supported,
+          live: r.live,
+          helpers: shown,
+          note: r.note,
+        },
+        null,
+        2,
+      ),
+    );
+    return 0;
+  }
+  if (!r.supported) {
+    d.out(`${r.rec.runtime} can't tell which helpers ${r.rec.id} started`);
+    return 0;
+  }
+  const earlier = r.helpers.length - r.helpers.filter((h) => !h.earlier).length;
+  if (!shown.length) {
+    d.out(
+      `${r.rec.id} has started no helpers${earlier && !p.flags["--all"] ? ` in this conversation (${earlier} earlier: --all)` : ""}`,
+    );
+    return 0;
+  }
+  const depth = shownDepths(shown);
+  for (const l of columns([
+    ["HELPER", "WHAT", "TYPE", "MODEL", "STATE", "STARTED", "FOR", "BRANCH"],
+    ...shown.map((h) => [
+      `${"  ".repeat(depth.get(h.id) ?? 0)}${h.id}`,
+      (h.description ?? "-").slice(0, 48),
+      h.workflow
+        ? `${h.type ?? "-"} (${h.workflow.name ?? "workflow"})`
+        : (h.type ?? "-"),
+      h.model ?? "-",
+      `${h.status}${h.earlier ? " (earlier)" : ""}`,
+      ago(h.startedAt),
+      h.durationMs === undefined ? "-" : duration(h.durationMs),
+      h.branch ?? "-",
+    ]),
+  ]))
+    d.out(l);
+  if (earlier && !p.flags["--all"])
+    d.out(`${earlier} more from earlier conversations: --all`);
+  d.out("");
+  d.out(r.note);
+  return 0;
+}
+
+/** 65 s → "1m 5s"; 2 h → "2h 0m". */
+function duration(ms: number): string {
+  const s = Math.max(0, Math.round(ms / 1000));
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m ${s % 60}s`;
+  return `${Math.floor(m / 60)}h ${m % 60}m`;
+}
+
 function idAndWorkspace(
   where: string,
   args: string[],
@@ -962,6 +1086,8 @@ export async function cmdAgents(
         case "persona":
           await loadAgentWorkspaces(deps);
           return await persona(rest, d);
+        case "helpers":
+          return await helpers(rest, d);
         case "rename":
           return rename(rest, d);
         case "rm":

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

@@ -482,12 +482,21 @@ export function hubLines(
   title: string,
 ): { lines: string[]; problem: boolean; check?: OnboardCheck } {
   if (!st.configured) return { lines: [], problem: false };
-  const who = [st.team && `team ${st.team}`, st.label && `install ${st.label}`]
+  const who = [
+    st.team && `company ${st.team}`,
+    st.label && `install ${st.label}`,
+    st.role && `role ${st.role}`,
+  ]
     .filter(Boolean)
     .join(", ");
+  // HUB-1.7: what to do about it is in Settings (Connect, Reconnect).
+  const fix =
+    st.state === "no_token" || st.state === "rejected"
+      ? ` (Settings › Agents › Hub: ${st.state === "rejected" ? "Reconnect" : "Connect"})`
+      : "";
   const detail = st.connected
     ? `${st.url}: connected${who ? ` (${who})` : ""}`
-    : `${st.url || "hub.url"}: not connected: ${st.problem ?? "no answer"}`;
+    : `${st.url || "hub.url"}: not connected: ${st.problem ?? "no answer"}${fix}`;
   return {
     lines: [
       "",

package/src/ui/mcp/api.ts

@@ -147,8 +147,9 @@ const ACTION_ROUTES: Record<string, string> = {
 };
 
 /**
- * Action routes with a parameter: an agent's resume (MCP agent_resume),
- * and Bring in's list and import (MCP agent_import, AG-17.1).
+ * Routes with a parameter: an agent's resume (MCP agent_resume), Bring
+ * in's list and import (MCP agent_import, AG-17.1), and an agent's helpers
+ * (MCP agent_helpers, D32, GET only).
  */
 const ACTION_ROUTE_PATTERNS: { re: RegExp; method: string }[] = [
   // One held request's state (its own, the server checks). Never /decide.
@@ -161,6 +162,11 @@ const ACTION_ROUTE_PATTERNS: { re: RegExp; method: string }[] = [
     re: /^\/api\/workspaces\/[A-Za-z0-9._-]{1,64}\/conversations$/,
     method: "GET",
   },
+  // D32 (MCP agent_helpers): an agent's helpers, or one's transcript. Reads.
+  {
+    re: /^\/api\/workspaces\/[A-Za-z0-9._-]{1,64}\/agents\/[A-Za-z0-9._-]{1,64}\/helpers(?:\/[A-Za-z0-9_-]{1,128})?$/,
+    method: "GET",
+  },
   {
     re: /^\/api\/workspaces\/[A-Za-z0-9._-]{1,64}\/conversations\/[A-Za-z0-9][A-Za-z0-9_-]{0,127}\/import$/,
     method: "POST",

package/src/ui/mcp/server.ts

@@ -109,13 +109,25 @@ export function createDenMcpServer(opts: DenMcpOptions): McpServer {
     ...(toolScope ? { scope: toolScope } : {}),
   };
 
+  // A pinned tool with no workspace parameter (no grants) still takes a
+  // `workspace` someone names, so that Den refuses it (callTool, scope.ts)
+  // instead of the SDK dropping the key and answering about this workspace
+  // (0.4.28-dev.0's gate: agent_helpers {workspace:"west"} answered for
+  // "default"). Not advertised; the one-shot path does the same.
+  const unpinned = new Map(toolsFor(opts.cfg).map((t) => [t.name, t]));
+  const schemaOf = (t: (typeof tools)[number]) =>
+    toolScope &&
+    !("workspace" in t.shape) &&
+    "workspace" in (unpinned.get(t.name)?.shape ?? {})
+      ? z.object(t.shape).passthrough()
+      : t.shape;
   for (const t of tools) {
     server.registerTool(
       t.name,
       {
         title: t.title,
         description: t.description,
-        inputSchema: t.shape,
+        inputSchema: schemaOf(t),
         annotations: {
           readOnlyHint: !t.action,
           destructiveHint: t.action,

package/src/ui/mcp/tools.ts

@@ -187,6 +187,55 @@ const read = (
 ): DenTool => ({ name, title, description, action: false, shape, run });
 
 const READ_TOOLS: DenTool[] = [
+  read(
+    "agent_helpers",
+    "An agent's helpers",
+    "D32: the helpers an agent started inside its own session (Claude Code's Agent and Workflow subagents), running first: id, description, type, model, branch, status (running, idle, done, failed, stopped), statusFrom (how that was told), startedAt, lastActivityAt, durationMs, workflow, and `earlier` for those from a conversation before a relaunch. With `helper`, that one helper's transcript, tool calls summarized (`items`, the last `limit` lines). Reads only: helpers belong to the agent's session, so nothing here stops or steers one.",
+    {
+      agent: z.string().describe("The agent's id"),
+      helper: z
+        .string()
+        .optional()
+        .describe("A helper's id: its transcript instead of the list"),
+      limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(5000)
+        .optional()
+        .describe("With helper: how many of its last lines (default 500)"),
+      workspace: workspaceArg,
+    },
+    async (a, { api, scope }) => {
+      const agent = str(a.agent);
+      if (!agent || !NAME_RE.test(agent))
+        throw new Refusal("agent_helpers: agent must be an agent id");
+      const helper = str(a.helper);
+      if (helper !== undefined && !/^[A-Za-z0-9_-]{1,128}$/.test(helper))
+        throw new Refusal("agent_helpers: helper must be a helper 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_helpers: name the agent's workspace");
+      if (scope && ws !== scope.workspace && !(scope.grants ?? []).includes(ws))
+        throw new ScopeRefusal(
+          `agent_helpers: workspace "${ws}" is outside this agent's scope ("${scope.workspace}")`,
+        );
+      const base = `/api/workspaces/${encodeURIComponent(ws)}/agents/${encodeURIComponent(agent)}/helpers`;
+      if (!helper) return api.get(base);
+      // The limit as a query, never in the path (the client's allowlist
+      // matches the path alone).
+      return api.get(
+        `${base}/${encodeURIComponent(helper)}`,
+        typeof a.limit === "number" ? { limit: String(a.limit) } : {},
+      );
+    },
+  ),
   read(
     "approval_check",
     "Check an approval",
@@ -1327,6 +1376,7 @@ const WORKSPACE_TOOLS = new Set([
   "run_tests",
   "agent_resume",
   "agent_import",
+  "agent_helpers",
 ]);
 
 /**