@ian-pascoe/pi-minimal-subagents 0.18.0 → 0.19.0

package/README.md

@@ -433,6 +433,13 @@ process-local fork handoff is lost, recovery reads only the destination's
 selected branch and proceeds only when its canonical `parentSession` proves the
 source file; it never substitutes the source session's newer head.
 
+Every child session also carries an Agent Lineage Record, defined by
+`@ian-pascoe/pi-utils/agent-lineage`, naming its own session, its Root Agent's
+session, its agent ID, and its parent agent. Other extensions read it to find a
+Child Agent's ancestors and descendants without depending on this package; it
+grants them nothing. A fork clone writes its own record when its destination
+adopts it. Children created before the record existed have none.
+
 ## Tool annotations
 
 The coordinator tools declare MCP-style `annotations`, which Pi reports through `pi.getAllTools()` for permission extensions and does not send to model providers. `subagent` is destructive and open-world because a Child Agent can use any tool it is granted. `agent_message` is not read-only but is non-destructive and closed-world. `subagent_cancel` is non-destructive and idempotent; `subagent_delete` is destructive and idempotent. `subagent_status` and `subagent_wait` are read-only (`subagent_wait` consumes queued deliveries, so it is not idempotent).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ian-pascoe/pi-minimal-subagents",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "private": false,
   "description": "Persistent nested subagents with bounded delegation for Pi",
   "keywords": [
@@ -31,7 +31,7 @@
     "provenance": true
   },
   "dependencies": {
-    "@ian-pascoe/pi-utils": "^0.6.0",
+    "@ian-pascoe/pi-utils": "^0.7.0",
     "minimatch": "^10.2.6"
   },
   "peerDependencies": {

package/src/minimal-subagents-sessions.ts

@@ -21,6 +21,12 @@ import {
   type SessionEntry,
   type ToolDefinition,
 } from "@earendil-works/pi-coding-agent";
+import {
+  AGENT_LINEAGE_ENTRY_TYPE,
+  agentLineageRecord,
+  readAgentLineage,
+  type AgentLineage,
+} from "@ian-pascoe/pi-utils/agent-lineage";
 import type { Static, TSchema } from "typebox";
 import { Value } from "typebox/value";
 import {
@@ -284,6 +290,20 @@ function appendImportedMessage(sessionManager: SessionManager, message: AgentMes
   sessionManager.appendMessage(message as Parameters<SessionManager["appendMessage"]>[0]);
 }
 
+/** The shared Agent Lineage of a child session, readable by packages that do not import this one. */
+function agentLineage(
+  agent: PersistedAgent,
+  rootSessionId: string,
+  sessionId: string,
+): AgentLineage {
+  return {
+    sessionId,
+    rootSessionId,
+    agentId: agent.agent_id,
+    parentAgentId: agent.parent_id === "root" ? null : agent.parent_id,
+  };
+}
+
 /** Create and force-flush a writable child JSONL identity before its first model response. */
 export function createPersistentChildIdentity(
   options: PersistentIdentityOptions,
@@ -296,6 +316,12 @@ export function createPersistentChildIdentity(
     direct_parent_id: options.agent.parent_id,
     created_at: options.agent.created_at,
   });
+  sessionManager.appendCustomEntry(
+    AGENT_LINEAGE_ENTRY_TYPE,
+    agentLineageRecord(
+      agentLineage(options.agent, options.rootSessionId, sessionManager.getSessionId()),
+    ),
+  );
   sessionManager.appendSessionInfo(`[subagent] ${options.agent.agent_id}`);
   sessionManager.appendModelChange(
     options.agent.launch_contract.model.slice(0, options.agent.launch_contract.model.indexOf("/")),
@@ -1043,6 +1069,15 @@ export class PiAgentSessionFactory implements AgentSessionFactory {
         direct_parent_id: agent.parent_id,
       });
     }
+    // A clone inherits its source's record, which names the source session; record this one's own.
+    const lineage = agentLineage(agent, this.options.rootSessionId, sessionManager.getSessionId());
+    const recorded = readAgentLineage(lineage.sessionId, sessionManager.getBranch());
+    if (
+      recorded?.rootSessionId !== lineage.rootSessionId ||
+      recorded.agentId !== lineage.agentId ||
+      recorded.parentAgentId !== lineage.parentAgentId
+    )
+      sessionManager.appendCustomEntry(AGENT_LINEAGE_ENTRY_TYPE, agentLineageRecord(lineage));
     return {
       sessionFile,
       sessionId: sessionManager.getSessionId(),

package/src/minimal-subagents-status-panel.ts

@@ -13,6 +13,8 @@ import {
   type Component,
   type OverlayHandle,
   type TUI,
+  type TuiMouseEvent,
+  type TuiMouseEventResult,
 } from "@earendil-works/pi-tui";
 import { hintLine, joinInline, noticeText } from "@ian-pascoe/pi-utils/ui";
 import type { MinimalSubagentsCoordinator } from "./minimal-subagents-coordinator.js";
@@ -143,6 +145,9 @@ export class MinimalSubagentsStatusPanelComponent implements Component {
   private transcriptLayout?: TranscriptLayout;
   private readonly transcriptCache = createTranscriptRenderCache();
   private bodyHeight = 1;
+  /** Panel row of the first body line in the last render; undefined when no body was drawn. */
+  private bodyTop?: number;
+  private mousePressedAgentId?: string;
   private ensureSelectionVisible = true;
   private toolOutputExpanded = false;
   private disposed = false;
@@ -204,6 +209,50 @@ export class MinimalSubagentsStatusPanelComponent implements Component {
     this.tui.requestRender();
   }
 
+  /**
+   * Handle the mouse like Pi's SelectList. The wheel mirrors the arrow keys: one row of selection
+   * per event in the tree, the wheel's logical lines in the transcript. In the tree, pressing a
+   * row selects it and clicking it opens its transcript. Other events stay unhandled so Pi's
+   * screen text selection still copies transcript text.
+   */
+  handleMouse(event: TuiMouseEvent): TuiMouseEventResult | undefined {
+    if (event.type === "wheel") {
+      if (!event.wheelDelta) return undefined;
+      this.moveSelection(
+        this.view === "transcript" ? event.wheelDelta : Math.sign(event.wheelDelta),
+      );
+      return { handled: true };
+    }
+    if (this.view !== "tree" || event.button !== "left") return undefined;
+    if (event.type === "press") {
+      const agentId = this.agentIdAtRow(event.y);
+      this.mousePressedAgentId = agentId;
+      if (!agentId) return undefined;
+      this.selectedAgentId = agentId;
+      this.ensureSelectionVisible = true;
+      return { handled: true, focus: true };
+    }
+    if (event.type === "click") {
+      const agentId = this.mousePressedAgentId ?? this.agentIdAtRow(event.y);
+      this.mousePressedAgentId = undefined;
+      if (!agentId || !this.flattened.some(({ agent }) => agent.agent_id === agentId)) {
+        return undefined;
+      }
+      this.selectedAgentId = agentId;
+      this.openSelectedTranscript();
+      return { handled: true };
+    }
+    return undefined;
+  }
+
+  /** The Child Agent drawn on a panel row in the tree, if any. */
+  private agentIdAtRow(row: number): string | undefined {
+    if (this.bodyTop === undefined) return undefined;
+    const bodyRow = row - this.bodyTop;
+    if (bodyRow < 0 || bodyRow >= this.bodyHeight) return undefined;
+    return this.flattened[this.scrollOffset + bodyRow]?.agent.agent_id;
+  }
+
   /** Render the tree or Child Session Transcript in Pi's selector frame, within the terminal. */
   render(width: number): string[] {
     if (width <= 0) return [];
@@ -214,6 +263,7 @@ export class MinimalSubagentsStatusPanelComponent implements Component {
         this.tui.terminal.rows - 2 * STATUS_PANEL_MARGIN,
       ),
     );
+    this.bodyTop = undefined;
     if (width < 6 || height < 5) {
       const cancelKey = this.keybindings.getKeys("tui.select.cancel").join("/");
       return new Text(this.theme.fg("muted", `${cancelKey} back · Enlarge terminal`), 0, 0)
@@ -235,6 +285,8 @@ export class MinimalSubagentsStatusPanelComponent implements Component {
     ].slice(0, Math.min(3, height - 4));
     const visibleHeader = header.slice(0, Math.max(1, height - help.length - 3));
     this.bodyHeight = Math.max(1, height - 2 - visibleHeader.length - help.length);
+    // The top border precedes the header.
+    this.bodyTop = 1 + visibleHeader.length;
     let body: string[];
     if (transcriptView) {
       const layout = renderTranscriptSnapshot(