@monster-orange/den 0.4.26 → 0.4.28

package/src/shared/agents/helpers.ts

@@ -0,0 +1,175 @@
+/**
+ * D32: the helpers an agent starts inside its own session (Claude Code's
+ * Agent and Workflow subagents). They belong to the agent's session, not
+ * to Den: Den shows them, read-only, and never stops or steers them.
+ *
+ * Runtime-neutral shapes; a runtime that can read its helpers implements
+ * Runtime.helpers / Runtime.helperTranscript (den-claude: claude-helpers.ts).
+ */
+
+/** running: working now. idle: no activity for a while, not known done. */
+export type HelperStatus = "running" | "idle" | "done" | "failed" | "stopped";
+
+export interface Helper {
+  /** The runtime's id for it (Claude Code: agent-<id>'s <id>). */
+  id: string;
+  /** What the agent asked it to do, in a few words. Missing: show the id. */
+  description?: string;
+  /** Its kind (general-purpose, Explore, a plugin's agent, …). */
+  type?: string;
+  model?: string;
+  /** The worktree it works in, when it has its own. */
+  branch?: string;
+  worktree?: string;
+  /** Started in the background (the agent kept going meanwhile). */
+  background?: boolean;
+  /** 1: started by the agent; 2+: started by another helper (parentId). */
+  depth: number;
+  parentId?: string;
+  /** When it ran inside a workflow. */
+  workflow?: { runId: string; name?: string; phase?: string; label?: string };
+  /** It ran in one of the agent's earlier conversations (before a relaunch). */
+  earlier?: true;
+  status: HelperStatus;
+  /** How the status was told, for "why does it say that". */
+  statusFrom: string;
+  /** Epoch ms. */
+  startedAt?: number;
+  lastActivityAt?: number;
+  durationMs?: number;
+  /** The tool it used last, when known. */
+  lastTool?: string;
+}
+
+/** One line of a helper's transcript, tool calls summarized. */
+export interface HelperTranscriptItem {
+  at?: number;
+  kind: "prompt" | "text" | "tool" | "result" | "note";
+  /** For a tool call: its name. */
+  tool?: string;
+  text: string;
+  error?: boolean;
+}
+
+export interface HelperTranscript {
+  helper: Helper;
+  items: HelperTranscriptItem[];
+  /** Earlier lines left out (only the last ones are shown). */
+  omitted: number;
+}
+
+/** Read-only, and why: shown wherever helpers are. */
+export const HELPERS_READ_ONLY_NOTE =
+  "Helpers run inside this agent's own session, so Den shows them but can't stop or steer them. To change what they do, tell the agent.";
+
+/** D32 settings (agents.helpers.*), permissive defaults. */
+export interface HelperSettings {
+  /** No activity for this long and not known done: idle, not running. */
+  activeMinutes: number;
+  /** Done, failed and stopped helpers fold away after this long. */
+  collapseDoneMinutes: number;
+}
+
+export const HELPER_DEFAULTS: HelperSettings = {
+  activeMinutes: 10,
+  collapseDoneMinutes: 30,
+};
+
+/** What a runtime's helpers hooks are given. */
+export interface HelperReadOptions {
+  env?: NodeJS.ProcessEnv;
+  now?: number;
+  settings?: Partial<HelperSettings>;
+  /** Whether the agent itself is running now. */
+  agentLive?: boolean;
+  /** A transcript's last lines (default 500). */
+  limit?: number;
+}
+
+/**
+ * Running helpers first, then the newest; a helper's own helpers right
+ * under it, in the same order (a tree, depth first). One whose parent
+ * isn't in the list sits at the top level.
+ */
+export function sortHelpers(hs: Helper[]): Helper[] {
+  const ids = new Set(hs.map((h) => h.id));
+  const kids = new Map<string, Helper[]>();
+  const roots: Helper[] = [];
+  for (const h of hs)
+    if (h.parentId && h.parentId !== h.id && ids.has(h.parentId))
+      kids.set(h.parentId, [...(kids.get(h.parentId) ?? []), h]);
+    else roots.push(h);
+  // Running counts for the whole branch: a done helper with a running
+  // helper under it sorts with the running ones (0.4.28-dev.1's gate).
+  const busy = new Map<string, boolean>();
+  const runs = (h: Helper, path = new Set<string>()): boolean => {
+    const known = busy.get(h.id);
+    if (known !== undefined) return known;
+    if (path.has(h.id)) return h.status === "running";
+    path.add(h.id);
+    const r =
+      h.status === "running" ||
+      (kids.get(h.id) ?? []).some((k) => runs(k, path));
+    path.delete(h.id);
+    busy.set(h.id, r);
+    return r;
+  };
+  const live = (h: Helper) => (runs(h) ? 0 : 1);
+  const order = (a: Helper, b: Helper) =>
+    live(a) - live(b) ||
+    (b.startedAt ?? b.lastActivityAt ?? 0) -
+      (a.startedAt ?? a.lastActivityAt ?? 0) ||
+    a.id.localeCompare(b.id);
+  const out: Helper[] = [];
+  const seen = new Set<string>();
+  const walk = (h: Helper) => {
+    if (seen.has(h.id)) return;
+    seen.add(h.id);
+    out.push(h);
+    for (const k of (kids.get(h.id) ?? []).sort(order)) walk(k);
+  };
+  for (const r of roots.sort(order)) walk(r);
+  // A loop of parents (never from Claude Code): still listed, flat.
+  for (const h of [...hs].sort(order)) if (!seen.has(h.id)) out.push(h);
+  return out;
+}
+
+/**
+ * At most `n` of `list`, in its order: the running ones first to stay,
+ * then the rest (a running helper is never cut for a done one).
+ */
+export function capHelpers(list: readonly Helper[], n: number): Helper[] {
+  const kept = new Set(
+    [
+      ...list.filter((h) => h.status === "running"),
+      ...list.filter((h) => h.status !== "running"),
+    ].slice(0, Math.max(0, n)),
+  );
+  return list.filter((h) => kept.has(h));
+}
+
+/**
+ * How far each helper of `list` (in sortHelpers' order) is indented: one
+ * step under a parent shown above it, none when its parent isn't in the
+ * list. The page's twin is agent-helpers.js shownDepths.
+ */
+export function shownDepths(list: readonly Helper[]): Map<string, number> {
+  const at = new Map<string, number>();
+  for (const h of list)
+    at.set(
+      h.id,
+      h.parentId && at.has(h.parentId) ? at.get(h.parentId)! + 1 : 0,
+    );
+  return at;
+}
+
+/** {running, total}: what a badge shows. */
+export function helperCounts(hs: readonly Helper[]): {
+  running: number;
+  total: number;
+} {
+  return {
+    running: hs.filter((h) => h.status === "running").length,
+    total: hs.length,
+  };
+}

