@d3ara1n/pi-subagent 0.10.1 → 0.10.3

package/README.md

@@ -30,12 +30,12 @@ This means:
 
 ## Built-in Roles
 
-| Role | Model Role | Tools | Can Delegate To | Description |
-|------|-----------|-------|-----------------|-------------|
-| `explorer` | fast | read, find, grep | — | Fast code search (read-only, no bash) |
-| `reviewer` | heavy | read, bash, grep, find | — | Deep code review (read-only, bash for git/log) |
-| `worker` | default | read, bash, edit, write, grep, find, delegate | explorer, researcher | Implementation — the only role that can modify files |
-| `researcher` | fast | web_search, fetch_content, read, bash, delegate | explorer | Web research + GitHub repo analysis |
+| Role | Model Role | Timeout | Tools | Can Delegate To | Description |
+|------|-----------|---------|-------|-----------------|-------------|
+| `explorer` | fast | 900s | read, find, grep | — | Fast code search (read-only, no bash) |
+| `reviewer` | heavy | 3600s | read, bash, grep, find | — | Deep code review (read-only, bash for git/log) |
+| `worker` | default | 2400s | read, bash, edit, write, grep, find, delegate | explorer, researcher | Implementation — the only role that can modify files |
+| `researcher` | fast | 2400s | web_search, fetch_content, read, bash, delegate | explorer | Web research + GitHub repo analysis |
 
 **Nested delegation**: `worker` and `researcher` can spawn their own subagents. This keeps the main model's context clean — a worker can explore unfamiliar code via an `explorer` subagent without returning intermediate results to the main model.
 
