feat(tools): add direct Bun script runner

rcarmo · rcarmo · commit 3693eed86897 · 2026-03-30T19:57:32.000+01:00
diff --git a/runtime/src/extensions/bun-runner.ts b/runtime/src/extensions/bun-runner.ts
@@ -0,0 +1,127 @@
+/**
+ * bun-runner – registers a Bun script execution tool.
+ *
+ * Runs workspace Bun scripts directly (no shell), with optional argv and cwd.
+ * Stdout is discarded; stderr is captured and returned.
+ */
+
+import { Type, type Static } from "@sinclair/typebox";
+import type { AgentToolResult, ExtensionAPI, ExtensionFactory } from "@mariozechner/pi-coding-agent";
+
+import { runBunScript } from "../tools/bun-runner.js";
+
+const BunRunSchema = Type.Object({
+  script: Type.String({ description: "Workspace-relative script file to execute with Bun (for example `runtime/scripts/foo.ts`)." }),
+  args: Type.Optional(Type.Array(Type.String(), { description: "Arguments passed to the script. No shell parsing is performed." })),
+  cwd: Type.Optional(Type.String({ description: "Working directory relative to the workspace (defaults to the workspace root)." })),
+  timeout_sec: Type.Optional(Type.Integer({ description: "Timeout in seconds.", minimum: 1, maximum: 3600 })),
+});
+
+type BunRunParams = Static<typeof BunRunSchema>;
+
+const HINT = [
+  "## Direct Bun scripts",
+  "Use bun_run to execute a workspace Bun script directly without a shell.",
+  "Pass script arguments as an array; do not rely on shell features like pipes or redirects.",
+  "Scripts should write structured output to files themselves; bun_run only captures stderr.",
+].join("\n");
+
+function formatArgs(args: string[]): string {
+  if (args.length === 0) return "(none)";
+  return args.map((arg) => JSON.stringify(arg)).join(" ");
+}
+
+function buildResultText(result: {
+  scriptDisplayPath: string;
+  cwdDisplayPath: string;
+  args: string[];
+  exitCode: number | null;
+  stderr: string;
+  stderrTruncated: boolean;
+}): string {
+  const status = result.exitCode === 0
+    ? `bun_run completed successfully for ${result.scriptDisplayPath}.`
+    : `bun_run finished with exit code ${result.exitCode ?? "unknown"} for ${result.scriptDisplayPath}.`;
+  const lines = [
+    status,
+    `cwd: ${result.cwdDisplayPath}`,
+    `args: ${formatArgs(result.args)}`,
+    "stdout: discarded",
+  ];
+
+  if (result.stderr) {
+    lines.push("stderr:");
+    lines.push(result.stderrTruncated ? `${result.stderr}\n[stderr truncated]` : result.stderr);
+  } else {
+    lines.push("stderr: (empty)");
+  }
+
+  return lines.join("\n");
+}
+
+export const bunRunner: ExtensionFactory = (pi: ExtensionAPI) => {
+  pi.on("before_agent_start", async (event) => ({
+    systemPrompt: `${event.systemPrompt}\n\n${HINT}`,
+  }));
+
+  pi.registerTool({
+    name: "bun_run",
+    label: "bun_run",
+    description: "Run a workspace Bun script directly with optional arguments and cwd. No shell parsing, piping, or redirects; stdout is discarded and only stderr is captured.",
+    promptSnippet: "bun_run: execute a workspace Bun script directly with optional arguments and cwd, capturing stderr only.",
+    parameters: BunRunSchema,
+    async execute(
+      _toolCallId: string,
+      params: BunRunParams,
+      signal?: AbortSignal,
+    ): Promise<AgentToolResult<Record<string, unknown>>> {
+      try {
+        const result = await runBunScript({
+          script: params.script,
+          args: params.args,
+          cwd: params.cwd,
+          timeoutSec: params.timeout_sec,
+        }, signal);
+
+        return {
+          content: [{ type: "text", text: buildResultText(result) }],
+          details: {
+            ok: result.exitCode === 0,
+            script: result.scriptDisplayPath,
+            cwd: result.cwdDisplayPath,
+            args: result.args,
+            bun_path: result.bunPath,
+            exit_code: result.exitCode,
+            stderr: result.stderr,
+            stderr_bytes: result.stderrBytes,
+            stderr_truncated: result.stderrTruncated,
+          },
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const timedOut = message.startsWith("timeout:");
+        const aborted = message === "aborted";
+        return {
+          content: [{
+            type: "text",
+            text: timedOut
+              ? `bun_run timed out after ${params.timeout_sec ?? 120}s while running ${params.script}.`
+              : aborted
+                ? `bun_run was aborted while running ${params.script}.`
+                : `bun_run failed: ${message}`,
+          }],
+          details: {
+            ok: false,
+            script: params.script,
+            cwd: params.cwd || ".",
+            args: Array.isArray(params.args) ? params.args : [],
+            timeout_sec: params.timeout_sec ?? 120,
+            timed_out: timedOut,
+            aborted,
+            error: message,
+          },
+        };
+      }
+    },
+  });
+};
diff --git a/runtime/src/extensions/index.ts b/runtime/src/extensions/index.ts
@@ -16,6 +16,7 @@
  *   - workspaceSearch: search_workspace tool for FTS over workspace files.
  *   - sendAdaptiveCard: send_adaptive_card for agent-owned Adaptive Card posting.
  *   - sendDashboardWidget: send_dashboard_widget for posting the built-in live dashboard widget.
+ *   - bunRunner: bun_run for direct Bun script execution without a shell.
  *
  * Consumers:
  *   - agent-pool/session.ts passes builtinExtensionFactories to the resource loader.
@@ -33,6 +34,7 @@ import { uiThemeExtension } from "./ui-theme.js";
 import { smartCompaction } from "./smart-compaction.js";
 import { sendAdaptiveCard } from "./send-adaptive-card.js";
 import { sendDashboardWidget } from "./send-dashboard-widget.js";
+import { bunRunner } from "./bun-runner.js";
 import { exitProcess } from "./exit-process.js";
 import { autoresearchSupervisor } from "./autoresearch-supervisor.js";
 
@@ -50,6 +52,7 @@ export const builtinExtensionFactories: ExtensionFactory[] = [
   smartCompaction,
   sendAdaptiveCard,
   sendDashboardWidget,
+  bunRunner,
   exitProcess,
   autoresearchSupervisor,
 ];
diff --git a/runtime/src/tools/bun-runner.ts b/runtime/src/tools/bun-runner.ts
@@ -0,0 +1,233 @@
+/**
+ * tools/bun-runner.ts – Run workspace Bun scripts directly without a shell.
+ *
+ * Spawns the Bun runtime with a script path + argv array, keeps cwd/script
+ * resolution inside the workspace, tracks the child process for abort/shutdown,
+ * discards stdout, and captures stderr only.
+ */
+
+import { spawn } from "child_process";
+import { existsSync, statSync } from "fs";
+import path from "path";
+
+import { WORKSPACE_DIR } from "../core/config.js";
+import { killProcessTree, registerProcess, unregisterProcess } from "../utils/process-tracker.js";
+
+const DEFAULT_TIMEOUT_SEC = 120;
+const MAX_TIMEOUT_SEC = 3600;
+const MAX_CAPTURED_STDERR_BYTES = 64 * 1024;
+
+export interface RunBunScriptParams {
+  script: string;
+  args?: string[];
+  cwd?: string;
+  timeoutSec?: number;
+}
+
+export interface ResolvedBunScriptTarget {
+  scriptPath: string;
+  scriptDisplayPath: string;
+  cwd: string;
+  cwdDisplayPath: string;
+  args: string[];
+  timeoutSec: number;
+}
+
+export interface RunBunScriptResult extends ResolvedBunScriptTarget {
+  bunPath: string;
+  exitCode: number | null;
+  stderr: string;
+  stderrBytes: number;
+  stderrTruncated: boolean;
+}
+
+function resolveWorkspacePath(input: string): string | null {
+  const raw = String(input || "").trim();
+  if (!raw) return null;
+  const resolved = path.resolve(WORKSPACE_DIR, raw);
+  const rel = path.relative(WORKSPACE_DIR, resolved);
+  if (rel.startsWith("..") || path.isAbsolute(rel)) return null;
+  return resolved;
+}
+
+function displayWorkspacePath(absPath: string): string {
+  const rel = path.relative(WORKSPACE_DIR, absPath);
+  if (!rel || rel === ".") return ".";
+  return rel.split(path.sep).join("/");
+}
+
+function normalizeArgs(input: unknown): string[] {
+  if (input === undefined || input === null) return [];
+  if (!Array.isArray(input)) {
+    throw new Error("args must be an array of strings.");
+  }
+  return input.map((value, index) => {
+    if (typeof value !== "string") {
+      throw new Error(`args[${index}] must be a string.`);
+    }
+    if (value.includes("\0")) {
+      throw new Error(`args[${index}] contains an invalid null byte.`);
+    }
+    return value;
+  });
+}
+
+export function resolveBunScriptTarget(params: RunBunScriptParams): ResolvedBunScriptTarget {
+  const resolvedScript = resolveWorkspacePath(params.script);
+  if (!resolvedScript) {
+    throw new Error("script must resolve to a file inside the workspace.");
+  }
+  if (!existsSync(resolvedScript)) {
+    throw new Error(`Script not found: ${params.script}`);
+  }
+
+  let scriptStats;
+  try {
+    scriptStats = statSync(resolvedScript);
+  } catch {
+    throw new Error(`Failed to stat script: ${params.script}`);
+  }
+  if (!scriptStats.isFile()) {
+    throw new Error("script must be a file, not a directory.");
+  }
+
+  const resolvedCwd = params.cwd && String(params.cwd).trim()
+    ? resolveWorkspacePath(params.cwd)
+    : WORKSPACE_DIR;
+  if (!resolvedCwd) {
+    throw new Error("cwd must stay within the workspace.");
+  }
+  if (!existsSync(resolvedCwd)) {
+    throw new Error(`cwd does not exist: ${params.cwd}`);
+  }
+
+  let cwdStats;
+  try {
+    cwdStats = statSync(resolvedCwd);
+  } catch {
+    throw new Error(`Failed to stat cwd: ${params.cwd}`);
+  }
+  if (!cwdStats.isDirectory()) {
+    throw new Error("cwd must be a directory.");
+  }
+
+  const timeoutSec = Number.isFinite(params.timeoutSec)
+    ? Math.min(Math.max(Number(params.timeoutSec), 1), MAX_TIMEOUT_SEC)
+    : DEFAULT_TIMEOUT_SEC;
+
+  return {
+    scriptPath: resolvedScript,
+    scriptDisplayPath: displayWorkspacePath(resolvedScript),
+    cwd: resolvedCwd,
+    cwdDisplayPath: displayWorkspacePath(resolvedCwd),
+    args: normalizeArgs(params.args),
+    timeoutSec,
+  };
+}
+
+export async function runBunScript(
+  params: RunBunScriptParams,
+  signal?: AbortSignal,
+): Promise<RunBunScriptResult> {
+  const target = resolveBunScriptTarget(params);
+  const bunPath = process.execPath || "bun";
+
+  return await new Promise<RunBunScriptResult>((resolve, reject) => {
+    let settled = false;
+    let child: ReturnType<typeof spawn> | null = null;
+    let timedOut = false;
+    let aborted = false;
+    let stderrBytes = 0;
+    let stderrTruncated = false;
+    const stderrChunks: string[] = [];
+
+    const cleanup = (timeoutHandle?: NodeJS.Timeout) => {
+      if (timeoutHandle) clearTimeout(timeoutHandle);
+      if (signal) signal.removeEventListener("abort", onAbort);
+      if (child?.pid) unregisterProcess(child.pid);
+    };
+
+    const finish = (result: RunBunScriptResult) => {
+      if (settled) return;
+      settled = true;
+      resolve(result);
+    };
+
+    const fail = (error: Error, timeoutHandle?: NodeJS.Timeout) => {
+      if (settled) return;
+      settled = true;
+      cleanup(timeoutHandle);
+      reject(error);
+    };
+
+    const onAbort = () => {
+      aborted = true;
+      if (child?.pid) killProcessTree(child.pid);
+    };
+
+    const timeoutHandle = setTimeout(() => {
+      timedOut = true;
+      if (child?.pid) killProcessTree(child.pid);
+    }, target.timeoutSec * 1000);
+
+    if (signal) {
+      if (signal.aborted) {
+        onAbort();
+      } else {
+        signal.addEventListener("abort", onAbort, { once: true });
+      }
+    }
+
+    child = spawn(bunPath, [target.scriptPath, ...target.args], {
+      cwd: target.cwd,
+      detached: true,
+      env: process.env,
+      stdio: ["ignore", "ignore", "pipe"],
+    });
+
+    if (child.pid) registerProcess(child.pid);
+
+    child.stderr?.on("data", (chunk) => {
+      const text = Buffer.isBuffer(chunk) ? chunk.toString("utf8") : String(chunk);
+      stderrBytes += Buffer.byteLength(text, "utf8");
+      const currentBytes = stderrChunks.reduce((sum, entry) => sum + Buffer.byteLength(entry, "utf8"), 0);
+      const remaining = MAX_CAPTURED_STDERR_BYTES - currentBytes;
+      if (remaining <= 0) {
+        stderrTruncated = true;
+        return;
+      }
+      if (Buffer.byteLength(text, "utf8") > remaining) {
+        stderrTruncated = true;
+        stderrChunks.push(Buffer.from(text, "utf8").subarray(0, remaining).toString("utf8"));
+        return;
+      }
+      stderrChunks.push(text);
+    });
+
+    child.on("error", (error) => {
+      fail(error, timeoutHandle);
+    });
+
+    child.on("close", (exitCode) => {
+      cleanup(timeoutHandle);
+
+      if (aborted || signal?.aborted) {
+        reject(new Error("aborted"));
+        return;
+      }
+      if (timedOut) {
+        reject(new Error(`timeout:${target.timeoutSec}`));
+        return;
+      }
+
+      finish({
+        ...target,
+        bunPath,
+        exitCode,
+        stderr: stderrChunks.join(""),
+        stderrBytes,
+        stderrTruncated,
+      });
+    });
+  });
+}
diff --git a/runtime/test/extensions/extensions-bun-runner.test.ts b/runtime/test/extensions/extensions-bun-runner.test.ts
