@aaroncql/pim-agent 0.0.1

package/src/extensions/bash/capture.ts

@@ -0,0 +1,80 @@
+import { Lines } from "../../shared/Lines";
+import {
+  type CapturedStream,
+  STREAM_HEAD_BYTES,
+  STREAM_TAIL_BYTES,
+} from "./schema";
+
+export function concat(parts: Uint8Array[], total: number): Uint8Array {
+  const out = new Uint8Array(total);
+  let off = 0;
+  for (const p of parts) {
+    out.set(p, off);
+    off += p.byteLength;
+  }
+  return out;
+}
+
+export class StreamCapture {
+  private chunks: Uint8Array[] = [];
+  private totalBytesAccum = 0;
+  private fullBytes: Uint8Array | null = null;
+
+  push(chunk: Uint8Array): void {
+    if (chunk.byteLength === 0) {
+      return;
+    }
+    this.chunks.push(chunk);
+    this.totalBytesAccum += chunk.byteLength;
+  }
+
+  get totalBytes(): number {
+    return this.totalBytesAccum;
+  }
+
+  get truncated(): boolean {
+    return this.totalBytesAccum > STREAM_HEAD_BYTES + STREAM_TAIL_BYTES;
+  }
+
+  full(): Uint8Array {
+    if (!this.fullBytes) {
+      this.fullBytes = concat(this.chunks, this.totalBytesAccum);
+    }
+    return this.fullBytes;
+  }
+
+  snapshot(): CapturedStream {
+    if (this.totalBytesAccum === 0) {
+      return {
+        text: "",
+        totalBytes: 0,
+        truncated: false,
+        path: null,
+        nextStart: null,
+      };
+    }
+    const dec = new TextDecoder();
+    if (!this.truncated) {
+      return {
+        text: dec.decode(this.full()),
+        totalBytes: this.totalBytesAccum,
+        truncated: false,
+        path: null,
+        nextStart: null,
+      };
+    }
+    const all = this.full();
+    const headText = dec.decode(all.subarray(0, STREAM_HEAD_BYTES));
+    const tailText = dec.decode(
+      all.subarray(all.byteLength - STREAM_TAIL_BYTES)
+    );
+    const middle = this.totalBytesAccum - STREAM_HEAD_BYTES - STREAM_TAIL_BYTES;
+    return {
+      text: `${headText}\n... ${middle} bytes truncated ...\n${tailText}`,
+      totalBytes: this.totalBytesAccum,
+      truncated: true,
+      path: null,
+      nextStart: Lines.continuationLine(headText),
+    };
+  }
+}

package/src/extensions/bash/format.test.ts

