import { type Translator } from "@translated/lara"; type MetricsEvent = { eventType: "auth_success" | "auth_fail" | "call_success" | "call_error" | "quota_exceeded"; /** Absent only on an `auth_fail` for credentials Lara never accepted. */ accountId?: string; errorType?: string; latencyMs?: number; charsTranslated?: number; metadata?: Record; }; export declare const metricsEnabled: () => boolean; /** * The per-call opt-out: a call that asks Lara not to trace it is not reported either — no event of * any kind. Read from the raw arguments, before validation, so a malformed flag still counts: it * says the user wanted privacy, and erring on their side costs one data point. */ export declare const isNoTrace: (args: unknown) => boolean; /** * The backend fields one tool call produces. It lives here with the rest of the reporting * vocabulary: `feature`, the language tags, the option flags and the character count are all facts * about how a tool's arguments map onto the funnel, and they change together. * * The arguments are unvalidated — the tool handler is what parses them, and on the error path the * parse is exactly what failed — so nothing raw is reported: language tags must look like one, and * the option flags come only from a successful parse. */ export declare function callFieldsFor(toolName: string, args: unknown): { metadata: Record; charsTranslated?: number; }; /** * The calling client, from what the request carries: ChatGPT's `openai/*` hints, the clientInfo of * the initialize handshake (STDIO only — on the stateless HTTP transport it went to another * request), then the HTTP User-Agent. Undefined when nothing identifies it. */ export declare function clientFor(clientInfoName: unknown, meta: unknown, userAgent: unknown): string | undefined; /** A client version only if it looks like one: it is free text the client sends. */ export declare const clientVersionFor: (value: unknown) => string | undefined; /** * Fire-and-forget event report. Never awaited, never throws: if the monitoring backend is down * the MCP keeps translating as though nothing happened. * * Events are batched rather than posted one by one because the ingest quota counts requests * (100/min per installation) far more tightly than events (20 000/min). */ export declare function logEvent(event: MetricsEvent): void; /** * Deliver whatever is queued. Awaited only on shutdown — otherwise the last batch dies with the * process. One drain at a time, so two can never race for the same token; a flush asked for while * one runs is folded into a single rerun after it, so a backend slower than the flush interval * cannot stack up drains. */ export declare function flushNow(): Promise; /** Deliver what is queued before the process goes, within a budget a supervisor will honour. */ export declare function flushBeforeExit(timeoutMs?: number): Promise; /** * The Lara account (`acc_...`) a Lara access token belongs to. Credits are consumed per account, * so it is the granularity the funnel shares with every other channel: the access key is not an * identity, it belongs to an account and is shared by its users. * * The payload is read without verifying the signature or `exp`: authorization already happened at * the Lara API itself, here we only need an identifier out of our own credential. */ export declare function accountIdFromToken(token: string): string | undefined; /** * Short stable token for dashboards — free text would make grouping useless. The vocabulary is the * one shared by every Lara integration, so the same failure reads the same way across channels. */ export declare function errorTypeFor(error: unknown): string; /** * Lara refused the call because the account is out of quota. The API has no dedicated status for * it, so it is matched on the error's type and message, as lara-cli does (`QuotaExceeded` too, but * not `quotation`): the same refusal reads the same way on every channel. */ export declare function isQuotaError(error: unknown): boolean; /** * What went wrong, beyond errorType, for the problems errorType groups together. Never a message: * those can quote the request. The Lara error type is an identifier from the API, kept only while it * looks like one; the invalid fields are schema paths with array indices folded, never a value, and * the invalid issues the same paths with the Zod issue code. */ export declare function errorDetailsFor(error: unknown): Record; /** * Everything one MCP session needs to report against. The account is not known when the session is * built: an access key is not an account, and the SDK only exchanges it for a Lara token lazily, on * the first request — so it is resolved after a call has succeeded and cached here. */ export type MetricsContext = { accountId?: string; translator: Translator; }; /** Undefined when telemetry is off, which makes every report below a no-op. */ export declare function createMetricsContext(translator: Translator): MetricsContext | undefined; /** One tool call, as CallTool sees it. */ export type CallInfo = { toolName: string; args: unknown; startedAt: number; /** A bucket from clientFor, never a raw name. */ client?: string; clientVersion?: string; }; /** * Report a tool call that returned. Called from inside CallTool rather than from a wrapper around * it, because CallTool turns every failure into an isError result before it escapes and the error * path below needs the original. * * Both reporters swallow their own failures: a bug in here must never turn a call Lara completed * into an error, or add a call_error to a call that succeeded. */ export declare function reportCallSuccess(ctx: MetricsContext | undefined, call: CallInfo, reasoningFallback?: boolean, planRestricted?: boolean): void; /** * Report a tool call that threw. The error itself is never altered, only described. * * Without an account — the SDK never got a token — only a credential Lara rejected is reported: it * is the one failure that explains why there is no account, and `auth_fail` is the one event the * backend takes without one. Any other early error is lost, by design. */ export declare function reportCallError(ctx: MetricsContext | undefined, call: CallInfo, error: unknown): void; export {};