import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
import { ConversationStore } from "../internal/store";
/** Return value of {@link useExecutionStream}. */
export interface UseExecutionStreamReturn {
    /** Latest full execution snapshot from the stream, or `null` before the first update arrives. */
    readonly execution: AgentExecution | null;
    /**
     * Convenience extraction of `execution.status.phase`.
     *
     * Derived from `execution` — always consistent with the current
     * snapshot. Returns `EXECUTION_PHASE_UNSPECIFIED` when `execution`
     * is `null`.
     */
    readonly phase: ExecutionPhase;
    /** `true` while receiving non-terminal updates from the server stream. */
    readonly isStreaming: boolean;
    /** `true` after subscription starts but before the first snapshot arrives. */
    readonly isConnecting: boolean;
    /** Error from the last failed stream attempt, or `null` when healthy. */
    readonly error: Error | null;
    /**
     * Reset error state and re-establish the stream subscription.
     *
     * Works in any lifecycle state — error, complete, or mid-stream.
     * Uses the `connectKey` counter pattern consistent with `refetch()`
     * in other SDK hooks.
     */
    readonly reconnect: () => void;
}
/**
 * Options for {@link useExecutionStream}.
 */
export interface UseExecutionStreamOptions {
    /**
     * External `ConversationStore` to ingest snapshots into.
     *
     * When provided, the hook writes directly to this store and reads
     * the execution snapshot back via `useSyncExternalStore`. This
     * allows `useSessionConversation` to share a single store instance
     * across the stream hook and the rendering tree.
     *
     * When omitted, an internal store is created automatically —
     * preserving backward compatibility for standalone usage.
     */
    readonly store?: ConversationStore;
}
/**
 * Behavior hook that subscribes to real-time {@link AgentExecution}
 * updates via `stigmer.agentExecution.subscribe()`.
 *
 * Manages the full subscription lifecycle through a finite state
 * machine: connection establishment, rAF-coalesced snapshot streaming,
 * terminal-phase detection, error handling, and manual reconnection.
 *
 * **Performance characteristics:**
 * - Non-terminal snapshots are coalesced via `requestAnimationFrame`
 *   so React commits at most once per display frame (~60Hz)
 * - Terminal snapshots (complete/failed/cancelled) flush immediately
 * - Store updates are wrapped in `startTransition` so thread renders
 *   don't block urgent interactions (e.g. composer typing)
 *
 * Pass `null` as `executionId` to skip subscribing (stable no-op).
 * When `executionId` changes, the previous subscription is aborted
 * and a fresh one begins.
 *
 * @example
 * ```tsx
 * function LiveExecution({ id }: { id: string }) {
 *   const { execution, isStreaming, error, reconnect } =
 *     useExecutionStream(id);
 *
 *   if (error) return <p>{error.message} <button onClick={reconnect}>Retry</button></p>;
 *   if (!execution) return <p>Connecting…</p>;
 *
 *   return (
 *     <div>
 *       {execution.status?.messages.map((m, i) => (
 *         <p key={i}>{m.content}</p>
 *       ))}
 *       {isStreaming && <span>Streaming…</span>}
 *     </div>
 *   );
 * }
 * ```
 */
export declare function useExecutionStream(executionId: string | null, options?: UseExecutionStreamOptions): UseExecutionStreamReturn;
//# sourceMappingURL=useExecutionStream.d.ts.map