/**
 * @module tools/_shared/long-poll
 * @description Long-poll promotion for long-running MCP tool calls.
 *
 * MCP hosts (notably Claude Desktop) time out tool calls after a minute or
 * two, while `build`/`render` legitimately run for many minutes. The fix:
 * run the work normally, and if it finishes inside the synchronous window
 * return its result untouched — byte-identical to the unwrapped call, and no
 * job record is ever written. If the window elapses first, persist a local
 * {@link JobRecord} (jobType "build"/"render", provider "local"), return a
 * `promoted` envelope immediately, and let the work continue in-process; the
 * settle handlers write the terminal record that `status_job` then serves.
 *
 * CLI surfaces never reach this module — callers gate on
 * `ctx.surface === "mcp"`.
 */
import type { ToolExecuteResult } from "../define-tool.js";
export interface LocalJobUpdate {
    /** 0-100 when a percentage is known; otherwise omit. */
    progress?: number;
    /** Pipeline stage label, e.g. "assets" | "compose" | "render". */
    stage?: string;
    message?: string;
}
export interface PromotionOptions {
    jobType: "build" | "render";
    /** Absolute project dir — the job record lands in `<projectDir>/.vibeframe/jobs/`. */
    projectDir: string;
    /** CLI equivalent of this invocation, stored on the record for retryWith. */
    command: string;
    /** Synchronous window before promotion. Default 45s; see resolveWindowMs. */
    windowMs?: number;
    /** Heartbeat cadence once promoted. Default 10s. */
    heartbeatMs?: number;
    now?: () => Date;
}
/**
 * Resolve the promotion window. `VIBE_MCP_PROMOTE_AFTER_MS` overrides the
 * default; `"off"` or `"0"` disables promotion entirely (pure synchronous
 * behavior — the escape hatch for hosts with generous timeouts).
 */
export declare function resolveWindowMs(optionMs?: number): number | null;
/**
 * Run `work`; promote to a polled background job if it outlives the window.
 *
 * The `report` callback passed to `work` is safe to call at any time: before
 * promotion it only buffers the latest update (callers typically also feed
 * `ctx.onProgress` for MCP progress notifications); after promotion it
 * coalesces updates into the job record on disk.
 */
export declare function runWithMcpPromotion(work: (report: (update: LocalJobUpdate) => void) => Promise<ToolExecuteResult>, opts: PromotionOptions): Promise<ToolExecuteResult>;
