@bacnh85/pi-subagent 0.15.1 → 0.15.3

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.15.3 (2026-08-20)
+ ### Improvements
+- Timeouts have been extracted as Environment Variables enabling overriding.
+- `PI_SUBAGENT_INACTIVITY_TIMEOUT_MINS` default : 3 Mins
+- `PI_SUBAGENT_HARD_TIMEOUT_MINS` default: 20 Mins
+
+## 0.15.2 (2026-08-18)
+
+### Improvements
+
+- Colored borders around thread viewer overlay using agent color.
+- Colored scroll-indicator arrows (↑/↓) matching agent color.
+- Scroll offset only resets when switching to a different thread, not on every refresh.
+
 ## 0.15.1 (2026-08-17)
 
 ### Improvements

package/README.md

@@ -140,8 +140,8 @@ each writes into its own checkout.
 
 Every child execution receives a timeout:
 
-- **Default inactivity window:** 3 minutes (`DEFAULT_TIMEOUT_MS`); real SDK lifecycle activity resets it.
-- **Absolute cap:** 20 minutes for every child, even when active.
+- **Default inactivity window:** 3 minutes (`DEFAULT_TIMEOUT_MS`); real SDK lifecycle activity resets it.  Overridable with Environment Variable `PI_SUBAGENT_INACTIVITY_TIMEOUT_MINS` 
+- **Absolute cap:** Default 20 minutes for every child, even when active. Overridable with Environment variable `PI_SUBAGENT_HARD_TIMEOUT_MINS` 
 - **Maximum requested inactivity window:** 60 minutes (`MAX_TIMEOUT_MS`); values must be positive integers.
 - Timeout diagnostics distinguish `Idle timeout` from `Hard timeout` and parent cancellation.
 - 30-second progress heartbeats only keep the parent transport alive; they never reset inactivity.

package/extensions/index.ts

@@ -39,6 +39,7 @@ import {
   startHeartbeat,
 } from "./runner.ts";
 import {
+  flushWarnings,
   isRateLimitError,
   normalizeTimeout,
   resolveSafeCwd,
@@ -107,14 +108,14 @@ const TaskItem = Type.Object({
   agent: Type.String({ description: "Name of the agent to invoke" }),
   task: Type.String({ description: "Task to delegate to the agent" }),
   cwd: Type.Optional(Type.String({ description: "Working directory for the agent" })),
-  timeout: Type.Optional(Type.Number({ description: "Inactivity timeout in milliseconds for this task; real child activity resets it (default 3 minutes, absolute cap 20 minutes)" })),
+  timeout: Type.Optional(Type.Number({ description: "Inactivity timeout in ms; aborts on no activity within timeout. Default: 3 min (PI_SUBAGENT_INACTIVITY_TIMEOUT_MINS). The agent always has a lifetime cap: default 20 min  or (PI_SUBAGENT_HARD_TIMEOUT_MINS)." })),
 });
 
 const ChainItem = Type.Object({
   agent: Type.String({ description: "Name of the agent to invoke" }),
   task: Type.String({ description: "Task with optional {previous} placeholder for prior output" }),
   cwd: Type.Optional(Type.String({ description: "Working directory for the agent" })),
-  timeout: Type.Optional(Type.Number({ description: "Inactivity timeout in milliseconds for this step; real child activity resets it (default 3 minutes, absolute cap 20 minutes)" })),
+  timeout: Type.Optional(Type.Number({ description: "Inactivity timeout in ms; aborts on no activity within timeout. Default: 3 min (PI_SUBAGENT_INACTIVITY_TIMEOUT_MINS). The agent always has a lifetime cap: default 20 min or (PI_SUBAGENT_HARD_TIMEOUT_MINS)." })),
 });
 
 const AgentScopeSchema = StringEnum(["user", "project", "both"] as const, {
@@ -153,7 +154,7 @@ const SubagentParams = Type.Object({
   // Project-agent confirmation is enforced via trusted configuration.
   // See Security model section in README.
   cwd: Type.Optional(Type.String({ description: "Working directory (single mode, must be inside workspace)" })),
-  timeout: Type.Optional(Type.Number({ description: "Global inactivity timeout in milliseconds (default 3 minutes; real activity resets it; fixed 20-minute absolute cap)" })),
+  timeout: Type.Optional(Type.Number({ description: "Inactivity timeout for the whole run, in ms; resets on activity, aborts on silence. Default 3 min (PI_SUBAGENT_INACTIVITY_TIMEOUT_MINS). Lifetime cap: 20 min or (PI_SUBAGENT_HARD_TIMEOUT_MINS)." })),
   instructions: Type.Optional(Type.String({ description: "Bounded repository/task instructions passed to each child (max 16 KB)" })),
   abortOnFailure: Type.Optional(Type.Boolean({ description: "In parallel mode, cancel remaining tasks when one fails. Default: false.", default: false })),
 });
@@ -477,6 +478,11 @@ export default function (pi: ExtensionAPI) {
       "Use /subagent to list all available agents or /subagent <name> for agent details.",
     ],
     async execute(_toolCallId, params, signal, onUpdate, ctx) {
+      // Surface env-var timeout warnings collected at module load. The
+      // interactive TUI swallows module-load stderr, so notify on launch.
+      for (const msg of flushWarnings()) {
+        ctx.ui?.notify?.(msg, "warning");
+      }
       const agentScope: AgentScope = params.agentScope ?? "user";
       const discovery = discoverAgents(ctx.cwd, agentScope, bundledAgentsDir);
       const agents = discovery.agents;
@@ -1711,4 +1717,4 @@ export default function (pi: ExtensionAPI) {
       }
     }, { overlay: true, overlayOptions: { maxHeight: "70%" } }); // Overlay: editor stays visible below
   }
-}
+}

