@d3ara1n/pi-subagent 0.3.0 → 0.5.0

package/README.md

@@ -17,7 +17,7 @@ This means:
 - **Multiple subagents can run in parallel** — emit multiple `delegate` calls in one turn; pi executes them concurrently
 - **Subagents can nest subagents** — a `worker` can delegate exploration to `explorer` without returning to the main model
 
-> This design intentionally excludes chain pipelines and context-forking — those patterns are better suited when subagents act as advisors (planner, oracle), not executors.
+> This design currently focuses on single-task delegation rather than chain pipelines or context-forking — those patterns fit better when subagents act as advisors (planner, oracle) rather than executors.
 
 ## How it works
 
@@ -47,11 +47,9 @@ 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
 
-## Requirements
+## Dependencies
 
-- **@d3ara1n/pi-model-roles** must be installed and configured
-- **@earendil-works/pi-tui** — bundled with pi, no separate install needed
-- Role definitions must exist in `modelRoles` settings
+- [`@d3ara1n/pi-model-roles`](../pi-model-roles) — model role resolution
 
 ## Installation
 
@@ -63,43 +61,44 @@ pi install @d3ara1n/pi-subagent
 
 Edit `~/.pi/agent/settings.json`:
 
-```jsonc
+```json
 {
   "subagent": {
-    // Default timeout per subagent (5 minutes)
-    "timeoutMs": 300000,
-
-    // Summary generation — uses a lightweight model to create
-    // a one-line summary for the TUI display
+    "timeout": 600,
+    "maxConcurrency": 4,
+    "maxDepth": 3,
+    "maxTurns": 0,
+    "maxCost": 0,
+    "history": {
+      "enabled": true
+    },
     "summary": {
-      "role": "utility",    // pi-model-roles role for summarization
-      "enabled": true        // set false to disable
+      "role": "utility",
+      "enabled": true
     }
   }
 }
 ```
 
-All fields are optional. Defaults: `timeoutMs: 300000`, `summary.role: "utility"`, `summary.enabled: true`.
+All fields are optional. Defaults: `timeout: 600` (seconds; 10 min; roles that can `delegate` get 2× automatically when no per-role timeout is set), `maxConcurrency: 4`, `maxDepth: 3`, `maxTurns: 0` (unlimited), `maxCost: 0` (unlimited), `history.enabled: true`, `summary.role: "utility"`, `summary.enabled: true`.
 
 ### 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.
 
-```jsonc
+```json
 {
   "subagent": {
     "agentOverrides": {
-      // ── Override a built-in role (only specify changed fields) ──
       "worker": {
-        "role": "heavy"               // use a stronger model
+        "role": "heavy",
+        "timeout": 600,
+        "maxTurns": 50,
+        "maxCost": 1.0
       },
-
-      // ── Disable a built-in role ──
       "reviewer": {
         "disabled": true
       },
-
-      // ── Add a custom role (all required fields must be provided) ──
       "tester": {
         "role": "default",
         "description": "Test automation & QA — write and run tests, validate fixes. Tools: read, bash, edit, write, grep. Can delegate to explorer.",
@@ -118,7 +117,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), `fallbackRole` (backup pi-model-roles role on provider errors).
+**Optional fields:** `subagentRoles` (roles this role can spawn via delegate), `timeout` (per-role timeout override in seconds; when unset, delegate-capable roles get 2× the global default automatically), `maxTurns` / `maxCost` (per-role budget overrides; 0 = unlimited), `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.
 
@@ -151,6 +150,48 @@ Delegate tasks that would generate many tool calls or verbose output to keep you
 ]
 ```
 
+### Passing context and reference files
+
+pi-subagent delivers context to the child as **independent channels**, never fused into the task string. This keeps the task an unambiguous directive and lets each channel be sized independently.
+
+#### `context` (inline text)
+
+Hand the subagent precise context — selected code, a prior delegate's result, a file list, a git diff — without inflating the `task` string. It's delivered as a separate channel:
+
+```json
+{
+  "role": "worker",
+  "task": "Add input validation to the login function",
+  "context": "Current implementation (src/auth.ts:42-70):\n```ts\nasync function login(email, pw) { ... }\n```\nValidation must reject empty/invalid emails and enforce a min 8-char password."
+}
+```
+
+The stored/displayed task stays as the original `task`. When small, `context` inlines as a `<context>` block; when large (over 8,000 chars) it spills to a temp file injected via `@file`, so a large context never drags a short task into a spill.
+
+#### `files` (reference paths)
+
+```json
+{
+  "role": "explorer",
+  "task": "Report the public API of the auth module",
+  "files": ["src/auth.ts", "src/auth.types.ts"]
+}
+```
+
+Each path is injected as an independent `@file` attachment the subagent reads directly. **File contents stay out of your context window** — you pass only the paths. Prefer this over pasting file contents into `context`, since the child receives the content on its first turn without spending a tool call to read it.
+
+### 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`.
+
+### Oversized outputs
+
+When a run's output exceeds the size limit (50,000 chars), pi-subagent first tries to **compress** it with the summary model (same role configured under `summary.role`) into a compact form that preserves conclusions, code, file paths, and errors. If compression fails or doesn't shrink enough, it falls back to mechanical head+tail truncation. The prepared text is what the main model receives and what the expanded TUI renders; a hint line notes which method was used. The **full raw output is always kept in the history file** for auditing.
+
+### Run history
+
+Every completed delegate run is written (best-effort) to `~/.pi/subagent/history/{sessionId}/{toolCallId}.json`, recording role, task, usage, activity log, and the **full raw output** (even when the main model saw a compressed/truncated version). Useful for auditing what subagents did and how much they cost. Disable with `history.enabled: false`.
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@d3ara1n/pi-subagent",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "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.ts

@@ -21,8 +21,7 @@ function readSettingsFile(filePath: string): any {
 	try {
 		if (!fs.existsSync(filePath)) return {};
 		const content = fs.readFileSync(filePath, "utf-8");
-		const stripped = content.replace(/\/\/.*$/gm, "").replace(/\/\*[\s\S]*?\*\//g, "");
-		return JSON.parse(stripped);
+		return JSON.parse(content);
 	} catch {
 		return {};
 	}
@@ -53,8 +52,16 @@ export function loadSubagentConfig(cwd?: string): SubagentConfig {
 	if (!raw) return DEFAULT_CONFIG;
 
 	const rawSummary = raw?.summary;
+	const rawHistory = raw?.history;
 	return {
-		timeoutMs: raw.timeoutMs ?? DEFAULT_CONFIG.timeoutMs,
+		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,
+		history: {
+			enabled: rawHistory?.enabled ?? DEFAULT_CONFIG.history.enabled,
+		},
 		summary: {
 			role: rawSummary?.role ?? DEFAULT_CONFIG.summary.role,
 			enabled: rawSummary?.enabled ?? DEFAULT_CONFIG.summary.enabled,