@d3ara1n/pi-subagent 0.9.1 → 0.10.1

package/README.md

@@ -32,9 +32,9 @@ This means:
 
 | Role | Model Role | Tools | Can Delegate To | Description |
 |------|-----------|-------|-----------------|-------------|
-| `explorer` | fast | read, find, grep, glob | — | Fast code search (read-only, no bash) |
-| `reviewer` | heavy | read, bash, grep, glob | — | Deep code review (read-only, bash for git/log) |
-| `worker` | default | read, bash, edit, write, grep, glob, delegate | explorer, researcher | Implementation — the only role that can modify files |
+| `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 |
 
 **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.
@@ -54,7 +54,19 @@ This means:
 ## Installation
 
 ```bash
-pi install @d3ara1n/pi-subagent
+pi install npm:@d3ara1n/pi-model-roles
+pi install npm:@d3ara1n/pi-subagent
+```
+
+Or add to `~/.pi/agent/settings.json`:
+
+```jsonc
+{
+  "extensions": [
+    "/absolute/path/to/pi-extensions/packages/pi-model-roles",
+    "/absolute/path/to/pi-extensions/packages/pi-subagent"
+  ]
+}
 ```
 
 ## Configuration
@@ -82,6 +94,8 @@ 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 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.
+
 ### Agent Overrides
 
 Override, disable, or add subagent roles via `agentOverrides`. Built-in and custom roles are treated equally — all descriptions, examples, and decision triggers feed into the LLM's prompt dynamically.
@@ -117,7 +131,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 timeout override in seconds of active time; the clock pauses while the child delegates), `maxTurns` / `maxCost` (per-role budget overrides; 0 = unlimited), `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 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).
 
 Invalid custom roles (missing required fields) are silently skipped with an error notification at session start.
 
@@ -182,7 +196,7 @@ Each path is injected as an independent `@file` attachment the subagent reads di
 
 ### Budget enforcement
 
-`maxTurns` / `maxCost` cap a run. When exceeded, the child is killed and the last completed output is returned with `stopReason: "budget_exceeded"` (shown in the expanded TUI). Defaults are unlimited (0); set global defaults in config or per-role via `agentOverrides`.
+`maxTurns` / `maxCost` cap a run. When exceeded, the child is killed and the last completed output is returned with `stopReason: "budget_exceeded"` (shown in the expanded TUI). Defaults are unlimited (`0`); set global defaults in config or per-role overrides in `agentOverrides`. Negative values are normalized to `0`.
 
 ### Oversized outputs
 

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@d3ara1n/pi-subagent",
-  "version": "0.9.1",
+  "version": "0.10.1",
   "type": "module",
   "description": "Role-based subagent orchestration for pi — delegates tasks to specialized pi child processes with configurable model roles",
   "main": "src/index.ts",
   "keywords": [
     "pi-package",
-    "pi"
+    "pi",
+    "pi-extension"
   ],
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",
@@ -26,7 +27,7 @@
     }
   },
   "dependencies": {
-    "@d3ara1n/pi-model-roles": "^0.1.0"
+    "@d3ara1n/pi-model-roles": "^0.7.0"
   },
   "pi": {
     "extensions": [

package/src/config.test.ts

@@ -0,0 +1,123 @@
+/**
+ * Configuration loading regression tests.
+ *
+ * Uses isolated global/project settings roots via PI_AGENT_DIR.
+ *   node --test packages/pi-subagent/src/config.test.ts
+ */
+
+import { afterEach, describe, test } from "node:test";
+import assert from "node:assert/strict";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { loadSubagentConfig } from "./config.ts";
+import { DEFAULT_CONFIG } from "./types.ts";
+
+const originalAgentDir = process.env.PI_AGENT_DIR;
+const tempRoots: string[] = [];
+
+function makeRoot(): { agentDir: string; projectDir: string } {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagent-config-test-"));
+  tempRoots.push(root);
+  const agentDir = path.join(root, "agent");
+  const projectDir = path.join(root, "project");
+  fs.mkdirSync(agentDir, { recursive: true });
+  fs.mkdirSync(projectDir, { recursive: true });
+  process.env.PI_AGENT_DIR = agentDir;
+  return { agentDir, projectDir };
+}
+
+function writeSettings(dir: string, settings: unknown): void {
+  writeSettingsText(dir, JSON.stringify(settings));
+}
+
+function writeSettingsText(dir: string, content: string): void {
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, "settings.json"), content);
+}
+
+afterEach(() => {
+  if (originalAgentDir === undefined) delete process.env.PI_AGENT_DIR;
+  else process.env.PI_AGENT_DIR = originalAgentDir;
+  for (const root of tempRoots.splice(0)) fs.rmSync(root, { recursive: true, force: true });
+});
+
+describe("loadSubagentConfig", () => {
+  test("preserves zero limits and clamps negative numeric limits to unlimited", () => {
+    const { agentDir } = makeRoot();
+    writeSettings(agentDir, {
+      subagent: {
+        timeout: 0,
+        maxConcurrency: -1,
+        maxDepth: -2,
+        maxTurns: 0,
+        maxCost: -0.5,
+      },
+    });
+
+    const config = loadSubagentConfig();
+    assert.equal(config.timeout, 0);
+    assert.equal(config.maxConcurrency, 0);
+    assert.equal(config.maxDepth, 0);
+    assert.equal(config.maxTurns, 0);
+    assert.equal(config.maxCost, 0);
+  });
+
+  test("uses defaults for non-finite or non-numeric numeric limits", () => {
+    const { agentDir } = makeRoot();
+    // JSON.parse accepts numeric overflow as Infinity, even though JSON.stringify
+    // 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"}}',
+    );
+
+    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);
+    assert.equal(config.maxCost, DEFAULT_CONFIG.maxCost);
+  });
+
+  test("floors finite fractional count limits", () => {
+    const { agentDir } = makeRoot();
+    writeSettings(agentDir, {
+      subagent: { maxConcurrency: 2.9, maxDepth: 3.1, maxTurns: 4.8 },
+    });
+
+    const config = loadSubagentConfig();
+    assert.equal(config.maxConcurrency, 2);
+    assert.equal(config.maxDepth, 3);
+    assert.equal(config.maxTurns, 4);
+  });
+
+  test("project subagent block replaces global wholesale and defaults omitted fields", () => {
+    const { agentDir, projectDir } = makeRoot();
+    writeSettings(agentDir, {
+      subagent: {
+        timeout: 999,
+        maxConcurrency: 8,
+        maxDepth: 7,
+        maxTurns: 6,
+        maxCost: 5,
+        history: { enabled: false },
+        summary: { enabled: false, role: "global-summary" },
+        agentOverrides: { global: { disabled: true } },
+      },
+    });
+    writeSettings(path.join(projectDir, ".pi"), {
+      subagent: { timeout: 12, 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);
+    assert.equal(config.maxCost, DEFAULT_CONFIG.maxCost);
+    assert.deepEqual(config.history, DEFAULT_CONFIG.history);
+    assert.deepEqual(config.summary, { enabled: DEFAULT_CONFIG.summary.enabled, role: "project-summary" });
+    assert.deepEqual(config.agentOverrides, {});
+  });
+});

