/**
 * run-state — fetches a prod execution projection from the agents surface and
 * renders it to a {@link RunView} the canvas can poll.
 *
 * WHY the agents surface: deployed agent runs are owned by the agents runtime
 * (`GET /agents/v1/executions/:id`), not the core-capabilities surface. The
 * response is the full ExecutionProjection JSON (same shape agent-core's
 * decodeExecutionProjection consumes).
 *
 * WHY the key stays server-side: the Sapiom API key is a harness credential that
 * must never reach the browser. The harness server fetches on behalf of the
 * canvas, so the SPA polls a local `/api/runs/:id/state` endpoint (no key in the
 * request) rather than calling the upstream surface directly.
 *
 * NOTE: this env-precedence helper for the agents base URL is duplicated
 * elsewhere in the harness; consolidate into one shared helper when convenient.
 */
import type { RunView } from "../shared/types.js";
import { type ApiKeyProvider } from "./api-key-provider.js";
/** Resolve the agents surface base URL from the environment. */
export declare function resolveAgentsBaseUrl(): string;
export type RunStateResult = {
    ok: true;
    runView: RunView;
} | {
    ok: false;
    status: number;
    error: string;
};
export interface RunStateFetcherOpts {
    /**
     * Sapiom API key. Accepts either a plain `string | null` (the boot-time key)
     * or an {@link ApiKeyProvider} — pass a provider to get the refresh-on-401
     * recovery path. A bare string never refreshes.
     */
    apiKey: string | null | ApiKeyProvider;
    baseUrl?: string;
    /** Injectable fetch implementation — defaults to global fetch. Test seam. */
    fetchImpl?: typeof fetch;
}
export interface RunStateFetcher {
    fetch(executionId: string): Promise<RunStateResult>;
}
/** Upstream statuses that mean "the API key was rejected" — worth one refresh
 *  + retry before we give up. 401 is the common case; 403 covers a key that
 *  authenticated but lost authorization (e.g. rotated to a new org). */
export declare function isAuthRejection(status: number): boolean;
/**
 * Create a fetcher that resolves an execution's current render state from the
 * agents surface. The fetcher is intentionally non-throwing: all error paths
 * return a typed {@link RunStateResult} with `ok: false` so the router can
 * forward the appropriate HTTP status without a try/catch at the call site.
 *
 * When constructed with an {@link ApiKeyProvider}, a 401/403 from the upstream
 * call triggers exactly one credential refresh + retry: if the shared store has
 * a newer key (e.g. the user re-logged-in), the retry uses it and the Studio
 * recovers in place instead of surfacing a dead-end auth error.
 */
export declare function createRunStateFetcher(opts: RunStateFetcherOpts): RunStateFetcher;
//# sourceMappingURL=run-state.d.ts.map