@jerryan/pi-subagent-tools 0.1.0 → 0.3.0

package/index.ts

@@ -1,428 +1,19 @@
 /**
  * pi-subagent-tools — Specialized subagent delegation for pi
  *
- * Registers three tools for the "agent as project manager" workflow:
- *   review   — Read-only code review in the current project
- *   explore  — Read-only exploration of external projects (requires cwd)
- *   delegate — General-purpose worker with optional readonly and context inheritance
+ * Registers four tools for the "agent as project manager" workflow:
+ *   review    — Read-only code review in the current project
+ *   explore   — Read-only exploration of external projects (requires cwd)
+ *   delegate  — General-purpose worker with full tool access
+ *   follow_up — Continue an existing subagent's session with full context
  *
- * Recursion guard via PI_SUBAGENT_TOOLS_ROLE env var:
- *   - Parent (unset): all three tools active
- *   - Delegate child: review/explore active, delegate registered but rejects at runtime
- *   - Review/explore child: no subagent tools registered
+ * Subagents run in-process as SDK AgentSessions (see agents.ts). Interactive
+ * prompts route to the parent TUI via the UI bridge (see ui-bridge.ts).
  */
 
-import * as fs from "node:fs";
-import { execFileSync } from "node:child_process";
-import { fileURLToPath } from "node:url";
-import * as path from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { getMarkdownTheme } from "@earendil-works/pi-coding-agent";
-import { Container, Spacer, Text, Markdown } from "@earendil-works/pi-tui";
-import { Type } from "@sinclair/typebox";
-import {
-  runSubagent,
-  READONLY_TOOLS,
-} from "./spawn.ts";
-import { shortenPath, formatUsage, createSpinner } from "./tui.ts";
-
-const subagentSpinners = new Map<string, () => string>();
-
-const EXTENSION_DIR = path.dirname(fileURLToPath(import.meta.url));
-
-// ---------------------------------------------------------------------------
-// Compact preview component — delegates to Text.render(width) for wrapping
-// ---------------------------------------------------------------------------
-
-export class CompactPreview {
-  private textComp: Text;
-  private maxLines: number;
-
-  constructor(text: string, maxLines: number = 5) {
-    this.maxLines = maxLines;
-    this.textComp = new Text(text, 0, 0);
-  }
-
-  render(width: number): string[] {
-    const lines = this.textComp.render(width);
-    if (lines.length === 0) return [];
-
-    if (lines.length <= this.maxLines) return lines;
-
-    return ["...", ...lines.slice(-this.maxLines)];
-  }
-
-  invalidate() {
-    this.textComp.invalidate();
-  }
-}
-
-const PROMPTS_DIR = path.resolve(EXTENSION_DIR, "prompts");
-const REVIEW_PROMPT_FILE = path.join(PROMPTS_DIR, "review.md");
-const EXPLORE_PROMPT_FILE = path.join(PROMPTS_DIR, "explore.md");
-const EXTENSION_FILE = path.join(EXTENSION_DIR, "index.ts");
-
-// Role guard
-// ---------------------------------------------------------------------------
-
-export const ROLE_ENV = "PI_SUBAGENT_TOOLS_ROLE";
-
-export type SubagentRole = "delegate" | "review" | "explore";
-
-export function getCurrentRole(): SubagentRole | undefined {
-  const value = process.env[ROLE_ENV];
-  if (value === "delegate" || value === "review" || value === "explore") {
-    return value;
-  }
-  return undefined;
-}
-
-// ---------------------------------------------------------------------------
-// Shared parameter types
-// ---------------------------------------------------------------------------
-
-export const TaskParam = Type.String({
-  description: "Task to delegate to the subagent",
-});
-
-export const SkillsParam = Type.Optional(
-  Type.Array(Type.String(), {
-    description: "Optional startup skills to load via --skill",
-  }),
-);
-
-export const CwdParam = Type.Optional(
-  Type.String({
-    description:
-      "Working directory for the subagent. Defaults to the parent's cwd.",
-  }),
-);
-
-export const ContextParam = Type.Optional(
-  Type.String({
-    enum: ["fresh", "inherit"],
-    description:
-      'Context mode. "fresh" (default): isolated process with no parent history. "inherit": forks parent session so child sees conversation history.',
-  }),
-);
-
-// Tool-specific parameter schemas
-export const ReviewParams = Type.Object({
-  task: TaskParam,
-  skills: SkillsParam,
-});
-
-export const ExploreParams = Type.Object({
-  task: TaskParam,
-  cwd: Type.String({
-    description:
-      "Working directory for the explorer. Required — the explorer runs in the target project to pick up its settings, skills, and context files.",
-  }),
-  skills: SkillsParam,
-});
-
-export const DelegateParams = Type.Object({
-  task: TaskParam,
-  cwd: CwdParam,
-  skills: SkillsParam,
-  context: ContextParam,
-});
-
-// ---------------------------------------------------------------------------
-// Shared execute helper
-// ---------------------------------------------------------------------------
-
-async function subagentExecute(
-  cwd: string,
-  task: string,
-  skills: string[] | undefined,
-  allowedTools: string[] | undefined,
-  extensionFile: string | undefined,
-  systemPromptFile: string | undefined,
-  childRole: "review" | "explore" | "delegate" | undefined,
-  signal: AbortSignal | undefined,
-  onUpdate: ((result: any) => void) | undefined,
-) {
-  // Validate cwd exists before spawning
-  if (!cwd) {
-    return {
-      content: [{ type: "text" as const, text: "Cannot spawn subagent: cwd is required." }],
-      isError: true,
-      details: { final: true },
-    };
-  }
-  try {
-    const stat = fs.statSync(cwd);
-    if (!stat.isDirectory()) {
-      return {
-        content: [{
-          type: "text" as const,
-          text: `Cannot spawn subagent: "${cwd}" is not a directory.`,
-        }],
-        isError: true,
-        details: { final: true },
-      };
-    }
-  } catch (err: any) {
-    return {
-      content: [{
-        type: "text" as const,
-        text: `Cannot spawn subagent: cwd "${cwd}" does not exist or is not accessible (${err.message}).`,
-      }],
-      isError: true,
-      details: { final: true },
-    };
-  }
-
-  try {
-    const result = await runSubagent({
-      cwd,
-      task,
-      skills,
-      allowedTools,
-      extensionFile,
-      systemPromptFile,
-      childRole,
-      signal,
-      onUpdate,
-    });
-    return {
-      content: [{ type: "text" as const, text: result.output }],
-      isError: result.isError,
-      details: {
-        usage: {
-          turns: result.turns,
-          total: result.tokens?.total,
-          input: result.tokens?.input,
-          output: result.tokens?.output,
-          durationMs: result.durationMs,
-        },
-        final: true,
-        stderr: result.stderr,
-      },
-      toolCalls: result.toolCalls,
-    };
-  } catch (err: any) {
-    return {
-      content: [{
-        type: "text" as const,
-        text: `Subagent failed: ${err.message || String(err)}`,
-      }],
-      isError: true,
-      details: { final: true },
-    };
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Shared render helpers
-// ---------------------------------------------------------------------------
-
-function renderSubagentCall(
-  label: string,
-  args: { task: string; cwd?: string },
-  theme: any,
-) {
-  const firstLine = args.task.split("\n")[0];
-  const combined = args.cwd ? `${shortenPath(args.cwd)} | ${firstLine}` : firstLine;
-  const preview = combined.length > 80 ? combined.slice(0, 77) + "..." : combined;
-  return new Text(
-    `${theme.fg("toolTitle", theme.bold(label))}${theme.fg("dim", preview)}`,
-    0, 0,
-  );
-}
-
-function renderSubagentResult(
-  result: { content: Array<{ type: string; text?: string }>; isError?: boolean; details?: any },
-  options: { expanded: boolean },
-  theme: any,
-  context: { toolCallId: string },
-) {
-  if (!subagentSpinners.has(context.toolCallId)) {
-    subagentSpinners.set(context.toolCallId, createSpinner());
-  }
-  const spin = subagentSpinners.get(context.toolCallId)!;
-  const raw = result.content.filter((c: any) => c.type === "text").map((c: any) => c.text).join("");
-  const output = raw.split("\n").map(l => l.startsWith("▸") ? theme.fg("muted", l) : l).join("\n");
-  const container = new Container();
-
-  if (result.details?.final) subagentSpinners.delete(context.toolCallId);
-
-  if (!options.expanded) {
-    const text = output || theme.fg("dim", "(no output)");
-    const usage = result.details?.usage;
-    const hint = ` · ${theme.fg("dim", "Ctrl+O to expand")}`;
-    const status = usage ? formatUsage(usage, spin) + hint : "";
-    container.addChild(new CompactPreview(text));
-    if (status) container.addChild(new Text(theme.fg("dim", status), 0, 0));
-    return container;
-  }
-
-  const isFinal = !!result.details?.final;
-  if (isFinal) {
-    const mdTheme = getMarkdownTheme();
-    container.addChild(new Markdown(raw, 0, 0, mdTheme));
-  } else {
-    container.addChild(new CompactPreview(output, 15));
-  }
-  if (result.details?.usage) {
-    container.addChild(new Spacer(1));
-    container.addChild(new Text(theme.fg("dim", formatUsage(result.details.usage, spin)), 0, 0));
-  }
-
-  return container;
-}
-
-// ---------------------------------------------------------------------------
-// Extension entry point
-// ---------------------------------------------------------------------------
+import { AgentManager, registerAgentTools } from "./agents.ts";
 
 export default function (pi: ExtensionAPI) {
-  const role = getCurrentRole();
-
-  // Review/explore children: register git tool only, then return
-  if (role === "review" || role === "explore") {
-    pi.registerTool({
-      name: "git",
-      label: "Git",
-      description: "Run read-only git commands (log, diff, status, show, branch, blame).",
-      promptSnippet: "Run a read-only git command",
-      parameters: Type.Object({
-        command: Type.String({
-          description: "Git command with arguments (e.g. 'log --oneline -10', 'diff HEAD~1', 'status').",
-        }),
-      }),
-      async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-        try {
-          const args = params.command.trim().split(/\s+/);
-          if (args.length === 0) {
-            return { content: [{ type: "text" as const, text: "No git command provided." }], isError: true };
-          }
-          const subcommand = args[0];
-          const READONLY_GIT = new Set(["log","diff","show","status","branch","blame",
-            "rev-parse","rev-list","ls-tree","ls-files","grep","describe","shortlog","whatchanged"]);
-          if (!READONLY_GIT.has(subcommand)) {
-            return {
-              content: [{ type: "text" as const, text: `git ${subcommand} is not allowed (read-only commands only).` }],
-              isError: true,
-            };
-          }
-          const output = execFileSync("git", args, {
-            cwd: ctx.cwd,
-            encoding: "utf-8",
-            maxBuffer: 10 * 1024 * 1024,
-            timeout: 30_000,
-          });
-          return { content: [{ type: "text" as const, text: output }] };
-        } catch (err: any) {
-          return {
-            content: [{ type: "text" as const, text: `git ${params.command}\n\n${err.stderr || err.message}` }],
-            isError: true,
-          };
-        }
-      },
-    });
-    return;
-  }
-
-
-  // Delegate tool: always registered (cache compatibility), rejects in delegate children
-  pi.registerTool({
-    name: "delegate",
-    label: "Delegate",
-    description:
-      "Delegate a task to an isolated subagent process. " +
-      "For general-purpose work that doesn't fit the review or explore tools.",
-    promptSnippet: "Delegate a task to a worker subagent",
-    promptGuidelines: [
-      "Use the delegate tool for non-trivial, self-contained implementation tasks — it has full tool access unlike the read-only review and explore tools.",
-    ],
-    parameters: DelegateParams,
-    async execute(_toolCallId, params, signal, onUpdate, ctx) {
-      if (role === "delegate") {
-        return {
-          content: [
-            {
-              type: "text" as const,
-              text: "Delegation not available in delegate subagents. Use review or explore instead.",
-            },
-          ],
-          isError: true,
-        };
-      }
-      return subagentExecute(
-        params.cwd ?? ctx.cwd,
-        params.task,
-        params.skills,
-        undefined, // no tool filtering — cache-compatible
-        EXTENSION_FILE, // same extensions → same system prompt → cache hit
-        undefined, // no system prompt — cache-compatible
-        "delegate", // delegate children can spawn review/explore but not delegate further
-        signal,
-        onUpdate,
-      );
-    },
-    renderCall: (args, theme) => renderSubagentCall("delegate ", args, theme),
-    renderResult: (result, options, theme, context) => renderSubagentResult(result as any, options, theme, context),
-  });
-
-  // Review tool
-  pi.registerTool({
-    name: "review",
-    label: "Review",
-    description:
-      "Review code changes or files in the current project. " +
-      "The reviewer is always read-only and runs in the parent's working directory. " +
-      "Use for code review, diff inspection, issue analysis, and quality checks.",
-    promptSnippet: "Review code or files with a read-only subagent",
-    promptGuidelines: [
-      "Use the review tool for code review, diff inspection, and quality checks — it is read-only and cannot modify files.",
-    ],
-    parameters: ReviewParams,
-    async execute(_toolCallId, params, signal, onUpdate, ctx) {
-      return subagentExecute(
-        ctx.cwd,
-        params.task,
-        params.skills,
-        READONLY_TOOLS,
-        EXTENSION_FILE,
-        REVIEW_PROMPT_FILE,
-        "review",
-        signal,
-        onUpdate,
-      );
-    },
-    renderCall: (args, theme) => renderSubagentCall("review ", args, theme),
-    renderResult: (result, options, theme, context) => renderSubagentResult(result as any, options, theme, context),
-  });
-
-  // Explore tool
-  pi.registerTool({
-    name: "explore",
-    label: "Explore",
-    description:
-      "Explore a project directory to understand its structure, patterns, and key files. " +
-      "The explorer is always read-only and runs in the specified working directory. " +
-      "Use for mapping codebases, scouting dependencies, or understanding unfamiliar projects.",
-    promptSnippet: "Explore a project directory with a read-only subagent",
-    promptGuidelines: [
-      "Use the explore tool to map unfamiliar codebases or scout dependencies — it runs read-only in the specified directory.",
-    ],
-    parameters: ExploreParams,
-    async execute(_toolCallId, params, signal, onUpdate, ctx) {
-      return subagentExecute(
-        params.cwd,
-        params.task,
-        params.skills,
-        READONLY_TOOLS,
-        EXTENSION_FILE,
-        EXPLORE_PROMPT_FILE,
-        "explore",
-        signal,
-        onUpdate,
-      );
-    },
-    renderCall: (args, theme) => renderSubagentCall("explore ", args, theme),
-    renderResult: (result, options, theme, context) => renderSubagentResult(result as any, options, theme, context),
-  });
+  registerAgentTools(pi, new AgentManager());
 }

package/package.json

@@ -1,14 +1,18 @@
 {
   "name": "@jerryan/pi-subagent-tools",
-  "version": "0.1.0",
-  "description": "Minimal pi extension: delegate, review, and explore via isolated subagent processes",
+  "version": "0.3.0",
+  "description": "Minimal pi extension: delegate, review, and explore via in-process subagent sessions",
   "type": "module",
   "main": "index.ts",
   "files": [
     "index.ts",
-    "spawn.ts",
+    "agents.ts",
+    "render.ts",
+    "sandbox-bash.ts",
+    "ui-bridge.ts",
     "tui.ts",
     "prompts/*.md",
+    "CHANGELOG.md",
     "README.md",
     "LICENSE"
   ],
@@ -31,23 +35,29 @@
     "registry": "https://registry.npmjs.org/"
   },
   "scripts": {
-    "pretest": "node -e \"const{cp}=require('fs');cp('test/mocks/@earendil-works','node_modules/@earendil-works',{recursive:true},()=>{})\"",
-    "test": "node --experimental-strip-types --test test/*.test.ts"
+    "test": "node --experimental-strip-types --import ./test/register-mocks.mjs --test test/*.test.ts",
+    "typecheck": "tsc --noEmit"
   },
   "pi": {
-    "extensions": ["./index.ts"]
+    "extensions": [
+      "./index.ts"
+    ]
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*"
+    "@earendil-works/pi-ai": ">=0.84.0",
+    "@earendil-works/pi-coding-agent": ">=0.84.0",
+    "@earendil-works/pi-tui": ">=0.84.0"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "^0.74.0",
-    "@earendil-works/pi-coding-agent": "^0.74.0",
-    "@earendil-works/pi-tui": "^0.74.0",
+    "@earendil-works/pi-ai": "^0.84.4",
+    "@earendil-works/pi-coding-agent": "^0.84.4",
+    "@earendil-works/pi-tui": "^0.84.4",
     "@sinclair/typebox": "^0.34.0",
     "@types/node": "^20.0.0",
     "typescript": "^5.4.0"
+  },
+  "dependencies": {
+    "just-bash": "^3.4.2",
+    "just-git": "^1.8.0"
   }
 }

