pi-subagents-lite 1.0.2 → 1.2.0

package/README.md

@@ -25,15 +25,21 @@ Tool names like `Agent` and `StopAgent`, and parameter names like `prompt`, `des
 ## Features
 
 - **Two tools** — `Agent` (spawn) and `StopAgent` (stop)
+- **Manual spawn** — spawn agents from the `/agents` menu without asking the LLM. Full control over model, thinking, turns, and background mode.
 - **Foreground & background** — block or fire-and-forget with auto-delivered results
 - **Custom agent types** — define via `.md` files with YAML frontmatter (tools, model, thinking, turn limits)
 - **Smart model resolution** — 6-level precedence: session → config → frontmatter → parent. Set once, forget
 - **Concurrency control** — per-model and per-provider slot limits with automatic queuing
 - **Cost tracking** — input/output/cache tokens and dollar cost per agent
+- **Cost display** — toggle agent cost in stats and status bar (OFF by default)
 - **Live widget** — persistent status bar above the editor showing running/completed agents
+- **Widget settings** — force compact mode, max lines, opt-in ctrl+o sync
 - **Result viewer** — fullscreen markdown viewer with stats
 - **Steer** — inject mid-execution guidance into running agents
 - **Output logs** — human-readable, `tail -f` friendly
+- **Grace turns** — configurable grace turns after `max_turns` before hard abort
+- **Reload safety** — warns when active agents are killed by session reload
+- **Worktree support** — `worktree_path` parameter runs agents in a git worktree with validated path, worktree agent discovery, and UI label
 
 ## Install
 
@@ -95,6 +101,7 @@ Stop a running agent at any time via /agents command
 | `description` | ✅ | Brief description for the LLM caller |
 | `agent` | | Type name — `general-purpose`, `Explore`, or any custom type you define (see [Custom Agent Types](#custom-agent-types)). The available values are **auto-populated** from `.md` files in your agent directories — drop a file, it appears in the enum. Set `hidden: true` in frontmatter to hide a type from this list (still callable by name). |
 | `run_in_background` | | Fire-and-forget; result delivered automatically when done |
+| `worktree_path` | | Absolute path to a git worktree. Agent runs in that worktree's context, discovers agents from its `.pi/agents/` directory, and displays a worktree label in the widget and menus. Path is validated against the parent repo's git common dir. |
 
 > `model`, `max_turns`, and `thinking` are **not visible to the LLM** through tool introspection — the extension injects them at call time from agent config and frontmatter. `model` is resolved via the [Model Resolution](#model-resolution) chain; `max_turns`/`thinking` come from the agent's config. See [Custom Agent Types](#custom-agent-types) to set them.
 
@@ -280,9 +287,12 @@ The LLM never passes `model` — it's injected at call time via the `tool_call`
 
 Management menu with four sections:
 
-- **Model settings** — global default, per-type overrides, force background mode
-- **Concurrency** — default limit, per-provider and per-model slots
-- **Running agents** — list, steer, stop, view snapshot, view result
+- **Running agents** — list with status and description; per-agent actions: view snapshot, view result, view error, steer, stop; bulk stop all running
+- **Spawn agent** — manually spawn an agent without asking the LLM. Pick a type, enter a prompt, configure options (model, thinking, max turns, grace turns, background), and spawn. Options are pre-filled from agent config and current settings. Spawn immediately or customize first.
+- **Settings** — model, concurrency, and widget settings grouped together
+  - **Model settings** — global default, per-type overrides, force background mode, cost display toggle, grace turns
+  - **Concurrency** — default limit, per-provider and per-model slots, reset to defaults
+  - **Widget settings** — force compact mode, max lines (full/compact), ctrl+o shortcut
 - **Debug** — agent types, agent briefing (sends capabilities to the LLM)
 
 ## Interface
@@ -294,15 +304,28 @@ Persistent bar above the editor showing running and completed agents. Updates li
 - Running agents show a spinner, current tool activity, turn count, token usage (with optional context-fill percent), and elapsed time
 - Completed agents show a check mark with final stats
 - Click `tail -f` path to follow output logs in real time
+- Two display modes: **full** (header + `tail -f` path + activity) and **compact** (single line, description truncated to 30 chars, activity inline)
 
-Format (tree structure with branch connectors):
+**Full mode** (tree structure with branch connectors):
 ```
 ├─ ⠙ Explore  description  3🛠 ·5≤30⟳ ·12.0k(45%)·1h 2m 3s
