@bastani/atomic 0.8.31-alpha.5 → 0.9.0-alpha.1

package/examples/extensions/subagent/render.ts

@@ -0,0 +1,383 @@
+import { getMarkdownTheme } from "@bastani/atomic";
+import { Container, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
+import { formatToolCall, formatUsageStats, getDisplayItems, getFinalOutput, type DisplayItem } from "./display.js";
+import type { SingleResult, SubagentDetails } from "./types.js";
+
+const COLLAPSED_ITEM_COUNT = 10;
+
+type TextContent = { type: "text"; text: string };
+type ToolResult = { content: TextContent[]; details?: SubagentDetails };
+type RenderState = { expanded: boolean };
+type RenderTheme = {
+  fg(color: string, text: string): string;
+  bold(text: string): string;
+};
+
+export function renderSubagentResult(
+  result: ToolResult,
+  { expanded }: RenderState,
+  theme: RenderTheme,
+) {
+const details = result.details as SubagentDetails | undefined;
+if (!details || details.results.length === 0) {
+  const text = result.content[0];
+  return new Text(
+    text?.type === "text" ? text.text : "(no output)",
+    0,
+    0,
+  );
+}
+
+const mdTheme = getMarkdownTheme();
+
+const renderDisplayItems = (items: DisplayItem[], limit?: number) => {
+  const toShow = limit ? items.slice(-limit) : items;
+  const skipped =
+    limit && items.length > limit ? items.length - limit : 0;
+  let text = "";
+  if (skipped > 0)
+    text += theme.fg("muted", `... ${skipped} earlier items\n`);
+  for (const item of toShow) {
+    if (item.type === "text") {
+      const preview = expanded
+        ? item.text
+        : item.text.split("\n").slice(0, 3).join("\n");
+      text += `${theme.fg("toolOutput", preview)}\n`;
+    } else {
+      text += `${theme.fg("muted", "→ ") + formatToolCall(item.name, item.args, theme.fg.bind(theme))}\n`;
+    }
+  }
+  return text.trimEnd();
+};
+
+if (details.mode === "single" && details.results.length === 1) {
+  const r = details.results[0];
+  const isError =
+    r.exitCode !== 0 ||
+    r.stopReason === "error" ||
+    r.stopReason === "aborted";
+  const icon = isError
+    ? theme.fg("error", "✗")
+    : theme.fg("success", "✓");
+  const displayItems = getDisplayItems(r.messages);
+  const finalOutput = getFinalOutput(r.messages);
+
+  if (expanded) {
+    const container = new Container();
+    let header = `${icon} ${theme.fg("toolTitle", theme.bold(r.agent))}${theme.fg("muted", ` (${r.agentSource})`)}`;
+    if (isError && r.stopReason)
+      header += ` ${theme.fg("error", `[${r.stopReason}]`)}`;
+    container.addChild(new Text(header, 0, 0));
+    if (isError && r.errorMessage)
+      container.addChild(
+        new Text(theme.fg("error", `Error: ${r.errorMessage}`), 0, 0),
+      );
+    container.addChild(new Spacer(1));
+    container.addChild(new Text(theme.fg("muted", "─── Task ───"), 0, 0));
+    container.addChild(new Text(theme.fg("dim", r.task), 0, 0));
+    container.addChild(new Spacer(1));
+    container.addChild(
+      new Text(theme.fg("muted", "─── Output ───"), 0, 0),
+    );
+    if (displayItems.length === 0 && !finalOutput) {
+      container.addChild(
+        new Text(theme.fg("muted", "(no output)"), 0, 0),
+      );
+    } else {
+      for (const item of displayItems) {
+        if (item.type === "toolCall")
+          container.addChild(
+            new Text(
+              theme.fg("muted", "→ ") +
+                formatToolCall(
+                  item.name,
+                  item.args,
+                  theme.fg.bind(theme),
+                ),
+              0,
+              0,
+            ),
+          );
+      }
+      if (finalOutput) {
+        container.addChild(new Spacer(1));
+        container.addChild(
+          new Markdown(finalOutput.trim(), 0, 0, mdTheme),
+        );
+      }
+    }
+    const usageStr = formatUsageStats(r.usage, r.model);
+    if (usageStr) {
+      container.addChild(new Spacer(1));
+      container.addChild(new Text(theme.fg("dim", usageStr), 0, 0));
+    }
+    return container;
+  }
+
+  let text = `${icon} ${theme.fg("toolTitle", theme.bold(r.agent))}${theme.fg("muted", ` (${r.agentSource})`)}`;
+  if (isError && r.stopReason)
+    text += ` ${theme.fg("error", `[${r.stopReason}]`)}`;
+  if (isError && r.errorMessage)
+    text += `\n${theme.fg("error", `Error: ${r.errorMessage}`)}`;
+  else if (displayItems.length === 0)
+    text += `\n${theme.fg("muted", "(no output)")}`;
+  else {
+    text += `\n${renderDisplayItems(displayItems, COLLAPSED_ITEM_COUNT)}`;
+    if (displayItems.length > COLLAPSED_ITEM_COUNT)
+      text += `\n${theme.fg("muted", "(ctrl+o to expand)")}`;
+  }
+  const usageStr = formatUsageStats(r.usage, r.model);
+  if (usageStr) text += `\n${theme.fg("dim", usageStr)}`;
+  return new Text(text, 0, 0);
+}
+
+const aggregateUsage = (results: SingleResult[]) => {
+  const total = {
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    cost: 0,
+    turns: 0,
+  };
+  for (const r of results) {
+    total.input += r.usage.input;
+    total.output += r.usage.output;
+    total.cacheRead += r.usage.cacheRead;
+    total.cacheWrite += r.usage.cacheWrite;
+    total.cost += r.usage.cost;
+    total.turns += r.usage.turns;
+  }
+  return total;
+};
+
+if (details.mode === "chain") {
+  const successCount = details.results.filter(
+    (r) => r.exitCode === 0,
+  ).length;
+  const icon =
+    successCount === details.results.length
+      ? theme.fg("success", "✓")
+      : theme.fg("error", "✗");
+
+  if (expanded) {
+    const container = new Container();
+    container.addChild(
+      new Text(
+        icon +
+          " " +
+          theme.fg("toolTitle", theme.bold("chain ")) +
+          theme.fg(
+            "accent",
+            `${successCount}/${details.results.length} steps`,
+          ),
+        0,
+        0,
+      ),
+    );
+
+    for (const r of details.results) {
+      const rIcon =
+        r.exitCode === 0
+          ? theme.fg("success", "✓")
+          : theme.fg("error", "✗");
+      const displayItems = getDisplayItems(r.messages);
+      const finalOutput = getFinalOutput(r.messages);
+
+      container.addChild(new Spacer(1));
+      container.addChild(
+        new Text(
+          `${theme.fg("muted", `─── Step ${r.step}: `) + theme.fg("accent", r.agent)} ${rIcon}`,
+          0,
+          0,
+        ),
+      );
+      container.addChild(
+        new Text(
+          theme.fg("muted", "Task: ") + theme.fg("dim", r.task),
+          0,
+          0,
+        ),
+      );
+
+      // Show tool calls
+      for (const item of displayItems) {
+        if (item.type === "toolCall") {
+          container.addChild(
+            new Text(
+              theme.fg("muted", "→ ") +
+                formatToolCall(
+                  item.name,
+                  item.args,
+                  theme.fg.bind(theme),
+                ),
+              0,
+              0,
+            ),
+          );
+        }
+      }
+
+      // Show final output as markdown
+      if (finalOutput) {
+        container.addChild(new Spacer(1));
+        container.addChild(
+          new Markdown(finalOutput.trim(), 0, 0, mdTheme),
+        );
+      }
+
+      const stepUsage = formatUsageStats(r.usage, r.model);
+      if (stepUsage)
+        container.addChild(new Text(theme.fg("dim", stepUsage), 0, 0));
+    }
+
+    const usageStr = formatUsageStats(aggregateUsage(details.results));
+    if (usageStr) {
+      container.addChild(new Spacer(1));
+      container.addChild(
+        new Text(theme.fg("dim", `Total: ${usageStr}`), 0, 0),
+      );
+    }
+    return container;
+  }
+
+  // Collapsed view
+  let text =
+    icon +
+    " " +
+    theme.fg("toolTitle", theme.bold("chain ")) +
+    theme.fg("accent", `${successCount}/${details.results.length} steps`);
+  for (const r of details.results) {
+    const rIcon =
+      r.exitCode === 0
+        ? theme.fg("success", "✓")
+        : theme.fg("error", "✗");
+    const displayItems = getDisplayItems(r.messages);
+    text += `\n\n${theme.fg("muted", `─── Step ${r.step}: `)}${theme.fg("accent", r.agent)} ${rIcon}`;
+    if (displayItems.length === 0)
+      text += `\n${theme.fg("muted", "(no output)")}`;
+    else text += `\n${renderDisplayItems(displayItems, 5)}`;
+  }
+  const usageStr = formatUsageStats(aggregateUsage(details.results));
+  if (usageStr) text += `\n\n${theme.fg("dim", `Total: ${usageStr}`)}`;
+  text += `\n${theme.fg("muted", "(ctrl+o to expand)")}`;
+  return new Text(text, 0, 0);
+}
+
+if (details.mode === "parallel") {
+  const running = details.results.filter((r) => r.exitCode === -1).length;
+  const successCount = details.results.filter(
+    (r) => r.exitCode === 0,
+  ).length;
+  const failCount = details.results.filter((r) => r.exitCode > 0).length;
+  const isRunning = running > 0;
+  const icon = isRunning
+    ? theme.fg("warning", "⏳")
+    : failCount > 0
+      ? theme.fg("warning", "◐")
+      : theme.fg("success", "✓");
+  const status = isRunning
+    ? `${successCount + failCount}/${details.results.length} done, ${running} running`
+    : `${successCount}/${details.results.length} tasks`;
+
+  if (expanded && !isRunning) {
+    const container = new Container();
+    container.addChild(
+      new Text(
+        `${icon} ${theme.fg("toolTitle", theme.bold("parallel "))}${theme.fg("accent", status)}`,
+        0,
+        0,
+      ),
+    );
+
+    for (const r of details.results) {
+      const rIcon =
+        r.exitCode === 0
+          ? theme.fg("success", "✓")
+          : theme.fg("error", "✗");
+      const displayItems = getDisplayItems(r.messages);
+      const finalOutput = getFinalOutput(r.messages);
+
+      container.addChild(new Spacer(1));
+      container.addChild(
+        new Text(
+          `${theme.fg("muted", "─── ") + theme.fg("accent", r.agent)} ${rIcon}`,
+          0,
+          0,
+        ),
+      );
+      container.addChild(
+        new Text(
+          theme.fg("muted", "Task: ") + theme.fg("dim", r.task),
+          0,
+          0,
+        ),
+      );
+
+      // Show tool calls
+      for (const item of displayItems) {
+        if (item.type === "toolCall") {
+          container.addChild(
+            new Text(
+              theme.fg("muted", "→ ") +
+                formatToolCall(
+                  item.name,
+                  item.args,
+                  theme.fg.bind(theme),
+                ),
+              0,
+              0,
+            ),
+          );
+        }
+      }
+
+      // Show final output as markdown
+      if (finalOutput) {
+        container.addChild(new Spacer(1));
+        container.addChild(
+          new Markdown(finalOutput.trim(), 0, 0, mdTheme),
+        );
+      }
+
+      const taskUsage = formatUsageStats(r.usage, r.model);
+      if (taskUsage)
+        container.addChild(new Text(theme.fg("dim", taskUsage), 0, 0));
+    }
+
+    const usageStr = formatUsageStats(aggregateUsage(details.results));
+    if (usageStr) {
+      container.addChild(new Spacer(1));
+      container.addChild(
+        new Text(theme.fg("dim", `Total: ${usageStr}`), 0, 0),
+      );
+    }
+    return container;
+  }
+
+  // Collapsed view (or still running)
+  let text = `${icon} ${theme.fg("toolTitle", theme.bold("parallel "))}${theme.fg("accent", status)}`;
+  for (const r of details.results) {
+    const rIcon =
+      r.exitCode === -1
+        ? theme.fg("warning", "⏳")
+        : r.exitCode === 0
+          ? theme.fg("success", "✓")
+          : theme.fg("error", "✗");
+    const displayItems = getDisplayItems(r.messages);
+    text += `\n\n${theme.fg("muted", "─── ")}${theme.fg("accent", r.agent)} ${rIcon}`;
+    if (displayItems.length === 0)
+      text += `\n${theme.fg("muted", r.exitCode === -1 ? "(running...)" : "(no output)")}`;
+    else text += `\n${renderDisplayItems(displayItems, 5)}`;
+  }
+  if (!isRunning) {
+    const usageStr = formatUsageStats(aggregateUsage(details.results));
+    if (usageStr) text += `\n\n${theme.fg("dim", `Total: ${usageStr}`)}`;
+  }
+  if (!expanded) text += `\n${theme.fg("muted", "(ctrl+o to expand)")}`;
+  return new Text(text, 0, 0);
+}
+
+const text = result.content[0];
+return new Text(text?.type === "text" ? text.text : "(no output)", 0, 0);
+}

package/examples/extensions/subagent/runner.ts

@@ -0,0 +1,252 @@
+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 { APP_NAME, withFileMutationQueue } from "@bastani/atomic";
+import type { AgentConfig } from "./agents.ts";
+import { getFinalOutput } from "./display.js";
+import type { OnUpdateCallback, SingleResult, SubagentDetails } from "./types.js";
+
+export async function mapWithConcurrencyLimit<TIn, TOut>(
+  items: TIn[],
+  concurrency: number,
+  fn: (item: TIn, index: number) => Promise<TOut>,
+): Promise<TOut[]> {
+  if (items.length === 0) return [];
+  const limit = Math.max(1, Math.min(concurrency, items.length));
+  const results: TOut[] = new Array(items.length);
+  let nextIndex = 0;
+  const workers = new Array(limit).fill(null).map(async () => {
+    while (true) {
+      const current = nextIndex++;
+      if (current >= items.length) return;
+      results[current] = await fn(items[current], current);
+    }
+  });
+  await Promise.all(workers);
+  return results;
+}
+
+async function writePromptToTempFile(
+  agentName: string,
+  prompt: string,
+): Promise<{ dir: string; filePath: string }> {
+  const tmpDir = await fs.promises.mkdtemp(
+    path.join(os.tmpdir(), `${APP_NAME}-subagent-`),
+  );
+  const safeName = agentName.replace(/[^\w.-]+/g, "_");
+  const filePath = path.join(tmpDir, `prompt-${safeName}.md`);
+  await withFileMutationQueue(filePath, async () => {
+    await fs.promises.writeFile(filePath, prompt, {
+      encoding: "utf-8",
+      mode: 0o600,
+    });
+  });
+  return { dir: tmpDir, filePath };
+}
+
+function getAtomicInvocation(args: string[]): { command: string; args: string[] } {
+  const currentScript = process.argv[1];
+  const isBunVirtualScript = currentScript?.startsWith("/$bunfs/root/");
+  if (currentScript && !isBunVirtualScript && fs.existsSync(currentScript)) {
+    return { command: process.execPath, args: [currentScript, ...args] };
+  }
+
+  const execName = path.basename(process.execPath).toLowerCase();
+  const isGenericRuntime = /^(node|bun)(\.exe)?$/.test(execName);
+  if (!isGenericRuntime) {
+    return { command: process.execPath, args };
+  }
+
+  return { command: APP_NAME, args };
+}
+
+type OnUpdateCallback = (partial: AgentToolResult<SubagentDetails>) => void;
+
+export async function runSingleAgent(
+  defaultCwd: string,
+  agents: AgentConfig[],
+  agentName: string,
+  task: string,
+  cwd: string | undefined,
+  step: number | undefined,
+  signal: AbortSignal | undefined,
+  onUpdate: OnUpdateCallback | undefined,
+  makeDetails: (results: SingleResult[]) => SubagentDetails,
+): Promise<SingleResult> {
+  const agent = agents.find((a) => a.name === agentName);
+
+  if (!agent) {
+    const available = agents.map((a) => `"${a.name}"`).join(", ") || "none";
+    return {
+      agent: agentName,
+      agentSource: "unknown",
+      task,
+      exitCode: 1,
+      messages: [],
+      stderr: `Unknown agent: "${agentName}". Available agents: ${available}.`,
+      usage: {
+        input: 0,
+        output: 0,
+        cacheRead: 0,
+        cacheWrite: 0,
+        cost: 0,
+        contextTokens: 0,
+        turns: 0,
+      },
+      step,
+    };
+  }
+
+  const args: string[] = ["--mode", "json", "-p", "--no-session"];
+  if (agent.model) args.push("--model", agent.model);
+  if (agent.tools && agent.tools.length > 0)
+    args.push("--tools", agent.tools.join(","));
+
+  let tmpPromptDir: string | null = null;
+  let tmpPromptPath: string | null = null;
+
+  const currentResult: SingleResult = {
+    agent: agentName,
+    agentSource: agent.source,
+    task,
+    exitCode: 0,
+    messages: [],
+    stderr: "",
+    usage: {
+      input: 0,
+      output: 0,
+      cacheRead: 0,
+      cacheWrite: 0,
+      cost: 0,
+      contextTokens: 0,
+      turns: 0,
+    },
+    model: agent.model,
+    step,
+  };
+
+  const emitUpdate = () => {
+    if (onUpdate) {
+      onUpdate({
+        content: [
+          {
+            type: "text",
+            text: getFinalOutput(currentResult.messages) || "(running...)",
+          },
+        ],
+        details: makeDetails([currentResult]),
+      });
+    }
+  };
+
+  try {
+    if (agent.systemPrompt.trim()) {
+      const tmp = await writePromptToTempFile(agent.name, agent.systemPrompt);
+      tmpPromptDir = tmp.dir;
+      tmpPromptPath = tmp.filePath;
+      args.push("--append-system-prompt", tmpPromptPath);
+    }
+
+    args.push(`Task: ${task}`);
+    let wasAborted = false;
+
+    const exitCode = await new Promise<number>((resolve) => {
+      const invocation = getAtomicInvocation(args);
+      const proc = spawn(invocation.command, invocation.args, {
+        cwd: cwd ?? defaultCwd,
+        shell: false,
+        stdio: ["ignore", "pipe", "pipe"],
+      });
+      let buffer = "";
+
+      const processLine = (line: string) => {
+        if (!line.trim()) return;
+        let event: { type?: string; message?: Message };
+        try {
+          event = JSON.parse(line);
+        } catch {
+          return;
+        }
+
+        if (event.type === "message_end" && event.message) {
+          const msg = event.message as Message;
+          currentResult.messages.push(msg);
+
+          if (msg.role === "assistant") {
+            currentResult.usage.turns++;
+            const usage = msg.usage;
+            if (usage) {
+              currentResult.usage.input += usage.input || 0;
+              currentResult.usage.output += usage.output || 0;
+              currentResult.usage.cacheRead += usage.cacheRead || 0;
+              currentResult.usage.cacheWrite += usage.cacheWrite || 0;
+              currentResult.usage.cost += usage.cost?.total || 0;
+              currentResult.usage.contextTokens = usage.totalTokens || 0;
+            }
+            if (!currentResult.model && msg.model)
+              currentResult.model = msg.model;
+            if (msg.stopReason) currentResult.stopReason = msg.stopReason;
+            if (msg.errorMessage) currentResult.errorMessage = msg.errorMessage;
+          }
+          emitUpdate();
+        }
+
+        if (event.type === "tool_result_end" && event.message) {
+          currentResult.messages.push(event.message as Message);
+          emitUpdate();
+        }
+      };
+
+      proc.stdout.on("data", (data) => {
+        buffer += data.toString();
+        const lines = buffer.split("\n");
+        buffer = lines.pop() || "";
+        for (const line of lines) processLine(line);
+      });
+
+      proc.stderr.on("data", (data) => {
+        currentResult.stderr += data.toString();
+      });
+
+      proc.on("close", (code) => {
+        if (buffer.trim()) processLine(buffer);
+        resolve(code ?? 0);
+      });
+
+      proc.on("error", () => {
+        resolve(1);
+      });
+
+      if (signal) {
+        const killProc = () => {
+          wasAborted = true;
+          proc.kill("SIGTERM");
+          setTimeout(() => {
+            if (!proc.killed) proc.kill("SIGKILL");
+          }, 5000);
+        };
+        if (signal.aborted) killProc();
+        else signal.addEventListener("abort", killProc, { once: true });
+      }
+    });
+
+    currentResult.exitCode = exitCode;
+    if (wasAborted) throw new Error("Subagent was aborted");
+    return currentResult;
+  } finally {
+    if (tmpPromptPath)
+      try {
+        fs.unlinkSync(tmpPromptPath);
+      } catch {
+        /* ignore */
+      }
+    if (tmpPromptDir)
+      try {
+        fs.rmdirSync(tmpPromptDir);
+      } catch {
+        /* ignore */
+      }
+  }
+}

package/examples/extensions/subagent/schemas.ts

@@ -0,0 +1,59 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Type } from "typebox";
+
+const TaskItem = Type.Object({
+  agent: Type.String({ description: "Name of the agent to invoke" }),
+  task: Type.String({ description: "Task to delegate to the agent" }),
+  cwd: Type.Optional(
+    Type.String({ description: "Working directory for the agent process" }),
+  ),
+});
+
+const ChainItem = Type.Object({
+  agent: Type.String({ description: "Name of the agent to invoke" }),
+  task: Type.String({
+    description: "Task with optional {previous} placeholder for prior output",
+  }),
+  cwd: Type.Optional(
+    Type.String({ description: "Working directory for the agent process" }),
+  ),
+});
+
+const AgentScopeSchema = StringEnum(["user", "project", "both"] as const, {
+  description:
+    'Which agent directories to use. Default: "user". Use "both" to include project-local agents.',
+  default: "user",
+});
+
+export const SubagentParams = Type.Object({
+  agent: Type.Optional(
+    Type.String({
+      description: "Name of the agent to invoke (for single mode)",
+    }),
+  ),
+  task: Type.Optional(
+    Type.String({ description: "Task to delegate (for single mode)" }),
+  ),
+  tasks: Type.Optional(
+    Type.Array(TaskItem, {
+      description: "Array of {agent, task} for parallel execution",
+    }),
+  ),
+  chain: Type.Optional(
+    Type.Array(ChainItem, {
+      description: "Array of {agent, task} for sequential execution",
+    }),
+  ),
+  agentScope: Type.Optional(AgentScopeSchema),
+  confirmProjectAgents: Type.Optional(
+    Type.Boolean({
+      description: "Prompt before running project-local agents. Default: true.",
+      default: true,
+    }),
+  ),
+  cwd: Type.Optional(
+    Type.String({
+      description: "Working directory for the agent process (single mode)",
+    }),
+  ),
+});