import type { Command, Host, RunOptions } from "../host/host.js";
/**
 * The stdlib's ways of running a program through `host.subprocess`. The
 * host reports how a child ended; the functions here decide what each
 * ending means, so every caller gets the same contract: a child killed
 * because the run's abort signal fired rejects with
 * `AgencyCancelledError`, which `__tryCall` re-throws.
 */
export type SpawnResult = {
    stdout: string;
    stderr: string;
    exitCode: number;
};
export type AbortableSpawnOptions = {
    cwd?: string;
    env?: Record<string, string>;
    input?: string;
    /** Time limit in ms. 0 or undefined = no time limit. */
    timeout?: number;
    /** When set, an abort fires the same teardown path as the timeout
     *  and the returned promise rejects with `AgencyCancelledError`. */
    signal?: AbortSignal;
    /** Max bytes to buffer per output stream, in UTF-8 bytes. Once stdout
     *  exceeds it the child is killed, stdout is marked truncated (a note
     *  is appended), and the call resolves successfully with the partial
     *  output; once stderr exceeds it the call resolves with exit code 1
     *  and a note in stderr. 0/undefined = unbounded. Keeps auto-approved
     *  reads (e.g. a huge `git diff`) from buffering unbounded memory. */
    maxOutputBytes?: number;
};
/** `command` as the host takes it: a program with its arguments. */
export declare function program(name: string, args: string[]): Command;
/**
 * Run `command` with `args` and collect its output. A timeout resolves
 * with exit code 1 and a note in stderr; the byte cap on stdout resolves
 * with the partial output and a note in stdout, and on stderr with exit
 * code 1 and a note; an abort rejects with `AgencyCancelledError`.
 */
export declare function abortableSpawn(host: Host, command: string, args: string[], options: AbortableSpawnOptions): Promise<SpawnResult>;
/** `abortableSpawn` for a script bash runs. */
export declare function abortableShell(host: Host, script: string, options: AbortableSpawnOptions): Promise<SpawnResult>;
/**
 * Run a child whose output is not wanted, with the same abort-on-signal
 * behavior. Used for `_say` (the `say` command), `_screenshot`, `_openUrl`,
 * etc. — anything where we just want to wait for the child to exit,
 * getting an `AgencyCancelledError` if the run is cancelled.
 *
 * Distinct from `abortableSpawn` so callers that don't want stdout
 * piping (some of these run for minutes streaming audio to the
 * speakers and would buffer indefinitely) get the right behavior. A
 * non-zero exit, or a signal nobody here sent, rejects with the
 * child's standard error in the message.
 */
export declare function abortableExec(host: Host, command: string, args: string[], signal: AbortSignal | undefined): Promise<void>;
/** The failure `runProgram` rejects with for a child that did not exit
 *  with 0, wrote past the output limit, ran past its time limit, or was
 *  cancelled, carrying its output the way Node's `execFile` does.
 *  `ending` says which. */
export declare class ProgramFailed extends Error {
    readonly exitCode: number | null;
    readonly stdout: string;
    readonly stderr: string;
    constructor(command: string, ending: string, exitCode: number | null, stdout: string, stderr: string);
}
/** How much of each output stream `runProgram` keeps unless the caller
 *  says otherwise: the default `maxBuffer` of Node's `execFile`. */
export declare const PROGRAM_OUTPUT_LIMIT: number;
/**
 * Run `command` with `args` and return its output, rejecting with
 * `ProgramFailed` when it does not exit with 0, writes more than the
 * output limit to one stream, runs past `timeoutMs`, or is cancelled by
 * `signal`, and with the host's error when it cannot be started. The
 * contract of Node's `execFile`, for the helpers that call a fixed
 * program such as `osascript` or `security`.
 */
export declare function runProgram(host: Host, command: string, args: string[], options?: RunOptions): Promise<{
    stdout: string;
    stderr: string;
}>;
/**
 * Sleep that wakes up early on abort. The default `setTimeout`-based
 * sleep ignores cancellation entirely; a 10-minute `sleep(10m)` after
 * Ctrl-C would just sit there for ten minutes. Translates to
 * `AgencyCancelledError` so `__tryCall` re-throws it.
 */
export declare function abortableSleep(ms: number, signal: AbortSignal | undefined): Promise<void>;