+│  │ tail -f /tmp/pi-agent-outputs/...
 │  └ thinking…
 ```
 
+**Compact mode** (single line, description truncated):
+```
+├─ ⠙ Explore  description trunc…  3🛠 ·5≤30⟳ ·12.0k(45%)·1h 2m 3s  thinking…
+```
+
 Turn format uses `≤` and `⟳` glyphs (`5≤30⟳` = 5 of 30 turns). Token count uses compact notation (`12.0k`) with optional context-fill percent in parentheses. No "tokens" label — the glyphs are self-explanatory.
 
+**Compact mode is active when:**
+- **Force compact mode** is ON (in `/agents > Widget settings`), OR
+- **Ctrl+o shortcut** is ON and the user has pressed ctrl+o to collapse tool expansion
+
+Force compact always wins. When force compact is ON, ctrl+o state changes are ignored.
+
 ### Result Viewer
 
 Fullscreen markdown viewer for agent results. Opens automatically when viewing a completed agent's result from the `/agents` menu.
@@ -311,6 +334,8 @@ Key bindings: `↑↓` navigate · `PgUp/PgDn` · `g`/`G` top/bottom · `f` togg
 
 Stats line: ` ↑12.0k · ↓8.0k · W3.0k · $0.024 · 15 turns · 47s`
 
+When **Cost display** is enabled (ON), agent stats show dollar cost: `✓ Builder·2🛠 ·5⟳ ·12.3k·$0.008·10s`. The status bar shows total agent cost: `agents: $0.008` or `2 agents: $0.008`.
+
 ## Configuration
 
 `~/.pi/agent/subagents-lite.json` — managed via `/agents` menu, or edit directly:
@@ -320,6 +345,12 @@ Stats line: ` ↑12.0k · ↓8.0k · W3.0k · $0.024 · 15 turns · 47s`
   "agent": {
     "default": null,
     "forceBackground": false,
+    "showCost": true,
+    "graceTurns": 6,
+    "widgetMaxLines": 12,
+    "widgetMaxLinesCompact": 6,
+    "widgetCompact": false,
+    "widgetShortcut": false,
     "Explore": "anthropic/claude-haiku-4-5-20251001"
   },
   "concurrency": {
@@ -332,7 +363,18 @@ Stats line: ` ↑12.0k · ↓8.0k · W3.0k · $0.024 · 15 turns · 47s`
 }
 ```
 
