@pi-archimedes/subagent 2.0.1 → 2.1.0

package/README.md

@@ -2,7 +2,9 @@
 
 Subagent dispatch with live TUI streaming and cost tracking for the [Pi coding agent](https://github.com/earendil-works/pi).
 
-## Features
+Dispatch specialized subagents to offload complex tasks with live TUI streaming, parallel execution, cost tracking, and per-agent model overrides. By fanning out work to dedicated subagents, complex workflows can be executed concurrently while maintaining full visibility into progress and token usage.
+
+## What you get
 
 - **Single & parallel execution** — dispatch one task or fan out multiple tasks across different agents simultaneously
 - **Live TUI streaming** — watch subagent progress in real-time with color-coded tool calls (grey while running, green/red on completion), readable argument previews, token counts, and cost updates
@@ -38,16 +40,16 @@ Toggle which tools are available to an agent from Pi's full toolset:
 
 ![subagents tool selection](../../docs/images/subagents-tool-selection.png)
 
-## Installation
+## Install
 
 ```bash
-pi install @pi-archimedes/subagent
+pi install npm:@pi-archimedes/subagent
 ```
 
-Or install the full [pi-archimedes](../..) meta package for the integrated experience (cost tracking in footer, shared chrome, etc.):
+Or install full meta package:
 
 ```bash
-pi install pi-archimedes
+pi install npm:pi-archimedes
 ```
 
 ## Usage
@@ -84,14 +86,18 @@ Run `/agents` to open the interactive Agents Manager for creating, editing, and
 
 Agents are defined as `.md` files with YAML frontmatter, placed in one of:
 
-- **Project scope:** `<cwd>/.pi/agents/` — available only in this project
-- **User scope:** `~/.pi/agents/` — available across all projects
-- **Global scope:** installed via packages or extensions
+- **Project scope:** `<repo root>/.pi/agents/` — available only in this project
+- **User scope:** `~/.pi/agent/agents/` — available across all projects
+- **Global scope:** `<repo root>/.agents/agents/` or `~/.agents/agents/` — shared or installed subagents
+
+Frontmatter supports: `name`, `description`, `model`, `tools`, and `thinking`. The markdown body becomes the agent's system prompt. Unknown frontmatter fields are preserved on edit but not interpreted.
 
-Frontmatter supports: `name`, `model`, `tools`, `thinking`, `inheritProjectContext`, `inheritSkills`, `systemPromptMode`, and `systemPrompt`.
+Per-agent `model` and `thinking` assignments made in the `/agents` TUI are stored in `~/.pi/agent/agents.local.json` (machine-local, not committed) and take precedence over frontmatter values; on save, the TUI also strips these fields from the `.md` frontmatter. Frontmatter `model:` and `thinking:` still work as a fallback for hand-written agent files.
 
 ## Integration
 
 When installed via `pi-archimedes` (the meta package), subagent cost events flow through `@pi-archimedes/core/bus` and are consumed by `@pi-archimedes/footer`'s `CostAccumulator`. This merges subagent tokens and cost into the main status bar for a unified view.
 
 The `/agents` command is also only registered by the meta package (not by standalone `@pi-archimedes/subagent`).
+
+← Back to [pi-archimedes](../../README.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-archimedes/subagent",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "type": "module",
   "keywords": [
     "pi-package"
@@ -11,7 +11,7 @@
   ],
   "main": "./src/index.ts",
   "dependencies": {
-    "@pi-archimedes/core": "2.0.1"
+    "@pi-archimedes/core": "2.1.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": ">=0.1.0",

package/src/agent-manager.ts

@@ -17,6 +17,9 @@ import { serializeAgent, validateAgentName } from "./frontmatter-io.js";
 import {
   writeLocalModel,
   deleteLocalModel,
+  writeLocalThinking,
+  deleteLocalThinking,
+  deleteLocalAgent,
   readLocalConfig,
   setLocalConfig,
   type LocalConfig,
@@ -1248,9 +1251,11 @@ export function saveAgent(state: ManagerState, requestRender: () => void): void
   const newName = agent.name.endsWith(".md") ? agent.name : `${agent.name}.md`;
   const newPath = path.join(dir, newName);
 
-  // Capture model before entering the try block so it is available in the
-  // catch block for .md rollback if a later step (JSON write, etc.) fails.
+  // Capture model and thinking before entering the try block so they are
+  // available in the catch block for .md rollback if a later step
+  // (JSON write, etc.) fails.
   const model = agent.model;
+  const thinking = agent.thinking;
 
   // Track whether the .md write succeeded so the catch block knows whether
   // to restore or clean up the on-disk file.
@@ -1277,11 +1282,13 @@ export function saveAgent(state: ManagerState, requestRender: () => void): void
     // Ensure directory exists
     fs.mkdirSync(dir, { recursive: true });
 
-    // Build a shallow copy without the model for .md serialization so the
-    // live edit object is NOT mutated during serialization. If the .md
-    // write fails below, the live object stays intact for a retry.
+    // Build a shallow copy without the model/thinking for .md serialization
+    // (both fields are stored in agents.local.json) so the live edit object
+    // is NOT mutated during serialization. If the .md write fails below, the
+    // live object stays intact for a retry.
     const mdAgent = { ...agent };
     delete mdAgent.model;
+    delete mdAgent.thinking;
 
     // Serialize and write the .md file FIRST. If this fails, no JSON state
     // is persisted and the live edit object is untouched.
@@ -1293,21 +1300,27 @@ export function saveAgent(state: ManagerState, requestRender: () => void): void
     // Capture a backup of the current JSON config so we can roll it back
     // if a later step (re-discovery, etc.) fails after this write succeeds.
     jsonConfigBefore = readLocalConfig();
-    // Write/remove the NEW name entry first, then clean up the OLD name.
+    // Write/remove the NEW name entries first, then clean up the OLD name.
     if (model !== undefined) {
       writeLocalModel(agent.name, model);
     } else {
       deleteLocalModel(agent.name);
     }
+    if (thinking !== undefined) {
+      writeLocalThinking(agent.name, thinking);
+    } else {
+      deleteLocalThinking(agent.name);
+    }
     jsonWritten = true;
 
     // Handle rename: delete old JSON entry keyed by original name (after
-    // the new entry is safely written). Wrapped in try-catch so a failure
-    // here does not leave the .md written but the live object un-stripped.
+    // the new entries are safely written) — deleteLocalAgent covers all
+    // fields (model and thinking). Wrapped in try-catch so a failure here
+    // does not leave the .md written but the live object un-stripped.
     const originalName = state.editOriginal?.name;
     if (originalName && originalName !== agent.name) {
       try {
-        deleteLocalModel(originalName);
+        deleteLocalAgent(originalName);
       } catch {
         // Best-effort: stale entry is harmless and will be cleaned up on
         // a subsequent save/rename
@@ -1348,22 +1361,24 @@ export function saveAgent(state: ManagerState, requestRender: () => void): void
     state.editError = null;
     requestRender();
 
-    // Only strip model from the live edit object AFTER all operations
-    // (including re-discovery) have succeeded. This ensures that if any
-    // step fails, the catch block can restore the model to .md and the
-    // live object retains it for a safe retry.
+    // Only strip model/thinking from the live edit object AFTER all
+    // operations (including re-discovery) have succeeded. This ensures
+    // that if any step fails, the catch block can restore them to .md
+    // and the live object retains them for a safe retry.
     delete agent.model;
+    delete agent.thinking;
   } catch (err) {
     // Restore prior .md state if the write succeeded but a later step
     // (JSON write, re-discovery, etc.) failed:
     //   - rename (old file not yet unlinked): check whether the old file
     //     still exists. If so, delete newPath so only the original remains.
     //     If the old file is gone (deleted externally or by a prior attempt),
-    //     newPath may be the sole copy — keep it with a model fallback, or
-    //     delete it when there is no model to fall back on.
+    //     newPath may be the sole copy — keep it with a model/thinking
+    //     fallback, or delete it when there is no model/thinking to fall
+    //     back on.
     //   - existing file: write the original content back verbatim.
-    //   - new file with a model: keep a frontmatter fallback so the model
-    //     override survives for the next retry.
+    //   - new file with model/thinking: keep a frontmatter fallback so the
+    //     overrides survive for the next retry.
     // If the old .md was already unlinked during rename (oldPathDeleted),
     // newPath is the sole surviving copy — leave it in place.
     // If the .md write itself failed (mdWritten is false) there is nothing
@@ -1373,19 +1388,25 @@ export function saveAgent(state: ManagerState, requestRender: () => void): void
         if (oldPath && fs.existsSync(oldPath)) {
           // Old file still exists — safe to delete newPath and restore prior state
           try { fs.unlinkSync(newPath); } catch { /* best-effort */ }
-        } else if (model !== undefined) {
-          // Old file is gone — keep newPath with model as fallback
-          try { fs.writeFileSync(newPath, serializeAgent({ ...agent, model }), "utf-8"); } catch { /* best-effort */ }
+        } else if (model !== undefined || thinking !== undefined) {
+          // Old file is gone — keep newPath with model/thinking as fallback
+          const fallback: AgentConfig = { ...agent };
+          if (model !== undefined) fallback.model = model;
+          if (thinking !== undefined) fallback.thinking = thinking;
+          try { fs.writeFileSync(newPath, serializeAgent(fallback), "utf-8"); } catch { /* best-effort */ }
         } else {
-          // Old file is gone and no model — delete newPath (no prior state to restore)
+          // Old file is gone and no model/thinking — delete newPath (no prior state to restore)
           try { fs.unlinkSync(newPath); } catch { /* best-effort */ }
         }
       } else if (originalContent !== undefined) {
         try { fs.writeFileSync(newPath, originalContent, "utf-8"); } catch { /* best-effort */ }
-      } else if (model !== undefined) {
-        try { fs.writeFileSync(newPath, serializeAgent({ ...agent, model }), "utf-8"); } catch { /* best-effort */ }
+      } else if (model !== undefined || thinking !== undefined) {
+        const fallback: AgentConfig = { ...agent };
+        if (model !== undefined) fallback.model = model;
+        if (thinking !== undefined) fallback.thinking = thinking;
+        try { fs.writeFileSync(newPath, serializeAgent(fallback), "utf-8"); } catch { /* best-effort */ }
       } else {
-        // New file without model — delete it (no prior state to restore)
+        // New file without model/thinking — delete it (no prior state to restore)
         try { fs.unlinkSync(newPath); } catch { /* best-effort */ }
       }
     }

package/src/agents.test.ts

@@ -14,6 +14,7 @@ process.env.PI_CODING_AGENT_DIR = testDir;
 function makeAgent(
   name: string,
   model?: string,
+  thinking?: string,
 ): AgentConfig {
   return {
     name,
@@ -22,6 +23,7 @@ function makeAgent(
     source: "global" as const,
     filePath: join(testDir, `${name}.md`),
     ...(model !== undefined ? { model } : {}),
+    ...(thinking !== undefined ? { thinking } : {}),
   };
 }
 
@@ -62,6 +64,41 @@ describe("applyLocalOverrides", () => {
     expect(() => applyLocalOverrides([])).not.toThrow();
   });
 
+  it("sets thinking from JSON override", () => {
+    const path = join(testDir, "agents.local.json");
+    writeFileSync(path, JSON.stringify({ codex: { thinking: "high" } }), "utf-8");
+
+    const agent = makeAgent("codex");
+    applyLocalOverrides([agent]);
+    expect(agent.thinking).toBe("high");
+  });
+
+  it("leaves thinking unchanged when no JSON entry exists", () => {
+    const agent = makeAgent("codex", undefined, "low");
+    applyLocalOverrides([agent]);
+    expect(agent.thinking).toBe("low");
+  });
+
+  it("leaves thinking unchanged when JSON entry has no thinking field (model still applied)", () => {
+    const path = join(testDir, "agents.local.json");
+    writeFileSync(path, JSON.stringify({ codex: { model: "o1" } }), "utf-8");
+
+    const agent = makeAgent("codex", "M1", "low");
+    applyLocalOverrides([agent]);
+    expect(agent.thinking).toBe("low");
+    expect(agent.model).toBe("o1");
+  });
+
+  it("applies model and thinking together when both are present", () => {
+    const path = join(testDir, "agents.local.json");
+    writeFileSync(path, JSON.stringify({ codex: { model: "o1", thinking: "high" } }), "utf-8");
+
+    const agent = makeAgent("codex", "M1", "low");
+    applyLocalOverrides([agent]);
+    expect(agent.model).toBe("o1");
+    expect(agent.thinking).toBe("high");
+  });
+
   it("works with corrupt JSON file (agent model stays unchanged)", () => {
     const path = join(testDir, "agents.local.json");
     writeFileSync(path, "{ broken json", "utf-8");

package/src/agents.ts

@@ -138,8 +138,10 @@ export interface AgentsDiscoveryResult {
 }
 
 /**
- * Apply local model overrides from agents.local.json to a list of agents.
- * Reads the config once and mutates matching agents in place.
+ * Apply local overrides from agents.local.json (model and thinking) to a list of agents.
+ * Reads the config once and mutates matching agents in place. JSON takes
+ * precedence over the agent's .md values; a missing entry or field leaves the
+ * agent's value untouched.
  */
 export function applyLocalOverrides(agents: AgentConfig[]): void {
   const config = readLocalConfig();
@@ -148,6 +150,9 @@ export function applyLocalOverrides(agents: AgentConfig[]): void {
     if (local?.model !== undefined) {
       agent.model = local.model;
     }
+    if (local?.thinking !== undefined) {
+      agent.thinking = local.thinking;
+    }
   }
 }