pi-subagents 0.80.0 → 0.81.0

package/src/tui/fleet.js

@@ -2,6 +2,8 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { getMarkdownTheme } from "@earendil-works/pi-coding-agent";
 import { matchesKey, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { fleetContains, fleetLayout } from "./fleet-layout.js";
+import { FleetViewport } from "./fleet-viewport.js";
 import { snapshotExternalRuns } from "../api/external-runs.js";
 import { getArtifactPaths, getArtifactsDir } from "../shared/artifacts.js";
 import { formatDuration, formatModelThinking, formatTokens, formatTokenUsage, shortenPath } from "../shared/formatters.js";
@@ -746,11 +748,8 @@ export class SubagentFleetComponent {
     snapshot = { items: [] };
     selected = 0;
     selectedKey;
-    detailScroll = 0;
-    detailAutoFollow = true;
-    detailLineCount = 0;
-    detailViewportHeight = 8;
-    bodyHeight = 8;
+    viewport;
+    renderedLayout;
     expandedTools = false;
     promptAuditOpen = false;
     promptAuditView = "authored";
@@ -773,6 +772,7 @@ export class SubagentFleetComponent {
     keybindings;
     constructor(tui, theme, state, done, options = {}) {
         this.tui = tui;
+        this.viewport = new FleetViewport(() => this.tui.requestRender());
         this.theme = theme;
         this.markdownTheme = options.markdownTheme ?? getMarkdownTheme();
         this.state = state;
@@ -820,11 +820,14 @@ export class SubagentFleetComponent {
         this.selectedKey = this.snapshot.items[this.selected]?.key;
     }
     moveSelection(delta) {
-        if (this.snapshot.items.length === 0)
+        this.selectItem(Math.max(0, Math.min(this.snapshot.items.length - 1, this.selected + delta)));
+    }
+    selectItem(index) {
+        if (!this.snapshot.items[index])
             return;
-        this.selected = Math.max(0, Math.min(this.snapshot.items.length - 1, this.selected + delta));
+        this.selected = index;
         this.selectedKey = this.snapshot.items[this.selected]?.key;
-        this.detailAutoFollow = true;
+        this.viewport.follow();
         this.resetActionInput();
         this.tui.requestRender();
     }
@@ -862,8 +865,7 @@ export class SubagentFleetComponent {
             return;
         this.selected = this.snapshot.items.findIndex((item) => item.key === target.key);
         this.selectedKey = target.key;
-        this.detailScroll = 0;
-        this.detailAutoFollow = false;
+        this.viewport.resetTop();
         this.tui.requestRender();
     }
     resetActionInput() {
@@ -951,8 +953,7 @@ export class SubagentFleetComponent {
     setActionNotice(result) {
         this.actionNotice = result;
         this.resetActionInput();
-        this.detailAutoFollow = false;
-        this.detailScroll = 0;
+        this.viewport.resetTop();
         this.refresh();
         this.tui.requestRender();
     }
@@ -972,10 +973,35 @@ export class SubagentFleetComponent {
         });
     }
     scrollDetail(delta) {
-        const maxScroll = Math.max(0, this.detailLineCount - this.detailViewportHeight);
-        this.detailScroll = Math.max(0, Math.min(maxScroll, this.detailScroll + delta));
-        this.detailAutoFollow = this.detailScroll >= maxScroll;
-        this.tui.requestRender();
+        this.viewport.scroll.scrollBy(delta);
+    }
+    handleMouse(event) {
+        // Block pointer fallback as well as inspector actions while a text/confirmation modal owns input.
+        if (this.steerDraft !== undefined || this.redoGuidanceDraft !== undefined || this.stopConfirming || this.actionBusy) {
+            return { handled: true, render: false };
+        }
+        const layout = this.renderedLayout;
+        if (!layout || layout.width !== event.width || layout.rows !== (this.tui.terminal?.rows ?? 32)) {
+            // Never use hit regions from a different size; wheel must not escape to the transcript.
+            return event.type === "wheel" ? { handled: true, render: false } : undefined;
+        }
+        if (event.type === "wheel" && fleetContains(layout.output, event.x, event.y)) {
+            this.scrollDetail(event.wheelDelta ?? 0);
+            return { handled: true, render: false };
+        }
+        if (this.promptAuditOpen)
+            return { handled: true, render: false };
+        if (event.type === "click" && event.button === "left" && !event.shift && !event.alt && !event.ctrl
+            && fleetContains(layout.roster, event.x, event.y)) {
+            const key = layout.rosterKeys[event.y - layout.roster.y];
+            const index = key === undefined ? -1 : this.snapshot.items.findIndex((item) => item.key === key);
+            if (index < 0)
+                return undefined;
+            this.selectItem(index);
+            return { handled: true, render: false };
+        }
+        // Unowned wheel inside the overlay would otherwise scroll the transcript behind it.
+        return event.type === "wheel" ? { handled: true, render: false } : undefined;
     }
     handleInput(data) {
         if (this.promptAuditOpen && this.redoGuidanceDraft !== undefined) {
@@ -1012,7 +1038,7 @@ export class SubagentFleetComponent {
         if (this.promptAuditOpen) {
             if (matchesKey(data, "escape") || matchesKey(data, "ctrl+c")) {
                 this.promptAuditOpen = false;
-                this.detailAutoFollow = true;
+                this.viewport.follow();
                 this.tui.requestRender();
                 return;
             }
@@ -1022,7 +1048,7 @@ export class SubagentFleetComponent {
                 return this.movePromptSelection(-1);
             if (data === "1" || data === "2" || data === "3") {
                 this.promptAuditView = data === "1" ? "authored" : data === "2" ? "runtime" : "effective";
-                this.detailScroll = 0;
+                this.viewport.resetTop();
                 this.tui.requestRender();
                 return;
             }
@@ -1037,8 +1063,7 @@ export class SubagentFleetComponent {
                 else {
                     this.actionNotice = undefined;
                     this.redoGuidanceDraft = "";
-                    this.detailAutoFollow = false;
-                    this.detailScroll = 0;
+                    this.viewport.resetTop();
                     this.tui.requestRender();
                 }
                 return;
@@ -1061,9 +1086,9 @@ export class SubagentFleetComponent {
             if (matchesFleetAction(data, this.keybindings, "scrollDown"))
                 return this.scrollDetail(1);
             if (matchesFleetAction(data, this.keybindings, "pageUp"))
-                return this.scrollDetail(-this.detailViewportHeight);
+                return this.scrollDetail(-this.viewport.scroll.viewportHeight);
             if (matchesFleetAction(data, this.keybindings, "pageDown"))
-                return this.scrollDetail(this.detailViewportHeight);
+                return this.scrollDetail(this.viewport.scroll.viewportHeight);
             return;
         }
         if (this.steerDraft !== undefined) {
@@ -1137,9 +1162,9 @@ export class SubagentFleetComponent {
         if (matchesFleetAction(data, this.keybindings, "selectLast"))
             return this.moveSelection(this.snapshot.items.length);
         if (matchesFleetAction(data, this.keybindings, "pageUp"))
-            return this.scrollDetail(-this.detailViewportHeight);
+            return this.scrollDetail(-this.viewport.scroll.viewportHeight);
         if (matchesFleetAction(data, this.keybindings, "pageDown"))
-            return this.scrollDetail(this.detailViewportHeight);
+            return this.scrollDetail(this.viewport.scroll.viewportHeight);
         if (matchesFleetAction(data, this.keybindings, "refresh")) {
             this.transcriptCache = undefined;
             this.refresh();
@@ -1152,8 +1177,7 @@ export class SubagentFleetComponent {
             else {
                 this.promptAuditOpen = true;
                 this.promptAuditView = "authored";
-                this.detailScroll = 0;
-                this.detailAutoFollow = false;
+                this.viewport.resetTop();
                 this.actionNotice = undefined;
                 this.tui.requestRender();
             }
@@ -1166,8 +1190,7 @@ export class SubagentFleetComponent {
             else {
                 this.actionNotice = undefined;
                 this.steerDraft = "";
-                this.detailAutoFollow = false;
-                this.detailScroll = 0;
+                this.viewport.resetTop();
                 this.tui.requestRender();
             }
             return;
@@ -1179,8 +1202,7 @@ export class SubagentFleetComponent {
             else {
                 this.actionNotice = undefined;
                 this.stopConfirming = true;
-                this.detailAutoFollow = false;
-                this.detailScroll = 0;
+                this.viewport.resetTop();
                 this.tui.requestRender();
             }
             return;
@@ -1196,18 +1218,18 @@ export class SubagentFleetComponent {
             return;
         }
     }
-    rosterLines(width) {
+    rosterLines(layout) {
         if (this.snapshot.items.length === 0)
             return [this.theme.fg("dim", "No tracked children")];
-        const start = Math.max(0, Math.min(this.selected - this.bodyHeight + 1, Math.max(0, this.snapshot.items.length - this.bodyHeight)));
-        return this.snapshot.items.slice(start, start + this.bodyHeight).map((item, offset) => {
-            const index = start + offset;
+        return layout.rosterKeys.map((_key, offset) => {
+            const index = layout.rosterStart + offset;
+            const item = this.snapshot.items[index];
             const marker = index === this.selected ? this.theme.fg("accent", "›") : " ";
             const context = item.kind === "async" ? contextModeBadge(this.theme, item.step?.context ?? item.run.context) : item.kind === "foreground-recent" ? contextModeBadge(this.theme, item.child.context) : "";
             const agent = index === this.selected ? this.theme.bold(item.agent) : item.agent;
             const identity = item.runId.slice(0, 8);
             const left = `${marker} ${statusGlyph(item, this.theme)} ${agent}${context} ${this.theme.fg("dim", `· ${identity}`)}`;
-            return rightAligned(left, this.theme.fg("dim", item.state), width);
+            return rightAligned(left, this.theme.fg("dim", item.state), layout.roster.width);
         });
     }
     renderedTranscript(target, width) {
@@ -1305,26 +1327,21 @@ export class SubagentFleetComponent {
         return { header: [], body: this.withActionLines(lines) };
     }
     render(width) {
-        if (width < 36)
+        const layout = fleetLayout(width, this.tui.terminal?.rows ?? 32, this.selected, this.snapshot.items);
+        this.renderedLayout = layout;
+        if (!layout)
             return [truncateToWidth("Subagent fleet needs at least 36 columns. Esc closes.", width)];
         const innerWidth = width - 2;
-        const rows = this.tui.terminal?.rows ?? 32;
-        this.bodyHeight = Math.max(2, Math.floor(rows * 0.85) - 6);
-        const rosterWidth = Math.max(22, Math.min(46, Math.floor((innerWidth - 1) * 0.38)));
-        const detailWidth = Math.max(1, innerWidth - rosterWidth - 1);
-        const roster = this.rosterLines(rosterWidth);
+        const { bodyHeight } = layout;
+        const rosterWidth = layout.roster.width;
+        const detailWidth = layout.output.width;
+        const roster = this.rosterLines(layout);
         const detail = this.wrappedDetail(detailWidth);
-        const detailHeader = detail.header.slice(0, Math.max(0, this.bodyHeight - 1));
-        this.detailViewportHeight = Math.max(1, this.bodyHeight - detailHeader.length);
-        this.detailLineCount = detail.body.length;
-        const maxDetailScroll = Math.max(0, detail.body.length - this.detailViewportHeight);
-        if (this.detailAutoFollow)
-            this.detailScroll = maxDetailScroll;
-        else if (this.detailScroll > maxDetailScroll)
-            this.detailScroll = maxDetailScroll;
+        const detailHeader = detail.header.slice(0, Math.max(0, bodyHeight - 1));
+        const outputBodyHeight = bodyHeight - detailHeader.length;
         const visibleDetails = [
             ...detailHeader,
-            ...detail.body.slice(this.detailScroll, this.detailScroll + this.detailViewportHeight),
+            ...this.viewport.render(detail.body, detailWidth, outputBodyHeight),
         ];
         const lines = [this.theme.fg("border", `╭${"─".repeat(innerWidth)}╮`)];
         const selected = this.snapshot.items[this.selected];
@@ -1336,7 +1353,7 @@ export class SubagentFleetComponent {
             : this.theme.fg("dim", "no children ");
         lines.push(this.theme.fg("border", "│") + rightAligned(title, selectedStatus, innerWidth) + this.theme.fg("border", "│"));
         lines.push(this.theme.fg("border", `├${"─".repeat(rosterWidth)}┬${"─".repeat(detailWidth)}┤`));
-        for (let index = 0; index < this.bodyHeight; index++) {
+        for (let index = 0; index < bodyHeight; index++) {
             lines.push(this.theme.fg("border", "│")
                 + fit(roster[index] ?? "", rosterWidth)
                 + this.theme.fg("border", "│")
@@ -1355,6 +1372,7 @@ export class SubagentFleetComponent {
         return lines.map((line) => truncateToWidth(line, width));
     }
     invalidate() {
+        this.renderedLayout = undefined;
         this.transcriptCache = undefined;
         this.refresh();
     }

package/src/workflows/structured-workflow-scripts.d.ts

@@ -4,6 +4,7 @@
  * and never becomes code. Scripts run on the ordinary workflow runtime.
  */
 export type StructuredWorkflowKind = "tasks" | "chain";
+export declare const TOP_LEVEL_CONTROLS_HINT = " Put worktree and other child controls on the subagent call itself; they apply to every child.";
 export declare function isPlainRecord(value: unknown): value is Record<string, unknown>;
 /** Validate exact data shapes and expand them into a package-owned workflow script. */
 export declare function buildStructuredWorkflowScript(kind: StructuredWorkflowKind, steps: unknown, originalTask: string | undefined): string;

package/src/workflows/structured-workflow-scripts.js

@@ -7,6 +7,7 @@ const OUTPUT_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
 const PLACEHOLDER_PATTERN = /\{(?:task|previous|outputs\.([A-Za-z_][A-Za-z0-9_]*))\}/g;
 /** Optional per-child launch fields copied verbatim onto the generated runs.all item. */
 const CHILD_FIELDS = ["cwd", "model"];
+export const TOP_LEVEL_CONTROLS_HINT = " Put worktree and other child controls on the subagent call itself; they apply to every child.";
 export function isPlainRecord(value) {
     if (!value || typeof value !== "object" || Array.isArray(value))
         return false;
@@ -97,7 +98,7 @@ function buildTasksScript(steps, originalTask) {
         throw new Error("tasks must be a non-empty array of { agent, task } items.");
     const children = steps.map((item, index) => {
         const path = `tasks[${index}]`;
-        const record = exactFields(item, path, ["agent", "task", ...CHILD_FIELDS], "Each tasks item accepts agent and task, plus optional cwd and model.");
+        const record = exactFields(item, path, ["agent", "task", ...CHILD_FIELDS], `Each tasks item accepts agent and task, plus optional cwd and model.${TOP_LEVEL_CONTROLS_HINT}`);
         const agent = nonEmptyString(record.agent, `${path}.agent`);
         const task = nonEmptyString(record.task, `${path}.task`);
         const taskExpression = compileTemplate(task, {
@@ -131,20 +132,20 @@ function buildChainScript(steps, originalTask) {
         let stepChildren;
         let outputName;
         if (isPlainRecord(step) && Object.hasOwn(step, "parallel")) {
-            const record = exactFields(step, path, ["parallel"], "A parallel step accepts only parallel; as is supported on sequential steps only.");
+            const record = exactFields(step, path, ["parallel"], `A parallel step accepts only parallel; as is supported on sequential steps only.${TOP_LEVEL_CONTROLS_HINT}`);
             const items = record.parallel;
             if (!Array.isArray(items) || items.length === 0)
                 throw new Error(`${path}.parallel must be a non-empty array of { agent, task } items.`);
             stepChildren = items.map((item, itemIndex) => {
                 const itemPath = `${path}.parallel[${itemIndex}]`;
-                const itemRecord = exactFields(item, itemPath, ["agent", "task", ...CHILD_FIELDS], "Each parallel item accepts agent and task, plus optional cwd and model.");
+                const itemRecord = exactFields(item, itemPath, ["agent", "task", ...CHILD_FIELDS], `Each parallel item accepts agent and task, plus optional cwd and model.${TOP_LEVEL_CONTROLS_HINT}`);
                 const agent = nonEmptyString(itemRecord.agent, `${itemPath}.agent`);
                 const task = nonEmptyString(itemRecord.task, `${itemPath}.task`);
                 return { key: `step-${number}-${itemIndex + 1}`, agent, fields: childFields(itemRecord, itemPath), taskExpression: compileTemplate(task, { path: `${itemPath}.task`, hasOriginalTask, previous, outputs }) };
             });
         }
         else {
-            const record = exactFields(step, path, ["agent", "task", "as", ...CHILD_FIELDS], "A sequential step accepts agent, task, as, cwd and model; a parallel step accepts only parallel.");
+            const record = exactFields(step, path, ["agent", "task", "as", ...CHILD_FIELDS], `A sequential step accepts agent, task, as, cwd and model; a parallel step accepts only parallel.${TOP_LEVEL_CONTROLS_HINT}`);
             const agent = nonEmptyString(record.agent, `${path}.agent`);
             let task;
             if (record.task === undefined) {

package/src/workflows/workflow-resources.js

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { stableJsonDigest } from "../shared/launch-contract.js";
 import { createWorkflowResourcePermit, } from "../shared/workflow-child-permit.js";
-import { buildStructuredWorkflowScript, isPlainRecord } from "./structured-workflow-scripts.js";
+import { buildStructuredWorkflowScript, isPlainRecord, TOP_LEVEL_CONTROLS_HINT } from "./structured-workflow-scripts.js";
 const RESOURCE_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 export const MAX_ARGS_BYTES = 16 * 1024;
 export const MAX_ARGS_FIELDS = 16;
@@ -152,7 +152,7 @@ function resolveRunCi(args) {
 function resolveParallel(args) {
     const unsupported = Object.keys(args).filter((key) => key !== "tasks");
     if (unsupported.length > 0)
-        return { error: `workflow 'parallel' args contain unsupported fields: ${unsupported.join(", ")}. Pass args.tasks: [{ agent, task, cwd?, model? }, ...].` };
+        return { error: `workflow 'parallel' args contain unsupported fields: ${unsupported.join(", ")}. Pass args.tasks: [{ agent, task, cwd?, model? }, ...].${TOP_LEVEL_CONTROLS_HINT}` };
     try {
         return { script: buildStructuredWorkflowScript("tasks", args.tasks, undefined) };
     }