import type { SessionEvent } from "@opengeni/sdk";
import { type ClientOverride } from "../provider.js";
/**
 * Newest terminal output rows read when the terminal opens: one page, which
 * the server also bounds to 1 MB. xterm keeps 1,000 lines of scrollback, so
 * older pages would scroll straight out of it.
 */
export declare const SANDBOX_TERMINAL_HISTORY_ROWS = 1000;
/** Output rows the terminal keeps (history and live) for a rewrite. */
export declare const SANDBOX_TERMINAL_MAX_ROWS = 4000;
export type TerminalChunk = {
    /** Stable key (the source event id) so the xterm writer tracks a written-cursor. */
    id: string;
    /** Raw output bytes (utf-8 lossy) — written verbatim into xterm. */
    text: string;
    /** stdout vs stderr (drives optional tinting). */
    stream: "stdout" | "stderr";
    /** Global ordering: the source event sequence. */
    seq: number;
};
export type UseSandboxTerminalOptions = ClientOverride & {
    /** The live session event log (usually `useSessionEvents().events`). */
    events: SessionEvent[];
    /** Restrict to one PTY (by ptyId). Omit to interleave the agent firehose +
     *  every PTY. */
    ptyId?: string | undefined;
    /** Include the agent's command-output firehose (sandbox.command.output.delta).
     *  Default true — the read-only "terminal-as-events" the data path settled on. */
    includeAgentFirehose?: boolean | undefined;
    /**
     * OPEN an interactive PTY against the box so the user can type, not just watch.
     * When true (and the session is live) the hook calls `terminalPtyOpen` once,
     * tracks the returned ptyId, exposes `write` immediately (bound to that ptyId),
     * and closes the PTY on unmount. The PTY's banner + every output delta ride the
     * SSE spine (`terminal.pty.*`) back into `events`, so xterm fills in. Default
     * false — a caller that only wants the read-only firehose stays projection-only.
     */
    interactive?: boolean | undefined;
    /** Lease liveness ("cold" | "warm" | "draining"). The interactive PTY is only
     *  opened once the box is warm — opening on a cold box (ptyCapable is advertised
     *  cold too) races the box and leaves a dead read-only terminal. */
    liveness?: string | undefined;
    /**
     * Read this session's terminal history when true: the newest
     * {@link SANDBOX_TERMINAL_HISTORY_ROWS} PTY output rows (and agent command
     * output rows with `includeAgentFirehose`). Conversation reads carry none of
     * these rows, so this read restores the scrollback after a reload. Default
     * true; the dock enables it when its Terminal opens.
     */
    history?: boolean | undefined;
};
export type UseSandboxTerminalResult = {
    /** Ordered, deduped output chunks to write() into xterm.js. */
    chunks: TerminalChunk[];
    /** Whether a PTY is currently open (drives the prompt/cursor affordance). */
    running: boolean;
    /**
     * Interactive write fn when a PTY is open and the backend supports stdin
     * (`terminal.transport === "pty-ws"` / `PtyOpenResponse.supportsInput`). Null
     * in the read-only event-projection case (v1 default).
     */
    write: ((data: string) => void) | null;
    /** The active PTY id, if one is open. */
    activePtyId: string | null;
    /** Close the active PTY (no-op when none is open). */
    close: () => void;
    /** A PTY-open failure (interactive mode), if any. */
    error: Error | null;
};
/**
 * Project the Channel-A event log into an xterm-writable byte stream. The
 * terminal is "terminal-as-events": there is NO new socket in v1 — the agent's
 * command output (`sandbox.command.output.delta`) and any interactive PTY
 * (`terminal.pty.output.delta`) ride the existing SSE spine. When a PTY is open
 * and the backend accepts stdin, `write` pipes keystrokes via the SDK
 * `terminalPtyWrite` (the synchronous Channel-A control path).
 */
export declare function useSandboxTerminal(sessionId: string | null | undefined, options: UseSandboxTerminalOptions): UseSandboxTerminalResult;