package/src/shared/agents/runtime.ts

@@ -7,6 +7,7 @@
  * Built-ins register here exactly as a runtime plugin would (AG-8a):
  * den-claude and generic.
  */
+import type { Helper, HelperReadOptions, HelperTranscript } from "./helpers.js";
 import * as fs from "fs";
 import * as path from "path";
 import {
@@ -62,7 +63,7 @@ export interface AgentMcp {
   scope: string;
   /**
    * HUB-1.5: Den Hub's MCP server (Streamable HTTP), when hub.url is set:
-   * its base URL and the headers (the bearer token among them). The
+   * its MCP endpoint (HUB-1.7: Hub's mcp_url, default <hub.url>/mcp) and the headers (the bearer token among them). The
    * headers go only into the agent's own 0600 MCP file, never into argv,
    * a record, a log or a page.
    */
@@ -252,6 +253,18 @@ export interface Runtime {
    * throw; its catalog entry's `sessionName` says how stable its source is.
    */
   sessionName?(rec: AgentRecord, env?: NodeJS.ProcessEnv): string | null;
+  /**
+   * D32: the helpers the agent started inside its own session (Claude
+   * Code's Agent and Workflow subagents), in every conversation it has had,
+   * running first. Read-only. None: the runtime can't tell. Never throws.
+   */
+  helpers?(rec: AgentRecord, opts?: HelperReadOptions): Helper[];
+  /** D32: one helper's transcript, tool calls summarized; null if none. Never throws. */
+  helperTranscript?(
+    rec: AgentRecord,
+    id: string,
+    opts?: HelperReadOptions,
+  ): HelperTranscript | null;
   /** Where permission prompts surface (Q-AG-2). */
   approvals?: "terminal" | "hook";
   /**
@@ -353,7 +366,7 @@ export function mcpConfigJson(mcp: AgentMcp): string {
             ? {
                 [mcp.hub.name]: {
                   type: "http",
-                  url: `${mcp.hub.url}/mcp`,
+                  url: mcp.hub.url,
                   headers: mcp.hub.headers,
                 },
               }

package/src/shared/den-config.ts

@@ -8,6 +8,7 @@
  * The user file can toggle local_dev on/off without touching the shared config.
  */
 
+import { HELPER_DEFAULTS, type HelperSettings } from "./agents/helpers.js";
 import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
@@ -916,6 +917,13 @@ export interface AgentsConfig {
    * false` keeps standing personas from rotating (default true).
    */
   rotate?: { after_compactions?: unknown; standing?: unknown };
+  /**
+   * D32, the helpers an agent starts in its own session:
+   * `{ active_minutes, collapse_done_minutes }`. A helper with no activity
+   * for `active_minutes` (default 10) and not known done shows idle; done
+   * ones fold away after `collapse_done_minutes` (default 30).
+   */
+  helpers?: { active_minutes?: unknown; collapse_done_minutes?: unknown };
   /**
    * Any other key is an agent id: `agents.<id>.grants` widens that agent's
    * MCP scope to other workspaces (AG spec §5b). Config only: an agent
@@ -940,6 +948,8 @@ export const AGENTS_RESERVED_KEYS = [
   "runtime_catalog",
   "default_pack",
   "rotate",
+  // D32: how helpers show.
+  "helpers",
   // AG-10.5, AG-11.1: the distribution's persona categories and roles.
   "categories",
   "roles",
@@ -968,12 +978,42 @@ export interface ResolvedAgentsConfig {
   rotate?: RotateSettings;
   /** D28: agents.rotate as written, the org scope. */
   rotateOrg?: OrgRotate;
+  /** agents.helpers (D32) with its defaults. */
+  helpers?: HelperSettings;
   /** agents.categories (AG-10.5): the distribution's, after Den's. */
   categories?: Category[];
   /** agents.roles (AG-11.1): new roles and Den roles' preset extensions. */
   roles?: RolesConfig;
 }
 
+/** `agents.helpers` (D32) checked; a bad key or value throws naming it. */
+export function helpersBlock(v: unknown): HelperSettings {
+  const out = { ...HELPER_DEFAULTS };
+  if (v === undefined || v === null) return out;
+  if (!isMapping(v))
+    throw new Error(
+      `agents.helpers: must be a mapping of active_minutes, collapse_done_minutes (got ${JSON.stringify(v)})`,
+    );
+  for (const [k, x] of Object.entries(v)) {
+    const key =
+      k === "active_minutes"
+        ? "activeMinutes"
+        : k === "collapse_done_minutes"
+          ? "collapseDoneMinutes"
+          : null;
+    if (!key)
+      throw new Error(
+        `agents.helpers.${k}: unknown key (agents.helpers takes active_minutes, collapse_done_minutes)`,
+      );
+    if (typeof x !== "number" || !Number.isFinite(x) || x <= 0 || x > 100_000)
+      throw new Error(
+        `agents.helpers.${k}: must be a number of minutes, above 0 and at most 100000 (got ${JSON.stringify(x)})`,
+      );
+    out[key] = x;
+  }
+  return out;
+}
+
 /** `agents.rotate` checked; any other key, or a bad value, throws naming it. */
 /**
  * `agents.rotate` checked, both ways: den#4's settings (afterCompactions 0
@@ -1077,6 +1117,7 @@ export function readAgentsConfig(
       return { rotate: r.settings, rotateOrg: r.org };
     })(),
   };
+  out.helpers = helpersBlock(raw.helpers);
   out.categories = checkCategoriesConfig(raw.categories);
   out.roles = checkRolesConfig(raw.roles, [
     ...DEN_CATEGORIES.map((c) => c.id),
@@ -1114,7 +1155,7 @@ export function readAgentsConfig(
     const where = `agents.${id}`;
     if (!AGENT_KEY_RE.test(id) || !isMapping(block))
       throw new Error(
-        `${where}: unknown key (agents: takes max_concurrent, persona_packs, runtime_catalog, default_pack, rotate, categories, roles, ` +
+        `${where}: unknown key (agents: takes max_concurrent, persona_packs, runtime_catalog, default_pack, rotate, helpers, categories, roles, ` +
           `or an agent id mapping to { grants: [...] })`,
       );
     for (const k of Object.keys(block))