/**
 * MCP self-telemetry — `log10x_mcp_tool_call_total` and `log10x_mcp_started_total`.
 *
 * Counters that fire on each tool dispatch and on server boot. Periodically
 * flushed to a Prometheus-compatible remote_write endpoint using the native
 * wire format (protobuf + snappy), so it works against any standard receiver
 * including Log10x's hosted Prometheus at prometheus.log10x.com/api/v1/write.
 *
 * Used by the Log10x console to render an "MCP active" badge on Step 1
 * (Connect 10x) — the console queries `count(log10x_mcp_tool_call_total)` over
 * a 24h window and lights up if any tool has been called.
 *
 * **Env scoping (key design choice)**: each tool call's counter is auth'd
 * with `<api_key>/<env_id>` for the env the tool acted on, so the metric
 * lands in THAT env's Prometheus tenant. Without this, every counter would
 * land in the user's default env regardless of where the tool was actually
 * pointed — making per-env activity attribution impossible AND making the
 * write fail outright for users whose default env is read-only (most
 * notably demo users on `Log10x Demo`).
 *
 * Skip rules at flush time:
 *   - If the env the tool acted on has READ permission only, the write
 *     would 403 — skip it (telemetry isn't worth a billing-side audit
 *     event of failed writes). This silently drops counters from
 *     read-only envs, which includes the entire demo-user population.
 *   - If the env list isn't loaded yet (race during boot), counters are
 *     held in memory and flushed on the next attempt once envs resolve.
 *
 * Privacy: bounded cardinality (~30 tool names × 2 statuses × small N envs
 * the user can write to × 4 tiers). No arguments, no payload sizes. Tool
 * name + outcome + tier only — env identity is implicit in the tenant the
 * write is auth'd to, not embedded as a label.
 *
 * Gating: silent no-op unless BOTH of the following are set:
 *   - LOG10X_API_KEY (required — identifies the customer)
 *   - LOG10X_TELEMETRY_URL (or PROMETHEUS_REMOTE_WRITE_URL fallback) — push target
 *
 * Counter semantics: counters are CUMULATIVE per process lifetime — never
 * reset on flush (Prometheus counters must monotonically increase between
 * resets; PromQL rate() detects process-restart resets automatically).
 */
import type { Environments } from './environments.js';
export declare function setEnvsProvider(fn: () => Environments | null): void;
/** Increment the started counter. Call once per process boot. */
export declare function recordStart(): void;
/**
 * Increment a tool-call counter. Called from `withTelemetry` wrapper. The
 * `envId` is best-effort — if the wrapper couldn't resolve the env (envs
 * not loaded yet, or no `environment` arg + no last-used + no default), the
 * counter is bucketed under an unknown env and reassigned to the user's
 * default at flush time.
 */
export declare function recordToolCall(toolName: string, status: 'success' | 'error', envId: string | undefined): void;
/**
 * Push pending counters to the configured Prometheus remote_write endpoint.
 * Uses native protobuf + snappy. Each writable env gets its own POST with
 * `<apiKey>/<envId>` auth so the metric lands in that env's tenant.
 *
 * Counters are NOT reset on flush — they're cumulative for the lifetime
 * of this process; restart = counter reset (handled by PromQL rate()).
 */
export declare function flush(): Promise<void>;
/**
 * Wrap a tool handler so every call is counted. status='success' on
 * resolve, 'error' on throw.
 *
 * Resolves the env the tool acted on by inspecting the first arg's
 * `environment` field (the standard arg the rest of the codebase uses to
 * pick an env per call), falling back to last-used / default if absent.
 * The resolution is best-effort — never throws into the handler path. If
 * envs aren't available yet (boot race), the call is bucketed with
 * `envId=undefined` and routed to the default env at flush time.
 */
export declare function withTelemetry<H extends (...args: any[]) => Promise<any>>(toolName: string, handler: H): H;