package/extensions/runner.ts

@@ -30,6 +30,8 @@ import {
   classifyStopReason,
   createCombinedAbortSignal,
   type SubagentStatus,
+  DEFAULT_TIMEOUT_MS,
+  HARD_TIMEOUT_MS,
 } from "./security.ts";
 
 // ---------------------------------------------------------------------------
@@ -46,8 +48,10 @@ export interface UsageStats {
   turns: number;
 }
 
-export const DEFAULT_INACTIVITY_TIMEOUT_MS = 3 * 60 * 1000;
-export const HARD_TIMEOUT_MS = 20 * 60 * 1000;
+/** Re-export from security.ts — single source of truth for both timeouts. */
+export const DEFAULT_INACTIVITY_TIMEOUT_MS = DEFAULT_TIMEOUT_MS;
+export { HARD_TIMEOUT_MS };
+
 
 // ---------------------------------------------------------------------------
 // Extension resource loader

package/extensions/security.ts

@@ -65,10 +65,57 @@ export const MUTATION_TOOLS: readonly string[] = ["edit", "write"];
 export const EXECUTION_TOOLS: readonly string[] = ["bash"];
 
 /**
- * Default inactivity timeout. Real SDK lifecycle activity resets this window;
- * the runner separately enforces a fixed 20-minute absolute cap.
+ * Generic warning sink for configuration problems. Stderr so it is visible
+ * with or without a TUI attached. Warnings are also buffered so the extension
+ * host can surface them as TUI notifications — the interactive TUI swallows
+ * module-load stderr, so module-load warnings alone are invisible in-TUI.
+ */
+const warnings: string[] = [];
+function warn(message: string): void {
+  process.stderr.write(`[pi-subagent] ${message}\n`);
+  warnings.push(message);
+}
+
+/**
+ * Flush env-var config warnings collected at module load. Called once from
+ * the /subagent tool handler so the warnings surface as TUI notifications
+ * (module-load stderr is not visible inside the interactive TUI).
  */
-export const DEFAULT_TIMEOUT_MS = 3 * 60 * 1_000; // 3 minutes
+export function flushWarnings(): string[] {
+  return warnings.splice(0, warnings.length);
+}
+
+/**
+ * Read a numeric value from an env var, with validation:
+ * - undefined/empty -> defaultValue (no warning)
+ * - not a finite number (NaN) -> defaultValue + warning
+ * - below `min` -> `min` + warning
+ * - above `max` -> `max` + warning
+ * - otherwise -> the parsed value (no warning)
+ */
+export function getNumericEnvVar(
+  envVar: string,
+  defaultValue: number,
+  min: number,
+  max: number,
+): number {
+  const raw = process.env[envVar];
+  if (raw === undefined || raw === "") return defaultValue;
+  const value = Number(raw);
+  if (!Number.isFinite(value)) {
+    warn(`ENV VAR: ${envVar}="${raw}" is not a number; using default ${defaultValue}.`);
+    return defaultValue;
+  }
+  if (value < min) {
+    warn(`ENV VAR: ${envVar}=${value} is below the minimum of ${min}; using ${min}.`);
+    return min;
+  }
+  if (value > max) {
+    warn(`ENV VAR: ${envVar}=${value} is above the maximum of ${max}; using ${max}.`);
+    return max;
+  }
+  return value;
+}
 
 /**
  * Absolute maximum timeout. Any requested value above this cap is rejected
@@ -76,6 +123,35 @@ export const DEFAULT_TIMEOUT_MS = 3 * 60 * 1_000; // 3 minutes
  */
 export const MAX_TIMEOUT_MS = 60 * 60 * 1_000; // 60 minutes
 
