@bacnh85/pi-subagent 0.15.2 → 0.16.0

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.
  */
-export const DEFAULT_TIMEOUT_MS = 3 * 60 * 1_000; // 3 minutes
+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 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
 // ---------------------------------------------------------------------------
@@ -489,6 +565,14 @@ export function validateExecutionRequest(
 ): ValidationError[] {
   const errors: ValidationError[] = [];
 
+  // Timeout (single/parallel/chain share one requested timeout)
+  if (options.timeout !== undefined) {
+    const t = normalizeTimeout({ requested: options.timeout });
+    if (t.error) {
+      errors.push({ field: "timeout", message: t.error });
+    }
+  }
+
   // Agent name
   if (options.agentName !== undefined) {
     if (typeof options.agentName !== "string" || options.agentName.trim().length === 0) {

package/extensions/service.ts

@@ -1,7 +1,8 @@
 import { type ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { type AgentConfig, getModelCandidates } from "./agents.ts";
+import { type AgentConfig } from "./agents.ts";
 import { runSubAgent, type SubAgentProgress, type SubAgentResult } from "./runner.ts";
-import { resolveModel } from "./model.ts";
+import { resolveModel, runWithModelFallback } from "./model.ts";
+import { readSubagentRoles, resolveAgentModelChain } from "./roles.ts";
 import {
   isRateLimitError,
   validateAgentTools,
@@ -42,10 +43,15 @@ export async function runNamedAgent(options: {
   signal?: AbortSignal;
   /** When true, only read-only tools are permitted regardless of agent.sandbox. */
   readOnly?: boolean;
+  /** Trusted opt-out for child cwd outside the workspace (from getTrustedConfig). */
+  allowExternalCwd?: boolean;
   onMessage?: (result: SubAgentResult) => void;
   onProgress?: (progress: SubAgentProgress) => void;
 }): Promise<SubAgentResult> {
-  const { model, attempted } = await resolveModel(getModelCandidates(options.agent), options.ctx.model, options.ctx.modelRegistry);
+  const rolesCfg = readSubagentRoles(options.ctx);
+  const agentChain = resolveAgentModelChain(options.agent, rolesCfg);
+  const resolvedModel = await resolveModel(agentChain.candidates, options.ctx.model, options.ctx.modelRegistry);
+  const { model, attempted } = resolvedModel;
   if (!model) throw new Error(`No model resolved for agent "${options.agent.name}" (tried: ${attempted.join(", ") || "none"})`);
 
   const modelRegistry = options.ctx.modelRegistry;
@@ -53,7 +59,11 @@ export async function runNamedAgent(options: {
   const authStorage = (modelRegistry as any).authStorage;
 
   // Security: validate and normalise timeout.
-  const effectiveTimeoutMs = normalizeTimeout({ requested: options.timeout }).timeoutMs;
+  const timeoutResult = normalizeTimeout({ requested: options.timeout });
+  if (timeoutResult.error) {
+    throw new Error(timeoutResult.error);
+  }
+  const effectiveTimeoutMs = timeoutResult.timeoutMs;
 
   // Parent tool names — agents without an explicit `tools` line inherit them.
   const parentToolNames = (options.ctx as any).getAllTools?.()?.map((t: { name: string }) => t.name) as string[] | undefined;
@@ -77,80 +87,55 @@ export async function runNamedAgent(options: {
 
   // Security: validate cwd (service caller must provide valid cwd).
   // The service path uses the same policy as the tool path.
-  const safeCwd = resolveSafeCwd({ workspaceRoot: options.ctx.cwd, childCwd: options.cwd });
+  const safeCwd = resolveSafeCwd({ workspaceRoot: options.ctx.cwd, childCwd: options.cwd, allowExternalCwd: options.allowExternalCwd });
   if (safeCwd.error) {
     throw new Error(safeCwd.error);
   }
 
   const contract = options.instructions?.slice(0, MAX_INSTRUCTIONS_LENGTH);
 
-  // Retry loop: rate-limit model fallback
-  const candidates = getModelCandidates(options.agent);
-  const triedModels: string[] = [];
-
-  const tryWithFallback = async (): Promise<SubAgentResult> => {
-    const remaining = candidates.filter(m => !triedModels.includes(m));
-    const isParentFallback = remaining.length === 0;
-    const fallbackResolved = await resolveModel(remaining, options.ctx.model, options.ctx.modelRegistry);
-    if (!fallbackResolved.model) {
-      throw new Error(
-        `All models rate-limited or unavailable. Tried: ${triedModels.join(" → ") || "(none)"}. ` +
-        `Remaining candidates: ${remaining.join(", ") || "none"}. ` +
-        `Parent: ${options.ctx.model?.provider}/${options.ctx.model?.id}.`,
-      );
-    }
-    const triedName = `${fallbackResolved.model!.provider}/${fallbackResolved.model!.id}`;
-    if (triedModels.includes(triedName)) {
-      // Already tried this model (e.g., all candidates unavailable
-      // and parent fallback) — no further options.
-      throw new Error(
-        `All available models exhausted. Tried: ${triedModels.join(" → ")}.`,
-      );
-    }
-    triedModels.push(triedName);
-    // Also track the raw candidate name so candidates.filter() can
-    // exclude it even when the agent uses unqualified names.
-    // Avoid duplicating when candidate name is already qualified (matchedCandidate === triedName).
-    if (fallbackResolved.matchedCandidate && fallbackResolved.matchedCandidate !== triedName) {
-      triedModels.push(fallbackResolved.matchedCandidate);
-    }
-
-    const result = await runSubAgent({
-      cwd: safeCwd.path,
-      sandbox: options.agent.sandbox === "worktree" ? "worktree" : undefined,
-      systemPrompt: contract ? `${options.agent.systemPrompt}\n\n## Task Contract\n${contract}` : options.agent.systemPrompt,
-      task: options.task,
-      tools: toolValidation.tools,
-      model: fallbackResolved.model,
-      modelRuntime,
-      authStorage,
-      modelRegistry,
-      signal: options.signal,
-      timeoutMs: effectiveTimeoutMs,
-      agentName: options.agent.name,
-      thinkingLevel: options.agent.thinking,
-      onMessage: options.onMessage,
-      onProgress: options.onProgress,
-      loadExtensions,
-      projectTrusted,
-    });
-
-    if (result.errorMessage && isRateLimitError(result.errorMessage)) {
-      // If the model that just rate-limited was the parent fallback
-      // (no remaining candidates), stop — no further options.
-      if (isParentFallback) {
+  // Retry loop: rate-limit model fallback — shared with the tool path so the
+  // triedModels bookkeeping and per-candidate `:thinking` resolution stay in
+  // one place (see runWithModelFallback in model.ts). Errors are thrown here;
+  // the caller maps them to its own response shape.
+  return runWithModelFallback<SubAgentResult>({
+    candidates: agentChain.candidates,
+    parentModel: options.ctx.model,
+    modelRegistry: options.ctx.modelRegistry,
+    thinkingByCandidate: agentChain.thinkingByCandidate,
+    defaultThinking: options.agent.thinking,
+    runAttempt: (model, thinkingLevel) =>
+      runSubAgent({
+        cwd: safeCwd.path,
+        sandbox: options.agent.sandbox === "worktree" ? "worktree" : undefined,
+        systemPrompt: contract ? `${options.agent.systemPrompt}\n\n## Task Contract\n${contract}` : options.agent.systemPrompt,
+        task: options.task,
+        tools: toolValidation.tools,
+        model,
+        modelRuntime,
+        authStorage,
+        modelRegistry,
+        signal: options.signal,
+        timeoutMs: effectiveTimeoutMs,
+        agentName: options.agent.name,
+        thinkingLevel,
+        onMessage: options.onMessage,
+        onProgress: options.onProgress,
+        loadExtensions,
+        projectTrusted,
+      }),
+    isRateLimited: (result) => Boolean(result.errorMessage && isRateLimitError(result.errorMessage)),
+    onExhausted: (reason, triedModels, remaining) => {
+      const tried = triedModels.join(" → ") || "(none)";
+      const parent = options.ctx.model ? `${options.ctx.model.provider}/${options.ctx.model.id}` : "none";
+      if (reason === "no-model") {
         throw new Error(
-          `All available models exhausted. Tried: ${triedModels.join(" → ")}.`,
+          `All models rate-limited or unavailable. Tried: ${tried}. ` +
+          `Remaining candidates: ${remaining.join(", ") || "none"}. ` +
+          `Parent: ${parent}.`,
         );
       }
-      return tryWithFallback();
-    }
-    return result;
-  };
-
-  try {
-    return await tryWithFallback();
-  } finally {
-    // No manual timeout handling needed — runSubAgent handles timeouts internally.
-  }
+      throw new Error(`All available models exhausted. Tried: ${tried}.`);
+    },
+  });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bacnh85/pi-subagent",
-  "version": "0.15.2",
+  "version": "0.16.0",
   "description": "In-process subagents for Pi with isolated SDK sessions, parallel and chained delegation, and inspectable threads.",
   "type": "module",
   "license": "MIT",
@@ -34,6 +34,8 @@
     "extensions/index.ts",
     "extensions/agents.ts",
     "extensions/model.ts",
+    "extensions/roles.ts",
+    "extensions/roles-panel.ts",
     "extensions/runner.ts",
     "extensions/service.ts",
     "extensions/render.ts",
@@ -66,6 +68,9 @@
     "@earendil-works/pi-tui": ">=0.80.0 <0.85.0",
     "typebox": ">=1.3.0 <2.0.0"
   },
+  "dependencies": {
+    "@bacnh85/pi-config-panel": "^0.1.0"
+  },
   "devDependencies": {
     "@earendil-works/pi-agent-core": "^0.84.0",
     "@earendil-works/pi-ai": "^0.84.0",
@@ -73,9 +78,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"
   }
 }