-> **Note:** `agent.default` (global fallback), `agent.forceBackground` (flag), and per-type overrides like `"Explore"` are peers in the same object. Agent type names become dynamic keys alongside the special fields.
+> **Note:** `agent.default` (global fallback), `agent.forceBackground` (flag), `agent.showCost` (toggle cost display), `agent.graceTurns` (grace turns after `max_turns` before hard abort), widget settings (`widgetMaxLines`, `widgetMaxLinesCompact`, `widgetCompact`, `widgetShortcut`), and per-type overrides like `"Explore"` are peers in the same object. Agent type names become dynamic keys alongside the special fields.
+
+### Widget settings
+
+| Field | Default | Description |
+|---|---|---|
+| `widgetMaxLines` | `12` | Maximum body lines in full mode (excluding the heading). |
+| `widgetMaxLinesCompact` | half of `widgetMaxLines` | Maximum body lines in compact mode. |
+| `widgetCompact` | `false` | Force compact mode regardless of ctrl+o state. |
+| `widgetShortcut` | `false` | Opt-in: when ON, ctrl+o (tool expansion toggle) syncs with widget compact mode. When OFF, compact mode is manual-only via `widgetCompact`. |
+
+> **Reload safety:** if a session reload (e.g. `/reload` or extension reload) kills running agents, the UI notifies you with the count of lost agents. Output logs and completed results are preserved on disk.
 
 ## StopAgent Tool
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-subagents-lite",
-  "version": "1.0.2",
+  "version": "1.2.0",
   "description": "Lightweight sub-agents for pi — spawn specialized agents with isolated sessions, tools, and models.",
   "keywords": [
     "pi-package",

package/src/agent-manager.ts

@@ -12,12 +12,13 @@ import { createOutputFilePath, streamToOutputFile, writeInitialEntry } from "./o
 import {
   type AgentInvocation,
   type AgentRecord,
+  type AgentStatus,
   type CompactionInfo,
   SHORT_ID_LENGTH,
   type SubagentType,
   type ThinkingLevel,
 } from "./types.js";
-import { addUsage, getLifetimeTotal, type LifetimeUsage } from "./usage.js";
+import { addUsage, getLifetimeTotal, getSessionContextPercent, type LifetimeUsage } from "./usage.js";
 import { errorMessage } from "./utils.js";
 
 /** How often to check for expired agent records (milliseconds). */
@@ -47,16 +48,16 @@ function createOutputCleanup(
   const outputStats = { turnCount: 0, toolUseCount: 0, totalTokens: 0, cost: 0 };
   const cleanup = streamToOutputFile(session, path, outputStats);
   return () => {
-    outputStats.turnCount = record.turnCount ?? 0;
-    outputStats.toolUseCount = record.toolUses;
-    outputStats.totalTokens = getLifetimeTotal(record.lifetimeUsage);
-    outputStats.cost = record.lifetimeUsage.cost;
+    outputStats.turnCount = record.stats.turnCount ?? 0;
+    outputStats.toolUseCount = record.stats.toolUses;
+    outputStats.totalTokens = getLifetimeTotal(record.stats.lifetimeUsage);
+    outputStats.cost = record.stats.lifetimeUsage.cost;
     cleanup();
   };
 }
 
 /** Whether the agent status is terminal (no longer running or queued). */
-function isTerminalStatus(status: AgentRecord["status"]): boolean {
+function isTerminalStatus(status: AgentStatus): boolean {
   return status !== "running" && status !== "queued";
 }
 
@@ -93,6 +94,10 @@ export interface SpawnOptions {
   maxTurns?: number;
   thinkingLevel?: ThinkingLevel;
   isBackground?: boolean;
+  /** Resolved worktree path — forwarded as cwd to runAgent. */
+  worktreePath?: string;
+  /** Short display label for the worktree (set on record display after spawn). */
+  worktreeLabel?: string;
   /**
    * Model key for concurrency pool lookup (e.g. "llamacpp/4b_small").
    * When set, the agent is counted against that model's concurrency limit.
@@ -125,6 +130,9 @@ export class AgentManager {
   private onComplete?: OnAgentComplete;
   private onStart?: OnAgentStart;
 
+  /** Session-level cumulative agent cost. Survives agent eviction. */
+  private totalAgentCost = 0;
+
   /** Per-model concurrency slots keyed by "provider/modelId". */
   private concurrencySlots = new Map<string, ConcurrencySlot>();
 
@@ -248,16 +256,26 @@ export class AgentManager {
 
     const record: AgentRecord = {
       id,
-      type,
-      description: options.description,
-      status: queued ? "queued" : "running",
-      toolUses: 0,
-      startedAt: Date.now(),
-      abortController,
-      lifetimeUsage: { input: 0, output: 0, cacheWrite: 0, cost: 0 },
-      compactionCount: 0,
-      invocation: options.invocation,
-      maxTurns: options.maxTurns,
+      lifecycle: {
+        status: queued ? "queued" : "running",
+        startedAt: Date.now(),
+      },
+      display: {
+        type,
+        description: options.description,
+        invocation: options.invocation,
+        worktreePath: options.worktreePath,
+        worktreeLabel: options.worktreeLabel,
+      },
+      execution: {
+        abortController,
+      },
+      stats: {
+        lifetimeUsage: { input: 0, output: 0, cacheWrite: 0, cost: 0 },
+        toolUses: 0,
+        compactionCount: 0,
+        maxTurns: options.maxTurns,
+      },
     };
     this.agents.set(id, record);
 
@@ -286,12 +304,12 @@ export class AgentManager {
   ) {
     if (concurrencySlot) concurrencySlot.running++;
 
-    record.status = "running";
-    record.startedAt = Date.now();
+    record.lifecycle.status = "running";
+    record.lifecycle.startedAt = Date.now();
 
     // Create output file for this agent
-    record.outputFile = createOutputFilePath(id);
-    writeInitialEntry(record.outputFile, prompt);
+    record.display.outputFile = createOutputFilePath(id);
+    writeInitialEntry(record.display.outputFile, prompt);
 
     this.onStart?.(record);
 
@@ -306,30 +324,31 @@ export class AgentManager {
       model: options.model,
       maxTurns: options.maxTurns,
       thinkingLevel: options.thinkingLevel,
+      cwd: options.worktreePath,
       graceTurns: options.graceTurns,
-      signal: record.abortController!.signal,
+      signal: record.execution.abortController!.signal,
       ...this.createRecordCallbacks(record, options),
       onTurnEnd: (turnCount) => {
-        record.turnCount = turnCount;
+        record.stats.turnCount = turnCount;
         options.onTurnEnd?.(turnCount);
       },
       onTextDelta: options.onTextDelta,
       onSessionCreated: (session) => {
-        record.session = session;
+        record.execution.session = session;
         // Flush any steers that arrived before the session was ready
-        if (record.pendingSteers?.length) {
-          for (const msg of record.pendingSteers) {
+        if (record.execution.pendingSteers?.length) {
+          for (const msg of record.execution.pendingSteers) {
             session.steer(msg).catch(() => {
               // Steer is advisory — a failure here (e.g. session already aborting)
               // is fine; the user can re-send if needed.
             });
           }
-          record.pendingSteers = undefined;
+          record.execution.pendingSteers = undefined;
         }
         // Stream session events to the output file
-        if (record.outputFile) {
-          record.outputCleanup = createOutputCleanup(
-            session, record.outputFile, record,
+        if (record.display.outputFile) {
+          record.execution.outputCleanup = createOutputCleanup(
+            session, record.display.outputFile, record,
           );
         }
         options.onSessionCreated?.(session);
@@ -337,28 +356,29 @@ export class AgentManager {
     })
       .then(({ responseText, session, aborted, steered }) => {
         // Don't overwrite status if externally stopped via abort()
-        if (record.status !== "stopped") {
-          record.status = aborted ? "aborted" : steered ? "steered" : "completed";
+        if (record.lifecycle.status !== "stopped") {
+          record.lifecycle.status = aborted ? "aborted" : steered ? "steered" : "completed";
         }
         record.result = responseText;
-        record.session = session;
-        record.completedAt ??= Date.now();
+        record.execution.session = session;
+        record.stats.contextPercent = getSessionContextPercent(session);
+        record.lifecycle.completedAt ??= Date.now();
         return responseText;
       })
       .catch((err) => {
         // Don't overwrite status if externally stopped via abort()
-        if (record.status !== "stopped") {
-          record.status = "error";
+        if (record.lifecycle.status !== "stopped") {
+          record.lifecycle.status = "error";
         }
         record.error = errorMessage(err);
-        record.completedAt ??= Date.now();
+        record.lifecycle.completedAt ??= Date.now();
         return "";
       })
       .finally(() => {
         // Final flush of streaming output file
-        if (record.outputCleanup) {
-          try { record.outputCleanup(); } catch { /* ignore */ }
-          record.outputCleanup = undefined;
+        if (record.execution.outputCleanup) {
+          try { record.execution.outputCleanup(); } catch { /* ignore */ }
+          record.execution.outputCleanup = undefined;
         }
 
         // Decrement per-model concurrency count
@@ -368,14 +388,20 @@ export class AgentManager {
         this.drainQueue();
       });
 
-    record.promise = promise;
+    record.execution.promise = promise;
   }
 
   /** Notify completion callback, ignoring any errors. */
   private safeNotifyComplete(record: AgentRecord): void {
+    this.totalAgentCost += record.stats.lifetimeUsage.cost;
     try { this.onComplete?.(record); } catch { /* ignore */ }
   }
 
+  /** Get the session-level cumulative agent cost. Survives agent eviction. */
+  getTotalAgentCost(): number {
+    return this.totalAgentCost;
+  }
+
   /**
    * Build common record-tracking callbacks shared by startAgent.
    * Updates the record's toolUses, lifetimeUsage, and compactionCount.
@@ -391,15 +417,15 @@ export class AgentManager {
   } {
     return {
       onToolActivity: (activity) => {
-        if (activity.type === "end") record.toolUses++;
+        if (activity.type === "end") record.stats.toolUses++;
         options?.onToolActivity?.(activity);
       },
       onAssistantUsage: (usage) => {
-        addUsage(record.lifetimeUsage, usage);
+        addUsage(record.stats.lifetimeUsage, usage);
         options?.onAssistantUsage?.(usage);
       },
       onCompaction: (info) => {
-        record.compactionCount++;
+        record.stats.compactionCount++;
         options?.onCompaction?.(info);
       },
     };
@@ -410,7 +436,7 @@ export class AgentManager {
     const started = new Set<string>();
     for (const entry of this.queue) {
       const record = this.agents.get(entry.id);
-      if (!record || record.status !== "queued") continue;
+      if (!record || record.lifecycle.status !== "queued") continue;
 
       const slot = this.getSlot(entry.modelKey);
       if (slot.running >= slot.limit) continue;
@@ -420,9 +446,9 @@ export class AgentManager {
         started.add(entry.id);
       } catch (err) {
         // Late failure — surface on the record so the user can see it
-        record.status = "error";
+        record.lifecycle.status = "error";
         record.error = errorMessage(err);
-        record.completedAt = Date.now();
+        record.lifecycle.completedAt = Date.now();
         started.add(entry.id);
         this.safeNotifyComplete(record);
       }
@@ -439,17 +465,17 @@ export class AgentManager {
     const record = this.agents.get(id);
     if (!record) return false;
 
-    if (record.status !== "running") return false;
+    if (record.lifecycle.status !== "running") return false;
 
-    if (!record.session) {
+    if (!record.execution.session) {
       // Session not yet created — queue the steer
-      if (!record.pendingSteers) record.pendingSteers = [];
-      record.pendingSteers.push(message);
+      if (!record.execution.pendingSteers) record.execution.pendingSteers = [];
+      record.execution.pendingSteers.push(message);
       return true;
     }
 
     try {
-      await record.session.steer(message);
+      await record.execution.session.steer(message);
       return true;
     } catch {
       // steer failures are surfaced to the caller via the boolean return value
@@ -463,7 +489,7 @@ export class AgentManager {
 
   listAgents(): AgentRecord[] {
     return [...this.agents.values()].sort(
-      (a, b) => b.startedAt - a.startedAt,
+      (a, b) => b.lifecycle.startedAt - a.lifecycle.startedAt,
     );
   }
 
@@ -479,30 +505,30 @@ export class AgentManager {
    * Returns true if the agent was stopped, false if it wasn't running/queued.
    */
   private stopAgent(record: AgentRecord): boolean {
-    if (record.status === "queued") {
+    if (record.lifecycle.status === "queued") {
       this.queue = this.queue.filter(q => q.id !== record.id);
-    } else if (record.status !== "running") {
+    } else if (record.lifecycle.status !== "running") {
       return false;
     } else {
-      record.abortController?.abort();
+      record.execution.abortController?.abort();
     }
-    record.status = "stopped";
-    record.completedAt = Date.now();
+    record.lifecycle.status = "stopped";
+    record.lifecycle.completedAt = Date.now();
     return true;
   }
 
   /** Dispose a record's session and remove it from the map. */
   private removeRecord(id: string, record: AgentRecord): void {
-    record.session?.dispose();
-    record.session = undefined;
+    record.execution.session?.dispose();
+    record.execution.session = undefined;
     this.agents.delete(id);
   }
 
   private cleanup() {
     const cutoff = Date.now() - CLEANUP_AGE_CUTOFF_MS;
     for (const [id, record] of this.agents) {
-      if (!isTerminalStatus(record.status)) continue;
-      if ((record.completedAt ?? 0) >= cutoff) continue;
+      if (!isTerminalStatus(record.lifecycle.status)) continue;
+      if ((record.lifecycle.completedAt ?? 0) >= cutoff) continue;
       this.removeRecord(id, record);
     }
   }
@@ -511,7 +537,7 @@ export class AgentManager {
     clearInterval(this.cleanupInterval);
     this.queue = [];
     for (const record of this.agents.values()) {
-      record.session?.dispose();
+      record.execution.session?.dispose();
     }
     this.agents.clear();
   }