@bacnh85/pi-subagent 0.15.2 → 0.15.3

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # 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

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bacnh85/pi-subagent",
-  "version": "0.15.2",
+  "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"
   }
 }