import type { EnvVarInput, ResourceRef } from "@stigmer/sdk";
import { type AgentSetupResult, type AgentSetupReadyResult, type AgentSetupState } from "./agentSetupReducer";
export type { AgentResolution, AgentSetupResult, AgentSetupReadyResult, AgentSetupState, AgentSetupPhase, } from "./agentSetupReducer";
/** Options for {@link UseAgentSetupReturn.submitEnvVars}. */
export interface SubmitEnvVarsOptions {
    /**
     * When `true` (default), the provided values are saved to the user's
     * personal environment and a personal agent instance is created.
     * Subsequent runs of the same agent will reuse these credentials.
     *
     * When `false`, the values are collected as `runtimeEnv` for this
     * execution only — no data is persisted and no agent instance is
     * created. This path is instant (no network calls).
     *
     * @default true
     */
    readonly saveForFuture?: boolean;
}
/** Return value of {@link useAgentSetup}. */
export interface UseAgentSetupReturn {
    /**
     * Current state of the agent setup flow.
     *
     * A discriminated union on `status`:
     * - `"idle"` — no agent selected
     * - `"resolving"` — evaluating an agent's requirements
     * - `"needsEnvVars"` — waiting for user to provide missing variables
     * - `"submitting"` — saving environment / creating instance
     * - `"ready"` — agent resolved, `resolution` describes how to proceed
     *
     * `error` is available on all variants (orthogonal to phase).
     */
    readonly state: AgentSetupState;
    /**
     * Evaluate whether an agent is ready to use or needs env var collection.
     *
     * Fetches the full agent to read its `env` declarations, checks for an
     * existing personal instance, and diffs env keys against the personal
     * environment. Returns `"ready"` when the agent can be used immediately,
     * or `"needsEnvVars"` when the caller should present {@link AgentEnvForm}.
     */
    readonly resolveAgent: (ref: ResourceRef) => Promise<AgentSetupResult>;
    /**
     * Complete the env var collection flow for the pending agent.
     *
     * Behavior depends on `options.saveForFuture`:
     * - `true` (default) — Creates or updates the personal environment
     *   with the provided values, then creates a personal agent instance.
     *   Returns `{ resolution: { mode: "saved", instanceId } }`.
     * - `false` — Collects values as `runtimeEnv` without any API calls.
     *   Returns `{ resolution: { mode: "oneTime", runtimeEnv } }`.
     *
     * Must only be called when `state.status === "needsEnvVars"`.
     */
    readonly submitEnvVars: (values: Record<string, EnvVarInput>, options?: SubmitEnvVarsOptions) => Promise<AgentSetupReadyResult>;
    /** Clear the error without changing the current phase. */
    readonly clearError: () => void;
    /** Reset to `idle` state, clearing all phase data and errors. */
    readonly reset: () => void;
}
/**
 * Layer 2 behavior hook that encapsulates the agent selection,
 * personal environment resolution, and secret delivery routing flow.
 *
 * When a user picks an agent in the {@link AgentPicker}, this hook
 * determines whether the agent requires credentials (via its
 * `env` declarations), checks what the user has already provided in their
 * personal environment, and either reports the agent as ready or
 * identifies the missing variables so the caller can render
 * {@link AgentEnvForm}.
 *
 * The hook supports two secret delivery paths via the `saveForFuture`
 * option on {@link submitEnvVars}:
 * - **Saved** — secrets are persisted to the personal environment and
 *   a personal agent instance is created for reuse.
 * - **One-time** — secrets are returned as `runtimeEnv` for a single
 *   execution, with no data persisted.
 *
 * State is managed by a `useReducer` state machine with five phases:
 * `idle → resolving → needsEnvVars → submitting → ready`.
 *
 * Composes {@link usePersonalEnvironment} for personal environment
 * operations and calls the Stigmer client directly for agent and
 * agent instance queries.
 *
 * > **Why not compose `usePersonalAgentInstance`?**
 * > `resolveAgent` is an imperative async callback that needs
 * > immediate results within a single invocation. Hook state
 * > updates require a render cycle. Instance creation is delegated
 * > through the shared `buildPersonalInstanceInput` helper instead.
 *
 * Pass `null` as `org` to disable all operations (stable no-op).
 *
 * @param org - Organization slug. Pass `null` to disable.
 * @param poolKeys - Optional set of env-var keys already available
 *   from the session env pool (manual secrets, one-time env vars from
 *   other components). When provided, agents whose `env` keys
 *   are fully covered by `poolKeys` + personal env auto-resolve to
 *   `ready` without prompting. Reactive — when `poolKeys` changes,
 *   `needsEnvVars` is re-evaluated.
 *
 * @example
 * ```tsx
 * const { state, resolveAgent, submitEnvVars } = useAgentSetup("acme", pool.availableKeys);
 *
 * const result = await resolveAgent({ org: "acme", slug: "code-reviewer" });
 *
 * if (result.status === "needsEnvVars") {
 *   // Render AgentEnvForm with result.missingVariables
 *   // On form submit:
 *   const ready = await submitEnvVars(formValues, { saveForFuture: true });
 *   // ready.resolution.mode === "saved" | "oneTime"
 * }
 * ```
 */
export declare function useAgentSetup(org: string | null, poolKeys?: Set<string>): UseAgentSetupReturn;
//# sourceMappingURL=useAgentSetup.d.ts.map