+/**
+ * Timeout caps, in minutes, shared by getNumericEnvVar for both env vars.
+ * No timeout may be shorter than 1 minute; the inactivity window may not
+ * exceed the 60-minute absolute maximum.
+ */
+const MIN_TIMEOUT_MINS = 1;
+const MAX_TIMEOUT_MINS = MAX_TIMEOUT_MS / 60_000;
+
+/**
+ * Default inactivity timeout. Real SDK lifecycle activity resets this window;
+ * the runner enforces a fixed absolute cap (HARD_TIMEOUT_MS).
+ *
+ * Reads PI_SUBAGENT_INACTIVITY_TIMEOUT_MINS (default 3 min, range 1–60) and
+ * PI_SUBAGENT_HARD_TIMEOUT_MINS (default 20 min, range 1–60) from env via
+ * getNumericEnvVar, which warns on invalid/out-of-range values. The hard cap
+ * is additionally clamped up to the inactivity window: a lifetime cap smaller
+ * than the idle window is nonsensical.
+ */
+const INACTIVITY_TIMEOUT_MINS = getNumericEnvVar("PI_SUBAGENT_INACTIVITY_TIMEOUT_MINS", 3, MIN_TIMEOUT_MINS, MAX_TIMEOUT_MINS);
+let hardTimeoutMins = getNumericEnvVar("PI_SUBAGENT_HARD_TIMEOUT_MINS", 20, MIN_TIMEOUT_MINS, MAX_TIMEOUT_MINS);
+if (hardTimeoutMins < INACTIVITY_TIMEOUT_MINS) {
+  warn(
+    `PI_SUBAGENT_HARD_TIMEOUT_MINS (${hardTimeoutMins}) is below the inactivity window (${INACTIVITY_TIMEOUT_MINS}); raising hard cap to ${INACTIVITY_TIMEOUT_MINS}.`,
+  );
+  hardTimeoutMins = INACTIVITY_TIMEOUT_MINS;
+}
+export const DEFAULT_TIMEOUT_MS = INACTIVITY_TIMEOUT_MINS * 60 * 1_000;
+export const HARD_TIMEOUT_MS = hardTimeoutMins * 60 * 1_000;
+
 // ---------------------------------------------------------------------------
 // Canonical result status
 // ---------------------------------------------------------------------------

package/extensions/thread-viewer.ts

