@velum-labs/routekit-daemon 0.16.4 → 0.16.6

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import type { ServiceRecord } from "@velum-labs/routekit-runtime";
+import { type TelemetryTransportFactory } from "./telemetry.js";
 export declare const ROUTEKIT_DAEMON_KIND = "daemon";
 export declare const ROUTEKIT_PRODUCT = "routekit";
 export type RouteKitDaemonOptions = {
@@ -13,6 +14,9 @@ export type RouteKitDaemonOptions = {
     portless?: boolean;
     drainGraceMs?: number;
     onShutdownRequested?: (reason: "stop" | "restart" | "upgrade") => void;
+    /** Test seam for a network-free telemetry transport. */
+    telemetryTransportFactory?: TelemetryTransportFactory;
+    telemetryFlushIntervalMs?: number;
     /** Test seam used by child-process interruption coverage. */
     onAccountTransactionPhase?: (phase: "prepared" | "credentials-written" | "router-swapped" | "committed") => void;
 };

package/dist/index.js

@@ -15,12 +15,13 @@ import { resolveLeaderboardConfig, startSwitchingGatewayProxy } from "@velum-lab
 import { accountKindForCliproxyAuthType, PROVIDERS, resolveAccountConnector } from "@velum-labs/routekit-registry";
 import { startRouter } from "@velum-labs/routekit-router";
 import { acquireLifecycleLock, CONTROL_PROTOCOL_VERSION, ControlClient, ControlError, createPortlessSession, createServiceRecordStore, createTokenStore, encodeJoinCredential, extendCleanupGrace, generateControlToken, nextServiceGeneration, processIdentity, registerCleanup, SERVICE_HOME_MODE, startControlServer, supervisorFromEnv, writeFileAtomic } from "@velum-labs/routekit-runtime";
-import { createConsentManager } from "@velum-labs/routekit-telemetry-core";
+import { createConsentManager, durationBucket, TELEMETRY_SCHEMA_INVENTORY, telemetryStatusMetadata } from "@velum-labs/routekit-telemetry-core";
 import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
 import { cleanupAccountTransaction, markAccountTransactionCommitted, prepareAccountTransaction, recoverAccountTransactions, rollbackAccountTransaction } from "./account-transaction.js";
 import { CallAttributionStore, callInspection } from "./call-attribution-store.js";
 import { createCliproxySidecar } from "./cliproxy-sidecar.js";
 import { aggregateInspections, buildLeaderboardResult, defaultLeaderboardWindow, LeaderboardRollupStore } from "./leaderboard.js";
+import { DaemonTelemetry, DEFAULT_TELEMETRY_HOST, GatewayTelemetryAggregator } from "./telemetry.js";
 export const ROUTEKIT_DAEMON_KIND = "daemon";
 export const ROUTEKIT_PRODUCT = "routekit";
 function dataTokenPath(home) {
@@ -275,6 +276,8 @@ export async function startRouteKitDaemon(options) {
     let sidecarRef;
     let activeRouter;
     let accountActivity;
+    let daemonTelemetry;
+    let gatewayTelemetry;
     let record;
     let closed = false;
     let draining = false;
@@ -326,6 +329,24 @@ export async function startRouteKitDaemon(options) {
             home,
             config: leaderboardConfig
         });
+        const telemetry = createConsentManager({
+            path: () => join(home, "telemetry.json"),
+            environmentVariable: "ROUTEKIT_TELEMETRY"
+        });
+        daemonTelemetry = new DaemonTelemetry({
+            env,
+            resolveConsent: telemetry.resolve,
+            ...(options.telemetryTransportFactory !== undefined
+                ? { factory: options.telemetryTransportFactory }
+                : {})
+        });
+        gatewayTelemetry = new GatewayTelemetryAggregator({
+            telemetry: daemonTelemetry,
+            version: options.packageVersion,
+            ...(options.telemetryFlushIntervalMs !== undefined
+                ? { flushIntervalMs: options.telemetryFlushIntervalMs }
+                : {})
+        });
         // Independent of leaderboard durable rollups: last-selection only.
         mkdirSync(join(home, "usage"), { recursive: true, mode: 0o700 });
         accountActivity = new AccountActivityCoordinator({
@@ -348,6 +369,7 @@ export async function startRouteKitDaemon(options) {
                 const inspection = callInspection(record);
                 if (inspection !== undefined)
                     leaderboardRollups.record(inspection);
+                gatewayTelemetry?.record(record);
             }
         };
         const wantsCliproxySidecar = (config) => config.providers["cliproxy"] !== undefined;
@@ -469,9 +491,10 @@ export async function startRouteKitDaemon(options) {
             sources: ["global"]
         });
         let handlers;
-        const telemetry = createConsentManager({
-            path: () => join(home, "telemetry.json"),
-            environmentVariable: "ROUTEKIT_TELEMETRY"
+        const telemetryStatus = () => telemetryStatusMetadata(telemetry.resolve(env), {
+            provider: "posthog",
+            host: env.ROUTEKIT_POSTHOG_HOST?.trim() || DEFAULT_TELEMETRY_HOST,
+            configured: (env.ROUTEKIT_POSTHOG_KEY ?? "").trim().length > 0
         });
         handlers = {
             "daemon.status": async () => ({
@@ -1288,16 +1311,69 @@ export async function startRouteKitDaemon(options) {
                     throw new ControlError({ code: "internal", message });
                 }
             },
-            "telemetry.get": async () => ({ enabled: telemetry.resolve().enabled }),
+            "telemetry.get": async () => telemetryStatus(),
             "telemetry.set": async (params) => {
                 await serializeMutation(async () => {
-                    if (params.enabled)
-                        telemetry.enable();
-                    else
-                        telemetry.disable();
+                    if (params.enabled === false) {
+                        if (telemetry.resolve(env).enabled) {
+                            gatewayTelemetry?.flush();
+                            await daemonTelemetry?.flush();
+                            await daemonTelemetry?.shutdown();
+                        }
+                        else {
+                            await daemonTelemetry?.discard();
+                        }
+                        gatewayTelemetry?.discard();
+                    }
+                    if (params.enabled !== undefined) {
+                        if (params.enabled)
+                            telemetry.enable();
+                        else
+                            telemetry.disable();
+                    }
+                    if (params.category !== undefined && params.categoryEnabled !== undefined) {
+                        if (!params.categoryEnabled &&
+                            (params.category === "usage" || params.category === "reliability")) {
+                            gatewayTelemetry?.discard(params.category);
+                        }
+                        telemetry.setCategory(params.category, params.categoryEnabled);
+                    }
+                    const result = telemetry.resolve(env);
+                    if (result.enabled && result.categories.adoption) {
+                        daemonTelemetry?.capture("routekit.telemetry_preference_changed", {
+                            action: params.enabled !== undefined ? "master" : "category",
+                            ...(params.category !== undefined ? { category: params.category } : {}),
+                            enabled: params.enabled ?? params.categoryEnabled,
+                            source: result.source,
+                            version: options.packageVersion
+                        });
+                    }
                 });
-                return { enabled: telemetry.resolve().enabled };
+                return telemetryStatus();
             },
+            "telemetry.resetIdentity": async () => {
+                await serializeMutation(async () => {
+                    gatewayTelemetry?.flush();
+                    await daemonTelemetry?.flush();
+                    await daemonTelemetry?.shutdown();
+                    gatewayTelemetry?.discard();
+                    telemetry.resetIdentity(env);
+                    const result = telemetry.resolve(env);
+                    if (result.enabled && result.categories.adoption) {
+                        daemonTelemetry?.capture("routekit.telemetry_preference_changed", {
+                            action: "identity-reset",
+                            enabled: true,
+                            source: result.source,
+                            version: options.packageVersion
+                        });
+                    }
+                });
+                return telemetryStatus();
+            },
+            "telemetry.schema": async () => TELEMETRY_SCHEMA_INVENTORY,
+            "telemetry.captureCommand": async (params) => ({
+                accepted: daemonTelemetry?.capture("routekit.command_completed", params) ?? false
+            }),
             "doctor.run": async (_params, context) => {
                 const providers = await activeRouter.providerStatuses(context.signal);
                 const configuredProviders = configuredProviderIds(currentConfig);
@@ -1444,8 +1520,53 @@ export async function startRouteKitDaemon(options) {
                 }
             }
         };
+        const operationFor = (method, params) => {
+            switch (method) {
+                case "daemon.reload":
+                    return "config_reload";
+                case "config.update":
+                    return "config_update";
+                case "config.import":
+                    return "config_import";
+                case "providers.set":
+                    return params.enabled === true
+                        ? "provider_enable"
+                        : "provider_disable";
+                case "accounts.enroll":
+                    return "account_enroll";
+                case "accounts.enrollActivate":
+                    return "account_enroll_activate";
+                case "accounts.remove":
+                    return "account_remove";
+                case "accounts.sync":
+                    return "account_sync";
+                case "launcher.prepare":
+                    return "launcher_prepare";
+                case "tokens.issue":
+                    return "token_issue";
+                case "tokens.revoke":
+                    return "token_revoke";
+                default:
+                    return undefined;
+            }
+        };
+        const captureOperation = (method, params, outcome, durationMs) => {
+            const operation = operationFor(method, params);
+            if (operation === undefined)
+                return;
+            daemonTelemetry?.capture("routekit.product_operation_completed", {
+                operation,
+                outcome,
+                duration_bucket: durationBucket(durationMs),
+                version: options.packageVersion
+            });
+        };
+        const dispatch = createRouteKitControlHandler(handlers, {
+            onCommitted: (method, params, durationMs) => captureOperation(method, params, "success", durationMs),
+            onControlError: (method, params, _code, durationMs) => captureOperation(method, params, "error", durationMs)
+        });
         control = await startControlServer({
-            handler: createRouteKitControlHandler(handlers),
+            handler: dispatch,
             token: generateControlToken(),
             product: ROUTEKIT_PRODUCT,
             packageVersion: options.packageVersion,
@@ -1500,6 +1621,14 @@ export async function startRouteKitDaemon(options) {
             dataPort: proxy.port(),
             startedAt
         });
+        daemonTelemetry.capture("routekit.daemon_lifecycle", {
+            action: "started",
+            outcome: "success",
+            supervisor: ["systemd", "launchd", "detached"].includes(supervisorFromEnv(env))
+                ? supervisorFromEnv(env)
+                : "unknown",
+            version: options.packageVersion
+        });
         extendCleanupGrace(drainGraceMs + 10_000);
         let closeRun;
         const close = () => {
@@ -1509,6 +1638,16 @@ export async function startRouteKitDaemon(options) {
                     lifecycle = "quiescing";
                 draining = true;
                 await mutationTail;
+                gatewayTelemetry?.close();
+                daemonTelemetry?.capture("routekit.daemon_lifecycle", {
+                    action: "stopped",
+                    outcome: "success",
+                    supervisor: ["systemd", "launchd", "detached"].includes(supervisorFromEnv(env))
+                        ? supervisorFromEnv(env)
+                        : "unknown",
+                    version: options.packageVersion
+                });
+                await daemonTelemetry?.shutdown();
                 lifecycle = "draining";
                 await proxy?.drain(drainGraceMs);
                 await activeRouter?.close();
@@ -1547,6 +1686,8 @@ export async function startRouteKitDaemon(options) {
         };
     }
     catch (error) {
+        gatewayTelemetry?.close();
+        await daemonTelemetry?.shutdown();
         await proxy?.close();
         await activeRouter?.close();
         accountActivity?.close();

package/dist/telemetry.d.ts

@@ -0,0 +1,62 @@
+import type { ModelCallRecord } from "@velum-labs/routekit-gateway";
+import { type ConsentDecision, type TelemetryCategory, type TelemetryEventName, type TelemetryEventProperties } from "@velum-labs/routekit-telemetry-core";
+export declare const DEFAULT_TELEMETRY_HOST = "https://us.i.posthog.com";
+export declare const DEFAULT_TELEMETRY_FLUSH_INTERVAL_MS: number;
+export declare const DEFAULT_TELEMETRY_GROUP_LIMIT = 256;
+export declare const DEFAULT_TELEMETRY_SHUTDOWN_TIMEOUT_MS = 2000;
+export type TelemetryTransportPayload = {
+    distinctId: string;
+    event: string;
+    properties: Record<string, unknown>;
+    disableGeoip: true;
+};
+export type TelemetryTransportClient = {
+    capture(payload: TelemetryTransportPayload): void;
+    flush(): Promise<void>;
+    optOut?(): Promise<void> | void;
+    shutdown(timeoutMs: number): Promise<void> | void;
+};
+export type TelemetryTransportFactory = (key: string, options: {
+    host: string;
+    flushAt: number;
+    flushInterval: number;
+    maxQueueSize: number;
+}) => TelemetryTransportClient;
+export type DaemonTelemetryOptions = {
+    env: NodeJS.ProcessEnv;
+    resolveConsent: (env: NodeJS.ProcessEnv) => ConsentDecision;
+    factory?: TelemetryTransportFactory;
+    shutdownTimeoutMs?: number;
+};
+/** Daemon-owned, consent-gated transport. All payloads pass through the schema builder. */
+export declare class DaemonTelemetry {
+    #private;
+    constructor(options: DaemonTelemetryOptions);
+    capture<N extends TelemetryEventName>(name: N, properties: TelemetryEventProperties[N]): boolean;
+    permitted(category: TelemetryCategory): boolean;
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+    resetTransport(): Promise<void>;
+    discard(): Promise<void>;
+}
+type IntervalHandle = ReturnType<typeof setInterval>;
+export type GatewayTelemetryAggregatorOptions = {
+    telemetry: Pick<DaemonTelemetry, "capture" | "permitted">;
+    version: string;
+    groupLimit?: number;
+    flushIntervalMs?: number;
+    setInterval?: (callback: () => void, ms: number) => IntervalHandle;
+    clearInterval?: (handle: IntervalHandle) => void;
+};
+/** Bounded, in-memory gateway summaries; never retains raw call records. */
+export declare class GatewayTelemetryAggregator {
+    #private;
+    constructor(options: GatewayTelemetryAggregatorOptions);
+    record(record: ModelCallRecord): void;
+    flush(): void;
+    size(): number;
+    /** Drop buffered summaries for an opted-out family without sending them later. */
+    discard(category?: "usage" | "reliability"): void;
+    close(): void;
+}
+export {};

package/dist/telemetry.js

@@ -0,0 +1,352 @@
+import { boundedShutdown, buildTelemetryEvent } from "@velum-labs/routekit-telemetry-core";
+import { PostHog } from "posthog-node";
+export const DEFAULT_TELEMETRY_HOST = "https://us.i.posthog.com";
+export const DEFAULT_TELEMETRY_FLUSH_INTERVAL_MS = 60 * 60 * 1_000;
+export const DEFAULT_TELEMETRY_GROUP_LIMIT = 256;
+export const DEFAULT_TELEMETRY_SHUTDOWN_TIMEOUT_MS = 2_000;
+const postHogFactory = (key, options) => {
+    const client = new PostHog(key, {
+        host: options.host,
+        flushAt: options.flushAt,
+        flushInterval: options.flushInterval,
+        maxQueueSize: options.maxQueueSize,
+        persistence: "memory",
+        enableLocalEvaluation: false,
+        enableExceptionAutocapture: false
+    });
+    return {
+        capture: (payload) => client.capture(payload),
+        flush: async () => await client.flush(),
+        optOut: async () => await client.optOut(),
+        shutdown: async (timeoutMs) => await client.shutdown(timeoutMs)
+    };
+};
+/** Daemon-owned, consent-gated transport. All payloads pass through the schema builder. */
+export class DaemonTelemetry {
+    #env;
+    #resolveConsent;
+    #factory;
+    #shutdownTimeoutMs;
+    #client;
+    #clientKey;
+    #clientHost;
+    constructor(options) {
+        this.#env = options.env;
+        this.#resolveConsent = options.resolveConsent;
+        this.#factory = options.factory ?? postHogFactory;
+        this.#shutdownTimeoutMs = options.shutdownTimeoutMs ?? DEFAULT_TELEMETRY_SHUTDOWN_TIMEOUT_MS;
+    }
+    capture(name, properties) {
+        let built;
+        try {
+            built = buildTelemetryEvent(name, properties);
+            const consent = this.#resolveConsent(this.#env);
+            if (!consent.enabled ||
+                !consent.categories[built.category] ||
+                consent.installId === undefined) {
+                if (!consent.enabled || consent.installId === undefined)
+                    void this.#retireTransport(false);
+                return false;
+            }
+            const client = this.#transport();
+            if (client === undefined)
+                return false;
+            client.capture({
+                distinctId: consent.installId,
+                event: built.event,
+                properties: built.properties,
+                disableGeoip: true
+            });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    permitted(category) {
+        const consent = this.#resolveConsent(this.#env);
+        const permitted = consent.enabled &&
+            consent.categories[category] &&
+            consent.installId !== undefined &&
+            this.#key() !== undefined;
+        if (!consent.enabled || consent.installId === undefined)
+            void this.#retireTransport(false);
+        return permitted;
+    }
+    async flush() {
+        try {
+            const consent = this.#resolveConsent(this.#env);
+            if (!consent.enabled || consent.installId === undefined) {
+                await this.#retireTransport(false);
+                return;
+            }
+            await boundedShutdown(async () => await this.#client?.flush(), this.#shutdownTimeoutMs);
+        }
+        catch {
+            // Telemetry cannot affect product paths.
+        }
+    }
+    async shutdown() {
+        await this.#retireTransport();
+    }
+    async resetTransport() {
+        await this.shutdown();
+    }
+    async discard() {
+        await this.#retireTransport(false);
+    }
+    #key() {
+        const key = this.#env.ROUTEKIT_POSTHOG_KEY?.trim();
+        return key === undefined || key.length === 0 ? undefined : key;
+    }
+    #retireTransport(flush = true) {
+        const client = this.#client;
+        this.#client = undefined;
+        this.#clientKey = undefined;
+        this.#clientHost = undefined;
+        if (client === undefined)
+            return Promise.resolve();
+        return boundedShutdown(async () => {
+            if (!flush)
+                await client.optOut?.();
+            await client.shutdown(this.#shutdownTimeoutMs);
+        }, this.#shutdownTimeoutMs);
+    }
+    #transport() {
+        const key = this.#key();
+        if (key === undefined) {
+            void this.#retireTransport();
+            return undefined;
+        }
+        const host = this.#env.ROUTEKIT_POSTHOG_HOST?.trim() || DEFAULT_TELEMETRY_HOST;
+        if (this.#client !== undefined && this.#clientKey === key && this.#clientHost === host)
+            return this.#client;
+        if (this.#client !== undefined)
+            void this.#retireTransport();
+        this.#client = this.#factory(key, {
+            host,
+            flushAt: 10,
+            flushInterval: 10_000,
+            maxQueueSize: 100
+        });
+        this.#clientKey = key;
+        this.#clientHost = host;
+        return this.#client;
+    }
+}
+function object(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function finite(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+function tokenBucket(value) {
+    const count = finite(value);
+    if (count === undefined)
+        return "unknown";
+    if (count === 0)
+        return "0";
+    if (count < 1_000)
+        return "1-1k";
+    if (count < 10_000)
+        return "1k-10k";
+    if (count < 100_000)
+        return "10k-100k";
+    return ">100k";
+}
+function retryBucket(value) {
+    const count = finite(value) ?? 0;
+    if (count <= 0)
+        return "0";
+    if (count === 1)
+        return "1";
+    if (count === 2)
+        return "2";
+    return "3+";
+}
+function countBucket(count) {
+    if (count === 1)
+        return "1";
+    if (count <= 5)
+        return "2-5";
+    if (count <= 20)
+        return "6-20";
+    return ">20";
+}
+function latencyBucket(ms) {
+    const value = finite(ms) ?? 0;
+    if (value < 1_000)
+        return "<1s";
+    if (value < 10_000)
+        return "1-10s";
+    if (value < 60_000)
+        return "10-60s";
+    if (value < 300_000)
+        return "1-5m";
+    if (value < 1_800_000)
+        return "5-30m";
+    return ">30m";
+}
+function dimensions(record) {
+    const metadata = object(record.metadata);
+    const attribution = object(metadata?.attribution);
+    const provider = typeof attribution?.provider === "string" ? attribution.provider : undefined;
+    const model = typeof attribution?.effective_model === "string" ? attribution.effective_model : undefined;
+    const rawDialect = metadata?.dialect;
+    const dialect = rawDialect === "openai-chat" ||
+        rawDialect === "openai-responses" ||
+        rawDialect === "anthropic-messages" ||
+        rawDialect === "openai-embeddings"
+        ? rawDialect
+        : undefined;
+    if (provider === undefined || model === undefined || dialect === undefined)
+        return undefined;
+    const requestKind = dialect === "openai-chat"
+        ? "chat"
+        : dialect === "openai-responses"
+            ? "responses"
+            : dialect === "anthropic-messages"
+                ? "messages"
+                : "embeddings";
+    const rawBilling = attribution?.billing_mode;
+    const billingMode = rawBilling === "api_key"
+        ? "metered-api"
+        : rawBilling === "subscription"
+            ? "subscription"
+            : rawBilling === "client_auth"
+                ? "upstream-managed"
+                : "unknown";
+    const usage = object(record.usage);
+    return {
+        provider,
+        model,
+        dialect,
+        request_kind: requestKind,
+        stream: metadata?.stream === true,
+        billing_mode: billingMode,
+        outcome: record.status === "succeeded" ? "success" : "error",
+        latency_bucket: latencyBucket(record.latency_ms),
+        retry_bucket: retryBucket(attribution?.retries),
+        input_token_bucket: tokenBucket(usage?.prompt_tokens),
+        output_token_bucket: tokenBucket(usage?.completion_tokens),
+        failover: (finite(attribution?.account_failovers) ?? 0) > 0
+    };
+}
+/** Bounded, in-memory gateway summaries; never retains raw call records. */
+export class GatewayTelemetryAggregator {
+    #telemetry;
+    #version;
+    #groupLimit;
+    #flushIntervalMs;
+    #setInterval;
+    #clearInterval;
+    #groups = new Map();
+    #timer;
+    constructor(options) {
+        this.#telemetry = options.telemetry;
+        this.#version = options.version;
+        this.#groupLimit = options.groupLimit ?? DEFAULT_TELEMETRY_GROUP_LIMIT;
+        this.#flushIntervalMs = options.flushIntervalMs ?? DEFAULT_TELEMETRY_FLUSH_INTERVAL_MS;
+        this.#setInterval = options.setInterval ?? setInterval;
+        this.#clearInterval = options.clearInterval ?? clearInterval;
+    }
+    record(record) {
+        try {
+            if (!this.#telemetry.permitted("usage") && !this.#telemetry.permitted("reliability"))
+                return;
+            const value = dimensions(record);
+            if (value === undefined)
+                return;
+            const key = JSON.stringify(value);
+            const current = this.#groups.get(key);
+            if (current !== undefined)
+                current.count += 1;
+            else if (this.#groups.size < this.#groupLimit)
+                this.#groups.set(key, { dimensions: value, count: 1, enqueued: {} });
+            this.#ensureTimer();
+        }
+        catch {
+            // Aggregation cannot affect gateway calls.
+        }
+    }
+    flush() {
+        const usagePermitted = this.#telemetry.permitted("usage");
+        const reliabilityPermitted = this.#telemetry.permitted("reliability");
+        if (!usagePermitted && !reliabilityPermitted) {
+            this.discard();
+            return;
+        }
+        for (const [key, entry] of this.#groups) {
+            const common = {
+                provider: entry.dimensions.provider,
+                model: entry.dimensions.model,
+                dialect: entry.dimensions.dialect,
+                request_kind: entry.dimensions.request_kind,
+                stream: entry.dimensions.stream,
+                request_count_bucket: countBucket(entry.count),
+                version: this.#version
+            };
+            const usageCaptured = !usagePermitted ||
+                entry.enqueued.usage === true ||
+                this.#telemetry.capture("routekit.gateway_usage_summary", {
+                    ...common,
+                    billing_mode: entry.dimensions.billing_mode,
+                    input_token_bucket: entry.dimensions.input_token_bucket,
+                    output_token_bucket: entry.dimensions.output_token_bucket
+                });
+            if (usagePermitted && usageCaptured)
+                entry.enqueued.usage = true;
+            const reliabilityCaptured = !reliabilityPermitted ||
+                entry.enqueued.reliability === true ||
+                this.#telemetry.capture("routekit.gateway_reliability_summary", {
+                    ...common,
+                    outcome: entry.dimensions.outcome,
+                    latency_bucket: entry.dimensions.latency_bucket,
+                    retry_bucket: entry.dimensions.retry_bucket,
+                    failover: entry.dimensions.failover
+                });
+            if (reliabilityPermitted && reliabilityCaptured)
+                entry.enqueued.reliability = true;
+            if (usageCaptured && reliabilityCaptured)
+                this.#groups.delete(key);
+        }
+        if (this.#groups.size === 0)
+            this.#stopTimer();
+    }
+    size() {
+        return this.#groups.size;
+    }
+    /** Drop buffered summaries for an opted-out family without sending them later. */
+    discard(category) {
+        if (category === undefined) {
+            this.#groups.clear();
+        }
+        else {
+            for (const [key, entry] of this.#groups) {
+                entry.enqueued[category] = true;
+                if (entry.enqueued.usage === true && entry.enqueued.reliability === true) {
+                    this.#groups.delete(key);
+                }
+            }
+        }
+        if (this.#groups.size === 0)
+            this.#stopTimer();
+    }
+    close() {
+        this.#stopTimer();
+        this.flush();
+    }
+    #ensureTimer() {
+        if (this.#timer !== undefined)
+            return;
+        this.#timer = this.#setInterval(() => this.flush(), this.#flushIntervalMs);
+        this.#timer.unref?.();
+    }
+    #stopTimer() {
+        if (this.#timer !== undefined)
+            this.#clearInterval(this.#timer);
+        this.#timer = undefined;
+    }
+}

package/dist/test/daemon.test.js

@@ -1345,3 +1345,61 @@ test("daemon recovers interrupted activation before loading config or starting r
 test("daemon recovers interrupted Claude activation before loading config or starting routers", async () => {
     await assertInterruptedNativeActivationRecovery("claude-code");
 });
+test("daemon telemetry emits lifecycle and committed operations exactly once without parameters", async () => {
+    const root = mkdtempSync(join(tmpdir(), "routekit-daemon-telemetry-"));
+    const stateHome = join(root, "state");
+    const configPath = join(root, "router.yaml");
+    mkdirSync(stateHome, { recursive: true });
+    writeFileSync(join(stateHome, "telemetry.json"), JSON.stringify({
+        enabled: true,
+        installId: "telemetry-test-install",
+        categories: { usage: true, reliability: true, adoption: true }
+    }));
+    writeFileSync(configPath, "providers:\n  openai: {}\ndefaultModel: openai/mock-model\n");
+    const upstream = await mockProvider();
+    const payloads = [];
+    const daemon = await startRouteKitDaemon({
+        packageVersion: "1.2.3",
+        stateHome,
+        configPath,
+        port: 0,
+        portless: false,
+        env: {
+            ...process.env,
+            HOME: root,
+            ROUTEKIT_HOME: stateHome,
+            OPENAI_API_KEY: "unique-api-key-canary",
+            OPENAI_BASE_URL: upstream.url,
+            ROUTEKIT_POSTHOG_KEY: "test-key",
+            ROUTEKIT_PORTLESS: "0"
+        },
+        telemetryTransportFactory: () => ({
+            capture: (payload) => payloads.push(payload),
+            flush: async () => undefined,
+            shutdown: async () => undefined
+        })
+    });
+    try {
+        const client = new RouteKitControlClient({
+            url: daemon.record.url,
+            token: daemon.record.controlToken
+        });
+        const snapshot = await client.call("config.get", {});
+        const params = {
+            expectedRevision: snapshot.revision,
+            document: "providers:\n  openai: {}\ndefaultModel: openai/mock-model\n"
+        };
+        await client.call("config.update", params, { idempotencyKey: "telemetry-once" });
+        await client.call("config.update", params, { idempotencyKey: "telemetry-once" });
+        assert.equal(payloads.filter((item) => item.event === "routekit.product_operation_completed").length, 1);
+        const serialized = JSON.stringify(payloads);
+        assert.doesNotMatch(serialized, /unique-api-key-canary|OPENAI_BASE_URL|expectedRevision|document|telemetry-once/);
+        assert.equal(payloads.filter((item) => item.event === "routekit.daemon_lifecycle" && item.properties.action === "started").length, 1);
+    }
+    finally {
+        await daemon.close();
+        await upstream.close();
+        assert.equal(payloads.filter((item) => item.event === "routekit.daemon_lifecycle" && item.properties.action === "stopped").length, 1);
+        rmSync(root, { recursive: true, force: true });
+    }
+});

package/dist/test/telemetry.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/telemetry.test.js

@@ -0,0 +1,493 @@
+import assert from "node:assert/strict";
+import { createServer } from "node:http";
+import test from "node:test";
+import { gunzipSync, inflateSync } from "node:zlib";
+import { DaemonTelemetry, GatewayTelemetryAggregator } from "../telemetry.js";
+function consent(enabled = true, categories = {}) {
+    return {
+        enabled,
+        source: "config",
+        categories: { usage: true, reliability: true, adoption: true, ...categories },
+        ...(enabled ? { installId: "stable-install" } : {})
+    };
+}
+function record(overrides = {}) {
+    return {
+        call_id: "forbidden-call-id",
+        endpoint_id: "forbidden-endpoint",
+        model: "openai/gpt-5.2",
+        request_hash: "forbidden-request-hash",
+        response_hash: "forbidden-response-hash",
+        messages: [{ role: "user", content: "forbidden-body" }],
+        status: "succeeded",
+        side_effects: "none",
+        started_at: "2026-07-28T12:34:56.789Z",
+        latency_ms: 1_500,
+        usage: { prompt_tokens: 2_000, completion_tokens: 20 },
+        metadata: {
+            dialect: "openai-responses",
+            stream: true,
+            attribution: {
+                provider: "openai",
+                effective_model: "openai/gpt-5.2",
+                billing_mode: "api_key",
+                retries: 1,
+                account_failovers: 1,
+                principal: { token_id: "forbidden-principal" },
+                account: { seat: "forbidden-account" }
+            },
+            raw_error: "forbidden-error",
+            cost_estimate_usd: 12.3456789
+        },
+        ...overrides
+    };
+}
+function fixture(decision = consent(), env = { ROUTEKIT_POSTHOG_KEY: "key" }) {
+    const payloads = [];
+    let created = 0;
+    let flushed = 0;
+    let shutdown = 0;
+    const client = {
+        capture: (payload) => {
+            payloads.push(payload);
+        },
+        flush: async () => {
+            flushed += 1;
+        },
+        shutdown: async () => {
+            shutdown += 1;
+        }
+    };
+    const telemetry = new DaemonTelemetry({
+        env,
+        resolveConsent: () => decision,
+        factory: () => {
+            created += 1;
+            return client;
+        },
+        shutdownTimeoutMs: 20
+    });
+    return {
+        telemetry,
+        payloads,
+        created: () => created,
+        flushed: () => flushed,
+        shutdown: () => shutdown
+    };
+}
+test("transport stays absent while disabled, DNT-equivalent, category-disabled, or unconfigured", () => {
+    for (const [decision, env] of [
+        [consent(false), { ROUTEKIT_POSTHOG_KEY: "key" }],
+        [consent(true, { reliability: false }), { ROUTEKIT_POSTHOG_KEY: "key" }],
+        [consent(), {}]
+    ]) {
+        const item = fixture(decision, env);
+        assert.equal(item.telemetry.capture("routekit.daemon_lifecycle", {
+            action: "started",
+            outcome: "success",
+            supervisor: "unknown",
+            version: "test"
+        }), false);
+        assert.equal(item.created(), 0);
+    }
+});
+test("transport payload has stable identity and mandatory privacy flags", () => {
+    const item = fixture();
+    assert.equal(item.telemetry.capture("routekit.daemon_lifecycle", {
+        action: "started",
+        outcome: "success",
+        supervisor: "unknown",
+        version: "test"
+    }), true);
+    assert.equal(item.telemetry.capture("routekit.daemon_lifecycle", {
+        action: "reloaded",
+        outcome: "success",
+        supervisor: "unknown",
+        version: "test"
+    }), true);
+    assert.equal(item.created(), 1);
+    assert.deepEqual(item.payloads.map((payload) => payload.distinctId), ["stable-install", "stable-install"]);
+    assert.equal(item.payloads[0]?.disableGeoip, true);
+    assert.equal(item.payloads[0]?.properties.$process_person_profile, false);
+    assert.equal(item.payloads[0]?.properties.$ip, null);
+});
+test("real PostHog transport serializes one anonymous privacy-hardened batch", async () => {
+    const requests = [];
+    const server = createServer((request, response) => {
+        const chunks = [];
+        request.on("data", (chunk) => chunks.push(chunk));
+        request.on("end", () => {
+            let body = Buffer.concat(chunks);
+            if (request.headers["content-encoding"] === "gzip")
+                body = gunzipSync(body);
+            if (request.headers["content-encoding"] === "deflate")
+                body = inflateSync(body);
+            requests.push({ url: request.url, body: body.toString("utf8") });
+            response.writeHead(200, { "content-type": "application/json" });
+            response.end("{}");
+        });
+    });
+    await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+    const port = server.address().port;
+    const telemetry = new DaemonTelemetry({
+        env: {
+            ROUTEKIT_POSTHOG_KEY: "phc_local_test",
+            ROUTEKIT_POSTHOG_HOST: `http://127.0.0.1:${port}`
+        },
+        resolveConsent: () => consent()
+    });
+    try {
+        assert.equal(telemetry.capture("routekit.command_completed", {
+            command: "status",
+            cli_version: "0.17.0",
+            os: "darwin",
+            arch: "arm64",
+            node_major: "22",
+            duration_bucket: "<1s",
+            outcome: "success",
+            exit_kind: "success",
+            is_ci: false,
+            target_kind: "local"
+        }), true);
+        await telemetry.flush();
+        await telemetry.shutdown();
+    }
+    finally {
+        await new Promise((resolve) => server.close(() => resolve()));
+    }
+    assert.equal(requests.length, 1);
+    assert.equal(requests[0]?.url, "/batch/");
+    const batch = JSON.parse(requests[0].body);
+    const event = batch.batch[0];
+    assert.equal(event.event, "routekit.command_completed");
+    assert.equal(event.distinct_id, "stable-install");
+    assert.equal(event.properties.$process_person_profile, false);
+    assert.equal(event.properties.$ip, null);
+    assert.equal(event.properties.$geoip_disable, true);
+    assert.doesNotMatch(JSON.stringify(event), /prompt|argv|cwd|stack|api_key/i);
+});
+test("out-of-band consent revoke discards the real PostHog queue without a request", async () => {
+    let requests = 0;
+    const server = createServer((request, response) => {
+        requests += 1;
+        request.resume();
+        response.end("{}");
+    });
+    await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+    const port = server.address().port;
+    let decision = consent();
+    const telemetry = new DaemonTelemetry({
+        env: {
+            ROUTEKIT_POSTHOG_KEY: "phc_local_test",
+            ROUTEKIT_POSTHOG_HOST: `http://127.0.0.1:${port}`
+        },
+        resolveConsent: () => decision
+    });
+    try {
+        assert.equal(telemetry.capture("routekit.daemon_lifecycle", {
+            action: "started",
+            outcome: "success",
+            supervisor: "unknown",
+            version: "test"
+        }), true);
+        decision = consent(false);
+        assert.equal(telemetry.capture("routekit.daemon_lifecycle", {
+            action: "stopped",
+            outcome: "success",
+            supervisor: "unknown",
+            version: "test"
+        }), false);
+        await new Promise((resolve) => setImmediate(resolve));
+    }
+    finally {
+        await telemetry.shutdown();
+        await new Promise((resolve) => server.close(() => resolve()));
+    }
+    assert.equal(requests, 0);
+});
+test("transport failures are isolated and shutdown is bounded", async () => {
+    const telemetry = new DaemonTelemetry({
+        env: { ROUTEKIT_POSTHOG_KEY: "key" },
+        resolveConsent: () => consent(),
+        factory: () => ({
+            capture: () => {
+                throw new Error("capture failed");
+            },
+            flush: async () => {
+                throw new Error("flush failed");
+            },
+            shutdown: async () => await new Promise(() => undefined)
+        }),
+        shutdownTimeoutMs: 20
+    });
+    assert.equal(telemetry.capture("routekit.daemon_lifecycle", {
+        action: "started",
+        outcome: "success",
+        supervisor: "unknown",
+        version: "test"
+    }), false);
+    const started = Date.now();
+    await telemetry.shutdown();
+    assert.ok(Date.now() - started < 200);
+});
+test("key transitions retire stale transports and consent denial never flushes implicitly", async () => {
+    const env = { ROUTEKIT_POSTHOG_KEY: "key-one" };
+    let decision = consent();
+    const clients = [];
+    const telemetry = new DaemonTelemetry({
+        env,
+        resolveConsent: () => decision,
+        factory: () => {
+            const state = { shutdowns: 0, optOuts: 0 };
+            clients.push(state);
+            return {
+                capture: () => undefined,
+                flush: async () => undefined,
+                optOut: async () => {
+                    state.optOuts += 1;
+                },
+                shutdown: async () => {
+                    state.shutdowns += 1;
+                }
+            };
+        }
+    });
+    assert.equal(telemetry.capture("routekit.daemon_lifecycle", {
+        action: "started",
+        outcome: "success",
+        supervisor: "unknown",
+        version: "test"
+    }), true);
+    env.ROUTEKIT_POSTHOG_KEY = "key-two";
+    assert.equal(telemetry.capture("routekit.daemon_lifecycle", {
+        action: "reloaded",
+        outcome: "success",
+        supervisor: "unknown",
+        version: "test"
+    }), true);
+    await new Promise((resolve) => setImmediate(resolve));
+    assert.equal(clients[0]?.shutdowns, 1);
+    decision = consent(false);
+    assert.equal(telemetry.capture("routekit.daemon_lifecycle", {
+        action: "stopped",
+        outcome: "success",
+        supervisor: "unknown",
+        version: "test"
+    }), false);
+    await new Promise((resolve) => setImmediate(resolve));
+    assert.equal(clients[1]?.optOuts, 1);
+    assert.equal(clients[1]?.shutdowns, 1);
+    await telemetry.shutdown();
+    assert.equal(clients[1]?.shutdowns, 1);
+    assert.equal(clients.length, 2);
+});
+test("aggregator groups locally and emits no per-call event", () => {
+    const item = fixture();
+    const aggregator = new GatewayTelemetryAggregator({
+        telemetry: item.telemetry,
+        version: "0.17.0",
+        flushIntervalMs: 60_000
+    });
+    aggregator.record(record());
+    aggregator.record(record({ call_id: "another-sensitive-id" }));
+    assert.equal(item.payloads.length, 0);
+    assert.equal(aggregator.size(), 1);
+    aggregator.flush();
+    assert.equal(item.payloads.length, 2);
+    assert.deepEqual(item.payloads.map((payload) => payload.event), ["routekit.gateway_usage_summary", "routekit.gateway_reliability_summary"]);
+    assert.equal(item.payloads[0]?.properties.request_count_bucket, "2-5");
+    assert.equal("outcome" in item.payloads[0].properties, false);
+    assert.equal("latency_bucket" in item.payloads[0].properties, false);
+    assert.equal("input_token_bucket" in item.payloads[1].properties, false);
+    assert.equal("billing_mode" in item.payloads[1].properties, false);
+    assert.equal(aggregator.size(), 0);
+    assert.doesNotMatch(JSON.stringify(item.payloads), /forbidden|12\.3456789|2026-07-28/);
+    aggregator.close();
+});
+test("aggregator bounds cardinality and keeps groups when enqueue fails", () => {
+    const successful = fixture();
+    const aggregator = new GatewayTelemetryAggregator({
+        telemetry: successful.telemetry,
+        version: "0.17.0",
+        groupLimit: 2
+    });
+    aggregator.record(record());
+    aggregator.record(record({
+        metadata: {
+            ...record().metadata,
+            attribution: {
+                ...record().metadata?.attribution,
+                effective_model: "openai/gpt-5.3"
+            }
+        }
+    }));
+    aggregator.record(record({
+        metadata: {
+            ...record().metadata,
+            attribution: {
+                ...record().metadata?.attribution,
+                effective_model: "openai/gpt-5.4"
+            }
+        }
+    }));
+    assert.equal(aggregator.size(), 2);
+    aggregator.close();
+    const failing = new GatewayTelemetryAggregator({
+        telemetry: { permitted: () => true, capture: () => false },
+        version: "0.17.0"
+    });
+    failing.record(record());
+    failing.flush();
+    assert.equal(failing.size(), 1);
+    failing.close();
+});
+test("aggregator gates collection and each payload family on live categories", () => {
+    const disabled = new GatewayTelemetryAggregator({
+        telemetry: fixture(consent(false)).telemetry,
+        version: "0.17.0"
+    });
+    disabled.record(record());
+    assert.equal(disabled.size(), 0);
+    disabled.close();
+    for (const [categories, expected] of [
+        [{ usage: true, reliability: false }, ["routekit.gateway_usage_summary"]],
+        [{ usage: false, reliability: true }, ["routekit.gateway_reliability_summary"]]
+    ]) {
+        const item = fixture(consent(true, categories));
+        const aggregator = new GatewayTelemetryAggregator({
+            telemetry: item.telemetry,
+            version: "0.17.0"
+        });
+        aggregator.record(record());
+        aggregator.flush();
+        assert.deepEqual(item.payloads.map((payload) => payload.event), expected);
+        assert.equal(aggregator.size(), 0);
+        aggregator.close();
+    }
+});
+test("aggregator discards opted-out summaries before a category or identity can be re-enabled", () => {
+    const captured = [];
+    const aggregator = new GatewayTelemetryAggregator({
+        telemetry: {
+            permitted: () => true,
+            capture: (name) => {
+                captured.push(name);
+                return true;
+            }
+        },
+        version: "0.17.0"
+    });
+    aggregator.record(record());
+    aggregator.discard("usage");
+    aggregator.flush();
+    assert.deepEqual(captured, ["routekit.gateway_reliability_summary"]);
+    assert.equal(aggregator.size(), 0);
+    aggregator.record(record());
+    aggregator.discard();
+    aggregator.flush();
+    assert.deepEqual(captured, ["routekit.gateway_reliability_summary"]);
+    assert.equal(aggregator.size(), 0);
+    aggregator.close();
+});
+test("aggregator retains a group until every currently permitted family enqueues", () => {
+    const captured = [];
+    let reliabilitySucceeds = false;
+    const aggregator = new GatewayTelemetryAggregator({
+        telemetry: {
+            permitted: () => true,
+            capture: (name) => {
+                captured.push(name);
+                return name === "routekit.gateway_usage_summary" || reliabilitySucceeds;
+            }
+        },
+        version: "0.17.0"
+    });
+    aggregator.record(record());
+    aggregator.flush();
+    assert.equal(aggregator.size(), 1);
+    reliabilitySucceeds = true;
+    aggregator.flush();
+    assert.equal(aggregator.size(), 0);
+    assert.deepEqual(captured, [
+        "routekit.gateway_usage_summary",
+        "routekit.gateway_reliability_summary",
+        "routekit.gateway_reliability_summary"
+    ]);
+    aggregator.close();
+});
+test("serialized payloads reject adversarial sensitive canaries across all families", () => {
+    const item = fixture();
+    const families = [
+        [
+            "routekit.command_completed",
+            {
+                command: "status",
+                cli_version: "0.17.0",
+                os: "darwin",
+                arch: "arm64",
+                node_major: "22",
+                duration_bucket: "<1s",
+                outcome: "success",
+                exit_kind: "success",
+                is_ci: false,
+                target_kind: "local"
+            }
+        ],
+        [
+            "routekit.product_operation_completed",
+            { operation: "config_update", outcome: "error", duration_bucket: "<1s", version: "0.17.0" }
+        ],
+        [
+            "routekit.daemon_lifecycle",
+            { action: "started", outcome: "success", supervisor: "detached", version: "0.17.0" }
+        ],
+        [
+            "routekit.telemetry_preference_changed",
+            { action: "master", enabled: true, source: "config", version: "0.17.0" }
+        ]
+    ];
+    for (const [name, properties] of families)
+        item.telemetry.capture(name, properties);
+    const aggregator = new GatewayTelemetryAggregator({
+        telemetry: item.telemetry,
+        version: "0.17.0"
+    });
+    aggregator.record(record({
+        metadata: {
+            ...record().metadata,
+            prompt: "forbidden-prompt",
+            source_path: "/Users/private/source.ts",
+            api_key: "sk-secret",
+            oauth_token: "oauth-secret",
+            account_id: "acct-secret",
+            principal_label: "private-user",
+            request_body: "raw-body",
+            raw_error: "stack trace",
+            exact_cost: 9.87654321,
+            exact_usage: 2345,
+            exact_time: "2026-07-28T12:34:56Z"
+        }
+    }));
+    aggregator.flush();
+    const serialized = JSON.stringify(item.payloads);
+    for (const canary of [
+        "forbidden-prompt",
+        "/Users/private",
+        "sk-secret",
+        "oauth-secret",
+        "acct-secret",
+        "private-user",
+        "raw-body",
+        "stack trace",
+        "9.87654321",
+        "2345",
+        "2026-07-28T12:34:56Z",
+        "forbidden-call-id",
+        "forbidden-request-hash"
+    ]) {
+        assert.doesNotMatch(serialized, new RegExp(canary.replace(/[.*+?^${}()|[\\]\\]/g, "\\$&")));
+    }
+    assert.match(serialized, /openai\/gpt-5\.2/);
+    assert.match(serialized, /1k-10k/);
+    aggregator.close();
+});

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@velum-labs/routekit-daemon",
   "private": false,
-  "version": "0.16.4",
+  "version": "0.16.6",
   "description": "Singleton RouteKit control daemon and stable model gateway.",
   "repository": {
     "type": "git",
@@ -33,15 +33,16 @@
     "service"
   ],
   "dependencies": {
+    "posthog-node": "5.46.1",
     "yaml": "2.9.0",
-    "@velum-labs/routekit-accounts": "0.16.4",
-    "@velum-labs/routekit-config": "0.16.4",
-    "@velum-labs/routekit-control": "0.16.4",
-    "@velum-labs/routekit-gateway": "0.16.4",
-    "@velum-labs/routekit-registry": "0.16.4",
-    "@velum-labs/routekit-router": "0.16.4",
-    "@velum-labs/routekit-runtime": "0.16.4",
-    "@velum-labs/routekit-telemetry-core": "0.16.4"
+    "@velum-labs/routekit-accounts": "0.16.6",
+    "@velum-labs/routekit-config": "0.16.6",
+    "@velum-labs/routekit-control": "0.16.6",
+    "@velum-labs/routekit-gateway": "0.16.6",
+    "@velum-labs/routekit-registry": "0.16.6",
+    "@velum-labs/routekit-router": "0.16.6",
+    "@velum-labs/routekit-runtime": "0.16.6",
+    "@velum-labs/routekit-telemetry-core": "0.16.6"
   },
   "scripts": {
     "build": "tsc -b",