/**
 * Sentry error tracking for the Amplitude Wizard CLI.
 *
 * Captures unhandled exceptions, classified errors, and breadcrumbs.
 * Integrates with the structured logger via a sink callback.
 *
 * Telemetry policy (industry standard for OSS CLIs):
 * - ON by default — users opt out via DO_NOT_TRACK=1 or AMPLITUDE_WIZARD_NO_TELEMETRY=1
 * - Sentry is included in the telemetry opt-out (same env vars that disable Amplitude)
 * - No PII is sent by default (sendDefaultPii: false)
 * - All events pass through the redaction layer before transmission
 */
import type { ExecutionMode } from '../mode-config';
export interface SentryConfig {
    sessionId: string;
    version: string;
    mode: ExecutionMode;
    debug: boolean;
}
/**
 * Initialize Sentry for the wizard CLI.
 *
 * Called from `bin.ts` early in startup after correlation is initialized.
 * The function is `async` so that the `@sentry/node` module — by far the
 * heaviest single import in the boot chain — loads on a microtask AFTER
 * `bin.ts` has finished its synchronous bootstrap. Callers don't need to
 * await: events captured before init resolves are silently dropped (the
 * `initialized` / `sentryRT` guards no-op every accessor), which is
 * acceptable for a CLI's first ~tens of milliseconds (the `sentryRT`
 * guards no-op every accessor until init resolves).
 *
 * When telemetry is disabled (DO_NOT_TRACK / AMPLITUDE_WIZARD_NO_TELEMETRY
 * / NODE_ENV=test), `@sentry/node` is never imported at all — saving the
 * full module-load cost for opted-out users and the entire test run.
 */
export declare function initSentry(config: SentryConfig): Promise<void>;
/**
 * Capture an error to Sentry with optional context.
 */
export declare function captureError(error: Error, context?: Record<string, unknown>): void;
/**
 * Add a breadcrumb to Sentry for debugging context.
 */
export declare function addBreadcrumb(category: string, message: string, data?: Record<string, unknown>): void;
/**
 * Set the Sentry user context (called when analytics.setDistinctId fires).
 */
export declare function setSentryUser(userId: string): void;
/**
 * Set a tag on the current Sentry scope.
 */
export declare function setSentryTag(key: string, value: string): void;
/**
 * Start a Sentry performance span that you manually `.end()`.
 *
 * Returns an object with `end()` and `setAttribute()` methods. When Sentry
 * is not initialized (telemetry disabled, init failed, etc.), returns a
 * no-op that's safe to call.
 *
 * Use this for cross-callback lifecycles (e.g., agent run from onInit to
 * onFinalize) where `sentryRT.startSpan(cb)` doesn't fit.
 */
export interface WizardSpan {
    end(): void;
    setAttribute(key: string, value: unknown): void;
}
export declare function startWizardSpan(name: string, op: string, attributes?: Record<string, unknown>): WizardSpan;
/**
 * Wrap a sync or async callback in an active Sentry span.
 *
 * Unlike `startWizardSpan` (inactive span — manual lifecycle, no context
 * propagation), this uses `sentryRT.startSpan` which sets the span as the
 * active scope. Outbound HTTP requests, child spans, and errors thrown
 * inside `fn` are automatically attached to this span — including any
 * `axios` / `fetch` call picked up by the default httpIntegration.
 *
 * Use this for discrete operations like an OAuth exchange, a single MCP
 * call, or a wizard step. Span status is set to `internal_error` if `fn`
 * throws, then the error is rethrown so existing control flow is preserved.
 *
 * No-ops cleanly when Sentry is not initialized — `fn` runs as if the
 * wrapper weren't there, with no overhead beyond the function call.
 */
export declare function withWizardSpan<T>(name: string, op: string, attributes: Record<string, unknown> | undefined, fn: () => T): T;
/**
 * Flush pending Sentry events before exit (2s timeout).
 */
export declare function flushSentry(): Promise<void>;
/**
 * Wrap an MCP server instance with Sentry's auto-instrumentation so every
 * tool call gets a span. Safe to call when telemetry is disabled — returns
 * the unwrapped server unchanged so the caller's typing stays stable.
 *
 * Use this on any MCP server constructed in the wizard:
 *   - `@modelcontextprotocol/sdk` `new McpServer(...)`
 *   - `@anthropic-ai/claude-agent-sdk` `createSdkMcpServer(...)`
 *
 * Sentry's `wrapMcpServerWithSentry` is idempotent — calling it twice on the
 * same server is a no-op the second time. We add our own initialization
 * guard so a Sentry-side throw doesn't take the wizard down.
 */
export declare function wrapMcpServerWithSentry<T extends object>(server: T): T;
/**
 * Record a numeric measurement on the active Sentry root span (e.g., token
 * counts on the agent run trace).
 *
 * Best-effort: when Sentry is not initialized or no active span context
 * exists, the call is a silent no-op. Existing benchmark math is unaffected
 * — measurements are an additive trace attribute, not a replacement.
 *
 * The unit follows OpenTelemetry conventions; common values for the wizard:
 *   - `'token'` for input/output/cache_read/cache_creation token counts
 *   - `'millisecond'` / `'second'` for durations
 *   - `'byte'` for sizes
 */
export declare function setSpanMeasurement(name: string, value: number, unit: string): void;
