@d3ara1n/pi-subagent 0.2.0 → 0.4.0

package/README.md

@@ -44,19 +44,17 @@ This means:
 ## TUI Display
 
 - **During execution**: Shows role, elapsed time, turn count, and live tool calls
-- **Collapsed result**: `✓ explorer · 找到了登录/注册/token三块逻辑` + recent tool calls + usage stats
+- **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
 
 ```bash
-pi extension add @d3ara1n/pi-subagent
+pi install @d3ara1n/pi-subagent
 ```
 
 ## Configuration
@@ -66,11 +64,30 @@ Edit `~/.pi/agent/settings.json`:
 ```jsonc
 {
   "subagent": {
-    // Default timeout per subagent (5 minutes)
-    "timeoutMs": 300000,
+    // Default timeout per subagent (10 minutes)
+    "timeoutMs": 600000,
+
+    // Max subagents running at once; extras queue with a "queued" TUI hint
+    "maxConcurrency": 4,
+
+    // Max subagent nesting depth (the main session is depth 0).
+    // Default 3 covers worker → researcher → explorer chains.
+    "maxDepth": 3,
+
+    // Turn / cost budgets (0 = unlimited). A run is killed once either is hit;
+    // partial output is returned with stopReason "budget_exceeded".
+    "maxTurns": 0,
+    "maxCost": 0,
+
+    // Audit log: one JSON per delegate run under
+    // ~/.pi/subagent/history/{sessionId}/{toolCallId}.json
+    "history": {
+      "enabled": true
+    },
 
     // Summary generation — uses a lightweight model to create
-    // a one-line Chinese summary for the TUI display
+    // a one-line summary for the TUI display.
+    // Outputs ≤ 150 chars skip the API call and reuse the text directly.
     "summary": {
       "role": "utility",    // pi-model-roles role for summarization
       "enabled": true        // set false to disable
@@ -79,7 +96,7 @@ Edit `~/.pi/agent/settings.json`:
 }
 ```
 
-All fields are optional. Defaults: `timeoutMs: 300000`, `summary.role: "utility"`, `summary.enabled: true`.
+All fields are optional. Defaults: `timeoutMs: 600000` (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
 
@@ -91,7 +108,10 @@ Override, disable, or add subagent roles via `agentOverrides`. Built-in and cust
     "agentOverrides": {
       // ── Override a built-in role (only specify changed fields) ──
       "worker": {
-        "role": "heavy"               // use a stronger model
+        "role": "heavy",              // use a stronger model
+        "timeoutMs": 600000,          // per-role timeout (overrides global)
+        "maxTurns": 50,               // per-role turn budget (0 = unlimited)
+        "maxCost": 1.0                // per-role cost ceiling in USD (0 = unlimited)
       },
 
       // ── Disable a built-in role ──
@@ -118,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), `fallbackRole` (backup pi-model-roles role on provider errors).
+**Optional fields:** `subagentRoles` (roles this role can spawn via delegate), `timeoutMs` (per-role timeout override; 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 +171,32 @@ Delegate tasks that would generate many tool calls or verbose output to keep you
 ]
 ```
 
+### Passing extra context
+
+The optional `context` field lets you hand a subagent precise context — selected code, a prior delegate's result, a file list, a git diff — without inflating the `task` string. It's prepended before the task:
+
+```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`; the `context` is merged into the prompt the subagent receives.
+
+### 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,7 @@
 {
   "name": "@d3ara1n/pi-subagent",
-  "version": "0.2.0",
+  "version": "0.4.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",
   "keywords": [

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,
+		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,