@clanker-code/pi-subagents 0.10.8 → 0.11.1

package/src/agent-manager.ts

@@ -12,6 +12,7 @@ import { isAbsolute } from "node:path";
 import type { Model } from "@earendil-works/pi-ai";
 import type { AgentSession, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { resumeAgent, runAgent, type ToolActivity } from "./agent-runner.js";
+import type { EventBus } from "./cross-extension-rpc.js";
 import { type AgentInvocation, type AgentRecord, type IsolationMode, MAX_RECURSIVE_DEPTH, type SubagentType, type ThinkingLevel } from "./types.js";
 import { addUsage } from "./usage.js";
 import { cleanupWorktree, createWorktree, pruneWorktrees, } from "./worktree.js";
@@ -102,6 +103,8 @@ interface SpawnOptions {
   onAssistantUsage?: (usage: { input: number; output: number; cacheWrite: number }) => void;
   /** Called when the session successfully compacts. */
   onCompaction?: (info: CompactionInfo) => void;
+  /** Parent's event bus — shared with child sessions so lifecycle events propagate to the parent widget. */
+  eventBus?: EventBus;
 }
 
 interface ResumeOptions {
@@ -126,6 +129,10 @@ export class AgentManager {
   private queue: { id: string; args: SpawnArgs }[] = [];
   /** Number of currently running background agents. */
   private runningBackground = 0;
+  /** Background agents by id; foreground agents must not emit background completion callbacks. */
+  private backgroundAgentIds = new Set<string>();
+  /** Background terminal callbacks already emitted; prevents abort/settle double delivery. */
+  private completedBackgroundCallbacks = new Set<string>();
 
   constructor(
     onComplete?: OnAgentComplete,
@@ -194,6 +201,7 @@ export class AgentManager {
       options.onOutputFileCreated?.(record.outputFile, id);
     }
     this.agents.set(id, record);
+    if (options.isBackground) this.backgroundAgentIds.add(id);
 
     const args: SpawnArgs = { pi, ctx, type, prompt, options };
 
@@ -208,12 +216,22 @@ export class AgentManager {
     try {
       this.startAgent(id, record, args);
     } catch (err) {
+      this.backgroundAgentIds.delete(id);
       this.agents.delete(id);
       throw err;
     }
     return id;
   }
 
+  /** Emit background completion once, optionally releasing a running concurrency slot. */
+  private completeBackground(record: AgentRecord, releaseRunningSlot: boolean, drain = true): void {
+    if (this.completedBackgroundCallbacks.has(record.id)) return;
+    this.completedBackgroundCallbacks.add(record.id);
+    if (releaseRunningSlot) this.runningBackground = Math.max(0, this.runningBackground - 1);
+    try { this.onComplete?.(record); } catch { /* ignore completion side-effect errors */ }
+    if (drain) this.drainQueue();
+  }
+
   /** Actually start an agent (called immediately or from queue drain). */
   private startAgent(id: string, record: AgentRecord, { pi, ctx, type, prompt, options }: SpawnArgs) {
     // Re-validate a caller-supplied cwd: queued spawns can start minutes after
@@ -295,6 +313,7 @@ export class AgentManager {
       },
       depth: record.depth,
       parentAgentId: record.parentAgentId,
+      eventBus: options.eventBus,
       onSessionCreated: (session) => {
         record.session = session;
         // Flush any steers that arrived before the session was ready
@@ -338,9 +357,7 @@ export class AgentManager {
         }
 
         if (options.isBackground) {
-          this.runningBackground--;
-          try { this.onComplete?.(record); } catch { /* ignore completion side-effect errors */ }
-          this.drainQueue();
+          this.completeBackground(record, true);
         }
         return responseText;
       })
@@ -369,9 +386,7 @@ export class AgentManager {
         }
 
         if (options.isBackground) {
-          this.runningBackground--;
-          this.onComplete?.(record);
-          this.drainQueue();
+          this.completeBackground(record, true);
         }
         return "";
       });
@@ -393,7 +408,7 @@ export class AgentManager {
         record.status = "error";
         record.error = err instanceof Error ? err.message : String(err);
         record.completedAt = Date.now();
-        this.onComplete?.(record);
+        this.completeBackground(record, false, false);
       }
     }
   }