@@ -0,0 +1,240 @@
+import { describe, expect, test } from "bun:test";
+import {
+  detailsOf,
+  formatResult,
+  formatTruncationAffordance,
+  isErrorResult,
+  stripTrailingNewline,
+} from "./format";
+import {
+  type BashCommandResult,
+  STREAM_HEAD_BYTES,
+  STREAM_TAIL_BYTES,
+} from "./schema";
+
+function makeResult(
+  overrides: Partial<BashCommandResult> = {}
+): BashCommandResult {
+  return {
+    exitCode: 0,
+    signal: null,
+    stdout: {
+      text: "",
+      totalBytes: 0,
+      truncated: false,
+      path: null,
+      nextStart: null,
+    },
+    stderr: {
+      text: "",
+      totalBytes: 0,
+      truncated: false,
+      path: null,
+      nextStart: null,
+    },
+    timedOut: false,
+    aborted: false,
+    durationMs: 1,
+    ...overrides,
+  };
+}
+
+describe("stripTrailingNewline", () => {
+  test("removes one trailing newline", () => {
+    expect(stripTrailingNewline("foo\n")).toBe("foo");
+  });
+  test("leaves no-newline strings alone", () => {
+    expect(stripTrailingNewline("foo")).toBe("foo");
+  });
+  test("only strips one", () => {
+    expect(stripTrailingNewline("foo\n\n")).toBe("foo\n");
+  });
+});
+
+describe("formatTruncationAffordance", () => {
+  test("emits bracketed affordance with byte counts and next-step", () => {
+    const out = formatTruncationAffordance("stderr", {
+      text: "x",
+      totalBytes: 12345,
+      truncated: true,
+      path: null,
+      nextStart: 1,
+    });
+    expect(out.startsWith("[bash tool:")).toBe(true);
+    expect(out.endsWith("]")).toBe(true);
+    expect(out).toContain("stderr showing first");
+    expect(out).toContain(`first ${STREAM_HEAD_BYTES} bytes`);
+    expect(out).toContain(`last ${STREAM_TAIL_BYTES} bytes`);
+    expect(out).toContain("of 12345");
+    expect(out).toContain("redirect to a file");
+    expect(out).toContain("read");
+  });
+
+  test("points to spill path with a resume line when one is provided", () => {
+    const out = formatTruncationAffordance("stdout", {
+      text: "x",
+      totalBytes: 99999,
+      truncated: true,
+      path: "/tmp/pim-bash-abc.out",
+      nextStart: 42,
+    });
+    expect(out).toContain(
+      "use read with path=/tmp/pim-bash-abc.out and start=42 for the rest."
+    );
+    expect(out).not.toContain("redirect to a file");
+  });
+});
+
+describe("formatResult", () => {
+  test("happy path with stdout only", () => {
+    const out = formatResult(
+      makeResult({
+        stdout: {
+          text: "hello\n",
+          totalBytes: 6,
+          truncated: false,
+          path: null,
+          nextStart: null,
+        },
+      }),
+      30_000
+    );
+    expect(out).toBe("Exit code: 0\nstdout:\nhello");
+  });
+
+  test("includes signal line when signal present", () => {
+    const out = formatResult(
+      makeResult({ exitCode: null, signal: "SIGTERM" }),
+      30_000
+    );
+    expect(out).toContain("Exit code: none");
+    expect(out).toContain("Signal: SIGTERM");
+  });
+
+  test("aborted overrides timed out message", () => {
+    const out = formatResult(
+      makeResult({ aborted: true, timedOut: true }),
+      30_000
+    );
+    expect(out).toContain("Aborted.");
+    expect(out).not.toContain("Timed out");
+  });
+
+  test("timed out adds duration message", () => {
+    const out = formatResult(makeResult({ timedOut: true }), 5000);
+    expect(out).toContain("Timed out after 5000 ms.");
+  });
+
+  test("includes both stdout and stderr when both have bytes", () => {
+    const out = formatResult(
+      makeResult({
+        exitCode: 1,
+        stdout: {
+          text: "out",
+          totalBytes: 3,
+          truncated: false,
+          path: null,
+          nextStart: null,
+        },
+        stderr: {
+          text: "err",
+          totalBytes: 3,
+          truncated: false,
+          path: null,
+          nextStart: null,
+        },
+      }),
+      30_000
+    );
+    expect(out).toBe("Exit code: 1\nstdout:\nout\nstderr:\nerr");
+  });
+
+  test("appends bracket affordance after a truncated stream body", () => {
+    const out = formatResult(
+      makeResult({
+        stdout: {
+          text: "head…tail",
+          totalBytes: 99999,
+          truncated: true,
+          path: null,
+          nextStart: 1,
+        },
+      }),
+      30_000
+    );
+    const lines = out.split("\n");
+    expect(lines[0]).toBe("Exit code: 0");
+    expect(lines[1]).toBe("stdout:");
+    expect(lines[2]).toBe("head…tail");
+    expect(lines[3]?.startsWith("[bash tool: stdout showing first")).toBe(true);
+    expect(lines[3]?.endsWith("]")).toBe(true);
+  });
+
+  test("does not append affordance when stream is not truncated", () => {
+    const out = formatResult(
+      makeResult({
+        stdout: {
+          text: "ok",
+          totalBytes: 2,
+          truncated: false,
+          path: null,
+          nextStart: null,
+        },
+      }),
+      30_000
+    );
+    expect(out).not.toContain("[bash tool:");
+  });
+});
+
+describe("detailsOf", () => {
+  test("mirrors per-stream truncation and byte counts", () => {
+    const details = detailsOf(
+      makeResult({
+        exitCode: 1,
+        durationMs: 42,
+        stdout: {
+          text: "x",
+          totalBytes: 99999,
+          truncated: true,
+          path: null,
+          nextStart: 1,
+        },
+        stderr: {
+          text: "y",
+          totalBytes: 5,
+          truncated: false,
+          path: null,
+          nextStart: null,
+        },
+      })
+    );
+    expect(details).toEqual({
+      exitCode: 1,
+      signal: null,
+      durationMs: 42,
+      timedOut: false,
+      aborted: false,
+      stdout: { totalBytes: 99999, truncated: true, path: null },
+      stderr: { totalBytes: 5, truncated: false, path: null },
+    });
+  });
+});
+
+describe("isErrorResult", () => {
+  test("zero exit code is not an error", () => {
+    expect(isErrorResult(makeResult({ exitCode: 0 }))).toBe(false);
+  });
+  test("non-zero exit code is an error", () => {
+    expect(isErrorResult(makeResult({ exitCode: 1 }))).toBe(true);
+  });
+  test("null exit code is an error", () => {
+    expect(isErrorResult(makeResult({ exitCode: null }))).toBe(true);
+  });
+  test("aborted is an error", () => {
+    expect(isErrorResult(makeResult({ aborted: true }))).toBe(true);
+  });
+  test("timed out is an error", () => {
+    expect(isErrorResult(makeResult({ timedOut: true }))).toBe(true);
+  });
+});

package/src/extensions/bash/format.ts

