pi-fast-subagent 0.7.0 → 0.9.0

package/README.md

@@ -14,6 +14,24 @@ Runs subagents with `createAgentSession()` in same process instead of spawning `
 - User + project agent discovery
 - Project agents override user agents
 - Max nesting depth guard
+- Chronological expanded view (Ctrl+O): subagent tool calls and response text interleaved in execution order
+- Collapsed view shows response + trailing tool calls as an indented tree
+
+## Settings
+
+Configure preview sizes in `~/.pi/agent/settings.json` or `.pi/settings.json`:
+
+```json
+{
+  "fastSubagent": {
+    "previewLines": 12,
+    "promptPreviewLines": 12
+  }
+}
+```
+
+- `previewLines` — response text preview lines in collapsed view (default 12)
+- `promptPreviewLines` — task/prompt preview lines in collapsed view (default 12)
 
 ## Install
 
@@ -69,6 +87,7 @@ You are code exploration specialist. Read relevant files, trace data flow, summa
 | `description` | yes | One-line description shown in `/fast-subagent:agent` |
 | `model` | no | Model override, format `provider/model-id` (e.g. `anthropic/claude-haiku-4-5`) |
 | `tools` | no | Tool allowlist (see below) |
+| `maxDepth` | no | Nested subagent depth this agent may spawn. Default `0` means this agent cannot call `subagent`. |
 
 ### `tools:` field
 
@@ -125,6 +144,28 @@ tools: all
 
 **YAML comments** (`# …`) are allowed inside the frontmatter — handy for documenting *why* a particular tool set was chosen. See `agents/general.md` and `agents/scout.md` for examples.
 
+### `maxDepth:` field
+
+Subagents cannot spawn other subagents by default, even when `tools` exposes the `subagent` tool.
+
+```md
+---
+name: planner
+description: Can delegate one level deeper
+maxDepth: 1
+---
+```
+
+Depth counts nested generations from that agent:
+
+| Value | Behavior |
+|-------|----------|
+| *(omitted)* / `0` | This agent cannot spawn subagents |
+| `1` | This agent may spawn subagents, but those children cannot spawn again unless their own `maxDepth` allows it |
+| `2` | Allows two nested generations, subject to each child agent's own `maxDepth` |
+
+Aliases accepted: `max_depth`, `depth`, `subagentDepth`.
+
 ## Background Agents
 
 Every foreground subagent can be moved to background at any time. Background jobs run concurrently while you continue chatting. When a job finishes, pi automatically posts the result as a follow-up message.

package/agents/general.md

@@ -11,6 +11,9 @@ model: anthropic/claude-haiku-4-5
 #   comma-separated list → explicit allowlist, e.g. `read, grep, web_search`
 # General is meant to be a do-anything fallback, so it keeps everything explicit.
 tools: all
+
+# Subagents cannot spawn subagents by default. Set maxDepth: 1+ to opt in.
+maxDepth: 0
 ---
 
 You are general-purpose subagent.

package/agents/scout.md

@@ -11,6 +11,9 @@ model: anthropic/claude-haiku-4-5
 #   comma-separated list → explicit allowlist
 # Scout is read-only: no `edit`, no `write`, no extension tools. Keeps the agent from mutating the codebase.
 tools: read, bash, grep, find, ls
+
+# Subagents cannot spawn subagents by default. Keep scout focused on exploration only.
+maxDepth: 0
 ---
 
 You are code exploration specialist.

package/agents.ts