@@ -434,6 +449,8 @@ export class AgentManager {
     record.error = undefined;
     record.resultConsumed = false;
     record.abortController = new AbortController();
+    this.backgroundAgentIds.add(id);
+    this.completedBackgroundCallbacks.delete(id);
     this.runningBackground++;
     this.onStart?.(record);
 
@@ -463,18 +480,14 @@ export class AgentManager {
       record.result = responseText;
       record.completedAt = Date.now();
       detach();
-      this.runningBackground--;
-      try { this.onComplete?.(record); } catch { /* ignore completion side-effect errors */ }
-      this.drainQueue();
+      this.completeBackground(record, true);
       return responseText;
     }).catch((err) => {
       if (record.status !== "stopped") record.status = "error";
       record.error = err instanceof Error ? err.message : String(err);
       record.completedAt = Date.now();
       detach();
-      this.runningBackground--;
-      try { this.onComplete?.(record); } catch { /* ignore completion side-effect errors */ }
-      this.drainQueue();
+      this.completeBackground(record, true);
       return "";
     });
 
@@ -501,6 +514,7 @@ export class AgentManager {
       this.queue = this.queue.filter(q => q.id !== id);
       record.status = "stopped";
       record.completedAt = Date.now();
+      this.completeBackground(record, false);
       return true;
     }
 
@@ -508,6 +522,7 @@ export class AgentManager {
     record.abortController?.abort();
     record.status = "stopped";
     record.completedAt = Date.now();
+    if (this.backgroundAgentIds.has(id)) this.completeBackground(record, true);
     return true;
   }
 
