@astrofoundry/pi-astro 0.17.1 → 0.18.2

package/extensions/astro-subagents/child.ts

@@ -0,0 +1,284 @@
+import { spawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { Message } from "@earendil-works/pi-ai";
+import type { AgentConfig, ResolvedSkill } from "./agents.ts";
+
+/** Environment the child session receives; `specialist-gate` reads the first one. */
+export const AGENT_ENV = "ASTRO_SUBAGENT_AGENT";
+export const DEPTH_ENV = "ASTRO_SUBAGENT_DEPTH";
+export const REMAINING_ENV = "ASTRO_SUBAGENT_REMAINING";
+
+/** Delegation levels allowed below a top-level session unless an agent tightens it. */
+export const DEFAULT_REMAINING = 2;
+
+export interface UsageStats {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    cost: number;
+    contextTokens: number;
+    turns: number;
+}
+
+export interface RunResult {
+    agent: string;
+    agentSource: AgentConfig["source"] | "unknown";
+    task: string;
+    /** -1 while running. */
+    exitCode: number;
+    messages: Message[];
+    stderr: string;
+    usage: UsageStats;
+    model?: string;
+    stopReason?: string;
+    errorMessage?: string;
+    step?: number;
+}
+
+export function emptyUsage(): UsageStats {
+    return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 };
+}
+
+export interface DispatchDefaults {
+    model?: string;
+    thinkingLevel?: string;
+}
+
+/** Current session's delegation state, read from the environment. */
+export function currentDepth(env: NodeJS.ProcessEnv = process.env): { depth: number; remaining: number } {
+    const depth = Number(env[DEPTH_ENV] ?? 0);
+    const remainingRaw = env[REMAINING_ENV];
+    const remaining = remainingRaw === undefined ? DEFAULT_REMAINING : Number(remainingRaw);
+    return {
+        depth: Number.isInteger(depth) && depth >= 0 ? depth : 0,
+        remaining: Number.isInteger(remaining) && remaining >= 0 ? remaining : 0,
+    };
+}
+
+/** The child may delegate `remaining - 1` more levels, tightened by its own `maxSubagentDepth`. */
+export function childRemaining(parentRemaining: number, agent: AgentConfig): number {
+    const inherited = Math.max(0, parentRemaining - 1);
+    return agent.maxSubagentDepth === undefined ? inherited : Math.min(inherited, agent.maxSubagentDepth);
+}
+
+export function composeSystemPrompt(agent: AgentConfig, skills: ResolvedSkill[]): string {
+    const parts = [agent.systemPrompt];
+    for (const skill of skills) parts.push(`## Skill: ${skill.name}\n\n${skill.body}`);
+    return parts.filter((p) => p.length > 0).join("\n\n");
+}
+
+export interface ChildArgsInput {
+    agent: AgentConfig;
+    task: string;
+    promptFile: string | null;
+    defaults: DispatchDefaults;
+}
+
+/** Arguments for the child `pi` process: print mode, JSON events, no session file. */
+export function buildChildArgs({ agent, task, promptFile, defaults }: ChildArgsInput): string[] {
+    const args = ["--mode", "json", "-p", "--no-session"];
+    const model = agent.model ?? defaults.model;
+    if (model) args.push("--model", model);
+    const thinking = agent.thinking ?? (agent.model ? undefined : defaults.thinkingLevel);
+    if (thinking) args.push("--thinking", thinking);
+    if (agent.tools && agent.tools.length > 0) args.push("--tools", agent.tools.join(","));
+    if (!agent.inheritProjectContext) args.push("--no-context-files");
+    if (!agent.inheritSkills) args.push("--no-skills");
+    if (promptFile) args.push(agent.systemPromptMode === "append" ? "--append-system-prompt" : "--system-prompt", promptFile);
+    args.push("--", `Task: ${task}`);
+    return args;
+}
+
+export function buildChildEnv(agent: AgentConfig, depth: number, remaining: number, base: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
+    return { ...base, [AGENT_ENV]: agent.name, [DEPTH_ENV]: String(depth + 1), [REMAINING_ENV]: String(remaining) };
+}
+
+export interface Invocation {
+    command: string;
+    args: string[];
+}
+
+/** Runs the same pi that runs this extension; falls back to `pi` on PATH. */
+export function piInvocation(args: string[]): Invocation {
+    const script = process.argv[1];
+    if (script && fs.existsSync(script)) return { command: process.execPath, args: [script, ...args] };
+    const execName = path.basename(process.execPath).toLowerCase();
+    if (!/^(node|bun)(\.exe)?$/.test(execName)) return { command: process.execPath, args };
+    return { command: "pi", args };
+}
+
+export function finalOutput(messages: Message[]): string {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const msg = messages[i];
+        if (msg.role !== "assistant") continue;
+        for (const part of msg.content) if (part.type === "text") return part.text;
+    }
+    return "";
+}
+
+export function isFailed(result: RunResult): boolean {
+    return result.exitCode !== 0 || result.stopReason === "error" || result.stopReason === "aborted";
+}
+
+export function resultOutput(result: RunResult): string {
+    if (isFailed(result)) return result.errorMessage || result.stderr.trim() || finalOutput(result.messages) || "(no output)";
+    return finalOutput(result.messages) || "(no output)";
+}
+
+interface JsonEvent {
+    type?: unknown;
+    message?: unknown;
+}
+
+/** Feeds one JSON-mode event line into the result; returns true when the result changed. */
+export function applyEventLine(line: string, result: RunResult): boolean {
+    if (!line.trim()) return false;
+    let event: JsonEvent;
+    try {
+        event = JSON.parse(line) as JsonEvent;
+    } catch {
+        return false;
+    }
+    if ((event.type !== "message_end" && event.type !== "tool_result_end") || typeof event.message !== "object" || event.message === null) {
+        return false;
+    }
+    const msg = event.message as Message;
+    result.messages.push(msg);
+    if (msg.role === "assistant") {
+        result.usage.turns++;
+        const usage = msg.usage;
+        if (usage) {
+            result.usage.input += usage.input || 0;
+            result.usage.output += usage.output || 0;
+            result.usage.cacheRead += usage.cacheRead || 0;
+            result.usage.cacheWrite += usage.cacheWrite || 0;
+            result.usage.cost += usage.cost?.total || 0;
+            result.usage.contextTokens = usage.totalTokens || 0;
+        }
+        if (!result.model && msg.model) result.model = msg.model;
+        if (msg.stopReason) result.stopReason = msg.stopReason;
+        if (msg.errorMessage) result.errorMessage = msg.errorMessage;
+    }
+    return true;
+}
+
+export interface RunOptions {
+    agent: AgentConfig;
+    skills: ResolvedSkill[];
+    task: string;
+    cwd: string;
+    depth: number;
+    remaining: number;
+    defaults: DispatchDefaults;
+    step?: number;
+    signal?: AbortSignal;
+    onUpdate?: (result: RunResult) => void;
+    invocation?: (args: string[]) => Invocation;
+}
+
+export async function runAgent(options: RunOptions): Promise<RunResult> {
+    const { agent, task } = options;
+    const result: RunResult = {
+        agent: agent.name,
+        agentSource: agent.source,
+        task,
+        exitCode: -1,
+        messages: [],
+        stderr: "",
+        usage: emptyUsage(),
+        model: agent.model ?? options.defaults.model,
+        step: options.step,
+    };
+    const prompt = composeSystemPrompt(agent, options.skills);
+    let tmpDir: string | null = null;
+    let promptFile: string | null = null;
+    if (prompt.length > 0) {
+        tmpDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "astro-subagent-"));
+        promptFile = path.join(tmpDir, `${agent.name.replace(/[^\w.-]+/g, "_")}.md`);
+        await fs.promises.writeFile(promptFile, prompt, { encoding: "utf-8", mode: 0o600 });
+    }
+    try {
+        const args = buildChildArgs({ agent, task, promptFile, defaults: options.defaults });
+        const invocation = (options.invocation ?? piInvocation)(args);
+        const env = buildChildEnv(agent, options.depth, options.remaining);
+        let aborted = false;
+        const exitCode = await new Promise<number>((resolve) => {
+            // Own process group so a kill reaches the child's own tool processes, not only pi itself.
+            const proc = spawn(invocation.command, invocation.args, { cwd: options.cwd, env, shell: false, stdio: ["ignore", "pipe", "pipe"], detached: true });
+            let buffer = "";
+            let settled = false;
+            const finish = (code: number) => {
+                if (settled) return;
+                settled = true;
+                if (buffer.trim() && applyEventLine(buffer, result)) options.onUpdate?.(result);
+                resolve(code);
+            };
+            const signalGroup = (sig: NodeJS.Signals) => {
+                try {
+                    if (proc.pid) process.kill(-proc.pid, sig);
+                    else proc.kill(sig);
+                } catch {
+                    proc.kill(sig);
+                }
+            };
+            const kill = () => {
+                aborted = true;
+                signalGroup("SIGTERM");
+                setTimeout(() => {
+                    if (!settled) signalGroup("SIGKILL");
+                }, 5000).unref();
+            };
+            const timer =
+                agent.timeoutMinutes !== undefined && agent.timeoutMinutes > 0
+                    ? setTimeout(() => {
+                          result.errorMessage = `timed out after ${agent.timeoutMinutes} min`;
+                          kill();
+                      }, agent.timeoutMinutes * 60_000)
+                    : null;
+            proc.stdout.on("data", (data: Buffer) => {
+                buffer += data.toString("utf-8");
+                const lines = buffer.split("\n");
+                buffer = lines.pop() ?? "";
+                let changed = false;
+                for (const line of lines) changed = applyEventLine(line, result) || changed;
+                if (changed) options.onUpdate?.(result);
+            });
+            proc.stderr.on("data", (data: Buffer) => {
+                result.stderr += data.toString("utf-8");
+            });
+            proc.on("close", (code) => {
+                if (timer) clearTimeout(timer);
+                finish(code ?? 1);
+            });
+            // On abort, orphaned grandchildren may keep the pipes open; do not wait for them.
+            proc.on("exit", (code) => {
+                if (aborted) {
+                    if (timer) clearTimeout(timer);
+                    finish(code ?? 1);
+                }
+            });
+            proc.on("error", (err) => {
+                if (timer) clearTimeout(timer);
+                result.stderr += err.message;
+                finish(1);
+            });
+            if (options.signal) {
+                if (options.signal.aborted) kill();
+                else options.signal.addEventListener("abort", kill, { once: true });
+            }
+        });
+        result.exitCode = exitCode;
+        if (aborted && !result.errorMessage) {
+            result.stopReason = "aborted";
+            result.errorMessage = "subagent aborted";
+        }
+        if (aborted && result.exitCode === 0) result.exitCode = 1;
+        return result;
+    } finally {
+        if (promptFile) fs.rmSync(promptFile, { force: true });
+        if (tmpDir) fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+}

