Bash reference

type ShellResult = ShellReport & { readonly content: readonly ContentPart[] };

type ShellReport = ShellRunReport | ShellFailure;

interface ShellRunReport {
  tool: "bash";
  status: "ok" | "failed" | "timeout";
  request: BashRequest;
  run: ShellRun;
  output: ShellOutput;
  notes: readonly Note[];
}

interface ShellFailure {
  tool: "bash";
  status: "error";
  error: ShellError; // { code, phase, message, data? }
  request: BashRequest | null; // null only for INVALID_INPUT
  run: ShellRun | null; // set only when the command started
  output: ShellOutput | null; // set only when the command started
  notes: readonly Note[];
}

import { createBashTool, shellEnv, textOf } from "@better-fs-tools/shell";
import type { CommandRunner, OutputChunk } from "@better-fs-tools/shell";

// A runner that runs nothing. It prints the command and exits with code 0.
const echoRunner: CommandRunner = {
  id: "echo",
  cwd: "/work",
  run: (request) => {
    async function* output(): AsyncIterable<OutputChunk> {
      yield { stream: "stdout", bytes: new TextEncoder().encode(`${request.command}\n`) };
    }
    return { output: output(), exit: Promise.resolve({ code: 0, signal: null }) };
  },
};

const bash = createBashTool({ runner: echoRunner, env: shellEnv() });
const result = await bash({ command: "ls -la", timeoutMs: 900_000 });

if (result.status === "error") {
  console.log(result.error.code, result.error.phase);
} else {
  console.log(result.request); // { command: "ls -la", timeoutMs: 600000, cwd: null }
  console.log(result.run.exitCode, result.run.cwd); // 0 /work
  console.log(result.output.head); // "ls -la\n"
}
console.log(result.notes.map((note) => note.code)); // ["clamped"]
console.log(textOf(result));

Exit code 0 · 0 s
ls -la

[bash:clamped] The requested timeout of 15 min is over the maximum, so 10 min was used.

interface BashRequest {
  command: string;
  timeoutMs: number;
  cwd: string | null;
}

interface ShellRun {
  command: string; // as run, after every beforeRun rewrite
  cwd: string; // absolute
  timeoutMs: number;
  exitCode: number | null; // null when a signal ended it, or the exit was not confirmed
  signal: string | null;
  durationMs: number;
  stoppedBy: "timeout" | "abort" | "output-cap" | null; // null when it ended by itself
  unconfirmedStop: boolean; // the runner did not settle its exit in the grace time
}

interface ShellOutput {
  head: string; // all of the output when omittedBytes is 0
  tail: string | null; // null when nothing was cut
  totalBytes: number;
  totalLines: number;
  omittedBytes: number;
  omittedLines: number;
  stdoutBytes: number;
  stderrBytes: number;
  spill: string | null; // the reference from the spill sink. null with no sink, or when the sink failed
}

interface Note {
  code: string;
  severity: "info" | "warning";
  message: string;
  data?: JsonObject;
}

interface CommandRunner {
  readonly id: string; // shown in the tool description, for example "node"
  readonly cwd: string; // the default folder. The tool resolves the cwd input against it
  run(request: RunRequest): RunHandle; // must not throw
}

interface RunRequest {
  readonly command: string;
  readonly cwd: string; // absolute and resolved. The runner checks that it is a folder
  readonly env: Readonly<Record<string, string>>; // the whole environment. The runner adds nothing
  readonly signal: AbortSignal; // aborted on a timeout, an abort of the caller, and the capture cap
  readonly killGraceMs: number; // time after the stop signal before SIGKILL
}

interface RunHandle {
  readonly output: AsyncIterable<OutputChunk>; // stdout and stderr chunks in arrival order
  readonly exit: Promise<RunExit>; // settles when the process ends. Never rejects
}

interface OutputChunk {
  readonly stream: "stdout" | "stderr";
  readonly bytes: Uint8Array;
}

interface RunExit {
  readonly code: number | null; // null when a signal ended the process, or the start failed
  readonly signal: string | null; // for example "SIGKILL". null for a normal exit
  readonly error?: RunStartError; // set when the command did not start
}

interface RunStartError {
  readonly reason: "cwd-not-found" | "cwd-not-a-directory" | "spawn-failed";
  readonly detail?: string; // a detail for the note. It must not hold secrets
}

import {
  defaultShellEnv,
  formatBytes,
  formatDuration,
  parseBashInput,
  resolveShellLimits,
  resolveShellMessages,
} from "@better-fs-tools/shell";

const limits = resolveShellLimits({ maxTimeoutMs: 60_000 });
console.log(limits.defaultTimeoutMs); // 60000: the default is lowered to the new ceiling

console.log(parseBashInput({ command: "ls", timeoutMs: 90_000.5 }, limits));
// { command: "ls", timeoutMs: 60000, cwd: null }

try {
  parseBashInput({ command: "ls", timeout: 5 }, limits);
} catch (error) {
  console.log((error as TypeError).message); // "unknown key timeout. Expected command, timeoutMs, cwd"
}

const messages = resolveShellMessages({ noOutput: () => "(empty)" });
console.log(messages.noOutput()); // "(empty)"

console.log(formatDuration(400), formatDuration(150_000)); // "0.4 s" "2 min 30 s"
console.log(formatBytes(1_800_000)); // "1.8 MB"
console.log(defaultShellEnv);