@@ -515,9 +530,24 @@ export class AgentManager {
   private removeRecord(id: string, record: AgentRecord): void {
     record.session?.dispose?.();
     record.session = undefined;
+    this.backgroundAgentIds.delete(id);
+    this.completedBackgroundCallbacks.delete(id);
     this.agents.delete(id);
   }
 
+  /** Remove selected terminal records. Running and queued records are never removed. */
+  clearRecords(ids: string[]): string[] {
+    const removed: string[] = [];
+    for (const id of ids) {
+      const record = this.agents.get(id);
+      if (!record) continue;
+      if (record.status === "running" || record.status === "queued") continue;
+      this.removeRecord(id, record);
+      removed.push(id);
+    }
+    return removed;
+  }
+
   private cleanup() {
     const cutoff = Date.now() - 10 * 60_000;
     for (const [id, record] of this.agents) {
@@ -554,6 +584,7 @@ export class AgentManager {
       if (record) {
         record.status = "stopped";
         record.completedAt = Date.now();
+        if (this.backgroundAgentIds.has(record.id)) this.completedBackgroundCallbacks.add(record.id);
         count++;
       }
     }
@@ -564,9 +595,11 @@ export class AgentManager {
         record.abortController?.abort();
         record.status = "stopped";
         record.completedAt = Date.now();
+        if (this.backgroundAgentIds.has(record.id)) this.completedBackgroundCallbacks.add(record.id);
         count++;
       }
     }
+    this.runningBackground = 0;
     return count;
   }
 
@@ -593,6 +626,8 @@ export class AgentManager {
       record.session?.dispose();
     }
     this.agents.clear();
+    this.backgroundAgentIds.clear();
+    this.completedBackgroundCallbacks.clear();
     // Prune any orphaned git worktrees (crash recovery)
     try { pruneWorktrees(process.cwd()); } catch { /* ignore */ }
     // Also prune repos that caller-supplied cwds created worktrees in — a clean

package/src/agent-runner.ts

@@ -11,6 +11,7 @@ import {
   type AgentSession,
   type AgentSessionEvent,
   createAgentSession,
+  createEventBus,
   DefaultResourceLoader,
   type ExtensionAPI,
   getAgentDir,
@@ -19,6 +20,7 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { BUILTIN_TOOL_NAMES, getAgentConfig, getConfig, getMemoryToolNames, getReadOnlyMemoryToolNames, getToolNamesForType } from "./agent-types.js";
 import { buildParentContext, extractText } from "./context.js";
+import type { EventBus } from "./cross-extension-rpc.js";
 import { DEFAULT_AGENTS } from "./default-agents.js";
 import { detectEnv } from "./env.js";
 import { buildMemoryBlock, buildReadOnlyMemoryBlock } from "./memory.js";
@@ -36,6 +38,8 @@ export const SUBAGENT_TOOL_NAMES = {
   AGENT: "Agent",
   GET_RESULT: "get_subagent_result",
   STEER: "steer_subagent",
+  LIST_SUBAGENTS: "list_subagents",
+  CLEAR_SUBAGENTS: "clear_subagents",
   LIST_MODELS: "list_models",
 } as const;
 
@@ -53,6 +57,40 @@ const RECURSIVE_TOOL_NAMES: string[] = [
 ];
 
 const EXTENSION_DEPTH_KEY = Symbol.for("pi-subagents:extension-depth");
+
+/** Lifecycle event names that should propagate from child to parent sessions. */
+const FORWARDABLE_EVENTS = new Set([
+  "subagents:created",
+  "subagents:started",
+  "subagents:completed",
+  "subagents:failed",
+  "subagents:compacted",
+]);
+
+/**
+ * Create a forwarding event bus for a child session.
+ * The child gets its own local bus for emit/on, but lifecycle events
+ * (subagents:*) are also forwarded to the parent bus so the parent widget
+ * can display depth 2+ agents.
+ */
+export function createForwardingEventBus(parentBus: EventBus): EventBus {
+  // Use the parent's EventBus factory to create a properly isolated local bus
+  const localBus = createEventBus();
+  return {
+    on(event, handler) {
+      // Subscribe to local bus only — child doesn't see parent/sibling events
+      return localBus.on(event, handler);
+    },
+    emit(event, data) {
+      // Always emit on local bus for child's own listeners
+      localBus.emit(event, data);
+      // Forward lifecycle events to parent bus for parent widget visibility
+      if (FORWARDABLE_EVENTS.has(event)) {
+        parentBus.emit(event, data);
+      }
+    },
+  };
+}
 const AUTO_EXPOSE_EXTENSION_NAMES = new Set(["pi-c2c"]);
 let extensionDepthLoadChain: Promise<void> = Promise.resolve();
 const packageNameCache = new Map<string, string[]>();
@@ -69,7 +107,12 @@ function getLoadingExtensionAgentId(): string | undefined {
   return value && typeof value.agentId === "string" ? value.agentId : undefined;
 }
 
-async function withLoadingExtensionDepth<T>(depth: number, agentId: string | undefined, fn: () => Promise<T>): Promise<T> {
+function getLoadingExtensionParentAgentId(): string | undefined {
+  const value = (globalThis as any)[EXTENSION_DEPTH_KEY];
+  return value && typeof value.parentAgentId === "string" ? value.parentAgentId : undefined;
+}
+
+async function withLoadingExtensionDepth<T>(depth: number, agentId: string | undefined, parentAgentId: string | undefined, fn: () => Promise<T>): Promise<T> {
   const previous = extensionDepthLoadChain;
   let release!: () => void;
   extensionDepthLoadChain = new Promise<void>((resolve) => {
@@ -80,7 +123,7 @@ async function withLoadingExtensionDepth<T>(depth: number, agentId: string | und
   try {
     const g = globalThis as any;
     const prev = g[EXTENSION_DEPTH_KEY];
-    g[EXTENSION_DEPTH_KEY] = { depth, agentId };
+    g[EXTENSION_DEPTH_KEY] = { depth, agentId, parentAgentId };
     try {
       return await fn();
     } finally {
@@ -100,6 +143,10 @@ export function getCurrentExtensionAgentId(): string | undefined {
   return getLoadingExtensionAgentId();
 }
 
+export function getCurrentExtensionParentAgentId(): string | undefined {
+  return getLoadingExtensionParentAgentId();
+}
+
 /**
  * Canonical name of an extension for `extensions: [...]` allowlist matching.
  * Lowercased — extension names match case-insensitively so `extensions: [Mcp]`
@@ -354,6 +401,9 @@ export interface RunOptions {
   depth?: number;
   /** Parent subagent id when spawned recursively from another subagent. */
   parentAgentId?: string;
+  /** Parent's event bus — shared with the child session so lifecycle events
+   * (subagents:created, subagents:started, etc.) propagate to the parent widget. */
+  eventBus?: EventBus;
 }
 
 export interface RunResult {
@@ -544,6 +594,11 @@ export async function runAgent(
           };
         };
 
+  // Create a forwarding event bus so the child session's lifecycle events
+  // (subagents:created, subagents:started, etc.) propagate to the parent's
+  // event bus — making depth 2+ agents visible in the parent widget.
+  const childEventBus = options.eventBus ? createForwardingEventBus(options.eventBus) : undefined;
+
   const loader = new DefaultResourceLoader({
     cwd: configCwd,
     agentDir,
@@ -556,8 +611,9 @@ export async function runAgent(
     noContextFiles: true,
     systemPromptOverride: () => systemPrompt,
     appendSystemPromptOverride: () => [],
+    eventBus: childEventBus,
   });
-  await withLoadingExtensionDepth(depth, options.agentId, () => loader.reload());
+  await withLoadingExtensionDepth(depth, options.agentId, options.parentAgentId, () => loader.reload());
 
   // Plain entries in `tools:` are expected to be built-in names (extension tools
   // go through `ext:`), so an unknown name there is unambiguously a typo. Previously

package/src/agent-tool-description.ts

@@ -44,7 +44,13 @@ const buildCompactTypeListText = () =>
 
 export interface AgentToolDescriptionOptions {
   mode: ToolDescriptionMode;
-  extensionDepth: number;
+  /**
+   * Depth at which the NEXT spawned subagent will run.
+   * This is `extensionDepth + 1` — the agent's own depth plus one.
+   * Displayed as "Current recursive depth" in the tool description so the
+   * LLM sees the depth of the agent it is about to create, not its own depth.
+   */
+  nextSubagentDepth: number;
   schedulingEnabled: boolean;
 }
 
@@ -56,7 +62,7 @@ export function buildScheduleGuideline(schedulingEnabled: boolean): string {
 
 export function buildAgentToolDescription(options: AgentToolDescriptionOptions): string {
   const scheduleGuideline = buildScheduleGuideline(options.schedulingEnabled);
-  const recursiveGuideline = `Recursive agents are allowed through depth ${MAX_RECURSIVE_DEPTH}. Current recursive depth: ${options.extensionDepth}/${MAX_RECURSIVE_DEPTH}.`;
+  const recursiveGuideline = `Recursive agents are allowed through depth ${MAX_RECURSIVE_DEPTH}. Current recursive depth: ${options.nextSubagentDepth}/${MAX_RECURSIVE_DEPTH}.`;
 
   const compactAgentToolDescription = `Launch an autonomous agent for complex, multi-step tasks. Agent types:
 ${buildCompactTypeListText()}
@@ -67,7 +73,7 @@ Notes:
 - description: 3-5 words (shown in UI). Prompts must be self-contained — the agent has not seen this conversation.
 - Parallel work: one message, multiple Agent calls; they all run in the background. You are notified when agents finish — never poll or sleep.
 - Background by default: when you have useful independent work, launch it and continue. Doing nothing while an agent runs is worse than letting background work proceed.
-- Recursive agents: current depth ${options.extensionDepth}/${MAX_RECURSIVE_DEPTH}; you may spawn subagents until depth ${MAX_RECURSIVE_DEPTH}.
+- Recursive agents: current depth ${options.nextSubagentDepth}/${MAX_RECURSIVE_DEPTH}; you may spawn subagents until depth ${MAX_RECURSIVE_DEPTH}.
 - The result is not shown to the user — summarize it for them. Verify an agent's claimed code changes before reporting work done.
 - resume continues a previous agent by ID; steer_subagent messages a running one.
 - list_models enumerates the model registry the \`model:\` param accepts — call it before picking a model explicitly.
@@ -125,7 +131,7 @@ Terse command-style prompts produce shallow, generic work.
       compactTypeList: buildCompactTypeListText,
       agentDir: getAgentDir,
       scheduleGuideline: () => scheduleGuideline,
-      currentDepth: () => String(options.extensionDepth),
+      currentDepth: () => String(options.nextSubagentDepth),
       maxDepth: () => String(MAX_RECURSIVE_DEPTH),
       recursiveGuideline: () => recursiveGuideline,
     };

package/src/cross-extension-rpc.ts

@@ -36,6 +36,10 @@ export interface RpcDeps {
   pi: unknown;                    // passed through to manager.spawn
   getCtx: () => unknown | undefined;  // returns current ExtensionContext
   manager: SpawnCapable;
+  /** Default recursive depth for RPC-spawned subagents in this session. */
+  depth?: number;
+  /** Parent subagent id for RPC-spawned subagents in this session. */
+  parentAgentId?: string;
 }
 
 export interface RpcHandle {
@@ -108,7 +112,16 @@ export function registerRpcHandlers(deps: RpcDeps): RpcHandle {
         normalizedOptions = { ...normalizedOptions, model: resolved };
       }
 
-      return { id: manager.spawn(pi, ctx, type, prompt, normalizedOptions) };
+      const spawnOptions = {
+        ...normalizedOptions,
+        eventBus: events,
+        depth: normalizedOptions.depth ?? deps.depth,
+        parentAgentId: normalizedOptions.parentAgentId ?? deps.parentAgentId,
+      };
+      if (spawnOptions.depth === undefined) delete spawnOptions.depth;
+      if (spawnOptions.parentAgentId === undefined) delete spawnOptions.parentAgentId;
+
+      return { id: manager.spawn(pi, ctx, type, prompt, spawnOptions) };
     },
   );
 

package/src/dashboard-ui.ts

@@ -0,0 +1,291 @@
+/**
+ * dashboard-ui.ts — Register dashboard UI modules for subagent visibility.
+ *
+ * Provides three integration points with pi-agent-dashboard:
+ * 1. Footer-segment decorator showing running/completed agent counts
+ * 2. Management-modal module with a table view of all subagent history
+ * 3. Round-trip event handlers for data fetch, abort, and steer actions
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { AgentManager } from "./agent-manager.js";
+import { formatMs, getDisplayName } from "./ui/agent-widget.js";
+import { getLifetimeTotal } from "./usage.js";
+
+// Dashboard shared types (inlined to avoid adding a dependency)
+interface DecoratorDescriptor {
+  kind: "footer-segment" | "agent-metric" | "breadcrumb" | "gate" | "toast";
+  namespace: string;
+  id: string;
+  payload: Record<string, unknown>;
+}
+
+interface ExtensionUiModule {
+  kind: "management-modal";
+  id: string;
+  command: string;
+  title: string;
+  description?: string;
+  icon?: string;
+  category?: string;
+  view: {
+    kind: "table" | "grid" | "form";
+    dataEvent?: string;
+    rowKey?: string;
+    fields?: Array<{
+      key: string;
+      label: string;
+      kind: string;
+      width?: string | number;
+    }>;
+    rowActions?: Array<{
+      id: string;
+      label: string;
+      icon?: string;
+      variant?: "primary" | "secondary" | "danger";
+      event: string;
+      confirm?: string;
+    }>;
+    emptyState?: string;
+    actions?: Array<{
+      id: string;
+      label: string;
+      icon?: string;
+      variant?: "primary" | "secondary" | "danger";
+      event: string;
+    }>;
+  };
+}
+
+type ModuleProbe = { modules: Array<ExtensionUiModule | DecoratorDescriptor> };
+
+const NAMESPACE = "subagents";
+const MODULE_ID = "subagents-overview";
+const DATA_EVENT = "subagents:rows";
+const INVALIDATE_DEBOUNCE_MS = 500;
+
+/**
+ * Build a row for the management-modal table from an AgentRecord.
+ */
+function buildAgentRow(record: any) {
+  const durationMs = record.completedAt
+    ? record.completedAt - record.startedAt
+    : Date.now() - record.startedAt;
+  const totalTokens = getLifetimeTotal(record.lifetimeUsage);
+
+  return {
+    id: record.id,
+    type: getDisplayName(record.type),
+    description: record.description ?? "",
+    model: record.invocation?.modelName ?? "—",
+    status: record.status,
+    toolUses: record.toolUses ?? 0,
+    tokens: totalTokens > 0 ? formatTokenCount(totalTokens) : "—",
+    duration: formatMs(durationMs),
+    outputFile: record.outputFile ?? "",
+    startedAt: record.startedAt,
+  };
+}
+
+function formatTokenCount(n: number): string {
+  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
+  if (n >= 1_000) return `${(n / 1_000).toFixed(1)}k`;
+  return String(n);
+}
+
+/**
+ * Register all dashboard UI integration points.
+ * Call once during extension setup when pi.events is available.
+ */
+export function registerDashboardModules(pi: ExtensionAPI, manager: AgentManager): void {
+  if (!pi.events) return;
+
+  let invalidateTimer: ReturnType<typeof setTimeout> | undefined;
+
+  function scheduleInvalidate() {
+    if (invalidateTimer) return;
+    invalidateTimer = setTimeout(() => {
+      invalidateTimer = undefined;
+      pi.events.emit("ui:invalidate", {});
+    }, INVALIDATE_DEBOUNCE_MS);
+  }
+
+  // ── 1. Module Discovery (ui:list-modules) ──────────────────────────
+  // Guard against duplicate pushes: the bridge may call refreshUiModules
+  // multiple times per probe cycle when multiple sessions each register
+  // their own ui:invalidate listener. Check if our modules are already
+  // present before pushing.
+  pi.events.on("ui:list-modules", ((probe: ModuleProbe) => {
+    const alreadyContributed = probe.modules.some(
+      (m: any) => m.kind === "management-modal" && m.id === MODULE_ID,
+    );
+    if (alreadyContributed) return;
+
+    const agents = manager.listAgents();
+    const running = agents.filter(a => a.status === "running").length;
+    const completed = agents.filter(a => a.status === "completed").length;
+    const total = agents.length;
+
+    // Footer-segment: running/completed counts
+    const parts: string[] = [];
+    if (running > 0) parts.push(`● ${running} running`);
+    if (completed > 0) parts.push(`✓ ${completed} done`);
+    if (total === 0) parts.push("No agents");
+
+    probe.modules.push({
+      kind: "footer-segment",
+      namespace: NAMESPACE,
+      id: "agent-counts",
+      payload: {
+        text: parts.join(" · "),
+        tooltip: `${total} total agents (${running} running, ${completed} completed)`,
+        icon: "mdiRobot",
+      },
+    } as DecoratorDescriptor);
+
+    // Management-modal: subagent overview table
+    probe.modules.push({
+      kind: "management-modal",
+      id: MODULE_ID,
+      command: "/subagents",
+      title: "Subagents",
+      description: "View and manage background subagents",
+      icon: "mdiRobotOutline",
+      category: "subagents",
+      view: {
+        kind: "table",
+        dataEvent: DATA_EVENT,
+        rowKey: "id",
+        fields: [
+          { key: "id", label: "ID", kind: "text", width: 120 },
+          { key: "type", label: "Type", kind: "text", width: 100 },
+          { key: "description", label: "Description", kind: "text" },
+          { key: "model", label: "Model", kind: "text", width: 80 },
+          { key: "status", label: "Status", kind: "text", width: 90 },
+          { key: "toolUses", label: "Tools", kind: "number", width: 60 },
+          { key: "tokens", label: "Tokens", kind: "text", width: 80 },
+          { key: "duration", label: "Duration", kind: "text", width: 80 },
+        ],
+        rowActions: [
+          {
+            id: "view-result",
+            label: "View Result",
+            icon: "mdiEye",
+            variant: "primary",
+            event: "subagents:ui:view-result",
+          },
+          {
+            id: "abort",
+            label: "Abort",
+            icon: "mdiStop",
+            variant: "danger",
+            event: "subagents:ui:abort",
+            confirm: "Abort this running agent?",
+          },
+          {
+            id: "steer",
+            label: "Steer",
+            icon: "mdiMessageArrowRight",
+            variant: "secondary",
+            event: "subagents:ui:steer",
+          },
+        ],
+        emptyState: "No subagents have been spawned in this session.",
+        actions: [
+          {
+            id: "refresh",
+            label: "Refresh",
+            icon: "mdiRefresh",
+            variant: "secondary",
+            event: "subagents:ui:refresh",
+          },
+        ],
+      },
+    } as ExtensionUiModule);
+  }) as any);
+
+  // ── 2. Data Fetch Handler ──────────────────────────────────────────
+  pi.events.on(DATA_EVENT, ((data: any) => {
+    const agents = manager.listAgents();
+    data.items = agents.map(buildAgentRow);
+  }) as any);
+
+  // ── 3. Action Handlers ─────────────────────────────────────────────
+
+  // Refresh: just invalidate to re-probe + re-fetch
+  pi.events.on("subagents:ui:refresh", (() => {
+    scheduleInvalidate();
+  }) as any);
+
+  // View Result: return the agent's result as table rows so the modal
+  // displays it. The bridge's synchronous fast path calls `_reply(items)`
+  // when `data.items` is populated by the handler — do NOT call
+  // `scheduleInvalidate()` here as the subsequent re-probe would
+  // overwrite the returned rows with the original table data.
+  pi.events.on("subagents:ui:view-result", ((data: any) => {
+    // Bridge spreads msg.params into data; row identity is at data.row.id.
+    const agentId = data.row?.id ?? data.id;
+    if (!agentId) return;
+    const record = manager.getRecord(agentId);
+    if (!record) return;
+
+    const resultText = record.result?.trim() || "No output yet.";
+    const preview = resultText.length > 2000
+      ? resultText.slice(0, 2000) + "\n…(truncated)"
+      : resultText;
+
+    // Populate data.items — the bridge's synchronous fast path forwards
+    // this as a `ui_data_list` message back to the dashboard.
+    data.items = [{
+      id: record.id,
+      type: getDisplayName(record.type),
+      description: record.description,
+      status: record.status,
+      result: preview,
+      outputFile: record.outputFile ?? "",
+    }];
+  }) as any);
+
+  // Abort: stop the running agent via the manager's abort() method
+  // which properly cancels the AbortController and cleans up state.
+  pi.events.on("subagents:ui:abort", ((data: any) => {
+    const agentId = data.row?.id ?? data.id;
+    if (!agentId) return;
+    manager.abort(agentId);
+    scheduleInvalidate();
+  }) as any);
+
+  // Steer: send a steering message to a running agent's session.
+  // The management-modal row action carries the row identity; we steer
+  // with a default "Continue" nudge. A future form view could accept
+  // custom text.
+  pi.events.on("subagents:ui:steer", ((data: any) => {
+    const agentId = data.row?.id ?? data.id;
+    if (!agentId) return;
+    const record = manager.getRecord(agentId);
+    if (!record) return;
+
+    if (record.status === "running" && record.session) {
+      // Session is live — steer immediately
+      record.session.steer("Continue").catch(() => {});
+    } else if (record.status === "queued") {
+      // Session not yet created — queue the steer for flush on start
+      if (!record.pendingSteers) record.pendingSteers = [];
+      record.pendingSteers.push("Continue");
+    }
+    scheduleInvalidate();
+  }) as any);
+
+  // ── 4. Invalidate on agent lifecycle events ────────────────────────
+  const lifecycleEvents = [
+    "subagents:created",
+    "subagents:started",
+    "subagents:completed",
+    "subagents:failed",
+    "subagents:compacted",
+  ];
+
+  for (const event of lifecycleEvents) {
+    pi.events.on(event, (() => scheduleInvalidate()) as any);
+  }
+}