/**
 * AsyncGate — lightweight async MCP handler wrapper.
 *
 * Long-running MCP tool calls timeout in Claude Code (~60s). This module lets
 * any handler opt into an async contract: if work exceeds maxSyncMs, return
 * {queued:true, runId} immediately and finish in the background. Callers poll
 * nexus_run_status(runId) for completion.
 *
 * Design:
 *   - In-memory ring buffer (cap 200 jobs). No SQLite dep — keep hot path fast.
 *   - withAsyncGate wraps a handler fn; uses Promise.race against a deadline.
 *   - getAsyncGate() returns the process-singleton instance.
 */
export type AsyncJobStatus = 'pending' | 'running' | 'completed' | 'failed';
export interface AsyncJob {
    runId: string;
    tool: string;
    args?: Record<string, unknown>;
    status: AsyncJobStatus;
    stage: string;
    progress: number;
    queuedAt: number;
    startedAt?: number;
    completedAt?: number;
    result?: {
        content: Array<{
            type: string;
            text: string;
        }>;
    };
    error?: string;
    etaMs?: number;
    lifecycleReportedAt?: number;
}
export interface AsyncGateOpts {
    /** Tool name — for job metadata */
    tool: string;
    /** Original tool args, used when a poll observes final lifecycle state. */
    args?: Record<string, unknown>;
    /** If handler resolves within this window, return inline. Default: 2000ms */
    maxSyncMs?: number;
    /** Human-readable hint for estimated duration */
    etaMs?: number;
    /** Return the async receipt before starting work. Use for cold paths that may block synchronously. */
    alwaysQueue?: boolean;
}
type HandlerFn = () => Promise<{
    content: Array<{
        type: string;
        text: string;
    }>;
}>;
declare class AsyncGate {
    private jobs;
    private insertOrder;
    /** Run handler; if it takes >maxSyncMs, queue it and return runId immediately. */
    run(fn: HandlerFn, opts: AsyncGateOpts): Promise<{
        content: Array<{
            type: string;
            text: string;
        }>;
    } | {
        queued: true;
        runId: string;
        etaMs?: number;
    }>;
    getJob(runId: string): AsyncJob | undefined;
    /** Format job status as MCP text response */
    formatStatus(runId: string): {
        content: Array<{
            type: string;
            text: string;
        }>;
    };
    updateStage(runId: string, stage: string, progress: number): void;
    markLifecycleReported(runId: string): void;
    /** Return jobs that have been running longer than their stale threshold. */
    getStaleJobs(now: number, defaultStaleMs: number, etaMultiplier: number): AsyncJob[];
    /** Mark a running job as failed (watchdog reap). */
    markFailed(runId: string, reason: string): void;
    private enqueueJob;
}
export declare function getAsyncGate(): AsyncGate;
/**
 * Wrap an MCP handler function in the async gate.
 *
 * Usage:
 *   return withAsyncGate(() => doSlowWork(), { tool: 'nexus_orchestrate', maxSyncMs: 2000, etaMs: 30_000 });
 *
 * If work finishes within maxSyncMs → inline result (transparent).
 * If not → { queued: true, runId } immediately; work continues in bg.
 */
export declare function withAsyncGate(fn: HandlerFn, opts: AsyncGateOpts): Promise<{
    content: Array<{
        type: string;
        text: string;
    }>;
} | {
    queued: true;
    runId: string;
    etaMs?: number;
}>;
export {};