package/extensions/astro-subagents/index.test.ts

@@ -0,0 +1,90 @@
+import { mkdirSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { AgentDirs } from "./agents.ts";
+import { DEPTH_ENV, REMAINING_ENV } from "./child.ts";
+import astroSubagents, { parseRunCommand, pruneLegacyCopies } from "./index.ts";
+
+type Handler = (event: Record<string, unknown>, ctx: unknown) => Promise<unknown>;
+
+interface CapturedPi {
+    tools: Map<string, { promptGuidelines?: string[] }>;
+    commands: Map<string, { handler: (args: string, ctx: unknown) => Promise<void> | void }>;
+    handlers: Record<string, Handler>;
+    registerTool: (tool: { name: string; promptGuidelines?: string[] }) => void;
+    registerCommand: (name: string, opts: { handler: (args: string, ctx: unknown) => Promise<void> | void }) => void;
+    on: (event: string, handler: Handler) => void;
+    sendMessage: ReturnType<typeof vi.fn>;
+}
+
+function makePi(): CapturedPi {
+    const tools = new Map();
+    const commands = new Map();
+    const handlers: Record<string, Handler> = {};
+    return {
+        tools,
+        commands,
+        handlers,
+        registerTool: (tool) => tools.set(tool.name, tool),
+        registerCommand: (name, opts) => commands.set(name, opts),
+        on: (event, handler) => {
+            handlers[event] = handler;
+        },
+        sendMessage: vi.fn(),
+    };
+}
+
+describe("astro-subagents extension", () => {
+    let root: string;
+    let dirs: AgentDirs;
+
+    beforeEach(() => {
+        root = mkdtempSync(join(tmpdir(), "astro-sub-"));
+        dirs = {
+            bundledAgents: join(root, "pkg", "agents"),
+            bundledSkills: join(root, "pkg", "skills"),
+            userAgents: join(root, "user", "agents"),
+            userSkills: join(root, "user", "skills"),
+        };
+        for (const d of Object.values(dirs)) mkdirSync(d, { recursive: true });
+        writeFileSync(join(dirs.bundledAgents, "arcane.md"), "---\nname: arcane\ndescription: Operates Arcane\n---\nB");
+    });
+
+    afterEach(() => rmSync(root, { recursive: true, force: true }));
+
+    it("registers the subagent tool with the agent list at the top level", () => {
+        const pi = makePi();
+        astroSubagents(pi as unknown as Parameters<typeof astroSubagents>[0], { dirs, env: {} });
+        expect(pi.tools.has("subagent")).toBe(true);
+        expect(pi.tools.get("subagent")?.promptGuidelines?.[1]).toContain("astro.arcane: Operates Arcane");
+        expect([...pi.commands.keys()].sort()).toEqual(["agents", "run"]);
+    });
+
+    it("registers no tool when no delegation level remains", async () => {
+        const pi = makePi();
+        astroSubagents(pi as unknown as Parameters<typeof astroSubagents>[0], { dirs, env: { [DEPTH_ENV]: "2", [REMAINING_ENV]: "0" } });
+        expect(pi.tools.has("subagent")).toBe(false);
+        const notify = vi.fn();
+        await pi.commands.get("run")?.handler("astro.arcane -- x", { ui: { notify }, cwd: root });
+        expect(notify).toHaveBeenCalledWith(expect.stringContaining("depth limit"), "warning");
+    });
+
+    it("removes legacy loader copies on session start", async () => {
+        writeFileSync(join(dirs.userAgents, "astro.arcane.md"), "old copy");
+        writeFileSync(join(dirs.userAgents, "mine.md"), "---\nname: mine\ndescription: keep\n---\n");
+        const pi = makePi();
+        astroSubagents(pi as unknown as Parameters<typeof astroSubagents>[0], { dirs, env: {} });
+        const notify = vi.fn();
+        await pi.handlers.session_start({}, { ui: { notify }, cwd: root });
+        expect(readdirSync(dirs.userAgents)).toEqual(["mine.md"]);
+        expect(notify).toHaveBeenCalledWith(expect.stringContaining("removed 1 legacy"), "info");
+    });
+
+    it("parses /run arguments", () => {
+        expect(parseRunCommand("astro.arcane -- list projects")).toEqual({ agent: "astro.arcane", task: "list projects" });
+        expect(parseRunCommand("scout find auth code")).toEqual({ agent: "scout", task: "find auth code" });
+        expect(parseRunCommand("scout")).toBeNull();
+        expect(pruneLegacyCopies(join(root, "missing"))).toEqual([]);
+    });
+});

package/extensions/astro-subagents/index.ts

@@ -0,0 +1,280 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import { StringEnum } from "@earendil-works/pi-ai";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { type AgentConfig, type AgentDirs, type AgentScope, BUNDLED_NAMESPACE, defaultDirs, discoverAgents, formatAgentList, resolveSkills } from "./agents.ts";
+import { childRemaining, currentDepth, type DispatchDefaults, finalOutput, isFailed, resultOutput, type RunResult, runAgent } from "./child.ts";
+import { renderCall, renderResult, type SubagentDetails } from "./render.ts";
+
+const MAX_PARALLEL_TASKS = 8;
+const MAX_CONCURRENCY = 4;
+const PER_TASK_OUTPUT_CAP = 50 * 1024;
+
+const TaskItem = Type.Object({
+    agent: Type.String({ description: "Agent name, e.g. astro.code-reviewer" }),
+    task: Type.String({ description: "Task for the agent. In a chain, {previous} is replaced by the previous step's output." }),
+    cwd: Type.Optional(Type.String({ description: "Working directory for the agent" })),
+});
+
+const Params = Type.Object({
+    agent: Type.Optional(Type.String({ description: "Agent name for a single run" })),
+    task: Type.Optional(Type.String({ description: "Task for a single run" })),
+    tasks: Type.Optional(Type.Array(TaskItem, { description: "Independent tasks run in parallel" })),
+    chain: Type.Optional(Type.Array(TaskItem, { description: "Sequential steps; {previous} carries the prior output" })),
+    agentScope: Type.Optional(
+        StringEnum(["user", "project", "both"] as const, {
+            description: 'Which extra agent folders to use besides the bundled ones. Default "user". "both" adds repo-controlled .pi/agents.',
+        }),
+    ),
+    cwd: Type.Optional(Type.String({ description: "Working directory for a single run" })),
+});
+
+function truncate(output: string): string {
+    if (Buffer.byteLength(output, "utf8") <= PER_TASK_OUTPUT_CAP) return output;
+    let cut = output.slice(0, PER_TASK_OUTPUT_CAP);
+    while (Buffer.byteLength(cut, "utf8") > PER_TASK_OUTPUT_CAP) cut = cut.slice(0, -1);
+    return `${cut}\n\n[Output truncated; full output in tool details.]`;
+}
+
+async function mapLimited<T, R>(items: T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]> {
+    const results: R[] = new Array<R>(items.length);
+    let next = 0;
+    await Promise.all(
+        Array.from({ length: Math.min(limit, items.length) }, async () => {
+            for (;;) {
+                const i = next++;
+                if (i >= items.length) return;
+                results[i] = await fn(items[i], i);
+            }
+        }),
+    );
+    return results;
+}
+
+/** Bundled agents used to be copied to ~/.pi/agent/agents/astro.*.md by the old loader; remove those copies. */
+export function pruneLegacyCopies(userAgentsDir: string): string[] {
+    const removed: string[] = [];
+    let entries: string[];
+    try {
+        entries = fs.readdirSync(userAgentsDir);
+    } catch {
+        return removed;
+    }
+    for (const name of entries) {
+        if (!name.startsWith(`${BUNDLED_NAMESPACE}.`) || !name.endsWith(".md")) continue;
+        const filePath = path.join(userAgentsDir, name);
+        try {
+            fs.unlinkSync(filePath);
+            removed.push(filePath);
+        } catch {
+            /* leave it */
+        }
+    }
+    return removed;
+}
+
+/** Parses `/run <agent> -- <task>` (the `--` is optional when the task has no leading dash). */
+export function parseRunCommand(input: string): { agent: string; task: string } | null {
+    const trimmed = input.trim();
+    const match = /^(\S+)\s+(?:--\s+)?([\s\S]+)$/.exec(trimmed);
+    if (!match) return null;
+    return { agent: match[1], task: match[2].trim() };
+}
+
+export interface GateOptions {
+    dirs?: AgentDirs;
+    env?: NodeJS.ProcessEnv;
+}
+
+export default function astroSubagents(pi: ExtensionAPI, options: GateOptions = {}): void {
+    const dirs = options.dirs ?? defaultDirs();
+    const { depth, remaining } = currentDepth(options.env ?? process.env);
+    const canDelegate = remaining > 0;
+
+    const listAgents = (cwd: string, scope: AgentScope) => discoverAgents(cwd, scope, dirs);
+
+    async function runOne(
+        ctx: ExtensionContext,
+        agents: AgentConfig[],
+        agentName: string,
+        task: string,
+        cwd: string | undefined,
+        step: number | undefined,
+        signal: AbortSignal | undefined,
+        onUpdate: ((r: RunResult) => void) | undefined,
+    ): Promise<RunResult> {
+        const agent = agents.find((a) => a.name === agentName);
+        if (!agent) {
+            return {
+                agent: agentName,
+                agentSource: "unknown",
+                task,
+                exitCode: 1,
+                messages: [],
+                stderr: `Unknown agent "${agentName}". Available: ${agents.map((a) => a.name).join(", ") || "none"}.`,
+                usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
+                step,
+            };
+        }
+        const { skills, missing } = resolveSkills(agent.skills, dirs);
+        if (missing.length > 0) ctx.ui.notify(`${agent.name}: skill(s) not found: ${missing.join(", ")}`, "warning");
+        const defaults: DispatchDefaults = {
+            model: ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined,
+            thinkingLevel: ctx.thinkingLevel,
+        };
+        return runAgent({
+            agent,
+            skills,
+            task,
+            cwd: cwd ?? ctx.cwd,
+            depth,
+            remaining: childRemaining(remaining, agent),
+            defaults,
+            step,
+            signal,
+            onUpdate,
+        });
+    }
+
+    if (canDelegate) {
+        const initial = listAgents(process.cwd(), "user");
+        pi.registerTool({
+            name: "subagent",
+            label: "Subagent",
+            description:
+                "Delegate a task to a specialized agent running in its own pi process with an isolated context. Modes: single (agent + task), parallel (tasks), chain (sequential, {previous} carries output).",
+            promptGuidelines: [
+                "Use subagent for work that a listed agent owns; give it a complete, self-contained task and report its answer.",
+                `Available agents:\n${formatAgentList(initial.agents)}`,
+            ],
+            parameters: Params,
+            async execute(_id, params, signal, onUpdate, ctx) {
+                const scope: AgentScope = params.agentScope ?? "user";
+                const discovery = listAgents(ctx.cwd, scope);
+                const agents = discovery.agents;
+                const details = (mode: SubagentDetails["mode"], results: RunResult[]): SubagentDetails => ({ mode, results });
+                const modes = Number(Boolean(params.chain?.length)) + Number(Boolean(params.tasks?.length)) + Number(Boolean(params.agent && params.task));
+                if (modes !== 1) {
+                    return {
+                        content: [{ type: "text", text: `Provide exactly one mode: agent+task, tasks, or chain.\nAvailable agents:\n${formatAgentList(agents)}` }],
+                        details: details("single", []),
+                        isError: true,
+                    };
+                }
+                if (scope !== "user" && ctx.hasUI && !ctx.isProjectTrusted()) {
+                    const requested = new Set<string>([...(params.chain ?? []).map((s) => s.agent), ...(params.tasks ?? []).map((t) => t.agent), ...(params.agent ? [params.agent] : [])]);
+                    const projectAgents = [...requested].map((n) => agents.find((a) => a.name === n)).filter((a): a is AgentConfig => a?.source === "project");
+                    if (projectAgents.length > 0) {
+                        const ok = await ctx.ui.confirm("Run project-local agents?", `${projectAgents.map((a) => a.name).join(", ")} from ${discovery.projectAgentsDir ?? "?"}. Repo-controlled prompts; continue only for trusted repositories.`);
+                        if (!ok) return { content: [{ type: "text", text: "Canceled: project-local agents not approved." }], details: details("single", []) };
+                    }
+                }
+
+                if (params.chain && params.chain.length > 0) {
+                    const results: RunResult[] = [];
+                    let previous = "";
+                    for (let i = 0; i < params.chain.length; i++) {
+                        const step = params.chain[i];
+                        const result = await runOne(ctx, agents, step.agent, step.task.replace(/\{previous\}/g, previous), step.cwd, i + 1, signal, (r) =>
+                            onUpdate?.({ content: [{ type: "text", text: finalOutput(r.messages) || "(running...)" }], details: details("chain", [...results, r]) }),
+                        );
+                        results.push(result);
+                        if (isFailed(result)) {
+                            return { content: [{ type: "text", text: `Chain stopped at step ${i + 1} (${step.agent}): ${resultOutput(result)}` }], details: details("chain", results), isError: true };
+                        }
+                        previous = finalOutput(result.messages);
+                    }
+                    return { content: [{ type: "text", text: finalOutput(results[results.length - 1].messages) || "(no output)" }], details: details("chain", results) };
+                }
+
+                if (params.tasks && params.tasks.length > 0) {
+                    if (params.tasks.length > MAX_PARALLEL_TASKS) {
+                        return { content: [{ type: "text", text: `Too many parallel tasks (${params.tasks.length}); the limit is ${MAX_PARALLEL_TASKS}.` }], details: details("parallel", []), isError: true };
+                    }
+                    const all: RunResult[] = params.tasks.map((t) => ({
+                        agent: t.agent,
+                        agentSource: "unknown",
+                        task: t.task,
+                        exitCode: -1,
+                        messages: [],
+                        stderr: "",
+                        usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
+                    }));
+                    const emit = () => {
+                        const running = all.filter((r) => r.exitCode === -1).length;
+                        onUpdate?.({ content: [{ type: "text", text: `Parallel: ${all.length - running}/${all.length} done, ${running} running...` }], details: details("parallel", [...all]) });
+                    };
+                    const results = await mapLimited(params.tasks, MAX_CONCURRENCY, async (t, i) => {
+                        const result = await runOne(ctx, agents, t.agent, t.task, t.cwd, undefined, signal, (r) => {
+                            all[i] = r;
+                            emit();
+                        });
+                        all[i] = result;
+                        emit();
+                        return result;
+                    });
+                    const ok = results.filter((r) => !isFailed(r)).length;
+                    const summaries = results.map((r) => `### [${r.agent}] ${isFailed(r) ? "failed" : "completed"}\n\n${truncate(resultOutput(r))}`);
+                    return { content: [{ type: "text", text: `Parallel: ${ok}/${results.length} succeeded\n\n${summaries.join("\n\n---\n\n")}` }], details: details("parallel", results) };
+                }
+
+                const result = await runOne(ctx, agents, params.agent as string, params.task as string, params.cwd, undefined, signal, (r) =>
+                    onUpdate?.({ content: [{ type: "text", text: finalOutput(r.messages) || "(running...)" }], details: details("single", [r]) }),
+                );
+                if (isFailed(result)) {
+                    return { content: [{ type: "text", text: `Agent ${result.stopReason ?? "failed"}: ${resultOutput(result)}` }], details: details("single", [result]), isError: true };
+                }
+                return { content: [{ type: "text", text: finalOutput(result.messages) || "(no output)" }], details: details("single", [result]) };
+            },
+            renderCall: (args, theme) => renderCall(args, theme),
+            renderResult: (result, { expanded }, theme) => renderResult(result as AgentToolResult<SubagentDetails>, expanded, theme),
+        });
+    }
+
+    pi.registerCommand("run", {
+        description: "Run an agent once: /run <agent> -- <task>",
+        handler: async (args, ctx) => {
+            if (!canDelegate) {
+                ctx.ui.notify("subagents: this session may not delegate further (depth limit)", "warning");
+                return;
+            }
+            const parsed = parseRunCommand(args);
+            if (!parsed) {
+                ctx.ui.notify("usage: /run <agent> -- <task>", "warning");
+                return;
+            }
+            const agents = listAgents(ctx.cwd, "user").agents;
+            ctx.ui.notify(`running ${parsed.agent}...`, "info");
+            ctx.ui.setStatus("subagent", `${parsed.agent} running`);
+            let result: RunResult;
+            try {
+                result = await runOne(ctx, agents, parsed.agent, parsed.task, undefined, undefined, undefined, undefined);
+            } finally {
+                ctx.ui.setStatus("subagent", undefined);
+            }
+            const status = isFailed(result) ? "failed" : "done";
+            ctx.ui.notify(`${parsed.agent} ${status}`, isFailed(result) ? "warning" : "info");
+            pi.sendMessage(
+                { customType: "astro-subagents", content: `Result from /run ${parsed.agent} (${status}). Task: ${parsed.task}\n\n${resultOutput(result)}`, display: true },
+                { deliverAs: "followUp", triggerTurn: true },
+            );
+        },
+    });
+
+    pi.registerCommand("agents", {
+        description: "List available subagents",
+        handler: async (_args, ctx) => {
+            const discovery = listAgents(ctx.cwd, "both");
+            const lines = [formatAgentList(discovery.agents), ...discovery.warnings.map((w) => `warning: ${w}`), `delegation: depth ${depth}, ${remaining} level(s) left`];
+            ctx.ui.notify(lines.join("\n"), "info");
+        },
+    });
+
+    pi.on("session_start", async (_event, ctx: ExtensionContext) => {
+        const removed = pruneLegacyCopies(dirs.userAgents);
+        if (removed.length > 0) ctx.ui.notify(`astro-subagents: removed ${removed.length} legacy agent cop${removed.length === 1 ? "y" : "ies"} from ${dirs.userAgents}`, "info");
+        for (const warning of listAgents(ctx.cwd, "user").warnings) ctx.ui.notify(`astro-subagents: ${warning}`, "warning");
+    });
+}