pim-agent 0.0.1 → 0.9.0

package/packages/core/src/extensions/bash/capture.ts

@@ -0,0 +1,86 @@
+import { Lines } from "../../shared/Lines";
+import {
+  type CapturedStream,
+  STREAM_HEAD_BYTES,
+  STREAM_TAIL_BYTES,
+} from "./schema";
+
+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;
+  }
+
+  /** The first `n` bytes, read across however many chunks the kernel split them into. */
+  lead(n: number): Uint8Array {
+    if (this.fullBytes) {
+      return this.fullBytes.subarray(0, n);
+    }
+    const lead = new Uint8Array(Math.min(n, this.totalBytesAccum));
+    let at = 0;
+    for (const chunk of this.chunks) {
+      if (at === lead.byteLength) {
+        break;
+      }
+      const take = chunk.subarray(0, lead.byteLength - at);
+      lead.set(take, at);
+      at += take.byteLength;
+    }
+    return lead;
+  }
+
+  full(): Uint8Array {
+    if (!this.fullBytes) {
+      this.fullBytes = Buffer.concat(this.chunks, this.totalBytesAccum);
+      this.chunks = [];
+    }
+    return this.fullBytes;
+  }
+
+  /** Opaque bytes are not text: a half-image is worthless, so they are neither cut nor decoded. */
+  snapshot(opaque = false): CapturedStream {
+    if (this.totalBytesAccum === 0 || opaque) {
+      return {
+        text: "",
+        totalBytes: this.totalBytesAccum,
+        truncated: false,
+        path: null,
+        nextStart: null,
+      };
+    }
+    const dec = new TextDecoder();
+    const all = this.full();
+    if (this.totalBytesAccum <= STREAM_HEAD_BYTES + STREAM_TAIL_BYTES) {
+      return {
+        text: dec.decode(all),
+        totalBytes: this.totalBytesAccum,
+        truncated: false,
+        path: null,
+        nextStart: null,
+      };
+    }
+    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/packages/core/src/extensions/bash/format.ts

@@ -0,0 +1,110 @@
+import { Format } from "../../shared/Format";
+import { type ImageMimeType, Images } from "../../shared/Images";
+import {
+  type BashCommandResult,
+  type BashDetails,
+  type CapturedStream,
+  STREAM_HEAD_BYTES,
+  STREAM_TAIL_BYTES,
+} from "./schema";
+
+const STREAMS = ["stdout", "stderr"] as const;
+
+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.`);
+  }
+  for (const label of STREAMS) {
+    const stream = result[label];
+    if (stream.totalBytes === 0) {
+      continue;
+    }
+    if (label === "stdout" && result.stdoutSniffed !== null) {
+      const line = unshownImageLine(
+        result,
+        result.stdoutSniffed,
+        stream.totalBytes
+      );
+      if (line !== null) {
+        lines.push(line);
+      }
+      continue;
+    }
+    lines.push(`${label}:`);
+    lines.push(stripTrailingNewline(stream.text));
+    if (stream.truncated) {
+      lines.push(formatTruncationAffordance(label, stream));
+    }
+  }
+  return lines.join("\n");
+}
+
+/** The words for a picture the content array will not carry; null when it will. */
+function unshownImageLine(
+  result: BashCommandResult,
+  sniffed: ImageMimeType,
+  totalBytes: number
+): string | null {
+  const subject = `stdout is ${Format.bytes(totalBytes)} of ${Images.extensionOf(sniffed)} data`;
+  if (isErrorResult(result)) {
+    return `[bash tool: ${subject}, not shown because the command failed.]`;
+  }
+  if (result.stdoutImage === null) {
+    return `[bash tool: ${subject} that could not be decoded as an image.]`;
+  }
+  return null;
+}
+
+export function isErrorResult(
+  result: Pick<BashCommandResult, "exitCode" | "timedOut" | "aborted">
+): 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: streamDetails(result.stdout),
+    stderr: streamDetails(result.stderr),
+    image:
+      result.stdoutImage === null
+        ? undefined
+        : Images.detailsOf(result.stdoutImage),
+  };
+}
+
+function streamDetails(stream: CapturedStream): BashDetails["stdout"] {
+  return {
+    totalBytes: stream.totalBytes,
+    truncated: stream.truncated,
+    path: stream.path,
+  };
+}

package/packages/core/src/extensions/bash/image.ts

@@ -0,0 +1,31 @@
+import { Format } from "../../shared/Format";
+import { Images, type NormalisedImage } from "../../shared/Images";
+
+/**
+ * The picture stdout printed, once a provider will take it. Bytes that sniffed
+ * as an image but cannot be decoded are not an error here: the command ran, and
+ * bash reports what it printed.
+ */
+export async function normaliseStdoutImage(
+  bytes: Uint8Array
+): Promise<NormalisedImage | null> {
+  try {
+    return await Images.normalise(bytes, "stdout");
+  } catch {
+    return null;
+  }
+}
+
+/** `stdout is a 1200x800 png (240 KB)`, the subject every note about the picture shares. */
+export function imageSubject(image: NormalisedImage): string {
+  return `stdout is a ${image.width}x${image.height} ${Images.extensionOf(image.mimeType)} (${Format.bytes(image.bytes)})`;
+}
+
+/** What the model is told next to the picture, or instead of it when it has no eyes. */
+export function imageNote(image: NormalisedImage, vision: boolean): string {
+  if (!vision) {
+    return Images.noVisionNote("bash", imageSubject(image));
+  }
+  const note = Images.noteOf(image);
+  return `[bash tool: ${imageSubject(image)}, shown as an image.${note ? ` ${note}` : ""}]`;
+}

package/packages/core/src/extensions/bash/index.ts

@@ -0,0 +1,88 @@
+import type {
+  AgentToolResult,
+  ExtensionAPI,
+} from "@earendil-works/pi-coding-agent";
+import { Images } from "../../shared/Images";
+import { SpillCache } from "../../shared/SpillCache";
+import { Tools } from "../../shared/Tools";
+import { detailsOf, formatResult, isErrorResult } from "./format";
+import { imageNote } from "./image";
+import { bashView } from "./render";
+import { killAllActiveBashGroups, runBashCommand } from "./run";
+import {
+  type BashDetails,
+  type BashInput,
+  bashSchema,
+  DEFAULT_TIMEOUT_MS,
+} from "./schema";
+
+let lifecycleHandlersInstalled = false;
+
+function installLifecycleHandlers(): void {
+  if (lifecycleHandlersInstalled) {
+    return;
+  }
+  lifecycleHandlersInstalled = true;
+
+  // Sweep escaped bash subtrees, then re-raise 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<typeof bashSchema, BashDetails>(pi, {
+    name: "bash",
+    label: "bash",
+    description:
+      "Execute a bash command in the cwd. " +
+      "Returns exit code, signal (if any), and stdout/stderr captured separately. " +
+      "Stdout that is a png/jpeg/gif/webp is returned as a picture. " +
+      "Prefer commands that emit only what you need; keep output as small as possible.",
+    parameters: bashSchema,
+    renderShell: "self",
+    effect: { kind: "unbounded" },
+    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);
+      }
+
+      const content: AgentToolResult<BashDetails>["content"] = [
+        { type: "text", text },
+      ];
+      const image = result.stdoutImage;
+      if (image !== null) {
+        const vision = Images.canSee(ctx.model);
+        const note = imageNote(image, vision);
+        content.push(
+          ...(vision
+            ? Images.contentOf(image, note)
+            : [{ type: "text" as const, text: note }])
+        );
+      }
+
+      return {
+        content,
+        details: detailsOf(result),
+      };
+    },
+    toViewModel: bashView,
+  });
+}

package/packages/core/src/extensions/bash/render.ts

@@ -0,0 +1,31 @@
+import { Renderer } from "../../shared/Renderer";
+import type { ToolViewInput } from "../../shared/Tools";
+import { Painting } from "../../view/Painting";
+import type { ToolView } from "../../view/ViewBlock";
+import type { BashDetails, bashSchema } from "./schema";
+
+type BashViewInput = ToolViewInput<typeof bashSchema, BashDetails>;
+
+export function bashView({ args, result }: BashViewInput): ToolView {
+  const command = commandTitle(args?.command);
+  const image = result?.details?.image;
+  return {
+    label: "Bash",
+    icon: "terminal",
+    // `spans`, not `text`: a `text` title is split on newlines and rejoined with spaces.
+    title: [
+      {
+        kind: "spans",
+        spans: [{ text: command, code: true }],
+      },
+    ],
+    body: [
+      ...(image ? Painting.imageBlocks(image, command) : []),
+      { kind: "text", text: Renderer.firstText(result) },
+    ],
+  };
+}
+
+function commandTitle(command: unknown): string {
+  return typeof command === "string" && command !== "" ? command : "...";
+}

package/packages/core/src/extensions/bash/run.ts

@@ -0,0 +1,221 @@
+import { type ImageMimeType, Images } from "../../shared/Images";
+import { SpillCache } from "../../shared/SpillCache";
+import { StreamCapture } from "./capture";
+import { isErrorResult } from "./format";
+import { normaliseStdoutImage } from "./image";
+import {
+  type BashCommandResult,
+  type CapturedStream,
+  DRAIN_GRACE_MS,
+  KILL_GRACE_MS,
+} from "./schema";
+
+type Reader = ReadableStreamDefaultReader<Uint8Array>;
+
+const activePids = new Set<number>();
+
+export function killAllActiveBashGroups(sig: NodeJS.Signals = "SIGTERM"): void {
+  for (const pid of activePids) {
+    killGroup(pid, sig);
+  }
+  activePids.clear();
+}
+
+async function drain(reader: Reader | null, cap: StreamCapture): Promise<void> {
+  if (!reader) {
+    return;
+  }
+  try {
+    while (true) {
+      const { value, done } = await reader.read();
+      if (done) {
+        break;
+      }
+      if (value) {
+        cap.push(value);
+      }
+    }
+  } catch {
+  } finally {
+    try {
+      reader.releaseLock();
+    } catch {}
+  }
+}
+
+async function spillIfTruncated(
+  stream: CapturedStream,
+  cap: StreamCapture,
+  ext: "out" | "err"
+): Promise<string | null> {
+  return stream.truncated ? SpillCache.write("bash", ext, cap.full()) : null;
+}
+
+/**
+ * The picture stdout printed, or null. The verdict is the leading bytes',
+ * before anything is decoded; the cap is the whole stream's, so an image too
+ * big to send is text again and truncates like any other output.
+ */
+export function sniffStdoutImage(cap: StreamCapture): ImageMimeType | null {
+  if (
+    cap.totalBytes < Images.SNIFF_BYTES ||
+    cap.totalBytes > Images.MAX_SOURCE_BYTES
+  ) {
+    return null;
+  }
+  return Images.sniff(cap.lead(Images.SNIFF_BYTES));
+}
+
+function killGroup(pid: number | undefined, sig: NodeJS.Signals): void {
+  if (pid === undefined) {
+    return;
+  }
+  try {
+    process.kill(-pid, sig);
+  } catch {
+    try {
+      process.kill(pid, sig);
+    } catch {}
+  }
+}
+
+function getReader(
+  stream: ReadableStream<Uint8Array> | undefined
+): Reader | null {
+  return stream ? stream.getReader() : null;
+}
+
+export async function runBashCommand(
+  command: string,
+  timeoutMs: number,
+  signal: AbortSignal | undefined,
+  cwd: string
+): Promise<BashCommandResult> {
+  const startedAt = Date.now();
+  const stdoutCap = new StreamCapture();
+  const stderrCap = new StreamCapture();
+
+  // setsid gives the tree its own process group (pgid == proc.pid) so the whole tree can be signalled.
+  const proc = Bun.spawn({
+    cmd: ["setsid", "bash", "-lc", command],
+    cwd,
+    stdout: "pipe",
+    stderr: "pipe",
+    env: { ...process.env },
+  });
+  if (proc.pid !== undefined) {
+    activePids.add(proc.pid);
+  }
+
+  let timedOut = false;
+  let aborted = false;
+
+  // Hold the readers: cancelling a locked stream through the stream itself throws.
+  const stdoutReader = getReader(
+    proc.stdout as unknown as ReadableStream<Uint8Array>
+  );
+  const stderrReader = getReader(
+    proc.stderr as unknown as ReadableStream<Uint8Array>
+  );
+
+  // Never block on EOF: a backgrounded child can hold the pipes open after bash exits.
+  const stdoutDrain = drain(stdoutReader, stdoutCap);
+  const stderrDrain = drain(stderrReader, stderrCap);
+
+  let timeoutHandle: ReturnType<typeof setTimeout> | null = null;
+  const exitedPromise = proc.exited.then(() => "exited" as const);
+  const timeoutPromise = new Promise<"timeout">((resolve) => {
+    timeoutHandle = setTimeout(() => resolve("timeout"), timeoutMs);
+  });
+
+  const abort = Promise.withResolvers<"aborted">();
+  const onAbort = () => {
+    aborted = true;
+    abort.resolve("aborted");
+  };
+  if (signal) {
+    if (signal.aborted) {
+      onAbort();
+    } else {
+      signal.addEventListener("abort", onAbort, { once: true });
+    }
+  }
+
+  let exitCode: number | null = null;
+  let signalCode: NodeJS.Signals | null = null;
+  try {
+    const result = await Promise.race([
+      exitedPromise,
+      timeoutPromise,
+      abort.promise,
+    ]);
+
+    if (result === "timeout") {
+      timedOut = true;
+    }
+
+    if (result !== "exited") {
+      killGroup(proc.pid, "SIGTERM");
+      const sigkillTimer = setTimeout(() => {
+        killGroup(proc.pid, "SIGKILL");
+      }, KILL_GRACE_MS);
+      try {
+        await proc.exited;
+      } finally {
+        clearTimeout(sigkillTimer);
+      }
+    }
+
+    exitCode = proc.exitCode ?? null;
+    signalCode = (proc.signalCode as NodeJS.Signals | null | undefined) ?? null;
+
+    // Bound the drain: a detached grandchild holding the pipe would outlive this call.
+    await Promise.race([
+      Promise.all([stdoutDrain, stderrDrain]),
+      Bun.sleep(DRAIN_GRACE_MS),
+    ]);
+  } finally {
+    if (timeoutHandle) {
+      clearTimeout(timeoutHandle);
+    }
+    if (signal) {
+      signal.removeEventListener("abort", onAbort);
+    }
+    for (const reader of [stdoutReader, stderrReader]) {
+      if (!reader) {
+        continue;
+      }
+      try {
+        void reader.cancel().catch(() => {});
+      } catch {}
+    }
+    if (proc.pid !== undefined) {
+      activePids.delete(proc.pid);
+    }
+  }
+
+  // A picture nothing will show is never decoded: a failed command reports its bytes instead.
+  const sniffed = sniffStdoutImage(stdoutCap);
+  const shows =
+    sniffed !== null && !isErrorResult({ exitCode, timedOut, aborted });
+  const stdout = stdoutCap.snapshot(sniffed !== null);
+  const stderr = stderrCap.snapshot();
+
+  const [stdoutPath, stderrPath, stdoutImage] = await Promise.all([
+    spillIfTruncated(stdout, stdoutCap, "out"),
+    spillIfTruncated(stderr, stderrCap, "err"),
+    shows ? normaliseStdoutImage(stdoutCap.full()) : null,
+  ]);
+
+  return {
+    exitCode,
+    signal: signalCode,
+    stdout: { ...stdout, path: stdoutPath },
+    stderr: { ...stderr, path: stderrPath },
+    stdoutSniffed: sniffed,
+    stdoutImage,
+    timedOut,
+    aborted,
+    durationMs: Date.now() - startedAt,
+  };
+}

package/packages/core/src/extensions/bash/schema.ts

@@ -0,0 +1,64 @@
+import { type Static, Type } from "typebox";
+import type {
+  ImageDetails,
+  ImageMimeType,
+  NormalisedImage,
+} from "../../shared/Images";
+
+export const STREAM_HEAD_BYTES = 8192;
+export const STREAM_TAIL_BYTES = 8192;
+export const DEFAULT_TIMEOUT_MS = 30_000;
+export const KILL_GRACE_MS = 2000;
+export const DRAIN_GRACE_MS = 1000;
+
+export const bashSchema = Type.Object({
+  command: Type.String({
+    description: "Runs via bash -lc, so login shell init applies.",
+  }),
+  timeoutMs: Type.Optional(
+    Type.Integer({
+      minimum: 1,
+      description: `Timeout in milliseconds. Default is ${DEFAULT_TIMEOUT_MS} (${DEFAULT_TIMEOUT_MS / 1000}s) — raise it for long-running commands like builds, test suites, training runs, or installs.`,
+    })
+  ),
+});
+export type BashInput = Static<typeof bashSchema>;
+
+export type CapturedStream = {
+  readonly text: string;
+  readonly totalBytes: number;
+  readonly truncated: boolean;
+  readonly path: string | null;
+  readonly nextStart: number | null;
+};
+
+export type BashCommandResult = {
+  readonly exitCode: number | null;
+  readonly signal: NodeJS.Signals | null;
+  readonly stdout: CapturedStream;
+  readonly stderr: CapturedStream;
+  /** What stdout's leading bytes sniffed as, whether or not the picture could then be decoded. */
+  readonly stdoutSniffed: ImageMimeType | null;
+  /** Set only when stdout sniffed as a picture and a provider will take it. */
+  readonly stdoutImage: NormalisedImage | null;
+  readonly timedOut: boolean;
+  readonly aborted: boolean;
+  readonly durationMs: number;
+};
+
+export type BashStreamDetails = {
+  readonly totalBytes: number;
+  readonly truncated: boolean;
+  readonly path: string | null;
+};
+
+export type BashDetails = {
+  readonly exitCode: number | null;
+  readonly signal: NodeJS.Signals | null;
+  readonly durationMs: number;
+  readonly timedOut: boolean;
+  readonly aborted: boolean;
+  readonly stdout: BashStreamDetails;
+  readonly stderr: BashStreamDetails;
+  readonly image?: ImageDetails;
+};