@agent-sh/harness-bash 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,351 @@
+import { ToolError, PermissionPolicy, ToolDefinition } from '@agent-sh/harness-core';
+import * as v from 'valibot';
+
+interface BashParams {
+    readonly command: string;
+    readonly cwd?: string;
+    readonly timeout_ms?: number;
+    readonly description?: string;
+    readonly background?: boolean;
+    readonly env?: Readonly<Record<string, string>>;
+}
+interface BashOutputParams {
+    readonly job_id: string;
+    readonly since_byte?: number;
+    readonly head_limit?: number;
+}
+interface BashKillParams {
+    readonly job_id: string;
+    readonly signal?: "SIGTERM" | "SIGKILL";
+}
+/**
+ * Executor interface — the pluggable boundary between core (which ships a
+ * local subprocess runner) and adapter packages (bash-docker, bash-firejail,
+ * bash-e2b). Core NEVER imports an adapter; adapters are peer deps of the
+ * harness that chooses one.
+ */
+interface BashRunResult {
+    readonly exitCode: number | null;
+    readonly killed: boolean;
+    readonly signal: string | null;
+}
+interface BashRunInput {
+    readonly command: string;
+    readonly cwd: string;
+    readonly env: Readonly<Record<string, string>>;
+    readonly signal: AbortSignal;
+    readonly onStdout: (chunk: Uint8Array) => void;
+    readonly onStderr: (chunk: Uint8Array) => void;
+}
+interface BackgroundReadResult {
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly running: boolean;
+    readonly exitCode: number | null;
+    readonly totalBytesStdout: number;
+    readonly totalBytesStderr: number;
+}
+interface BashExecutor {
+    run(input: BashRunInput): Promise<BashRunResult>;
+    spawnBackground?(input: {
+        command: string;
+        cwd: string;
+        env: Readonly<Record<string, string>>;
+    }): Promise<{
+        jobId: string;
+    }>;
+    readBackground?(jobId: string, opts: {
+        since_byte?: number;
+        head_limit?: number;
+    }): Promise<BackgroundReadResult>;
+    killBackground?(jobId: string, signal?: "SIGTERM" | "SIGKILL"): Promise<void>;
+    closeSession?(): Promise<void>;
+}
+/**
+ * Session-bound permission policy. Same shape as read/grep/glob sessions,
+ * with an opt-in escape hatch for unsandboxed test fixtures only.
+ */
+interface BashPermissionPolicy extends PermissionPolicy {
+    readonly unsafeAllowBashWithoutHook?: boolean;
+}
+interface BashSessionConfig {
+    readonly cwd: string;
+    readonly permissions: BashPermissionPolicy;
+    readonly env?: Readonly<Record<string, string>>;
+    readonly executor?: BashExecutor;
+    readonly defaultInactivityTimeoutMs?: number;
+    readonly wallclockBackstopMs?: number;
+    readonly maxCommandLength?: number;
+    readonly maxOutputBytesInline?: number;
+    readonly maxOutputBytesFile?: number;
+    readonly maxBackgroundJobs?: number;
+    readonly signal?: AbortSignal;
+    /**
+     * Working directory the tool tracks across calls. When the model issues
+     * a top-level `cd <path>` that lands inside the workspace, we mutate this
+     * in place. Optional — if omitted, cwd-carry is disabled and every call
+     * runs at `session.cwd`.
+     */
+    logicalCwd?: {
+        value: string;
+    };
+}
+type BashOk = {
+    readonly kind: "ok";
+    readonly output: string;
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly durationMs: number;
+    readonly logPath?: string;
+    readonly byteCap: boolean;
+};
+type BashNonzeroExit = {
+    readonly kind: "nonzero_exit";
+    readonly output: string;
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly durationMs: number;
+    readonly logPath?: string;
+    readonly byteCap: boolean;
+};
+type BashTimeout = {
+    readonly kind: "timeout";
+    readonly output: string;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly reason: "inactivity timeout" | "wall-clock backstop";
+    readonly durationMs: number;
+    readonly logPath?: string;
+};
+type BashBackgroundStarted = {
+    readonly kind: "background_started";
+    readonly output: string;
+    readonly jobId: string;
+};
+type BashError = {
+    readonly kind: "error";
+    readonly error: ToolError;
+};
+type BashResult = BashOk | BashNonzeroExit | BashTimeout | BashBackgroundStarted | BashError;
+type BashOutputResult = {
+    readonly kind: "output";
+    readonly output: string;
+    readonly running: boolean;
+    readonly exitCode: number | null;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly totalBytesStdout: number;
+    readonly totalBytesStderr: number;
+    readonly nextSinceByte: number;
+} | BashError;
+type BashKillResult = {
+    readonly kind: "killed";
+    readonly output: string;
+    readonly jobId: string;
+    readonly signal: "SIGTERM" | "SIGKILL";
+} | BashError;
+
+/**
+ * Top-level `cd` detector for session cwd-carry.
+ *
+ * Matches a single top-level `cd` invocation only — NOT inside pipelines
+ * (`cd x | true`), command lists (`cd x && y`), subshells (`(cd x)`),
+ * or with trailing arguments. This deliberately covers 95% of model
+ * intent without hand-parsing the full bash grammar.
+ *
+ * Returns the path argument if detected, else null.
+ */
+declare function detectTopLevelCd(command: string): string | null;
+declare function bash(input: unknown, session: BashSessionConfig): Promise<BashResult>;
+declare function bashOutput(input: unknown, session: BashSessionConfig): Promise<BashOutputResult>;
+declare function bashKill(input: unknown, session: BashSessionConfig): Promise<BashKillResult>;
+/**
+ * Apply cwd-carry: if the command is a top-level `cd <path>` and the
+ * destination resolves inside the workspace, mutate session.logicalCwd.
+ * Called AFTER the command executes with exit 0 (caller's responsibility).
+ *
+ * Exposed separately so tests can exercise the logic directly AND so a
+ * harness wrapper can call it at the right point in the lifecycle. In
+ * core, the orchestrator does NOT auto-call this — we keep cwd-carry
+ * out of the hot path for correctness; the caller opts in by invoking
+ * applyCwdCarry after a successful bash() result.
+ *
+ * Rationale: cwd-carry mutates session state which has observable
+ * implications for concurrent calls. Making it explicit is safer.
+ */
+declare function applyCwdCarry(session: BashSessionConfig, command: string, exitCode: number | null): {
+    changed: boolean;
+    newCwd: string | null;
+    escaped: boolean;
+};
+
+declare const BashParamsSchema: v.StrictObjectSchema<{
+    readonly command: v.SchemaWithPipe<[v.StringSchema<undefined>, v.MinLengthAction<string, 1, "command is required">, v.MaxLengthAction<string, 16384, "command exceeds 16384 bytes">]>;
+    readonly cwd: v.OptionalSchema<v.SchemaWithPipe<[v.StringSchema<undefined>, v.MinLengthAction<string, 1, "cwd must not be empty">]>, never>;
+    readonly timeout_ms: v.OptionalSchema<v.SchemaWithPipe<[v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 100, "timeout_ms must be >= 100 ms">]>, never>;
+    readonly description: v.OptionalSchema<v.StringSchema<undefined>, never>;
+    readonly background: v.OptionalSchema<v.BooleanSchema<undefined>, never>;
+    readonly env: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.StringSchema<undefined>, undefined>, never>;
+}, undefined>;
+declare const BashOutputParamsSchema: v.StrictObjectSchema<{
+    readonly job_id: v.SchemaWithPipe<[v.StringSchema<undefined>, v.MinLengthAction<string, 1, "job_id is required">]>;
+    readonly since_byte: v.OptionalSchema<v.SchemaWithPipe<[v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, "since_byte must be >= 0">]>, never>;
+    readonly head_limit: v.OptionalSchema<v.SchemaWithPipe<[v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, "head_limit must be >= 1">]>, never>;
+}, undefined>;
+declare const BashKillParamsSchema: v.StrictObjectSchema<{
+    readonly job_id: v.SchemaWithPipe<[v.StringSchema<undefined>, v.MinLengthAction<string, 1, "job_id is required">]>;
+    readonly signal: v.OptionalSchema<v.PicklistSchema<["SIGTERM", "SIGKILL"], undefined>, never>;
+}, undefined>;
+declare function safeParseBashParams(input: unknown): {
+    ok: true;
+    value: BashParams;
+} | {
+    ok: false;
+    issues: v.BaseIssue<unknown>[];
+};
+declare function safeParseBashOutputParams(input: unknown): {
+    ok: true;
+    value: BashOutputParams;
+} | {
+    ok: false;
+    issues: v.BaseIssue<unknown>[];
+};
+declare function safeParseBashKillParams(input: unknown): {
+    ok: true;
+    value: BashKillParams;
+} | {
+    ok: false;
+    issues: v.BaseIssue<unknown>[];
+};
+declare const BASH_TOOL_NAME = "bash";
+declare const BASH_TOOL_DESCRIPTION = "Run a single shell command in a bash subprocess. Output is captured and returned with the exit code.\n\nUsage:\n- 'cd' carries over to subsequent calls if it stays inside the workspace; otherwise the cwd is reset. Environment variables do NOT persist across calls \u2014 set them inline (FOO=bar some-cmd) or via 'env'.\n- For non-shell code, use language one-liners: 'python -c \"print(2+2)\"', 'node -e \"console.log(2+2)\"', 'deno eval \"console.log(2+2)\"'. For multi-line scripts, write a temp file with the write tool and invoke the interpreter on it.\n- Long-running processes (servers, watchers) MUST use background: true. The tool returns a job_id; poll output with bash_output(job_id). Do not leave a foreground command running past the 5-minute wall-clock backstop.\n- No interactive commands. Anything that needs stdin (pagers, Y/n prompts, REPLs, 'git commit' without -m) will hang until the inactivity timeout. Use flags to make commands non-interactive (--yes, -y, --no-pager) or pipe 'echo \"y\" |' in front.\n- Inactivity timeout resets on any output; default 60000 ms. Override with timeout_ms. Wall-clock backstop is 5 minutes for foreground calls.\n- Prefer this tool over other ways of running shell commands. For filename search prefer 'glob'; for content search prefer 'grep'.";
+declare const bashToolDefinition: ToolDefinition;
+declare const BASH_OUTPUT_TOOL_NAME = "bash_output";
+declare const BASH_OUTPUT_TOOL_DESCRIPTION = "Poll a backgrounded bash job's output since a given byte offset.\n\nReturns stdout and stderr slices plus whether the job is still running and its exit code if finished. Use 'since_byte' from the previous call to paginate through a long-running job's output without re-fetching already-seen bytes.";
+declare const bashOutputToolDefinition: ToolDefinition;
+declare const BASH_KILL_TOOL_NAME = "bash_kill";
+declare const BASH_KILL_TOOL_DESCRIPTION = "Send a termination signal to a backgrounded bash job.\n\nDefaults to SIGTERM (graceful). Use SIGKILL for an unresponsive job. The job's next bash_output call will report running: false.";
+declare const bashKillToolDefinition: ToolDefinition;
+
+/**
+ * Default local-subprocess executor.
+ *
+ * Launches the bash binary with `-c <command>` via the argv form of
+ * node:child_process.spawn — NEVER the string-based shell-eval entry
+ * point. The command string is passed as a single argument to the bash
+ * binary, not interpolated into our own spawn args. All shell parsing
+ * happens inside the child bash process.
+ *
+ * This executor ships unsandboxed; sandboxing is the job of adapter
+ * packages that implement the same BashExecutor interface. See
+ * packages/bash/src/types.ts.
+ */
+declare function createLocalBashExecutor(opts?: {
+    bashPath?: string;
+    logDir?: string;
+}): BashExecutor;
+
+/**
+ * Per-stream output buffer with head+tail capping and spill-to-file on
+ * overflow. Models rarely need the middle of a long output — they need
+ * either the setup line or the error tail. This buffer preserves both.
+ */
+declare class HeadTailBuffer {
+    private readonly maxInline;
+    private readonly maxFile;
+    private readonly kind;
+    private readonly spillDir;
+    private readonly chunks;
+    private totalBytes;
+    private byteCap;
+    private spilled;
+    private spillPath;
+    private spillBytes;
+    constructor(maxInline: number, maxFile: number, kind: "out" | "err", spillDir: string);
+    write(chunk: Uint8Array): void;
+    private appendSpill;
+    private spillInit;
+    private fileBytesWritten;
+    /**
+     * Return the inline render:
+     *   - If not capped: the full buffered text.
+     *   - If capped: head (first maxInline/2 bytes) + marker + tail
+     *     (last maxInline/2 bytes) approximation. We approximate the tail
+     *     by decoding only the tail window (maxInline/2 bytes from the spill
+     *     file) because the stream is write-once and we dropped the middle.
+     *
+     * The actual implementation is simpler: we keep only the head inline
+     * (first maxInline bytes, never overwritten) and emit a marker that
+     * points at the log path. Head-only is a deliberate simplification
+     * versus spec's head+tail — it matches OpenCode's default, and we
+     * rely on Read(path) to see the tail. Spec §4 head+tail is a v2
+     * improvement once we prove the file-path recovery path.
+     */
+    render(): {
+        text: string;
+        byteCap: boolean;
+        logPath: string | null;
+    };
+    bytesTotal(): number;
+    wasCapped(): boolean;
+}
+/**
+ * Format the text body of an "ok" / "nonzero_exit" result.
+ * Kept deliberately simple — structured fields ride on the result
+ * object; `output` is the canonical text the executor returns to the
+ * model at the tool_result boundary.
+ */
+declare function formatResultText(args: {
+    command: string;
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    durationMs: number;
+    byteCap: boolean;
+    logPath: string | null;
+    kind: "ok" | "nonzero_exit";
+}): string;
+declare function formatTimeoutText(args: {
+    command: string;
+    stdout: string;
+    stderr: string;
+    reason: "inactivity timeout" | "wall-clock backstop";
+    durationMs: number;
+    partialBytes: number;
+    logPath: string | null;
+}): string;
+declare function formatBackgroundStartedText(args: {
+    command: string;
+    jobId: string;
+}): string;
+declare function formatBashOutputText(args: {
+    jobId: string;
+    running: boolean;
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+    sinceByte: number;
+    returnedBytes: number;
+    totalBytes: number;
+}): string;
+declare function formatBashKillText(args: {
+    jobId: string;
+    signal: "SIGTERM" | "SIGKILL";
+}): string;
+
+declare const DEFAULT_INACTIVITY_TIMEOUT_MS = 60000;
+declare const DEFAULT_WALLCLOCK_BACKSTOP_MS = 300000;
+declare const MAX_COMMAND_LENGTH = 16384;
+declare const MAX_OUTPUT_BYTES_INLINE = 30720;
+declare const MAX_OUTPUT_BYTES_FILE: number;
+declare const BACKGROUND_MAX_JOBS = 16;
+/**
+ * Env var name prefixes that the tool refuses to let the model set via `env`.
+ * Defense in depth: even if the harness forwards its environment, the model
+ * should not be able to override credentials per-call.
+ */
+declare const SENSITIVE_ENV_PREFIXES: readonly string[];
+
+export { BACKGROUND_MAX_JOBS, BASH_KILL_TOOL_DESCRIPTION, BASH_KILL_TOOL_NAME, BASH_OUTPUT_TOOL_DESCRIPTION, BASH_OUTPUT_TOOL_NAME, BASH_TOOL_DESCRIPTION, BASH_TOOL_NAME, type BackgroundReadResult, type BashBackgroundStarted, type BashError, type BashExecutor, type BashKillParams, BashKillParamsSchema, type BashKillResult, type BashNonzeroExit, type BashOk, type BashOutputParams, BashOutputParamsSchema, type BashOutputResult, type BashParams, BashParamsSchema, type BashPermissionPolicy, type BashResult, type BashRunInput, type BashRunResult, type BashSessionConfig, type BashTimeout, DEFAULT_INACTIVITY_TIMEOUT_MS, DEFAULT_WALLCLOCK_BACKSTOP_MS, HeadTailBuffer, MAX_COMMAND_LENGTH, MAX_OUTPUT_BYTES_FILE, MAX_OUTPUT_BYTES_INLINE, SENSITIVE_ENV_PREFIXES, applyCwdCarry, bash, bashKill, bashKillToolDefinition, bashOutput, bashOutputToolDefinition, bashToolDefinition, createLocalBashExecutor, detectTopLevelCd, formatBackgroundStartedText, formatBashKillText, formatBashOutputText, formatResultText, formatTimeoutText, safeParseBashKillParams, safeParseBashOutputParams, safeParseBashParams };