import { type FrameworkConfig } from './framework-config';
import { type WizardSession, type AdditionalFeature } from './wizard-session';
import { AgentErrorType } from './agent-interface';
/**
 * Stable ids for the post-agent step queue. Each id is used in two
 * places — `getUI().seedPostAgentSteps` to register the row, and
 * `getUI().setPostAgentStep(id, …)` from inside the step function to
 * update its status. Coupled by string but cheap to find-and-replace.
 */
export declare const POST_AGENT_STEP_COMMIT_EVENTS = "commit-events";
export declare const POST_AGENT_STEP_CREATE_DASHBOARD = "create-dashboard";
/**
 * Sentry subtype tags we attach to `API_ERROR` / `RATE_LIMIT` runs so we can
 * group and alert on each upstream-shape separately. See
 * {@link classifyApiErrorSubtype} for the rules.
 */
export type ApiErrorSubtype = 'stream_closed' | 'terminated_400' | 'rate_limit' | 'other';
/**
 * Classify a surfaced API error into a Sentry-friendly subtype tag.
 *
 *   - `stream_closed`  — Hook bridge race during prior-attempt teardown
 *                        (issue #297). PR #298 drains the prior iterator
 *                        and treats this as transient inside the inner
 *                        retry loop, so seeing it surface here means
 *                        every retry exhausted with the same race —
 *                        strong signal that the drain isn't fully
 *                        effective and we need a deeper fix.
 *   - `terminated_400` — Vertex/Anthropic killed the request mid-flight.
 *                        Slipped past the GATEWAY_DOWN guard because
 *                        earlier attempts had succeeded. (Sentry #7442894144)
 *   - `rate_limit`     — Wizard exhausted retries against a 429 storm.
 *   - `other`          — Unclassified API error. Catch-all.
 *
 * Pure for unit testing — no side effects. Exported so the
 * agent-runner test can lock down the matching rules without standing up
 * the full agent runtime.
 */
export declare function classifyApiErrorSubtype(input: {
    errorType: AgentErrorType;
    message: string;
}): ApiErrorSubtype;
/**
 * Decide whether a late-stage API failure should be treated as a soft
 * error (continue to MCP / outro) or a hard abort (wizardAbort).
 *
 * The agent stream can throw `API_ERROR` / `RATE_LIMIT` AFTER it has
 * already done all the meaningful work — common shapes:
 *   - dashboard MCP create succeeded, then a final flush hits a 429
 *   - setup-report.md was written, then the stream closed mid-tear-down
 *   - hook bridge fired its last event after the agent yielded
 *
 * In those cases the user's project is in a fully-set-up state. We
 * shouldn't punish them with a network error code and skip the MCP /
 * Slack / Outro screens — the wizard's job is done.
 *
 * Heuristic: the dashboard URL on the session is the most reliable
 * "we got past the long pole" signal. The dashboard MCP call happens
 * last in the agent's conclude phase, after events have been
 * instrumented and the setup report has been drafted. If the URL is
 * present, everything else is too.
 */
export declare function agentArtifactsLookComplete(session: WizardSession): boolean;
/**
 * Heuristic: did the agent at least install the SDK and instrument
 * events, even if it didn't reach the dashboard creation step?
 *
 * The wizard's `confirm_event_plan` MCP tool persists the approved
 * event plan to `<installDir>/.amplitude/events.json`. Legacy
 * `<installDir>/.amplitude-events.json` is still read when present. The
 * presence of either location with non-empty parseable content is a hard signal that:
 *
 *   - The user approved an instrumentation plan
 *   - The agent reached the post-confirmation phase
 *   - Track call insertion was attempted (whether or not every callsite
 *     landed cleanly — but typically by this point it has)
 *
 * Used as a complement to `agentArtifactsLookComplete` for failure modes
 * where the dashboard URL is NOT set but the project is still in a
 * usable instrumented state — most commonly: the Amplitude MCP server
 * (mcp.amplitude.com) is unreachable at the END of the run, after the
 * events were instrumented but before the dashboard could be created.
 *
 * Distinct from `agentArtifactsLookComplete` because that function's
 * "complete" includes dashboard. This one's "instrumented" stops at the
 * code-changes phase. Dashboard-failed-but-everything-else-worked is a
 * meaningfully different state — the user has working analytics; the
 * only loss is the auto-built dashboard. They can build one manually at
 * app.amplitude.com.
 */
export declare function agentEventsInstrumented(session: WizardSession): boolean;
/**
 * Single decision point for whether a late-stage agent error should be
 * treated as a soft fall-through (continue to MCP / Slack / Outro) or a
 * hard abort. Was previously inlined twice in `runAgentWizardBody` with
 * subtly different rules between the MCP-error and API-error branches —
 * a rate limit during dashboard creation would hard-abort even when
 * events were instrumented, while the same situation under MCP_MISSING
 * fell through softly. This function is the single source of truth.
 *
 * Soft if EITHER the dashboard URL is set on the session OR the event
 * plan was persisted to disk (`.amplitude/events.json` or its legacy
 * mirror). Hard otherwise.
 */
export declare function classifyAgentOutcome(session: WizardSession): {
    severity: 'soft' | 'hard';
    dashboardComplete: boolean;
    eventsInstrumented: boolean;
};
/**
 * Read the freshest stored OAuth token, refreshing it from the stored
 * refresh token when it has expired (or is within the 5-minute pre-expiry
 * buffer). Returns the new access token on success, or `fallback` when no
 * stored token / refresh token / refresh-attempt success is available.
 *
 * This is the post-run-token-staleness fix:
 *
 * Pre-PR, agent-runner had this logic inline ONCE — at the top of the
 * run, before the agent started. After a 14-minute Excalidraw run the
 * 1-hour OAuth token was already past its `expiresAt` by the time
 * `commitPlannedEventsStep` / `createDashboardStep` / `pollForDataIngestion`
 * fired their MCP / data-API calls, surfacing the same
 * "Authentication failed while trying to fetch Amplitude user data"
 * cascade we already fixed for the in-run path in PR #348.
 *
 * Now extracted so the agent-runner can re-invoke it at the post-run
 * boundary, AND so the freshly-refreshed token gets mirrored back onto
 * `session.credentials.accessToken` — that way late-render screens
 * (SlackScreen, OutroScreen) automatically pick up the new value when
 * they read from session.
 *
 * Failure mode: returns `fallback` and logs an analytics breadcrumb. The
 * downstream API call will then fail loudly — better than swallowing the
 * auth error twice.
 */
export declare function refreshTokenIfStale(fallback: string, label: string): Promise<string>;
/**
 * Universal agent-powered wizard runner.
 * Handles the complete flow for any framework using Amplitude MCP integration.
 *
 * All user decisions come from the session — no UI prompts.
 */
export declare function runAgentWizard(config: FrameworkConfig, session: WizardSession, getAdditionalFeatureQueue?: () => readonly AdditionalFeature[], featureProgress?: {
    onFeatureStart?: (feature: AdditionalFeature) => void;
    onFeatureComplete?: (feature: AdditionalFeature) => void;
}): Promise<void>;
