@crewhaus/tool-bash 0.1.0

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@crewhaus/tool-bash",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Built-in Bash tool: spawns shell commands via Bun.spawn with a default 30s timeout",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "@crewhaus/errors": "0.0.0",
+    "@crewhaus/tool-builder": "0.0.0",
+    "@crewhaus/tool-catalog": "0.0.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@crewhaus/tool-executor": "0.0.0",
+    "@crewhaus/tool-permission-matcher": "0.0.0",
+    "@crewhaus/tool-validate": "0.0.0"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Max Meier",
+    "email": "max@studiomax.io",
+    "url": "https://studiomax.io"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crewhaus/factory.git",
+    "directory": "packages/tool-bash"
+  },
+  "homepage": "https://github.com/crewhaus/factory/tree/main/packages/tool-bash#readme",
+  "bugs": {
+    "url": "https://github.com/crewhaus/factory/issues"
+  },
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ]
+}

package/src/index.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, test } from "bun:test";
+import { bash } from "./index";
+
+describe("Bash tool metadata", () => {
+  test("name + flags", () => {
+    expect(bash.name).toBe("Bash");
+    expect(bash.destructive).toBe(true);
+    expect(bash.readOnly).toBe(false);
+    expect(bash.concurrencySafe).toBe(false);
+  });
+});
+
+describe("Bash tool execution", () => {
+  test("captures stdout and exit code 0 on success", async () => {
+    const out = await bash.execute({ command: "echo hello" });
+    expect(out).toContain("hello");
+    expect(out).toContain("[exit] 0");
+    expect(out).not.toContain("timed out");
+  });
+
+  test("reports non-zero exit code", async () => {
+    const out = await bash.execute({ command: "exit 7" });
+    expect(out).toContain("[exit] 7");
+  });
+
+  test("captures stderr separately from stdout", async () => {
+    const out = await bash.execute({ command: ">&2 echo oops" });
+    expect(out).toContain("[stderr]");
+    expect(out).toContain("oops");
+  });
+
+  test("captures both streams and shows them in order", async () => {
+    const out = await bash.execute({
+      command: "echo out; >&2 echo err; exit 1",
+    });
+    expect(out).toContain("out");
+    expect(out).toContain("[stderr]");
+    expect(out).toContain("err");
+    expect(out).toContain("[exit] 1");
+  });
+
+  test("kills the process and reports timeout when exceeded", async () => {
+    const start = Date.now();
+    const out = await bash.execute({ command: "sleep 10", timeout: 150 });
+    const elapsed = Date.now() - start;
+    expect(out).toContain("timed out after 150ms");
+    expect(elapsed).toBeLessThan(2000);
+  });
+
+  test("does not time out when command finishes within budget", async () => {
+    const out = await bash.execute({ command: "echo fast", timeout: 5000 });
+    expect(out).not.toContain("timed out");
+    expect(out).toContain("fast");
+    expect(out).toContain("[exit] 0");
+  });
+
+  test("rejects timeouts above the cap via schema", () => {
+    const result = bash.inputSchema.safeParse({
+      command: "echo",
+      timeout: 999_999_999,
+    });
+    expect(result.success).toBe(false);
+  });
+
+  test("rejects empty command via schema", () => {
+    const result = bash.inputSchema.safeParse({ command: "" });
+    expect(result.success).toBe(false);
+  });
+});

package/src/index.ts

