pi-fast-subagent 0.1.0

package/README.md

@@ -0,0 +1,141 @@
+# pi-fast-subagent
+
+In-process subagent delegation for [pi](https://github.com/badlogic/pi-mono).
+
+Runs subagents with `createAgentSession()` in same process instead of spawning `pi` subprocesses. This removes subprocess cold-start and reuses pi auth/model registry.
+
+## Features
+
+- Single mode: `{ agent, task }`
+- Parallel mode: `{ tasks: [...] }`
+- Chain mode: `{ chain: [...] }`
+- Per-call or per-step model override
+- User + project agent discovery
+- Project agents override user agents
+- Max nesting depth guard
+
+## Install
+
+```bash
+pi install /absolute/path/to/pi-fast-subagent
+```
+
+Or from npm after publish:
+
+```bash
+pi install npm:pi-fast-subagent
+```
+
+## Package contents
+
+This package exposes one pi extension:
+
+- `./index.ts` — registers `subagent` tool
+
+## Included agents
+
+This package bundles default agents:
+
+- `scout` — code exploration specialist
+- `general` — general-purpose helper
+
+Discovery priority:
+
+1. bundled package agents
+2. `~/.pi/agent/agents/`
+3. nearest `.pi/agents/`
+4. nearest legacy `.agents/`
+
+User and project agents override bundled agents with same name.
+
+Example override agent file:
+
+```md
+---
+name: scout
+description: Explore codebases and summarize findings
+model: anthropic/claude-haiku-4-5
+---
+
+You are code exploration specialist. Read relevant files, trace data flow, summarize findings clearly.
+```
+
+## Usage
+
+### List agents
+
+```js
+subagent({ action: "list" })
+```
+
+### Single
+
+```js
+subagent({
+  agent: "scout",
+  task: "Explore src and summarize architecture"
+})
+```
+
+### General-purpose built-in agent
+
+```js
+subagent({
+  agent: "general",
+  task: "Summarize open TODOs and propose next step"
+})
+```
+
+### Override model
+
+```js
+subagent({
+  agent: "scout",
+  task: "Explore src and summarize architecture",
+  model: "anthropic/claude-haiku-4-5"
+})
+```
+
+### Parallel
+
+```js
+subagent({
+  tasks: [
+    { agent: "scout", task: "Map auth flow" },
+    { agent: "scout", task: "Map navigation" }
+  ],
+  concurrency: 2
+})
+```
+
+### Chain
+
+```js
+subagent({
+  chain: [
+    { agent: "scout", task: "Explore app structure" },
+    { agent: "scout", task: "Based on this: {previous}\n\nExtract only auth flow." }
+  ]
+})
+```
+
+## Notes
+
+- Async/background isolation not supported in-process
+- Git worktree isolation not supported
+- Nested subagent depth limited to 2 by default
+
+## Publish
+
+```bash
+cd ~/.pi/agent/extensions/fast-subagent
+npm publish
+```
+
+If package name is taken, rename `name` in `package.json` first, usually with your npm scope:
+
+```json
+{
+  "name": "@your-scope/pi-fast-subagent"
+}
+```

package/agents/general.md

@@ -0,0 +1,27 @@
+---
+name: general
+description: General-purpose helper for coding, analysis, writing, debugging, and task execution
+model: anthropic/claude-haiku-4-5
+---
+
+You are general-purpose subagent.
+
+Use this agent for focused tasks that do not need specialized behavior.
+
+Priorities:
+- follow task exactly
+- stay concise
+- prefer direct answers over long essays
+- use available tools when needed
+- report concrete results, not narration
+
+When task involves code:
+- inspect relevant files
+- explain root cause before fix when debugging
+- preserve existing style
+- mention changed files if edits are made
+
+When task involves analysis:
+- summarize key findings first
+- list assumptions and unknowns briefly
+- keep recommendations practical

package/agents/scout.md

@@ -0,0 +1,28 @@
+---
+name: scout
+description: Explores codebases, maps structure, traces data flow, answers how things work across many files
+model: anthropic/claude-haiku-4-5
+---
+
+You are code exploration specialist.
+
+Goals:
+- understand unfamiliar codebases fast
+- map structure, modules, ownership, and boundaries
+- trace data flow, auth flow, navigation flow, state flow, and side effects
+- summarize findings with concrete file paths and function/component names
+
+How to work:
+1. Start broad. Find top-level structure first.
+2. Read only files needed to answer task well.
+3. Prefer facts from code over guesses.
+4. When tracing flow, name entry point, intermediate layers, and destination.
+5. Call out uncertainty clearly if code is incomplete.
+6. Keep output concise but information-dense.
+
+Output style:
+- use sections
+- include file paths
+- include short bullets
+- mention notable patterns, risks, and coupling
+- do not propose code changes unless asked

package/agents.ts

@@ -0,0 +1,100 @@
+/**
+ * Agent discovery — reads .md files from user + project agent directories.
+ * Compatible with pi-subagents frontmatter format.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { getAgentDir, parseFrontmatter } from "@mariozechner/pi-coding-agent";
+
+export interface AgentConfig {
+  name: string;
+  description: string;
+  model?: string;
+  tools?: string[];
+  systemPrompt: string;
+  source: "user" | "project";
+  filePath: string;
+}
+
+function loadAgentsFromDir(dir: string, source: "user" | "project"): AgentConfig[] {
+  if (!fs.existsSync(dir)) return [];
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  const agents: AgentConfig[] = [];
+  for (const entry of entries) {
+    if (!entry.name.endsWith(".md")) continue;
+    if (!entry.isFile() && !entry.isSymbolicLink()) continue;
+    const filePath = path.join(dir, entry.name);
+    try {
+      const content = fs.readFileSync(filePath, "utf-8");
+      const { frontmatter, body } = parseFrontmatter<Record<string, string>>(content);
+      if (!frontmatter?.name || !frontmatter?.description) continue;
+      const rawTools = frontmatter.tools;
+      const tools = rawTools?.split(",").map((t: string) => t.trim()).filter(Boolean);
+      agents.push({
+        name: frontmatter.name,
+        description: frontmatter.description,
+        model: frontmatter.model,
+        tools: tools?.length ? tools : undefined,
+        systemPrompt: body.trim(),
+        source,
+        filePath,
+      });
+    } catch {
+      // skip malformed files
+    }
+  }
+  return agents;
+}
+
+function findNearestProjectAgentsDir(cwd: string): string | null {
+  let dir = cwd;
+  while (true) {
+    const candidate = path.join(dir, ".pi", "agents");
+    try {
+      if (fs.statSync(candidate).isDirectory()) return candidate;
+    } catch {}
+    // Also support legacy .agents/ dir
+    const legacy = path.join(dir, ".agents");
+    try {
+      if (fs.statSync(legacy).isDirectory()) return legacy;
+    } catch {}
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+export function discoverAgents(cwd: string): AgentConfig[] {
+  const agentMap = new Map<string, AgentConfig>();
+
+  // Bundled package agents (lowest priority)
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const bundledDir = path.join(here, "agents");
+  for (const agent of loadAgentsFromDir(bundledDir, "user")) {
+    agentMap.set(agent.name, { ...agent, source: "user" });
+  }
+
+  // User agents override bundled agents
+  const userDir = path.join(getAgentDir(), "agents");
+  for (const agent of loadAgentsFromDir(userDir, "user")) {
+    agentMap.set(agent.name, agent);
+  }
+
+  // Project agents override user agents
+  const projectDir = findNearestProjectAgentsDir(cwd);
+  if (projectDir) {
+    for (const agent of loadAgentsFromDir(projectDir, "project")) {
+      agentMap.set(agent.name, agent);
+    }
+  }
+
+  return Array.from(agentMap.values());
+}

package/index.ts

@@ -0,0 +1,602 @@
+/**
+ * fast-subagent — In-process subagent delegation.
+ *
+ * Uses createAgentSession() to run subagents in the same process as pi —
+ * no subprocess spawn, no cold-start overhead.
+ *
+ * Drop-in replacement for pi-subagents subprocess mode.
+ * Supports: single, parallel, chain.
+ * Agent .md files are compatible with pi-subagents frontmatter format.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { Text } from "@mariozechner/pi-tui";
+import {
+  AuthStorage,
+  createAgentSession,
+  DefaultResourceLoader,
+  getAgentDir,
+  ModelRegistry,
+  SessionManager,
+} from "@mariozechner/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import { type AgentConfig, discoverAgents } from "./agents.js";
+
+// ─── Shared auth (created once, reused across calls) ─────────────────────────
+
+let _authStorage: ReturnType<typeof AuthStorage.create> | null = null;
+let _modelRegistry: ReturnType<typeof ModelRegistry.create> | null = null;
+
+function getAuth() {
+  if (!_authStorage) _authStorage = AuthStorage.create();
+  if (!_modelRegistry) _modelRegistry = ModelRegistry.create(_authStorage);
+  return { authStorage: _authStorage, modelRegistry: _modelRegistry };
+}
+
+// ─── In-process runner ───────────────────────────────────────────────────────
+
+const MAX_DEPTH = 2;
+const DEPTH_ENV = "PI_FAST_SUBAGENT_DEPTH";
+
+interface RunResult {
+  output: string;
+  exitCode: number;
+  error?: string;
+  model?: string;
+  usage: { input: number; output: number; cost: number; turns: number };
+}
+
+type OnUpdate = (partial: { content: [{ type: "text"; text: string }]; details: unknown }) => void;
+
+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`;
+}
+
+async function runAgent(
+  agent: AgentConfig,
+  task: string,
+  cwd: string,
+  modelOverride: string | undefined,
+  signal: AbortSignal | undefined,
+  onUpdate: OnUpdate | undefined,
+): Promise<RunResult> {
+  const depth = parseInt(process.env[DEPTH_ENV] ?? "0", 10);
+  if (depth >= MAX_DEPTH) {
+    return {
+      output: "",
+      exitCode: 1,
+      error: `Max subagent depth (${MAX_DEPTH}) exceeded. Increase PI_FAST_SUBAGENT_DEPTH env to allow deeper nesting.`,
+      usage: { input: 0, output: 0, cost: 0, turns: 0 },
+    };
+  }
+
+  const { authStorage, modelRegistry } = getAuth();
+  const agentDir = getAgentDir();
+
+  // Build resource loader — no extensions/context files to keep subagent lean
+  const loaderOptions: ConstructorParameters<typeof DefaultResourceLoader>[0] = {
+    cwd,
+    agentDir,
+    noExtensions: true,
+    noContextFiles: true,
+    noSkills: true,
+  };
+  if (agent.systemPrompt) {
+    // Replace pi's base system prompt with the agent's own prompt
+    loaderOptions.systemPromptOverride = () => agent.systemPrompt;
+  }
+
+  const loader = new DefaultResourceLoader(loaderOptions);
+  await loader.reload();
+
+  const { session } = await createAgentSession({
+    cwd,
+    agentDir,
+    sessionManager: SessionManager.inMemory(cwd),
+    authStorage,
+    modelRegistry,
+    resourceLoader: loader,
+  });
+
+  // Resolve and apply model
+  const modelStr = modelOverride ?? agent.model;
+  if (modelStr) {
+    const [provider, ...rest] = modelStr.split("/");
+    const modelId = rest.join("/");
+    if (provider && modelId) {
+      const model = modelRegistry.find(provider, modelId);
+      if (model) await session.setModel(model);
+    }
+  }
+
+  // Restrict tools if agent specifies them
+  if (agent.tools && agent.tools.length > 0) {
+    session.setActiveToolsByName(agent.tools);
+  }
+
+  // Track output and usage
+  const usage = { input: 0, output: 0, cost: 0, turns: 0 };
+  let lastOutput = "";
+  let currentDelta = "";
+  let detectedModel: string | undefined;
+  const startedAt = Date.now();
+  const configuredModel = modelOverride ?? agent.model;
+
+  onUpdate?.({
+    content: [{ type: "text", text: "Starting subagent..." }],
+    details: {
+      agent: agent.name,
+      usage,
+      running: true,
+      elapsedMs: 0,
+      model: configuredModel,
+    },
+  });
+
+  const heartbeat = setInterval(() => {
+    onUpdate?.({
+      content: [{ type: "text", text: currentDelta || lastOutput || "Running..." }],
+      details: {
+        agent: agent.name,
+        usage,
+        running: true,
+        elapsedMs: Date.now() - startedAt,
+        model: detectedModel ?? configuredModel,
+      },
+    });
+  }, 1000);
+
+  const unsubscribe = session.subscribe((event: any) => {
+    // Stream text deltas live to the UI
+    if (event.type === "message_update") {
+      const e = event.assistantMessageEvent;
+      if (e?.type === "text_delta" && e.delta) {
+        currentDelta += e.delta;
+        onUpdate?.({
+          content: [{ type: "text", text: currentDelta }],
+          details: {
+            agent: agent.name,
+            usage,
+            running: true,
+            elapsedMs: Date.now() - startedAt,
+            model: detectedModel ?? configuredModel,
+          },
+        });
+      }
+      return;
+    }
+
+    if (event.type !== "message_end" || !event.message) return;
+    const msg = event.message;
+    if (msg.role !== "assistant") return;
+
+    usage.turns++;
+    const u = msg.usage;
+    if (u) {
+      usage.input += u.input ?? 0;
+      usage.output += u.output ?? 0;
+      usage.cost += u.cost?.total ?? 0;
+    }
+    if (msg.model) detectedModel = msg.model;
+
+    // Extract last text content
+    for (const part of msg.content ?? []) {
+      if (part.type === "text") {
+        lastOutput = part.text;
+        break;
+      }
+    }
+    // Reset delta accumulator for next turn
+    currentDelta = "";
+
+    onUpdate?.({
+      content: [{ type: "text", text: lastOutput || "(running...)" }],
+      details: {
+        agent: agent.name,
+        usage,
+        running: true,
+        elapsedMs: Date.now() - startedAt,
+        model: detectedModel ?? configuredModel,
+      },
+    });
+  });
+
+  // Propagate depth to any nested fast-subagent calls
+  const prevDepth = process.env[DEPTH_ENV];
+  process.env[DEPTH_ENV] = String(depth + 1);
+
+  let exitCode = 0;
+  let error: string | undefined;
+
+  try {
+    if (signal?.aborted) throw new Error("Aborted");
+
+    const onAbort = () => void session.abort();
+    signal?.addEventListener("abort", onAbort, { once: true });
+    try {
+      await session.prompt(task);
+    } finally {
+      signal?.removeEventListener("abort", onAbort);
+    }
+  } catch (e) {
+    exitCode = 1;
+    error = signal?.aborted ? "Aborted" : e instanceof Error ? e.message : String(e);
+  } finally {
+    clearInterval(heartbeat);
+    unsubscribe();
+    session.dispose();
+    if (prevDepth === undefined) delete process.env[DEPTH_ENV];
+    else process.env[DEPTH_ENV] = prevDepth;
+  }
+
+  return { output: lastOutput, exitCode, error, model: detectedModel, usage };
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+async function mapConcurrent<TIn, TOut>(
+  items: TIn[],
+  concurrency: number,
+  fn: (item: TIn, i: number) => Promise<TOut>,
+): Promise<TOut[]> {
+  if (!items.length) return [];
+  const limit = Math.max(1, Math.min(concurrency, items.length));
+  const results: TOut[] = new Array(items.length);
+  let next = 0;
+  await Promise.all(
+    Array.from({ length: limit }, async () => {
+      while (true) {
+        const i = next++;
+        if (i >= items.length) return;
+        results[i] = await fn(items[i], i);
+      }
+    }),
+  );
+  return results;
+}
+
+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`;
+}
+
+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(" ");
+}
+
+function getFinalText(r: RunResult): string {
+  if (r.exitCode !== 0) return `Error: ${r.error ?? r.output ?? "(no output)"}`;
+  return r.output || "(no output)";
+}
+
+// ─── Tool schemas ─────────────────────────────────────────────────────────────
+
+const TaskItem = Type.Object({
+  agent: Type.String({ description: "Agent name" }),
+  task: Type.String({ description: "Task to delegate" }),
+  model: Type.Optional(Type.String({ description: "Model override (provider/model)" })),
+  cwd: Type.Optional(Type.String({ description: "Working directory" })),
+  count: Type.Optional(Type.Number({ description: "Repeat this task N times" })),
+});
+
+const ChainItem = Type.Object({
+  agent: Type.String({ description: "Agent name" }),
+  task: Type.Optional(
+    Type.String({
+      description:
+        "Task template. Supports {previous} (output from prior step) and {task} (first step task). " +
+        "Defaults to {previous} for steps 2+.",
+    }),
+  ),
+  model: Type.Optional(Type.String({ description: "Model override (provider/model)" })),
+  cwd: Type.Optional(Type.String({ description: "Working directory" })),
+});
+
+const SubagentParams = Type.Object({
+  // Single mode
+  agent: Type.Optional(Type.String({ description: "Agent name (single mode)" })),
+  task: Type.Optional(Type.String({ description: "Task (single mode)" })),
+  model: Type.Optional(Type.String({ description: "Model override (single mode)" })),
+  cwd: Type.Optional(Type.String({ description: "Working directory" })),
+
+  // Parallel mode
+  tasks: Type.Optional(
+    Type.Array(TaskItem, {
+      description: "Array of {agent, task} for parallel execution. Use count to repeat one task.",
+    }),
+  ),
+  concurrency: Type.Optional(
+    Type.Number({ description: "Max parallel concurrency (default: 4)", default: 4 }),
+  ),
+
+  // Chain mode
+  chain: Type.Optional(
+    Type.Array(ChainItem, {
+      description: "Sequential chain. Use {previous} in task to receive prior step output.",
+    }),
+  ),
+
+  // Management
+  action: Type.Optional(
+    Type.Union(
+      [
+        Type.Literal("list"),
+        Type.Literal("get"),
+      ],
+      { description: "'list' to discover agents, 'get' to inspect one agent" },
+    ),
+  ),
+  agentScope: Type.Optional(
+    Type.Union(
+      [Type.Literal("user"), Type.Literal("project"), Type.Literal("both")],
+      { description: "Agent scope filter", default: "both" },
+    ),
+  ),
+});
+
+// ─── Extension entry point ────────────────────────────────────────────────────
+
+export default function (pi: ExtensionAPI) {
+  pi.registerTool({
+    name: "subagent",
+    label: "Subagent",
+    description: [
+      "Delegate tasks to specialized subagents. Runs IN-PROCESS — no subprocess cold-start overhead.",
+      "Modes: single ({ agent, task }), parallel ({ tasks: [...] }), chain ({ chain: [...] }).",
+      "Chain supports {task} (first step task) and {previous} (prior step output) template vars.",
+      "Agents defined as .md files in ~/.pi/agent/agents/ (user) or .pi/agents/ (project).",
+      "Use { action: 'list' } to discover available agents.",
+    ].join(" "),
+    parameters: SubagentParams,
+
+    renderResult(result, { isPartial }, theme) {
+      const text = result.content?.[0]?.type === "text" ? result.content[0].text : "";
+      const details = (result.details ?? {}) as {
+        usage?: RunResult["usage"];
+        running?: boolean;
+        elapsedMs?: number;
+        model?: string;
+      };
+
+      let status = "";
+      if (details.running) {
+        const statusParts: string[] = ["running"];
+        if (details.usage?.turns) statusParts.push(`${details.usage.turns} turn${details.usage.turns > 1 ? "s" : ""}`);
+        if (details.elapsedMs !== undefined) statusParts.push(formatDuration(details.elapsedMs));
+        if (details.model) statusParts.push(details.model);
+        status = `\n${statusParts.join(" · ")}`;
+      } else if (details.usage) {
+        const usageStr = formatUsage(details.usage, details.model);
+        if (usageStr) status = `\n${usageStr}`;
+      }
+
+      if (isPartial) {
+        return new Text(theme.fg("dim", (text || "Running...") + status), 0, 0);
+      }
+      return new Text(text + status, 0, 0);
+    },
+
+    async execute(_id, params, signal, onUpdate, ctx) {
+      const cwd = params.cwd ?? ctx.cwd;
+      const agents = discoverAgents(cwd);
+
+      const findAgent = (name: string): { agent?: AgentConfig; error?: string } => {
+        const found = agents.find((a) => a.name === name);
+        if (!found) {
+          const list = agents.map((a) => `"${a.name}"`).join(", ") || "none";
+          return { error: `Unknown agent: "${name}". Available: ${list}` };
+        }
+        return { agent: found };
+      };
+
+      // ── Management: list ──────────────────────────────────────────────────────
+      if (params.action === "list" || (!params.agent && !params.tasks && !params.chain)) {
+        if (agents.length === 0) {
+          return {
+            content: [{
+              type: "text",
+              text: "No agents found. Add .md files to ~/.pi/agent/agents/ or .pi/agents/.",
+            }],
+          };
+        }
+        const lines = agents.map(
+          (a) => `${a.name} [${a.source}]${a.model ? ` · ${a.model}` : ""}: ${a.description}`,
+        );
+        return { content: [{ type: "text", text: `Agents (${agents.length}):\n${lines.join("\n")}` }] };
+      }
+
+      // ── Management: get ───────────────────────────────────────────────────────
+      if (params.action === "get" && params.agent) {
+        const { agent, error } = findAgent(params.agent);
+        if (error || !agent) return { content: [{ type: "text", text: error ?? "Not found" }] };
+        const info = [
+          `## ${agent.name} [${agent.source}]`,
+          `**Description:** ${agent.description}`,
+          agent.model ? `**Model:** ${agent.model}` : null,
+          agent.tools ? `**Tools:** ${agent.tools.join(", ")}` : null,
+          agent.systemPrompt ? `\n**System prompt:**\n${agent.systemPrompt}` : null,
+        ].filter(Boolean).join("\n");
+        return { content: [{ type: "text", text: info }] };
+      }
+
+      // ── Single mode ───────────────────────────────────────────────────────────
+      if (params.agent && params.task) {
+        const { agent, error } = findAgent(params.agent);
+        if (error || !agent) return { content: [{ type: "text", text: error ?? "Not found" }] };
+
+        const result = await runAgent(
+          agent,
+          params.task,
+          cwd,
+          params.model,
+          signal,
+          onUpdate,
+        );
+
+        return {
+          content: [{ type: "text", text: getFinalText(result) }],
+          details: {
+            usage: result.usage,
+            running: false,
+            elapsedMs: undefined,
+            model: result.model,
+          },
+          isError: result.exitCode !== 0,
+        };
+      }
+
+      // ── Parallel mode ─────────────────────────────────────────────────────────
+      if (params.tasks && params.tasks.length > 0) {
+        // Expand count shorthand
+        const expanded: Array<{ agent: string; task: string; model?: string; cwd?: string }> = [];
+        for (const t of params.tasks) {
+          const n = t.count ?? 1;
+          for (let i = 0; i < n; i++) expanded.push({ agent: t.agent, task: t.task, model: t.model, cwd: t.cwd });
+        }
+
+        const concurrency = params.concurrency ?? 4;
+        let doneCount = 0;
+
+        const allResults = await mapConcurrent(
+          expanded,
+          concurrency,
+          async (t, _i) => {
+            const { agent, error } = findAgent(t.agent);
+            if (error || !agent) {
+              return { agentName: t.agent, output: "", exitCode: 1, error, model: undefined, usage: { input: 0, output: 0, cost: 0, turns: 0 } };
+            }
+            const result = await runAgent(agent, t.task, t.cwd ?? cwd, t.model, signal, undefined);
+            doneCount++;
+            onUpdate?.({
+              content: [{ type: "text", text: `Parallel: ${doneCount}/${expanded.length} done...` }],
+              details: {},
+            });
+            return { ...result, agentName: t.agent };
+          },
+        );
+
+        const successCount = allResults.filter((r) => r.exitCode === 0).length;
+        const summaries = allResults.map((r) => {
+          const out = getFinalText(r);
+          const preview = out.length > 300 ? `${out.slice(0, 300)}...` : out;
+          return `**[${r.agentName}]** ${r.exitCode === 0 ? "✓" : "✗"}\n${preview}`;
+        });
+        const totalUsage = allResults.reduce(
+          (acc, r) => ({
+            input: acc.input + r.usage.input,
+            output: acc.output + r.usage.output,
+            cost: acc.cost + r.usage.cost,
+            turns: acc.turns + r.usage.turns,
+          }),
+          { input: 0, output: 0, cost: 0, turns: 0 },
+        );
+
+        return {
+          content: [{
+            type: "text",
+            text: [
+              `Parallel: ${successCount}/${allResults.length} succeeded`,
+              "",
+              summaries.join("\n\n"),
+              "",
+              formatUsage(totalUsage),
+            ].join("\n"),
+          }],
+        };
+      }
+
+      // ── Chain mode ────────────────────────────────────────────────────────────
+      if (params.chain && params.chain.length > 0) {
+        const firstTask = params.chain[0]?.task ?? "";
+        let previousOutput = "";
+
+        const stepResults: Array<RunResult & { agentName: string; step: number }> = [];
+
+        for (let i = 0; i < params.chain.length; i++) {
+          const step = params.chain[i];
+          const { agent, error } = findAgent(step.agent);
+          if (error || !agent) {
+            return {
+              content: [{ type: "text", text: `Chain stopped at step ${i + 1}: ${error ?? "Not found"}` }],
+              isError: true,
+            };
+          }
+
+          // Resolve task template
+          let task = step.task ?? (i === 0 ? firstTask : "{previous}");
+          task = task
+            .replace(/\{previous\}/g, previousOutput)
+            .replace(/\{task\}/g, firstTask);
+
+          if (onUpdate) {
+            onUpdate({
+              content: [{
+                type: "text",
+                text: `Chain step ${i + 1}/${params.chain.length}: ${step.agent}...`,
+              }],
+              details: {},
+            });
+          }
+
+          const result = await runAgent(
+            agent,
+            task,
+            step.cwd ?? cwd,
+            step.model,
+            signal,
+            onUpdate,
+          );
+
+          stepResults.push({ ...result, agentName: step.agent, step: i + 1 });
+
+          if (result.exitCode !== 0) {
+            return {
+              content: [{
+                type: "text",
+                text: `Chain failed at step ${i + 1} (${step.agent}): ${result.error ?? "(no output)"}`,
+              }],
+              isError: true,
+            };
+          }
+
+          previousOutput = result.output;
+        }
+
+        const last = stepResults[stepResults.length - 1];
+        const totalUsage = stepResults.reduce(
+          (acc, r) => ({
+            input: acc.input + r.usage.input,
+            output: acc.output + r.usage.output,
+            cost: acc.cost + r.usage.cost,
+            turns: acc.turns + r.usage.turns,
+          }),
+          { input: 0, output: 0, cost: 0, turns: 0 },
+        );
+
+        return {
+          content: [{
+            type: "text",
+            text: [
+              last.output,
+              "",
+              `Chain: ${stepResults.length} steps · ${formatUsage(totalUsage)}`,
+            ].join("\n"),
+          }],
+        };
+      }
+
+      // Shouldn't reach here
+      return { content: [{ type: "text", text: "Provide agent+task, tasks array, or chain array." }] };
+    },
+  });
+}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "pi-fast-subagent",
+  "version": "0.1.0",
+  "description": "In-process subagent delegation for pi with single, parallel, and chain modes",
+  "type": "module",
+  "keywords": ["pi-package", "pi", "subagent", "agents", "extension"],
+  "files": [
+    "index.ts",
+    "agents.ts",
+    "agents/*.md",
+    "README.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "@mariozechner/pi-tui": "*",
+    "@sinclair/typebox": "*"
+  }
+}