import { type CodeToolCatalogEntry } from "./code-description";
export type { CodeToolCatalogEntry };
export interface CodeWaveCall {
    name: string;
    args: Record<string, unknown>;
}
export interface CodeToolResultInput {
    text?: string;
    raw?: unknown;
    isError?: boolean;
    notes?: string[];
    truncated?: boolean;
    anchored?: string;
    /** Numeric process exit status when the host reported one (bash-role tools).
     *  Carried privately over wave IPC; the sandbox exposes it only on
     *  codemode.exec results. */
    exitCode?: number;
}
export interface CodeDone {
    value?: string;
    error?: string;
    logs: string[];
    waves: number;
    calls: number;
}
export type CodeEvent = {
    kind: "wave";
    wave: number;
    calls: CodeWaveCall[];
} | {
    kind: "done";
    done: CodeDone;
};
export interface CodeSessionOptions {
    sandboxPath: string;
    toolNames: string[];
    files?: Record<string, string>;
    /** Client tool docs, so codemode.describe/search answer from real bytes. */
    catalog?: CodeToolCatalogEntry[];
}
export declare class CodeSession {
    private readonly opts;
    private child;
    private buf;
    private settled;
    private events;
    private waiter;
    private waiterTimer;
    private stderr;
    /** The wave sequence number the sandbox is currently parked on. */
    currentWave: number | null;
    /** tool_call ids emitted for the current wave, in call order. */
    pendingToolCallIds: string[];
    /** The composer `code` exec this session must answer on done. */
    composerToolCallId: string;
    lastAccessMs: number;
    /** In-band note appended to a successful result when a heal rewrote the script. */
    private resultNote;
    constructor(opts: CodeSessionOptions);
    /** Spawn the sandbox and post the run message. Events arrive via nextEvent(). */
    start(script: string): void;
    private formatDoneValue;
    private handleSandboxMessage;
    private consumeStdoutLine;
    private onStdout;
    private push;
    private pushDone;
    /** Await the next wave or done event. Bounded by a watchdog: a sandbox that
     *  stays silent past the timeout is killed and the awaiter receives a done
     *  error instead of parking forever. */
    nextEvent(timeoutMs?: number): Promise<CodeEvent>;
    /** Feed tool results for the parked wave back into the sandbox (call order).
     *  Returns false when the IPC write failed (dead child / closed stdin) so the
     *  caller can error the composer instead of stranding the resumed request. */
    deliverWaveResults(wave: number, results: CodeToolResultInput[]): boolean;
    abort(): void;
    private kill;
    private post;
}
export declare const CODE_TOOL_NAME = "code";
/**
 * Build the description for the single `code` tool advertised to composer.
 * Prefer passing full catalog entries (name + description + parameters) so
 * signatures are TS-shaped; a bare string[] of names still works.
 */
export declare function buildCodeToolDescription(tools: string[] | CodeToolCatalogEntry[]): string;
/** The JSON schema for the `code` tool arguments. */
export declare function codeToolParameters(): Record<string, unknown>;