@crewhaus/tool-bash 0.1.4 → 0.1.6

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+import type { RegisteredTool } from "@crewhaus/tool-catalog";
+export declare const bash: RegisteredTool;

package/dist/index.js

@@ -0,0 +1,84 @@
+import { buildTool } from "@crewhaus/tool-builder";
+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(),
+});
+function formatResult(out) {
+    const parts = [];
+    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 = buildTool({
+    name: "Bash",
+    description: "Run a shell command via `sh -c`. Captures stdout and stderr; default timeout 30s, max 10min.",
+    inputSchema: bashSchema,
+    destructive: true,
+    // Pillar 3 sink-side: Bash spawns a host process and its command string is an
+    // exfiltration channel (curl, nc, `base64 | sh`, …). Mark it external +
+    // process so runtime-core runs classifyEgress on the command payload and the
+    // substring matcher can flag tagged secrets on the command line (#146).
+    scope: "external",
+    ioCapability: "process",
+    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 = () => 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/package.json

@@ -1,26 +1,29 @@
 {
   "name": "@crewhaus/tool-bash",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "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",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
   },
   "scripts": {
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/errors": "0.1.4",
-    "@crewhaus/tool-builder": "0.1.4",
-    "@crewhaus/tool-catalog": "0.1.4",
+    "@crewhaus/errors": "0.1.6",
+    "@crewhaus/tool-builder": "0.1.6",
+    "@crewhaus/tool-catalog": "0.1.6",
     "zod": "^3.23.8"
   },
   "devDependencies": {
-    "@crewhaus/tool-executor": "0.1.4",
-    "@crewhaus/tool-permission-matcher": "0.1.4",
-    "@crewhaus/tool-validate": "0.1.4"
+    "@crewhaus/tool-executor": "0.1.6",
+    "@crewhaus/tool-permission-matcher": "0.1.6",
+    "@crewhaus/tool-validate": "0.1.6"
   },
   "license": "Apache-2.0",
   "author": {
@@ -40,5 +43,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "files": ["src", "README.md", "LICENSE", "NOTICE"]
+  "files": ["dist", "README.md", "LICENSE", "NOTICE"]
 }

package/src/index.drain-fallback.test.ts

@@ -1,119 +0,0 @@
-/**
- * Isolated coverage for the stream **drain-fallback** path in the Bash tool.
- *
- * On Linux, when the spawned `sh` forks a long-running grandchild and is
- * SIGKILLed, the orphan keeps the pipe's write-end open, so
- * `new Response(proc.stdout).text()` never EOFs. The tool guards against this
- * by racing each stream read against a fixed `DRAIN_GRACE_MS` fallback that
- * resolves to `""`. That fallback closure (`() => resolve("")`) cannot be
- * reached with a real, well-behaved subprocess — both pipes EOF immediately —
- * so we exercise it here with a fully mocked `Bun.spawn` whose streams never
- * close, plus a synchronous `setTimeout` so there is zero wall-clock delay and
- * no leaked timer handle.
- *
- * Everything (spawn + timers) is mocked and restored in `afterEach`, and this
- * lives in its own file so the stubs never leak into the real-subprocess
- * suites in `index.test.ts` / `integration.test.ts`.
- */
-import { afterEach, describe, expect, mock, spyOn, test } from "bun:test";
-import { bash } from "./index";
-
-/** A ReadableStream that emits one chunk and then NEVER closes — modelling the
- * orphaned-grandchild pipe that keeps the write-end alive. `Response.text()`
- * on this stream never resolves, forcing the drain fallback to win the race. */
-function neverClosingStream(): ReadableStream<Uint8Array> {
-  return new ReadableStream<Uint8Array>({
-    start(controller) {
-      controller.enqueue(new TextEncoder().encode("partial-output-no-eof"));
-      // Deliberately no controller.close() → the stream hangs open forever.
-    },
-  });
-}
-
-const spies: Array<{ mockRestore: () => void }> = [];
-
-afterEach(() => {
-  for (const s of spies.splice(0)) s.mockRestore();
-});
-
-describe("Bash tool — stream drain fallback (orphaned-pipe guard)", () => {
-  test("falls back to empty streams when neither pipe EOFs before the grace window", async () => {
-    const killMock = mock((_sig?: unknown) => {});
-    // Fake proc: exits cleanly, but its stdout/stderr never close.
-    spies.push(
-      spyOn(Bun, "spawn").mockImplementation(
-        ((): ReturnType<typeof Bun.spawn> =>
-          ({
-            stdout: neverClosingStream(),
-            stderr: neverClosingStream(),
-            exited: Promise.resolve(0),
-            kill: killMock,
-          }) as unknown as ReturnType<typeof Bun.spawn>) as unknown as typeof Bun.spawn,
-      ),
-    );
-    // Fire ONLY the short DRAIN_GRACE (500ms) fallback timers synchronously —
-    // their `() => resolve("")` bodies are the target of this test. The long
-    // command-timeout timer (30s default) must NOT fire, or the run would be
-    // wrongly marked timed-out; for it we return an inert handle.
-    spies.push(
-      spyOn(globalThis, "setTimeout").mockImplementation(((
-        fn: (...a: unknown[]) => void,
-        ms?: number,
-      ) => {
-        if (ms !== undefined && ms <= 500) fn();
-        return 0 as unknown as ReturnType<typeof setTimeout>;
-      }) as unknown as typeof setTimeout),
-    );
-    spies.push(
-      spyOn(globalThis, "clearTimeout").mockImplementation(
-        (() => {}) as unknown as typeof clearTimeout,
-      ),
-    );
-
-    const out = await bash.execute({ command: "sleep 999" });
-
-    // Both streams drained to "" via the fallback, so the formatted result is
-    // just the exit line (no stdout/stderr sections) and the run is not marked
-    // as timed out (the process `exited` resolved on its own).
-    expect(out).toBe("[exit] 0");
-    expect(out).not.toContain("partial-output-no-eof");
-    expect(out).not.toContain("[stderr]");
-    expect(out).not.toContain("timed out");
-  });
-
-  test("drain fallback still reports a non-zero exit code from a hung-pipe process", async () => {
-    const killMock = mock((_sig?: unknown) => {});
-    spies.push(
-      spyOn(Bun, "spawn").mockImplementation(
-        ((): ReturnType<typeof Bun.spawn> =>
-          ({
-            stdout: neverClosingStream(),
-            stderr: neverClosingStream(),
-            exited: Promise.resolve(42),
-            kill: killMock,
-          }) as unknown as ReturnType<typeof Bun.spawn>) as unknown as typeof Bun.spawn,
-      ),
-    );
-    // Same selective firing as the first test: only the short DRAIN_GRACE
-    // (≤500ms) fallback timers run synchronously; the 30s command-timeout timer
-    // must stay inert, otherwise the run would be wrongly flagged as timed out
-    // and the exit line would read "[exit] 42 (timed out after 30000ms)".
-    spies.push(
-      spyOn(globalThis, "setTimeout").mockImplementation(((
-        fn: (...a: unknown[]) => void,
-        ms?: number,
-      ) => {
-        if (ms !== undefined && ms <= 500) fn();
-        return 0 as unknown as ReturnType<typeof setTimeout>;
-      }) as unknown as typeof setTimeout),
-    );
-    spies.push(
-      spyOn(globalThis, "clearTimeout").mockImplementation(
-        (() => {}) as unknown as typeof clearTimeout,
-      ),
-    );
-
-    const out = await bash.execute({ command: "exit 42" });
-    expect(out).toBe("[exit] 42");
-  });
-});

package/src/index.test.ts

@@ -1,74 +0,0 @@
-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);
-  });
-
-  test("crosses a process boundary → external scope + process io-capability (#146)", () => {
-    expect(bash.scope).toBe("external");
-    expect(bash.ioCapability).toBe("process");
-  });
-});
-
-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

@@ -1,97 +0,0 @@
-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,
-  // Pillar 3 sink-side: Bash spawns a host process and its command string is an
-  // exfiltration channel (curl, nc, `base64 | sh`, …). Mark it external +
-  // process so runtime-core runs classifyEgress on the command payload and the
-  // substring matcher can flag tagged secrets on the command line (#146).
-  scope: "external",
-  ioCapability: "process",
-  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

@@ -1,75 +0,0 @@
-/**
- * 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");
-  });
-});