package/prompts/delegate.md

@@ -0,0 +1,6 @@
+You are a task worker. Your job is to execute the assigned task directly — do the work, don't discuss it.
+You have full file and bash access. Make changes, run commands, and complete the task.
+You do not need to present plans for approval. If requirements are clear, implement immediately.
+Minor uncertainties: proceed with a reasonable assumption, state it clearly in your result.
+Major uncertainties or obstacles: cannot be resolved — report back, suggest the caller investigate and re-delegate with clarification.
+Be concise. Deliver results, not deliberation.

package/prompts/explore.md

@@ -1,4 +1,4 @@
 You are a codebase explorer. Map the structure, identify key files, and report patterns.
-You are in read-only mode — use the git tool for repository inspection. Do not modify files or run destructive commands.
+You are in read-only mode — project files cannot be modified (writes to them fail by design). Use bash for searching, file inspection, and git history.
 Focus on entry points, architecture, dependencies, and areas of interest.
 End with a clear summary of the codebase structure and notable findings.

package/prompts/review.md

@@ -1,4 +1,4 @@
 You are a code reviewer. Inspect code, find issues, and report findings clearly.
-You are in read-only mode — use the git tool for repository inspection. Do not modify files or run destructive commands.
+You are in read-only mode — project files cannot be modified (writes to them fail by design). Use bash for searching, file inspection, and git history.
 Focus on correctness, edge cases, readability, and adherence to the task requirements.
 End with a clear summary of findings organized by severity.