@@ -0,0 +1,91 @@
+import { buildTool } from "@crewhaus/tool-builder";
+import type { RegisteredTool } from "@crewhaus/tool-catalog";
+import { z } from "zod";
+
+/**
+ * Built-in Bash tool. Spawns the command through `sh -c` via `Bun.spawn`,
+ * captures stdout + stderr, and enforces a default 30s timeout (max 10min)
+ * by SIGKILLing the subprocess when the deadline elapses. The returned
+ * string is human-readable and encodes both streams plus the exit code.
+ *
+ * Linux note: when `sh` forks a long-running grandchild (e.g. `sleep 10`),
+ * SIGKILL on the shell does not propagate to the orphan, which keeps the
+ * pipe write-end alive and prevents `text()` from ever EOFing. After the
+ * shell exits we therefore give each stream a fixed drain grace window
+ * before falling back to an empty string — the orphan still exits on its
+ * own, but the tool call returns within `timeoutMs + DRAIN_GRACE_MS`.
+ *
+ * Layer R4. Pairs with the `target-cli` codegen contract (`bash` export).
+ */
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+const MAX_TIMEOUT_MS = 600_000;
+const DRAIN_GRACE_MS = 500;
+
+const bashSchema = z.object({
+  command: z.string().min(1),
+  timeout: z.number().int().positive().max(MAX_TIMEOUT_MS).optional(),
+});
+
+type BashOutput = {
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly exitCode: number;
+  readonly timedOut: boolean;
+  readonly timeoutMs: number;
+};
+
+function formatResult(out: BashOutput): string {
+  const parts: string[] = [];
+  if (out.stdout.length > 0) parts.push(out.stdout.replace(/\n+$/, ""));
+  if (out.stderr.length > 0) {
+    parts.push("[stderr]");
+    parts.push(out.stderr.replace(/\n+$/, ""));
+  }
+  const exitLine = out.timedOut
+    ? `[exit] ${out.exitCode} (timed out after ${out.timeoutMs}ms)`
+    : `[exit] ${out.exitCode}`;
+  parts.push(exitLine);
+  return parts.join("\n");
+}
+
+export const bash: RegisteredTool = buildTool({
+  name: "Bash",
+  description:
+    "Run a shell command via `sh -c`. Captures stdout and stderr; default timeout 30s, max 10min.",
+  inputSchema: bashSchema,
+  destructive: true,
+  execute: async (input, ctx) => {
+    const timeoutMs = input.timeout ?? DEFAULT_TIMEOUT_MS;
+    const proc = Bun.spawn(["sh", "-c", input.command], {
+      stdout: "pipe",
+      stderr: "pipe",
+      // When the orchestrator aborts the turn (Ctrl-C, recovery exhaustion),
+      // Bun forwards the signal as SIGTERM to the spawned shell.
+      ...(ctx?.signal !== undefined ? { signal: ctx.signal } : {}),
+    });
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      try {
+        proc.kill("SIGKILL");
+      } catch {
+        // Process already exited between the timer firing and the kill call.
+      }
+    }, timeoutMs);
+    try {
+      const stdoutText = new Response(proc.stdout).text();
+      const stderrText = new Response(proc.stderr).text();
+      const exitCode = await proc.exited;
+      const drainFallback = (): Promise<string> =>
+        new Promise((resolve) => setTimeout(() => resolve(""), DRAIN_GRACE_MS));
+      const [stdout, stderr] = await Promise.all([
+        Promise.race([stdoutText, drainFallback()]),
+        Promise.race([stderrText, drainFallback()]),
+      ]);
+      return formatResult({ stdout, stderr, exitCode, timedOut, timeoutMs });
+    } finally {
+      clearTimeout(timer);
+    }
+  },
+});

package/src/integration.test.ts

@@ -0,0 +1,75 @@
+/**
+ * Integration test: wire ToolCatalog + buildTool + validateToolInput +
+ * matchesPattern + executeTool around the bash tool. Confirms the timeout
+ * path surfaces a non-error result whose content includes the timeout
+ * marker, and that permission patterns gate prefix-style command rules.
+ */
+import { beforeEach, describe, expect, test } from "bun:test";
+import { type RegisteredTool, ToolCatalog } from "@crewhaus/tool-catalog";
+import { executeTool } from "@crewhaus/tool-executor";
+import { bash } from "./index";
+
+let catalog: ToolCatalog;
+
+function lookup(name: string): RegisteredTool {
+  const tool = catalog.get(name);
+  if (!tool) throw new Error(`expected tool "${name}" to be registered`);
+  return tool;
+}
+
+beforeEach(() => {
+  catalog = new ToolCatalog();
+  catalog.register(bash);
+});
+
+describe("integration: tool-bash through executeTool", () => {
+  test("happy path returns stdout and exit code", async () => {
+    const result = await executeTool(
+      lookup("Bash"),
+      { command: "echo integration" },
+      { toolUseId: "b1" },
+    );
+    expect(result.isError).toBe(false);
+    expect(result.content).toContain("integration");
+    expect(result.content).toContain("[exit] 0");
+  });
+
+  test("non-zero exit is reported via formatted content (not isError)", async () => {
+    const result = await executeTool(lookup("Bash"), { command: "exit 3" }, { toolUseId: "b2" });
+    expect(result.isError).toBe(false);
+    expect(result.content).toContain("[exit] 3");
+  });
+
+  test("timeout surfaces in content", async () => {
+    const result = await executeTool(
+      lookup("Bash"),
+      { command: "sleep 5", timeout: 120 },
+      { toolUseId: "b3" },
+    );
+    expect(result.isError).toBe(false);
+    expect(result.content).toContain("timed out");
+  });
+
+  test("invalid input is caught before execute (empty command)", async () => {
+    const result = await executeTool(lookup("Bash"), { command: "" }, { toolUseId: "b4" });
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain("Bash");
+  });
+
+  test("permission pattern Bash gates the call", async () => {
+    const allowed = await executeTool(
+      lookup("Bash"),
+      { command: "echo ok" },
+      { toolUseId: "b5", allowedPatterns: ["Bash"] },
+    );
+    expect(allowed.isError).toBe(false);
+
+    const denied = await executeTool(
+      lookup("Bash"),
+      { command: "echo ok" },
+      { toolUseId: "b6", allowedPatterns: ["Read"] },
+    );
+    expect(denied.isError).toBe(true);
+    expect(denied.content).toContain("not permitted");
+  });
+});