/**
 * Desktop notifications for the moments the user has to come back to the terminal: a held call the agent will ask
 * about, a confirm dialog waiting for an answer, a stopped runaway. The notifier is detected once per session with a
 * probe (never inside a tool_call handler); sending is fire-and-forget, and a failure is silent.
 */
export type NotifierName = "osascript" | "notify-send" | "dunstify" | "gdbus" | "kdialog" | "zenity" | "powershell" | "wsl-powershell";
export interface Notification {
    title: string;
    body: string;
}
export interface NotifierCommand {
    file: string;
    args: string[];
    /** Text travels in the environment where the shell needs no quoting (PowerShell). */
    env?: Record<string, string>;
}
interface Candidate {
    name: NotifierName;
    /** Probe: the command exists and answers. */
    probe: {
        file: string;
        args: readonly string[];
    };
}
/** Platform order: the native route first, then the desktop-agnostic tools, then the shells that reach another desktop (WSL). */
export declare function candidates(platform?: NodeJS.Platform): readonly Candidate[];
/** A user-configured argv: `{title}` and `{body}` in any argument are replaced; the text is also in PI_WARDEN_TITLE / PI_WARDEN_BODY. */
export type NotifierTarget = NotifierName | readonly string[];
/** The command that shows one notification with the given tool. Text goes as arguments or environment, never through a shell. */
export declare function notifierCommand(target: NotifierTarget, notification: Notification): NotifierCommand;
export type Runner = (file: string, args: readonly string[], options: {
    timeoutMs: number;
    env?: Record<string, string>;
}) => Promise<boolean>;
/** Runs a command detached from the terminal; resolves to whether it exited cleanly. Never throws. */
export declare const run: Runner;
/** First notifier whose probe answers on this machine, or undefined when the desktop cannot be reached. */
export declare function detectNotifier(platform?: NodeJS.Platform, runner?: Runner, timeoutMs?: number): Promise<NotifierName | undefined>;
/** Notifications truncate around a hundred characters; keep the reason first. */
export declare function clipBody(text: string, limit?: number): string;
export declare function sendNotification(target: NotifierTarget, notification: Notification, runner?: Runner, timeoutMs?: number): Promise<boolean>;
export {};