@@ -0,0 +1,76 @@
+import {
+  type BashCommandResult,
+  type BashDetails,
+  type CapturedStream,
+  STREAM_HEAD_BYTES,
+  STREAM_TAIL_BYTES,
+} from "./schema";
+
+export function stripTrailingNewline(s: string): string {
+  return s.endsWith("\n") ? s.slice(0, -1) : s;
+}
+
+export function formatTruncationAffordance(
+  label: string,
+  s: CapturedStream
+): string {
+  const base = `[bash tool: ${label} showing first ${STREAM_HEAD_BYTES} bytes + last ${STREAM_TAIL_BYTES} bytes of ${s.totalBytes}`;
+  if (s.path) {
+    return `${base}; use read with path=${s.path} and start=${s.nextStart} for the rest.]`;
+  }
+  return `${base}; redirect to a file (e.g. \`cmd > /tmp/out.log\`) and use read for the full output.]`;
+}
+
+export function formatResult(
+  result: BashCommandResult,
+  timeoutMs: number
+): string {
+  const lines: string[] = [`Exit code: ${result.exitCode ?? "none"}`];
+  if (result.signal !== null) {
+    lines.push(`Signal: ${result.signal}`);
+  }
+  if (result.aborted) {
+    lines.push("Aborted.");
+  } else if (result.timedOut) {
+    lines.push(`Timed out after ${timeoutMs} ms.`);
+  }
+  if (result.stdout.totalBytes > 0) {
+    lines.push("stdout:");
+    lines.push(stripTrailingNewline(result.stdout.text));
+    if (result.stdout.truncated) {
+      lines.push(formatTruncationAffordance("stdout", result.stdout));
+    }
+  }
+  if (result.stderr.totalBytes > 0) {
+    lines.push("stderr:");
+    lines.push(stripTrailingNewline(result.stderr.text));
+    if (result.stderr.truncated) {
+      lines.push(formatTruncationAffordance("stderr", result.stderr));
+    }
+  }
+  return lines.join("\n");
+}
+
+export function isErrorResult(result: BashCommandResult): boolean {
+  return result.aborted || result.timedOut || result.exitCode !== 0;
+}
+
+export function detailsOf(result: BashCommandResult): BashDetails {
+  return {
+    exitCode: result.exitCode,
+    signal: result.signal,
+    durationMs: result.durationMs,
+    timedOut: result.timedOut,
+    aborted: result.aborted,
+    stdout: {
+      totalBytes: result.stdout.totalBytes,
+      truncated: result.stdout.truncated,
+      path: result.stdout.path,
+    },
+    stderr: {
+      totalBytes: result.stderr.totalBytes,
+      truncated: result.stderr.truncated,
+      path: result.stderr.path,
+    },
+  };
+}

package/src/extensions/bash/index.ts

@@ -0,0 +1,86 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Renderer } from "../../shared/Renderer";
+import { SpillCache } from "../../shared/SpillCache";
+import { Tools } from "../../shared/Tools";
+import { detailsOf, formatResult, isErrorResult } from "./format";
+import { killAllActiveBashGroups, runBashCommand } from "./run";
+import { type BashInput, bashSchema, DEFAULT_TIMEOUT_MS } from "./schema";
+
+const PREVIEW_LINES = 5;
+
+let lifecycleHandlersInstalled = false;
+
+function installLifecycleHandlers(): void {
+  if (lifecycleHandlersInstalled) {
+    return;
+  }
+  lifecycleHandlersInstalled = true;
+
+  // Sweep bash subtrees that escaped our process group (double-forked
+  // daemons via their own setsid) or that the parent harness is about to
+  // strand by signalling us. Re-raise the signal so the default handler
+  // still runs.
+  for (const sig of ["SIGTERM", "SIGINT", "SIGHUP"] as const) {
+    process.once(sig, () => {
+      try {
+        killAllActiveBashGroups(sig);
+      } catch {}
+      process.kill(process.pid, sig);
+    });
+  }
+}
+
+export default function (pi: ExtensionAPI): void {
+  SpillCache.installSweeper();
+  installLifecycleHandlers();
+  Tools.register(pi, {
+    name: "bash",
+    label: "bash",
+    description:
+      `Execute a bash command in the cwd. ` +
+      `Returns exit code, signal (if any), and stdout/stderr captured separately. ` +
+      `Prefer commands that emit only what you need; keep output as small as possible.`,
+    parameters: bashSchema,
+    renderShell: "self",
+    executionMode: "sequential",
+    async execute(_id, params, signal, _onUpdate, ctx) {
+      const { command, timeoutMs: requestedTimeoutMs } = params as BashInput;
+      const timeoutMs = requestedTimeoutMs ?? DEFAULT_TIMEOUT_MS;
+
+      if (signal?.aborted) {
+        throw new Error("Command aborted before execution.");
+      }
+
+      const result = await runBashCommand(command, timeoutMs, signal, ctx.cwd);
+      const text = formatResult(result, timeoutMs);
+      if (isErrorResult(result)) {
+        throw new Error(text);
+      }
+      return {
+        content: [{ type: "text", text }],
+        details: detailsOf(result),
+      };
+    },
+    renderCall(args, theme, context) {
+      const cmd =
+        typeof args?.command === "string" && args.command
+          ? args.command
+          : "...";
+      return Renderer.renderToolCallTitle({
+        label: "Bash",
+        title: cmd,
+        theme,
+        context,
+      });
+    },
+    renderResult(result, options, theme, context) {
+      return Renderer.renderBorderedResult({
+        result,
+        options,
+        theme,
+        context,
+        previewLines: PREVIEW_LINES,
+      });
+    },
+  });
+}