@@ -35,6 +35,12 @@ export interface ThreadViewerCallbacks {
 
 /** Viewport height for the overlay (estimated lines). Must be > 3. */
 const OVERLAY_HEIGHT = 24;
+const borderSize = 1;
+const truncateFit = function (text: string, width: number): string {
+  text = " " + text;
+  return truncateToWidth(text, width - ((borderSize*2) +1), "...", true) + " ";
+
+  }
 
 export class ThreadViewer {
   private thread: SubagentThread;
@@ -44,13 +50,17 @@ export class ThreadViewer {
   private cachedWidth?: number;
   private cachedUpdatedAt?: number;
   private cachedLines?: string[];
+  private lastThreadId: string | null = null;
 
   constructor(thread: SubagentThread, callbacks: ThreadViewerCallbacks, theme: ViewerTheme) {
     this.thread = thread;
     this.callbacks = callbacks;
     this.theme = theme;
+    this.lastThreadId = thread.id;
+
   }
 
+
   handleInput(data: string): void {
     if (matchesKey(data, Key.escape)) {
       this.callbacks.onClose();
@@ -58,14 +68,12 @@ export class ThreadViewer {
     }
     if (matchesKey(data, Key.alt("left"))) {
       if (this.callbacks.hasPrev) {
-        this.scrollOffset = 0;
         this.callbacks.onPrev();
       }
       return;
     }
     if (matchesKey(data, Key.alt("right"))) {
       if (this.callbacks.hasNext) {
-        this.scrollOffset = 0;
         this.callbacks.onNext();
       }
       return;
@@ -131,19 +139,19 @@ export class ThreadViewer {
       const reasonColor = result.stopReason === "timeout" ? "warning" : "error";
       header += ` ${t.fg(reasonColor, `[${result.stopReason}]`)}`;
     }
-    lines.push(truncateToWidth(header, width));
+    lines.push(truncateFit(header, width));
 
     // Error message
     if (result && isErr && result.errorMessage) {
       const msgColor = result.stopReason === "timeout" ? "warning" : "error";
-      lines.push(truncateToWidth(t.fg(msgColor, `Error: ${result.errorMessage}`), width));
+      lines.push(truncateFit(t.fg(msgColor, `Error: ${result.errorMessage}`), width));
     }
 
     lines.push("");
 
     // Task
-    lines.push(truncateToWidth(t.fg("muted", "─── Task ───"), width));
-    lines.push(truncateToWidth(t.fg("dim", this.thread.task), width));
+    lines.push(truncateFit(t.fg("muted", "─── Task ───"), width));
+    lines.push(truncateFit(t.fg("dim", this.thread.task), width));
     lines.push("");
 
     if (status === "running") {
@@ -152,18 +160,18 @@ export class ThreadViewer {
       const activity = this.thread.lastActivityAt ? `${Math.floor((now - this.thread.lastActivityAt) / 1000)}s ago (${this.thread.lastActivityLabel})` : "none yet";
       const idleMs = this.thread.inactivityDeadline ? this.thread.inactivityDeadline - now : 0;
       const idle = this.thread.inactivityDeadline ? `${Math.max(0, Math.ceil(idleMs / 1000))}s remaining` : "pending";
-      lines.push(truncateToWidth(t.fg(idleMs < 30_000 ? "warning" : "muted", `Elapsed ${elapsed}s · last activity ${activity} · idle ${idle}`), width));
+      lines.push(truncateFit(t.fg(idleMs < 30_000 ? "warning" : "muted", `Elapsed ${elapsed}s · last activity ${activity} · idle ${idle}`), width));
     }
     if (status === "running" && (!result || result.messages.length === 0)) {
-      lines.push(truncateToWidth(t.fg("muted", "(waiting for first message...)"), width));
+      lines.push(truncateFit(t.fg("muted", "(waiting for first message...)"), width));
     } else if (result) {
       const displayItems = getDisplayItems(result.messages);
       const finalOutput = getFinalOutput(result.messages);
 
-      lines.push(truncateToWidth(t.fg("muted", "─── Output ───"), width));
+      lines.push(truncateFit(t.fg("muted", "─── Output ───"), width));
 
       if (displayItems.length === 0 && !finalOutput) {
-        lines.push(truncateToWidth(t.fg("muted", "(no output)"), width));
+        lines.push(truncateFit(t.fg("muted", "(no output)"), width));
       } else {
         const mdTheme = getMarkdownTheme();
 
@@ -171,7 +179,7 @@ export class ThreadViewer {
         for (const item of displayItems) {
           if (item.type === "toolCall") {
             lines.push(
-              truncateToWidth(
+              truncateFit(
                 t.fg("muted", "→ ") + formatToolCall(item.name, item.args, t.fg.bind(t)),
                 width,
               ),
@@ -182,7 +190,7 @@ export class ThreadViewer {
             const md = new Markdown(item.text.trim(), 0, 0, mdTheme);
             const mdLines = md.render(contentWidth);
             for (const mdLine of mdLines) {
-              lines.push(`  ${truncateToWidth(mdLine, contentWidth)}`);
+              lines.push(`  ${truncateFit(mdLine, contentWidth)}`);
             }
           }
         }
@@ -194,7 +202,7 @@ export class ThreadViewer {
           const contentWidth = Math.max(1, width - 2);
           const md = new Markdown(finalOutput.trim(), 0, 0, mdTheme);
           for (const mdLine of md.render(contentWidth)) {
-            lines.push(`  ${truncateToWidth(mdLine, contentWidth)}`);
+            lines.push(`  ${truncateFit(mdLine, contentWidth)}`);
           }
         }
       }
@@ -203,7 +211,7 @@ export class ThreadViewer {
       const usageStr = formatUsageStats(result.usage, result.model);
       if (usageStr) {
         lines.push("");
-        lines.push(truncateToWidth(t.fg("dim", usageStr), width));
+        lines.push(truncateFit(t.fg("dim", usageStr), width));
       }
     }
 
@@ -215,7 +223,7 @@ export class ThreadViewer {
     if (this.callbacks.hasPrev) navParts.push("alt+← prev");
     if (this.callbacks.hasNext) navParts.push("alt+→ next");
     navParts.push("↑↓ scroll");
-    lines.push(truncateToWidth(t.fg("dim", navParts.join(" · ")), width));
+    lines.push(truncateFit(t.fg("dim", navParts.join(" · ")), width));
 
     this.cachedLines = lines;
     this.cachedWidth = width;
@@ -227,6 +235,7 @@ export class ThreadViewer {
   private renderVisible(allLines: string[], width: number): string[] {
     const total = allLines.length;
     const maxVisible = Math.max(3, OVERLAY_HEIGHT);
+    const color = this.thread.color ?? "accent";
 
     // Clamp scrollOffset so the last page shows a full viewport minus one indicator line
     const maxOffset =
@@ -246,21 +255,47 @@ export class ThreadViewer {
 
     // Scroll indicator at top
     if (aboveShown) {
-      visible.unshift(truncateToWidth(
-        this.theme.fg("muted", `↑ ${offset} more lines above`),
+      const abmsg = this.theme.fg(color, `↑ ${offset}`) + this.theme.fg("muted", ` more lines above`);
+      visible.unshift(truncateFit(
+        abmsg,
         width,
       ));
     }
     // Scroll indicator at bottom
     if (belowShown) {
       const remaining = total - offset - bodyHeight;
-      visible.push(truncateToWidth(
-        this.theme.fg("muted", `↓ ${remaining} more lines below`),
+      const remmsg = this.theme.fg(color, `↓ ${remaining}`) + this.theme.fg("muted", ` more lines below`);
+        visible.push(truncateFit(
+        remmsg,
         width,
       ));
     }
 
-    return visible;
+    // Add border around the visible content
+    const borderWidth = width - 2;
+    const borderedLines: string[] = [];
+
+
+    // Top border with colored characters
+    const borderColor = this.theme.fg(color, "─");
+    const cornerColor = this.theme.fg(color, "┌");
+    const bottomCornerColor = this.theme.fg(color, "└");
+    const sideBorder = this.theme.fg(color, "│");
+    borderedLines.push(cornerColor + borderColor.repeat(borderWidth) + this.theme.fg(color, "┐"));
+
+    // Content with side borders
+    for (const line of visible) {
+      let borderedLine = sideBorder + line + sideBorder;
+      if (line.trim() === "") {
+      borderedLine = sideBorder + " ".repeat(Math.max(0, width - ( borderSize * 2))) + sideBorder;
+      }
+      borderedLines.push(borderedLine);
+    }
+
+    // Bottom border with colored characters
+    borderedLines.push(bottomCornerColor + borderColor.repeat(borderWidth) + this.theme.fg(color, "┘"));
+
+    return borderedLines;
   }
 
   invalidate(): void {
@@ -273,7 +308,11 @@ export class ThreadViewer {
   setThread(thread: SubagentThread, callbacks: ThreadViewerCallbacks): void {
     this.thread = thread;
     this.callbacks = callbacks;
-    this.scrollOffset = 0;
+    // Only reset scrollOffset when switching to a different thread
+    if (this.lastThreadId !== thread.id) {
+      this.scrollOffset = 0;
+      this.lastThreadId = thread.id;
+    }
     this.invalidate();
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bacnh85/pi-subagent",
-  "version": "0.15.1",
+  "version": "0.15.3",
   "description": "In-process subagents for Pi with isolated SDK sessions, parallel and chained delegation, and inspectable threads.",
   "type": "module",
   "license": "MIT",
@@ -73,9 +73,15 @@
     "@earendil-works/pi-tui": "^0.84.0",
     "@types/mocha": "^10.0.10",
     "@types/node": "^20.19.43",
-    "mocha": "^10.8.2",
+    "mocha": "^11.8.0",
     "tsx": "^4.22.4",
     "typescript": "^5.9.3",
     "typebox": "^1.3.1"
+  },
+  "overrides": {
+    "serialize-javascript@>=5.0.0 <7.0.5": "^7.0.5",
+    "js-yaml@>=4.0.0 <4.3.1": "^4.3.1",
+    "brace-expansion@>=2.0.0 <2.1.4": "^2.1.4",
+    "diff": "^8.0.3"
   }
 }