@@ -31,6 +31,8 @@ export interface AgentConfig {
   description: string;
   model?: string;
   tools: AgentTools;
+  /** Number of nested subagent generations this agent may spawn. Default: 0. */
+  maxDepth: number;
   systemPrompt: string;
   source: "user" | "project";
   filePath: string;
@@ -46,7 +48,7 @@ export function agentNeedsExtensions(tools: AgentTools): boolean {
 
 // Default: all tools, matching pi-subagents behavior. Agents opt into lean mode
 // with `tools: builtins` or explicit built-in allowlists.
-function parseToolsField(raw: unknown): AgentTools {
+export function parseToolsField(raw: unknown): AgentTools {
   if (raw === undefined || raw === null) return "all";
   const str = String(raw).trim();
   if (!str) return "all";
@@ -58,6 +60,13 @@ function parseToolsField(raw: unknown): AgentTools {
   return list.length ? list : "all";
 }
 
+export function parseMaxDepthField(raw: unknown): number {
+  if (raw === undefined || raw === null || raw === "") return 0;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n < 0) return 0;
+  return Math.floor(n);
+}
+
 function loadAgentsFromDir(dir: string, source: "user" | "project"): AgentConfig[] {
   if (!fs.existsSync(dir)) return [];
   let entries: fs.Dirent[];
@@ -77,11 +86,15 @@ function loadAgentsFromDir(dir: string, source: "user" | "project"): AgentConfig
       const { frontmatter, body } = parseFrontmatter<Record<string, string>>(content);
       if (!frontmatter?.name || !frontmatter?.description) continue;
       const tools = parseToolsField(frontmatter.tools);
+      const maxDepth = parseMaxDepthField(
+        frontmatter.maxDepth ?? frontmatter.max_depth ?? frontmatter.depth ?? frontmatter.subagentDepth,
+      );
       agents.push({
         name: frontmatter.name,
         description: frontmatter.description,
         model: frontmatter.model,
         tools,
+        maxDepth,
         systemPrompt: body.trim(),
         source,
         filePath,

package/format.ts

@@ -0,0 +1,119 @@
+/**
+ * Pure formatting helpers used by runner + render + command layers.
+ */
+
+import type { AgentConfig } from "./agents.js";
+import type { BackgroundSubagentJob } from "./background-types.js";
+import type { RunResult } from "./types.js";
+
+export function formatTools(tools: AgentConfig["tools"]): string {
+  if (tools === "all") return "all";
+  if (tools === "builtins") return "builtins (default)";
+  if (tools === "none") return "none";
+  return tools.join(", ");
+}
+
+export function shortPath(p: unknown): string {
+  if (typeof p !== "string") return "";
+  const cwd = process.cwd();
+  if (p.startsWith(cwd + "/")) return p.slice(cwd.length + 1);
+  return p.replace(/^\/Users\/[^/]+\/[^/]+\//, "");
+}
+
+export function summarizeToolArgs(toolName: unknown, toolInput: unknown): string {
+  const name = String(toolName ?? "");
+  const input =
+    toolInput && typeof toolInput === "object" ? (toolInput as Record<string, unknown>) : {};
+  const filePath = (): string => shortPath(input.path ?? input.file_path) || "";
+  switch (name) {
+    case "Read":
+    case "read":
+    case "Write":
+    case "write":
+    case "Edit":
+    case "edit":
+      return filePath();
+    case "Bash":
+    case "bash": {
+      const cmd = String(input.command ?? "");
+      return cmd.length > 80 ? cmd.slice(0, 77) + "..." : cmd;
+    }
+    case "Glob":
+    case "glob":
+      return String(input.pattern ?? "");
+    case "find": {
+      const pat = String(input.pattern ?? "");
+      const p = shortPath(input.path);
+      return p ? `${pat} in ${p}` : pat;
+    }
+    case "Grep":
+    case "grep": {
+      const pat = String(input.pattern ?? "");
+      const g = input.glob ? ` ${input.glob}` : "";
+      return `${pat}${g}`;
+    }
+    case "ls":
+      return shortPath(input.path) || "";
+    case "subagent": {
+      const agent = String(input.agent ?? "");
+      const t = String(input.task ?? "");
+      const summary = t.length > 50 ? t.slice(0, 47) + "..." : t;
+      return agent ? `${agent}: ${summary}` : summary;
+    }
+    default: {
+      for (const v of Object.values(input)) {
+        if (typeof v === "string" && v.length > 0)
+          return v.length > 60 ? v.slice(0, 57) + "..." : v;
+      }
+      return "";
+    }
+  }
+}
+
+export function formatDuration(ms: number): string {
+  const s = Math.max(0, Math.floor(ms / 1000));
+  const m = Math.floor(s / 60);
+  const rem = s % 60;
+  return m > 0 ? `${m}m ${rem}s` : `${rem}s`;
+}
+
+export function summarizeTask(task: string, max = 60): string {
+  return task.length > max ? task.slice(0, max - 3) + "..." : task;
+}
+
+export function formatTokens(n: number): string {
+  if (n < 1000) return String(n);
+  if (n < 10000) return `${(n / 1000).toFixed(1)}k`;
+  return `${Math.round(n / 1000)}k`;
+}
+
+export function formatUsage(usage: RunResult["usage"], model?: string): string {
+  const parts: string[] = [];
+  if (usage.turns) parts.push(`${usage.turns} turn${usage.turns > 1 ? "s" : ""}`);
+  if (usage.input) parts.push(`↑${formatTokens(usage.input)}`);
+  if (usage.output) parts.push(`↓${formatTokens(usage.output)}`);
+  if (usage.cost) parts.push(`$${usage.cost.toFixed(4)}`);
+  if (model) parts.push(model);
+  return parts.join(" ");
+}
+
+export function getFinalText(r: RunResult): string {
+  if (r.exitCode !== 0) return `Error: ${r.error ?? r.output ?? "(no output)"}`;
+  return r.output || "(no output)";
+}
+
+export function formatBgJobSummary(job: BackgroundSubagentJob, now = Date.now()): string {
+  const dur = job.completedAt ? formatDuration(job.completedAt - job.startedAt) : formatDuration(now - job.startedAt);
+  return `${job.id} [${job.status}] ${job.agentName} · ${dur} · ${summarizeTask(job.task)}`;
+}
+
+export function formatBgJobDetails(job: BackgroundSubagentJob, now = Date.now()): string {
+  const dur = job.completedAt ? formatDuration(job.completedAt - job.startedAt) : formatDuration(now - job.startedAt);
+  const lines = [`${job.id} [${job.status}] ${job.agentName} · ${dur}`, `Task: ${job.task}`];
+  if (job.model) lines.push(`Model: ${job.model}`);
+  if (job.status === "completed") lines.push(`\nResult:\n${job.resultSummary ?? "(no output)"}`);
+  if (job.status === "failed") lines.push(`\nError: ${job.error ?? "(unknown)"}`);
+  if (job.status === "cancelled") lines.push("\nCancelled.");
+  if (job.status === "running") lines.push("\nStill running.");
+  return lines.join("\n");
+}