import { BaseKernel, type KernelExecuteOptions, type KernelExecuteResult, type KernelStartOptions } from "../kernel-base.js";
import { type BackendProbeOptions } from "../probe.js";
import type { ShadowPlan } from "../speculation/types.js";
import { type PythonRuntime } from "./runtime.js";
import type { PythonToolRequest } from "./executor.js";
export type { KernelExecuteOptions, KernelExecuteResult, KernelRuntimeEnv, KernelShutdownOptions, KernelShutdownResult, } from "../kernel-base.js";
/** Bounds interrupt escalation plus the three shutdown grace windows before ACP abandons a session. */
export declare const PYTHON_KERNEL_CANCEL_BUDGET_MS: number;
export interface PythonKernelAvailability {
    ok: boolean;
    pythonPath?: string;
    reason?: string;
    /** The probed-working runtime, when one was found. */
    runtime?: PythonRuntime;
    /** Cancellation or an exhausted probe budget does not establish runtime unavailability. */
    transient?: boolean;
}
export interface PythonPreludeSource {
    name: string;
    exports: string[];
    source: string;
}
export interface PythonShadowSnapshot {
    revision: number;
    values: Readonly<Record<string, unknown>>;
    digest: string;
}
export interface PythonShadowPlan extends ShadowPlan {
    snapshot: PythonShadowSnapshot;
}
interface PythonKernelExecuteOptions extends KernelExecuteOptions {
    expectedShadowRevision?: number;
    expectedShadowDigest?: string;
}
/** Read the last definitive probe without spawning or awaiting interpreter discovery. */
export declare function getCachedPythonKernelAvailability(cwd: string, interpreter?: string): PythonKernelAvailability | undefined;
export declare function checkPythonKernelAvailability(cwd: string, interpreter?: string, options?: {
    forceProbe?: boolean;
} & BackendProbeOptions): Promise<PythonKernelAvailability>;
export declare class PythonKernel extends BaseKernel<PythonKernelExecuteOptions> {
    #private;
    readonly pythonPath: string;
    /** @param pythonPath Interpreter executable this kernel runs on; reported as the runtime in eval state. */
    private constructor();
    /** Describe or invoke a tool defined in this retained Python kernel; cancelling it cancels an async tool's coroutine. */
    invokeTool(request: PythonToolRequest, options?: KernelExecuteOptions): Promise<KernelExecuteResult>;
    /** Synchronize enabled capability snippets before the next user cell. */
    syncPreludes(preludes: readonly PythonPreludeSource[], signal: AbortSignal | undefined, timeoutMs: number): Promise<void>;
    static start(options: KernelStartOptions): Promise<PythonKernel>;
    /**
     * Captures the runner's JSON-safe user namespace only when no Python cell is
     * executing. Ineligible or malformed responses deliberately fall back.
     */
    snapshotUserNamespace(timeoutMs?: number): Promise<PythonShadowSnapshot | null>;
    /** Projects a candidate against an already-running, idle Python kernel. */
    shadowPlan(code: string, timeoutMs?: number): Promise<PythonShadowPlan | null>;
    /** Atomically starts a cell only if its retained shadow snapshot is still current. */
    executeIfSnapshotMatches(code: string, snapshot: Pick<PythonShadowSnapshot, "revision" | "digest">, options?: KernelExecuteOptions): Promise<KernelExecuteResult | null>;
}