package/render.ts

@@ -0,0 +1,87 @@
+/**
+ * TUI rendering for subagent tool calls and results.
+ */
+
+import { getMarkdownTheme } from "@earendil-works/pi-coding-agent";
+import { Container, Spacer, Text, Markdown } from "@earendil-works/pi-tui";
+import { formatUsage, spinnerFrame, truncate, TOOL_LINE_PREFIX } from "./tui.ts";
+
+// ---------------------------------------------------------------------------
+// Compact preview component — delegates to Text.render(width) for wrapping
+// ---------------------------------------------------------------------------
+
+export class CompactPreview {
+  private textComp: Text;
+  private maxLines: number;
+
+  constructor(text: string, maxLines: number = 5) {
+    this.maxLines = maxLines;
+    this.textComp = new Text(text, 0, 0);
+  }
+
+  render(width: number): string[] {
+    const lines = this.textComp.render(width);
+    if (lines.length === 0) return [];
+
+    if (lines.length <= this.maxLines) return lines;
+
+    return ["...", ...lines.slice(-this.maxLines)];
+  }
+
+  invalidate() {
+    this.textComp.invalidate();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Call / result renderers shared by all subagent tools
+// ---------------------------------------------------------------------------
+
+export function renderSubagentCall(
+  label: string,
+  args: { task: string; hint?: string },
+  theme: any,
+) {
+  const firstLine = args.task.split("\n")[0];
+  const combined = args.hint ? `${args.hint} | ${firstLine}` : firstLine;
+  const preview = truncate(combined, 80);
+  return new Text(
+    `${theme.fg("toolTitle", theme.bold(label))}${theme.fg("dim", preview)}`,
+    0, 0,
+  );
+}
+
+export function renderSubagentResult(
+  result: { content: Array<{ type: string; text?: string }>; isError?: boolean; details?: any },
+  options: { expanded: boolean },
+  theme: any,
+  _context: { toolCallId: string },
+) {
+  const raw = result.content.filter((c: any) => c.type === "text").map((c: any) => c.text).join("");
+  const output = raw.split("\n").map(l => l.startsWith(TOOL_LINE_PREFIX) ? theme.fg("muted", l) : l).join("\n");
+  const container = new Container();
+
+  if (!options.expanded) {
+    const text = output || theme.fg("dim", "(no output)");
+    const usage = result.details?.usage;
+    const hint = ` · ${theme.fg("dim", "Ctrl+O to expand")}`;
+    const status = usage ? formatUsage(usage, spinnerFrame) + hint : "";
+    container.addChild(new CompactPreview(text));
+    if (status) container.addChild(new Text(theme.fg("dim", status), 0, 0));
+    return container;
+  }
+
+  const isFinal = !!result.details?.final;
+  if (isFinal) {
+    const mdTheme = getMarkdownTheme();
+    container.addChild(new Markdown(raw, 0, 0, mdTheme));
+  } else {
+    container.addChild(new CompactPreview(output, 15));
+  }
+  if (result.details?.usage) {
+    container.addChild(new Spacer(1));
+    container.addChild(new Text(theme.fg("dim", formatUsage(result.details.usage, spinnerFrame)), 0, 0));
+  }
+
+  return container;
+}