@@ -47,6 +47,12 @@ This means:
 - **Collapsed result**: `✓ explorer · Found login, registration, and token logic` + recent tool calls + usage stats
 - **Expanded result** (Ctrl+O): Full task text, all tool calls, final output as rendered Markdown, and usage details
 
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/subagent:doctor` | Diagnose pi invocation, model-role resolution, configuration, and role references |
+
 ## Dependencies
 
 - [`@d3ara1n/pi-model-roles`](../pi-model-roles) — model role resolution
@@ -76,7 +82,6 @@ Edit `~/.pi/agent/settings.json`:
 ```json
 {
   "subagent": {
-    "timeout": 1500,
     "maxConcurrency": 4,
     "maxDepth": 3,
     "maxTurns": 0,
@@ -92,9 +97,11 @@ Edit `~/.pi/agent/settings.json`:
 }
 ```
 
-All fields are optional. Defaults: `timeout: 1500` (seconds; 25 min; active time — the clock pauses while the child is inside a nested `delegate` call, so delegate-capable roles need no extra headroom), `maxConcurrency: 4`, `maxDepth: 3`, `maxTurns: 0` (unlimited), `maxCost: 0` (unlimited), `history.enabled: true`, `summary.role: "utility"`, `summary.enabled: true`.
+All fields are optional. Defaults: `maxConcurrency: 4`, `maxDepth: 3`, `maxTurns: 0` (unlimited), `maxCost: 0` (unlimited), `history.enabled: true`, `summary.role: "utility"`, `summary.enabled: true`.
+
+Timeouts are defined per role. Built-in defaults are `explorer: 900`, `reviewer: 3600`, `worker: 2400`, and `researcher: 2400` seconds. The timeout is active time — the clock pauses while the child is inside a nested `delegate` call, so delegate-capable roles need no extra headroom.
 
-All numeric limits accept `0` for unlimited: `timeout`, `maxConcurrency`, `maxDepth`, `maxTurns`, and `maxCost`. Negative values are normalized to `0`; non-numeric or non-finite values fall back to their defaults. `maxConcurrency: 0` runs delegates without queuing, and `maxDepth: 0` permits unrestricted nesting.
+All numeric limits accept `0` for unlimited: `maxConcurrency`, `maxDepth`, `maxTurns`, `maxCost`, and per-role `timeout`. Negative values are normalized to `0`; non-numeric or non-finite values fall back to their defaults. `maxConcurrency: 0` runs delegates without queuing, and `maxDepth: 0` permits unrestricted nesting.
 
 ### Agent Overrides
 
@@ -131,7 +138,7 @@ Override, disable, or add subagent roles via `agentOverrides`. Built-in and cust
 
 **Required fields for custom roles:** `role`, `description`, `examples`, `decisionTrigger`, `tools`, `systemPrompt`.
 
-**Optional fields:** `subagentRoles` (roles this role can spawn via delegate), `timeout` (per-role active-time timeout in seconds; unset uses the global setting, `0` is unlimited, negative values normalize to `0`), `maxTurns` / `maxCost` (per-role budget overrides; unset uses the global setting, `0` is unlimited, negative values normalize to `0`), `fallbackRole` (backup pi-model-roles role on provider errors).
+**Optional fields:** `subagentRoles` (roles this role can spawn via delegate), `timeout` (per-role active-time timeout in seconds; unset or `0` is unlimited, negative values normalize to `0`), `maxTurns` / `maxCost` (per-role budget overrides; unset uses the top-level `maxTurns` / `maxCost` setting, `0` is unlimited, negative values normalize to `0`), `fallbackRole` (backup pi-model-roles role on provider errors).
 
 Invalid custom roles (missing required fields) are silently skipped with an error notification at session start.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@d3ara1n/pi-subagent",
-  "version": "0.10.1",
+  "version": "0.10.3",
   "type": "module",
   "description": "Role-based subagent orchestration for pi — delegates tasks to specialized pi child processes with configurable model roles",
   "main": "src/index.ts",

package/src/config.test.ts

@@ -47,7 +47,6 @@ describe("loadSubagentConfig", () => {
     const { agentDir } = makeRoot();
     writeSettings(agentDir, {
       subagent: {
-        timeout: 0,
         maxConcurrency: -1,
         maxDepth: -2,
         maxTurns: 0,
@@ -56,7 +55,6 @@ describe("loadSubagentConfig", () => {
     });
 
     const config = loadSubagentConfig();
-    assert.equal(config.timeout, 0);
     assert.equal(config.maxConcurrency, 0);
     assert.equal(config.maxDepth, 0);
     assert.equal(config.maxTurns, 0);
@@ -69,11 +67,10 @@ describe("loadSubagentConfig", () => {
     // would serialize it as null. Exercise both non-finite and wrong-type inputs.
     writeSettingsText(
       agentDir,
-      '{"subagent":{"timeout":1e999,"maxConcurrency":-1e999,"maxDepth":{},"maxTurns":false,"maxCost":"NaN"}}',
+      '{"subagent":{"maxConcurrency":-1e999,"maxDepth":{},"maxTurns":false,"maxCost":"NaN"}}',
     );
 
     const config = loadSubagentConfig();
-    assert.equal(config.timeout, DEFAULT_CONFIG.timeout);
     assert.equal(config.maxConcurrency, DEFAULT_CONFIG.maxConcurrency);
     assert.equal(config.maxDepth, DEFAULT_CONFIG.maxDepth);
     assert.equal(config.maxTurns, DEFAULT_CONFIG.maxTurns);
@@ -96,7 +93,6 @@ describe("loadSubagentConfig", () => {
     const { agentDir, projectDir } = makeRoot();
     writeSettings(agentDir, {
       subagent: {
-        timeout: 999,
         maxConcurrency: 8,
         maxDepth: 7,
         maxTurns: 6,
@@ -107,11 +103,10 @@ describe("loadSubagentConfig", () => {
       },
     });
     writeSettings(path.join(projectDir, ".pi"), {
-      subagent: { timeout: 12, summary: { role: "project-summary" } },
+      subagent: { summary: { role: "project-summary" } },
     });
 
     const config = loadSubagentConfig(projectDir);
-    assert.equal(config.timeout, 12);
     assert.equal(config.maxConcurrency, DEFAULT_CONFIG.maxConcurrency);
     assert.equal(config.maxDepth, DEFAULT_CONFIG.maxDepth);
     assert.equal(config.maxTurns, DEFAULT_CONFIG.maxTurns);

package/src/config.ts

@@ -46,7 +46,6 @@ export function loadSubagentConfig(cwd?: string): SubagentConfig {
   const rawSummary = raw?.summary;
   const rawHistory = raw?.history;
   return {
-    timeout: normalizeNonNegativeNumber(raw.timeout, DEFAULT_CONFIG.timeout),
     maxConcurrency: normalizeNonNegativeInteger(raw.maxConcurrency, DEFAULT_CONFIG.maxConcurrency),
     maxDepth: normalizeNonNegativeInteger(raw.maxDepth, DEFAULT_CONFIG.maxDepth),
     maxTurns: normalizeNonNegativeInteger(raw.maxTurns, DEFAULT_CONFIG.maxTurns),

package/src/index.ts

@@ -23,8 +23,7 @@ import {
   AsyncSemaphore,
   isProviderError,
   effectiveTimeout,
-  normalizeNonNegativeInteger,
-  normalizeNonNegativeNumber,
+  hasFailedSubagentResult,
 } from "./utils.ts";
 import { persistSubagentHistory } from "./history.ts";
 import { compressOutput, generateSummary } from "./output.ts";
@@ -171,6 +170,11 @@ export default function subagentExtension(pi: ExtensionAPI) {
     rebuildGuidelines(availableRoles);
   });
 
+  pi.on("tool_result", (event) => {
+    if (event.toolName !== "delegate") return;
+    if (hasFailedSubagentResult(event.details)) return { isError: true };
+  });
+
   pi.registerTool({
     name: "delegate",
     label: "Delegate to subagent",
@@ -220,16 +224,9 @@ export default function subagentExtension(pi: ExtensionAPI) {
 
       // Guard against bounded subagent nesting. A configured depth of 0 is unlimited.
       if (config.maxDepth > 0 && CURRENT_DEPTH >= config.maxDepth) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: `Cannot delegate: maximum nesting depth (${config.maxDepth}) reached (current depth ${CURRENT_DEPTH}). Return a result to the caller instead of delegating further.`,
-            },
-          ],
-          details: undefined as any,
-          isError: true,
-        };
+        throw new Error(
+          `Cannot delegate: maximum nesting depth (${config.maxDepth}) reached (current depth ${CURRENT_DEPTH}). Return a result to the caller instead of delegating further.`,
+        );
       }
 
       // Throttle state hoisted to the execute scope so the finally block can clear it.
@@ -287,13 +284,7 @@ export default function subagentExtension(pi: ExtensionAPI) {
       try {
         await gate.acquire(signal);
       } catch {
-        return {
-          content: [
-            { type: "text", text: `Subagent (${params.role}) was cancelled while queued.` },
-          ],
-          details: { mode: "single", results: [] },
-          isError: true,
-        };
+        throw new Error(`Subagent (${params.role}) was cancelled while queued.`);
       }
 
       try {
@@ -336,12 +327,9 @@ export default function subagentExtension(pi: ExtensionAPI) {
         const startTime = Date.now();
         // Total active-time budget for this run (ms). The clock pauses while the
         // child delegates, so this caps *active* time, not wall time.
-        const timeoutBudgetMs = effectiveTimeout(roleDef, config.timeout) * 1000;
-        const maxTurns = normalizeNonNegativeInteger(
-          roleDef.maxTurns ?? config.maxTurns,
-          config.maxTurns,
-        );
-        const maxCost = normalizeNonNegativeNumber(roleDef.maxCost ?? config.maxCost, config.maxCost);
+        const timeoutBudgetMs = effectiveTimeout(roleDef) * 1000;
+        const maxTurns = roleDef.maxTurns ?? config.maxTurns;
+        const maxCost = roleDef.maxCost ?? config.maxCost;
 
         // Throttled progress: coalesces bursty thinking/tool events so the TUI
         // repaints at most ~every PROGRESS_THROTTLE_MS, always keeping the latest state.
@@ -529,7 +517,6 @@ export default function subagentExtension(pi: ExtensionAPI) {
           return {
             content: [{ type: "text", text: failedText }],
             details: { mode: "single", results: [result] },
-            isError: true,
           };
         }
 
@@ -552,11 +539,7 @@ export default function subagentExtension(pi: ExtensionAPI) {
       } catch (err: any) {
         const errorText = `Subagent (${params.role}) error: ${err.message || err}`;
         emitFinal([], errorText);
-        return {
-          content: [{ type: "text", text: errorText }],
-          details: { mode: "single", results: [] },
-          isError: true,
-        };
+        throw new Error(errorText);
       } finally {
         // Cancel any trailing throttled onUpdate regardless of how we exited
         // (success / fallback / budget / error). A stale "still running" progress
@@ -592,7 +575,7 @@ export default function subagentExtension(pi: ExtensionAPI) {
         try {
           const cfg = loadSubagentConfig(ctx.cwd);
           lines.push(
-            `[\u2713] config: timeout=${cfg.timeout || "∞"}s concurrency=${cfg.maxConcurrency || "∞"} depth=${cfg.maxDepth || "∞"} turns=${cfg.maxTurns || "∞"} cost=$${cfg.maxCost || "∞"} summary=${cfg.summary.enabled ? cfg.summary.role : "off"} history=${cfg.history.enabled}`,
+            `[\u2713] config: concurrency=${cfg.maxConcurrency || "∞"} depth=${cfg.maxDepth || "∞"} turns=${cfg.maxTurns || "∞"} cost=$${cfg.maxCost || "∞"} summary=${cfg.summary.enabled ? cfg.summary.role : "off"} history=${cfg.history.enabled}`,
           );
         } catch {
           lines.push("[\u2717] config: failed to load");

package/src/roles.ts

@@ -12,6 +12,7 @@ export const BUILTIN_ROLES: Record<string, SubagentRole> = {
   explorer: {
     role: "fast",
     fallbackRole: "default",
+    timeout: 900,
     description:
       "READ-ONLY codebase exploration — locate files, grep symbols, trace imports, explain structures. Tools: read, find, grep. NO bash, NO edits, NO web access.",
     examples: ["Find where auth middleware is implemented", "Map the routing structure"],
@@ -31,6 +32,7 @@ export const BUILTIN_ROLES: Record<string, SubagentRole> = {
   reviewer: {
     role: "heavy",
     fallbackRole: "default",
+    timeout: 3600,
     description:
       "READ-ONLY code review & analysis — audit code, assess architecture, review diffs. Tools: read, bash, grep, find. Has bash (git diff/log, test runs). NO edits, NO web access.",
     examples: [
@@ -52,6 +54,7 @@ export const BUILTIN_ROLES: Record<string, SubagentRole> = {
   },
   worker: {
     role: "default",
+    timeout: 2400,
     description:
       "the ONLY role that can MODIFY files — edit, write, refactor, fix, implement. Tools: read, bash, edit, write, grep, find, delegate. Can delegate to explorer/researcher.",
     examples: ["Rename all snake_case fields to camelCase", "Add input validation to POST /login"],
@@ -77,6 +80,7 @@ export const BUILTIN_ROLES: Record<string, SubagentRole> = {
   researcher: {
     role: "fast",
     fallbackRole: "default",
+    timeout: 2400,
     description:
       "the ONLY role with WEB ACCESS — search docs, fetch pages, analyze GitHub repos. Tools: web_search, fetch_content, read, bash, delegate. Can clone repos & delegate to explorer.",
     examples: ["Find the React 19 migration guide", "Check GitHub issue #1234 for context"],

package/src/types.ts

@@ -4,8 +4,6 @@
 
 /** Configuration for the subagent extension. */
 export interface SubagentConfig {
-  /** Per-subagent active-time timeout in seconds. `0` means unlimited; negative values are normalized to `0`. The clock pauses while the child is inside a nested `delegate` call, so no widening is needed for delegate-capable roles. */
-  timeout: number;
   /** Max concurrent subagents. `0` means unlimited; negative values are normalized to `0`. Extras queue with a TUI hint when this is positive. */
   maxConcurrency: number;
   /** Max subagent nesting depth (the top-level session is depth 0). `0` means unlimited; negative values are normalized to `0`. */
@@ -35,7 +33,6 @@ export interface SubagentSummaryConfig {
 }
 
 export const DEFAULT_CONFIG: SubagentConfig = {
-  timeout: 1500,
   maxConcurrency: 4,
   maxDepth: 3,
   maxTurns: 0,
@@ -61,7 +58,7 @@ export interface SubagentRole {
   tools: string[];
   /** If this role has `delegate`, restrict which roles it may spawn. undefined = no restriction. */
   subagentRoles?: string[];
-  /** Per-role active-time timeout override in seconds. `0` means unlimited; negative values are normalized to `0`. Falls back to config.timeout when unset. */
+  /** Per-role active-time timeout in seconds. `0` or unset means unlimited; negative values are normalized to `0`. */
   timeout?: number;
   /** Max assistant turns before the run is killed. `0` means unlimited; negative values are normalized to `0`. */
   maxTurns?: number;

package/src/utils.test.ts

@@ -21,9 +21,50 @@ import {
   formatTokens,
   effectiveTimeout,
   elapsedSeconds,
+  hasFailedSubagentResult,
 } from "./utils.ts";
 import type { SubagentResult, SubagentRole } from "./types.ts";
 
+describe("subagent failure details", () => {
+  const baseResult = (overrides: Partial<SubagentResult> = {}): SubagentResult => ({
+    role: "worker",
+    task: "test task",
+    exitCode: 0,
+    messages: [],
+    output: "ok",
+    stderr: "",
+    usage: {
+      input: 0,
+      output: 0,
+      cacheRead: 0,
+      cacheWrite: 0,
+      cost: 0,
+      contextTokens: 0,
+      turns: 0,
+    },
+    activityLog: [],
+    ...overrides,
+  });
+
+  test("detects failed delegate results for tool_result error marking", () => {
+    assert.equal(
+      hasFailedSubagentResult({ mode: "single", results: [baseResult({ exitCode: 1 })] }),
+      true,
+    );
+    assert.equal(
+      hasFailedSubagentResult({ mode: "single", results: [baseResult({ stopReason: "timeout" })] }),
+      true,
+    );
+  });
+
+  test("does not mark successful or malformed details as failed", () => {
+    assert.equal(hasFailedSubagentResult({ mode: "single", results: [baseResult()] }), false);
+    assert.equal(hasFailedSubagentResult({ mode: "single", results: [] }), false);
+    assert.equal(hasFailedSubagentResult(undefined), false);
+    assert.equal(hasFailedSubagentResult({}), false);
+  });
+});
+
 // ── sanitizeFilename: guards the path-injection fix ──
 describe("sanitizeFilename", () => {
   test("never yields a path separator (no directory traversal)", () => {
@@ -248,17 +289,18 @@ describe("effectiveTimeout", () => {
       timeout,
     }) as unknown as SubagentRole;
 
-  test("non-delegate role uses base timeout", () => {
-    assert.equal(effectiveTimeout(role(["read", "grep"]), 600), 600);
+  test("role without timeout is unlimited", () => {
+    assert.equal(effectiveTimeout(role(["read", "grep"])), 0);
   });
-  test("delegate role uses base timeout (no widening — active-time clock pauses for nested delegate)", () => {
-    assert.equal(effectiveTimeout(role(["read", "delegate"]), 600), 600);
+  test("delegate-capable role without timeout is also unlimited", () => {
+    assert.equal(effectiveTimeout(role(["read", "delegate"])), 0);
   });
-  test("explicit roleDef.timeout is always honored (no widening)", () => {
-    assert.equal(effectiveTimeout(role(["read", "delegate"], 300), 600), 300);
+  test("explicit role timeout is honored", () => {
+    assert.equal(effectiveTimeout(role(["read", "delegate"], 300)), 300);
   });
-  test("explicit timeout on non-delegate also honored", () => {
-    assert.equal(effectiveTimeout(role(["read"]), 600), 600);
+  test("negative and non-finite values normalize to unlimited", () => {
+    assert.equal(effectiveTimeout(role(["read"], -1)), 0);
+    assert.equal(effectiveTimeout(role(["read"], Number.POSITIVE_INFINITY)), 0);
   });
 });
 

package/src/utils.ts

@@ -4,7 +4,13 @@
  */
 
 import * as os from "node:os";
-import type { ActivityEntry, SubagentRole, SubagentResult, ToolStatus } from "./types.ts";
+import type {
+  ActivityEntry,
+  SubagentDetails,
+  SubagentRole,
+  SubagentResult,
+  ToolStatus,
+} from "./types.ts";
 
 /** Max output chars fed to the main model and the expanded TUI. Larger outputs are compressed (or truncated) to fit. */
 export const MAX_OUTPUT_CHARS = 50_000;
@@ -194,6 +200,11 @@ export function isFailedResult(r: SubagentResult): boolean {
   );
 }
 
+export function hasFailedSubagentResult(details: unknown): boolean {
+  const d = details as SubagentDetails | undefined;
+  return Array.isArray(d?.results) && d.results.some(isFailedResult);
+}
+
 /** Heuristic: does this result look like a provider-side failure worth retrying on the fallback role? */
 export function isProviderError(result: SubagentResult): boolean {
   const haystack = `${result.stderr || ""}\n${result.errorMessage || ""}`;
@@ -291,13 +302,10 @@ export class AsyncSemaphore {
 
 /**
  * Effective per-role timeout in SECONDS (convert to ms at the spawn boundary).
- * No widening for delegate-capable roles: the parent's active-time clock
- * pauses while the child is inside a nested `delegate` call, so the base
- * budget is already enough. An explicit roleDef.timeout always wins.
- * Non-finite values fall back to the base timeout; negative values become 0 (unlimited).
+ * `0` or unset means unlimited; non-finite and negative values normalize to 0.
  */
-export function effectiveTimeout(roleDef: SubagentRole, baseTimeoutSec: number): number {
-  return normalizeNonNegativeNumber(roleDef.timeout, normalizeNonNegativeNumber(baseTimeoutSec, 0));
+export function effectiveTimeout(roleDef: SubagentRole): number {
+  return normalizeNonNegativeNumber(roleDef.timeout, 0);
 }
 
 // ── Output truncation ────────────────────────────────────────