mcp-google-multi 6.0.0-beta.1 → 6.0.0-beta.2

package/dist/usage-metrics.d.ts

@@ -0,0 +1,155 @@
+export declare const METRICS_DIR_NAME = "metrics";
+/** Union of every `error:` slug literal emitted anywhere in src/ (kept honest
+ * by a set-equality grep test). Anything outside buckets to `other`. */
+export declare const KNOWN_ERROR_SLUGS: ReadonlySet<string>;
+export declare function stateDir(env?: NodeJS.ProcessEnv): string;
+export declare function latBucket(ms: number): string;
+export declare function charsBucket(n: number): string;
+export declare function fanBucket(width: number): string | undefined;
+export type MetricsSource = {
+    kind: 'default';
+} | {
+    kind: 'config';
+} | {
+    kind: 'process-env';
+} | {
+    kind: 'env-file';
+    file: string;
+};
+export interface UsageMetricsState {
+    enabled: boolean;
+    source: MetricsSource;
+    /** exactly one stderr warning on a malformed non-empty env value (fail-closed) */
+    warning?: string;
+}
+/**
+ * Fail-closed resolution (mirror of resolveDiscoveryMode's fail-open: here the
+ * safe state is off). Env wins over config; empty env value = unset, silent;
+ * any other value = one warning, off. `envFile` is the .env path that supplied
+ * the variable when it did not come from the real process env (attribution
+ * is computed by the caller; this module never reads env files).
+ */
+export declare function resolveUsageMetrics(env: NodeJS.ProcessEnv, configValue: boolean | undefined, envFile?: string): UsageMetricsState;
+export declare function sourceLabel(source: MetricsSource): string;
+export interface ToolEntryInfo {
+    name: string;
+    service: string;
+    meta: boolean;
+    generated: boolean;
+}
+interface ToolAgg {
+    n: number;
+    err: Record<string, number>;
+    hint: number;
+    lat: Record<string, number>;
+    fanout?: {
+        calls: number;
+    } & Record<string, number>;
+    argfix?: number;
+    /** undeclared keys, counted by the DECLARED key they resolve to */
+    argdrop?: Record<string, number>;
+}
+export interface DayAgg {
+    v: 1;
+    day: string;
+    boots: Record<string, number>;
+    node: string;
+    calls: number;
+    tools: Record<string, ToolAgg>;
+    hints: Record<string, {
+        hinted: number;
+        unhinted: number;
+    }>;
+    retries: Record<string, {
+        hintedOk: number;
+        hintedFail: number;
+        unhintedOk: number;
+        unhintedFail: number;
+    }>;
+    escape: {
+        methods: Record<string, number>;
+        _overflow: number;
+        unknown_method: number;
+        apis_searched: Record<string, number>;
+        unknown_api: number;
+    };
+    validation: Record<string, number>;
+    rpc: Record<string, number>;
+    bigrams: Record<string, number>;
+}
+export interface InitOptions {
+    dir?: string;
+    version: string;
+    mode: string;
+    transport: string;
+    env?: NodeJS.ProcessEnv;
+    now?: () => number;
+    monotonic?: () => number;
+    log?: (line: string) => void;
+}
+/** Deep-add b into a for the DayAgg shape (numbers add, maps union). */
+export declare function mergeDay(a: DayAgg, b: DayAgg): DayAgg;
+export declare class Metrics {
+    private readonly dir;
+    private readonly aggDir;
+    private readonly eventsFile;
+    private readonly now;
+    private readonly mono;
+    private readonly log;
+    private readonly bootKey;
+    private readonly bootId;
+    private seq;
+    private deltas;
+    private events;
+    private lastError;
+    private lastTool;
+    private pendingMid;
+    private timer;
+    private dirty;
+    private failures;
+    private disabled;
+    constructor(opts: InitOptions);
+    private day;
+    private initStorage;
+    private pruneAggs;
+    private day2ms;
+    private pruneEventAge;
+    /** Outermost dispatch wrapper; a throw inside recording never affects the call. */
+    wrap<A extends unknown[], R>(entry: ToolEntryInfo, handler: (...args: A) => Promise<R> | R, widthOf?: (args: unknown) => number): (...args: A) => Promise<R>;
+    private record;
+    /** Escape hatch: only the RESOLVED methodId (double-gated) or a miss. */
+    recordEscapeMethod(idOrNull: string | null): void;
+    /** Search instrument: post-resolution SUPPORTED_APIS keys, or null on failure. */
+    recordSearchApi(resolvedApis: string[] | null): void;
+    /**
+     * Undeclared argument keys seen on a call. `resolvedKeys` carries only the
+     * SUGGESTED (declared) key or the literal `_unmatched`, never the caller's
+     * key, so the closed-vocabulary guarantee holds: a client cannot write an
+     * invented string to disk through this path.
+     */
+    recordArgDrop(tool: string, resolvedKeys: string[]): void;
+    recordArgFix(tool: string, by?: number): void;
+    /** Protocol-level failures (no handler ran); wired by the transport tap. */
+    recordRpc(kind: 'schema_validation' | 'tool_not_found' | number, tool?: string): void;
+    private rolloverIfNeeded;
+    /** Merge deltas into the day file under lock; append buffered events. */
+    flush(): void;
+    private rotateIfNeeded;
+    /** Best-effort synchronous flush for shutdown paths. */
+    shutdown(): void;
+    /** For the doctor/diagnose status line. */
+    statusLine(): string;
+}
+/** Read-only description of the metrics dir for doctor/diagnose status lines
+ * (never creates anything; safe to call with the feature off). */
+export declare function describeMetricsDir(env?: NodeJS.ProcessEnv): {
+    dir: string;
+    files: number;
+    kb: number;
+};
+/**
+ * null when off: no directory, no file, no timer, nothing initializes; setting
+ * USAGE_METRICS_PATH alone never enables anything and never creates anything.
+ */
+export declare function initUsageMetrics(state: UsageMetricsState, opts: InitOptions): Metrics | null;
+export {};