import type { BashOperations } from "./bash.js";
/** Configuration for the OPT-IN OS sandbox applied to bash command execution. */
export interface SandboxConfig {
    /** Master switch. When false/undefined the sandbox seam is a pure no-op. */
    enabled?: boolean;
    /**
     * When true, the sandbox permits outbound network access. When false (the
     * default) all network traffic is denied at the OS level.
     */
    allowNetwork?: boolean;
    /**
     * Extra absolute paths the command is allowed to write to, in addition to the
     * working directory and the OS temp directory which are always writable.
     */
    writableRoots?: string[];
    /**
     * Override for the temp directory treated as writable. Defaults to the OS
     * temp directory. Exposed mainly so tests can pin a deterministic value.
     */
    tmpDir?: string;
}
/** A platform/availability probe result for the OS sandbox tooling. */
export interface SandboxAvailability {
    platform: "macos" | "linux" | "unsupported";
    /** The sandbox launcher binary for this platform, if one exists. */
    binary: "sandbox-exec" | "bwrap" | null;
    /** True only when the launcher binary is actually present on PATH. */
    binaryPresent: boolean;
    /** Human-readable explanation when the sandbox cannot be applied. */
    reason?: string;
}
/**
 * Build a Seatbelt profile string for `sandbox-exec -p`.
 *
 * Policy: deny by default, allow process exec + read everywhere, allow write
 * only under the resolved writable roots (cwd + tmp + extras), and deny network
 * unless `allowNetwork` is set. This is a PURE function — no I/O, no spawning —
 * so the generated text is unit-testable on any platform.
 */
export declare function buildSeatbeltProfile(config: SandboxConfig, cwd: string): string;
/**
 * Build the `sandbox-exec` argv that runs `command` under the generated
 * profile. PURE: returns the argv vector without spawning anything.
 *
 * Shape: `sandbox-exec -p <profile> /bin/sh -c <command>`.
 */
export declare function buildSeatbeltArgv(config: SandboxConfig, cwd: string, command: string): string[];
/**
 * Build the `bwrap` argv that runs `command` with the writable roots bind
 * mounted read-write over an otherwise read-only root. PURE: no spawning.
 *
 * Shape: `bwrap --ro-bind / / [--bind <root> <root> ...] [--unshare-net]
 *         --dev /dev --proc /proc /bin/sh -c <command>`.
 *
 * Network is denied by unsharing the network namespace unless `allowNetwork`.
 */
export declare function buildBwrapArgv(config: SandboxConfig, cwd: string, command: string): string[];
/**
 * Probe the current platform for OS-sandbox support. Never throws and never
 * spawns the sandbox itself — it only checks for the launcher binary so callers
 * can decide between sandboxed execution and an honest passthrough fallback.
 *
 * The optional `platform`/`probe` parameters are seams for unit tests so the
 * pure decision logic can be exercised without depending on the host OS.
 */
export declare function sandboxAvailability(platform?: NodeJS.Platform, probe?: (binary: string) => boolean): SandboxAvailability;
/**
 * Build the platform-appropriate sandbox argv for `command`, or `null` when no
 * sandbox can be applied. PURE with respect to the OS: callers pass an
 * availability result (or rely on the live probe) and get back either the
 * wrapped argv or `null`, never a spawn.
 */
export declare function buildSandboxArgv(config: SandboxConfig, cwd: string, command: string, availability?: SandboxAvailability): string[] | null;
/** Renders an argv vector into a single `sh -c`-safe command string. */
export declare function argvToCommandString(argv: string[]): string;
/** Optional reporting hook so callers can surface sandbox status honestly. */
export interface SandboxedOperationsOptions {
    /** Underlying backend that actually spawns. Defaults are supplied by bash.ts. */
    base: BashOperations;
    /** Availability probe override (mainly for tests). */
    availability?: SandboxAvailability;
    /**
     * Called once per exec with a human-readable note describing whether the
     * sandbox was applied or why it was skipped. Lets the caller record the
     * truth instead of the wrapper silently claiming sandboxing.
     */
    onNote?: (note: string) => void;
}
/**
 * Wrap a `BashOperations` backend so each command is executed inside the OS
 * sandbox when one is available. When the sandbox tool is missing or the
 * platform is unsupported, the command is passed through UNCHANGED and an
 * honest note is emitted via `onNote` — we never pretend a command was
 * sandboxed when it was not.
 *
 * When `config.enabled` is falsy this returns the base operations unchanged so
 * the seam is a guaranteed no-op for the default (off) path.
 */
export declare function createSandboxedBashOperations(config: SandboxConfig, options: SandboxedOperationsOptions): BashOperations;