package/src/config.ts

@@ -10,6 +10,7 @@ import * as os from "node:os";
 import * as path from "node:path";
 import type { SubagentConfig } from "./types.ts";
 import { DEFAULT_CONFIG } from "./types.ts";
+import { normalizeNonNegativeInteger, normalizeNonNegativeNumber } from "./utils.ts";
 
 function getAgentDir(): string {
   const envDir = process.env.PI_AGENT_DIR;
@@ -45,11 +46,11 @@ export function loadSubagentConfig(cwd?: string): SubagentConfig {
   const rawSummary = raw?.summary;
   const rawHistory = raw?.history;
   return {
-    timeout: raw.timeout ?? DEFAULT_CONFIG.timeout,
-    maxConcurrency: raw.maxConcurrency ?? DEFAULT_CONFIG.maxConcurrency,
-    maxDepth: raw.maxDepth ?? DEFAULT_CONFIG.maxDepth,
-    maxTurns: raw.maxTurns ?? DEFAULT_CONFIG.maxTurns,
-    maxCost: raw.maxCost ?? DEFAULT_CONFIG.maxCost,
+    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),
+    maxCost: normalizeNonNegativeNumber(raw.maxCost, DEFAULT_CONFIG.maxCost),
     history: {
       enabled: rawHistory?.enabled ?? DEFAULT_CONFIG.history.enabled,
     },

package/src/history.ts

@@ -0,0 +1,56 @@
+/**
+ * History persistence for pi-subagent delegate runs.
+ *
+ * Best-effort audit log: writes one JSON record per delegate run under
+ * ~/.pi/subagent/history/{sessionId}/{toolCallId}.json. Never throws — persistence
+ * must not fail the delegation. Privacy parity with pi's own session files.
+ */
+
+import * as os from "node:os";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { SubagentResult } from "./types.ts";
+import { sanitizeFilename } from "./utils.ts";
+
+export function persistSubagentHistory(
+  sessionId: string | undefined,
+  toolCallId: string,
+  role: string,
+  task: string,
+  r: SubagentResult,
+  rawOutput?: string,
+): void {
+  try {
+    const dir = path.join(
+      os.homedir(),
+      ".pi",
+      "subagent",
+      "history",
+      sanitizeFilename(sessionId ?? "unknown"),
+    );
+    fs.mkdirSync(dir, { recursive: true });
+    const payload = {
+      id: toolCallId,
+      role,
+      task,
+      timestamp: Date.now(),
+      exitCode: r.exitCode,
+      stopReason: r.stopReason,
+      model: r.model,
+      summary: r.summary,
+      // Keep the full original output for auditing even if LLM/TUI saw a compressed/truncated version.
+      output: rawOutput ?? r.output,
+      outputMethod: r.outputMethod,
+      errorMessage: r.errorMessage,
+      usage: r.usage,
+      activityLog: r.activityLog,
+    };
+    fs.writeFileSync(
+      path.join(dir, `${sanitizeFilename(toolCallId)}.json`),
+      JSON.stringify(payload, null, 2),
+      { mode: 0o600 },
+    );
+  } catch {
+    /* best-effort — never fail the delegation */
+  }
+}