codesift-mcp 0.9.10 → 0.10.1

package/dist/storage/telemetry/config.js

@@ -0,0 +1,130 @@
+// Telemetry level resolution + opt-out. No network here — this module only
+// decides WHETHER and at what level telemetry runs. See spec
+// docs/specs/2026-07-19-telemetry-spec.md §4.
+import { readFileSync, writeFileSync, mkdirSync, renameSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+/** Bump when the L1 payload shape changes. Collector tolerates unknown versions. */
+export const TELEMETRY_SCHEMA_VERSION = 1;
+function dataDir() {
+    return process.env["CODESIFT_DATA_DIR"] ?? join(homedir(), ".codesift");
+}
+export function getConfigPath() {
+    return join(dataDir(), "config.json");
+}
+/** Best-effort read of ~/.codesift/config.json — never throws. */
+export function readStoredConfig() {
+    try {
+        const raw = readFileSync(getConfigPath(), "utf-8");
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === "object")
+            return parsed;
+    }
+    catch {
+        /* absent or malformed → defaults */
+    }
+    return {};
+}
+function normalizeLevel(v) {
+    if (typeof v !== "string")
+        return null;
+    const s = v.trim().toLowerCase();
+    if (s === "off" || s === "0" || s === "false" || s === "no")
+        return "off";
+    if (s === "full")
+        return "full";
+    if (s === "anon" || s === "on" || s === "1" || s === "true" || s === "anonymous")
+        return "anon";
+    return null;
+}
+function isTruthyEnv(v) {
+    if (!v)
+        return false;
+    const s = v.trim().toLowerCase();
+    return s !== "" && s !== "0" && s !== "false" && s !== "no";
+}
+/**
+ * Resolve the effective telemetry level. Precedence (first match wins):
+ *   1. DO_NOT_TRACK truthy            → off   (respect the cross-tool standard)
+ *   2. CODESIFT_TELEMETRY env         → off | anon | full
+ *   3. config.json `telemetry`        → off | anon | full   (level string or {level})
+ *   4. default                        → anon  (opt-out model — spec decision)
+ */
+export function resolveTelemetryLevel() {
+    if (isTruthyEnv(process.env["DO_NOT_TRACK"]))
+        return "off";
+    const fromEnv = normalizeLevel(process.env["CODESIFT_TELEMETRY"]);
+    if (fromEnv)
+        return fromEnv;
+    const stored = readStoredConfig().telemetry;
+    const fromStore = normalizeLevel(typeof stored === "object" && stored !== null ? stored.level : stored);
+    if (fromStore)
+        return fromStore;
+    return "anon";
+}
+/**
+ * Persist the telemetry level into ~/.codesift/config.json (merging with any
+ * existing config). Atomic tmp+rename. Used by `codesift telemetry on|off|full`.
+ */
+export function writeStoredTelemetryLevel(level) {
+    const path = getConfigPath();
+    let cfg = {};
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf-8"));
+        if (parsed && typeof parsed === "object")
+            cfg = parsed;
+    }
+    catch {
+        /* absent/malformed → start fresh */
+    }
+    cfg["telemetry"] = { level };
+    mkdirSync(dataDir(), { recursive: true });
+    const tmp = path + ".tmp";
+    writeFileSync(tmp, JSON.stringify(cfg, null, 2) + "\n", "utf-8");
+    renameSync(tmp, path);
+}
+function noticePath() {
+    return join(dataDir(), "telemetry-notice-shown");
+}
+/**
+ * Print the one-time consent notice to STDERR (spec §4). Shown once per machine
+ * when telemetry is anon, then a marker file suppresses it. STDERR so it never
+ * corrupts the MCP stdio protocol. Best-effort — never throws.
+ */
+export function maybePrintFirstRunNotice() {
+    try {
+        if (resolveTelemetryLevel() !== "anon")
+            return;
+        const marker = noticePath();
+        try {
+            readFileSync(marker, "utf-8");
+            return; // already shown
+        }
+        catch {
+            /* not shown yet */
+        }
+        process.stderr.write("[codesift] Anonymous usage stats are ON (tool names, latencies, error/empty rates,\n" +
+            "  bucketed env — NO queries, paths, repo names or code). See exactly what is sent:\n" +
+            "  `codesift telemetry show`.  Opt out: CODESIFT_TELEMETRY=off (or DO_NOT_TRACK=1).\n");
+        mkdirSync(dataDir(), { recursive: true });
+        writeFileSync(marker, String(Date.now()) + "\n", "utf-8");
+    }
+    catch {
+        /* ignore */
+    }
+}
+/** Human-readable reason for the current level — powers `codesift telemetry show`. */
+export function telemetrySource() {
+    if (isTruthyEnv(process.env["DO_NOT_TRACK"])) {
+        return { level: "off", reason: "DO_NOT_TRACK env is set" };
+    }
+    const fromEnv = normalizeLevel(process.env["CODESIFT_TELEMETRY"]);
+    if (fromEnv)
+        return { level: fromEnv, reason: `CODESIFT_TELEMETRY=${process.env["CODESIFT_TELEMETRY"]}` };
+    const stored = readStoredConfig().telemetry;
+    const fromStore = normalizeLevel(typeof stored === "object" && stored !== null ? stored.level : stored);
+    if (fromStore)
+        return { level: fromStore, reason: `config.json telemetry=${fromStore}` };
+    return { level: "anon", reason: "default (anonymous, opt-out)" };
+}
+//# sourceMappingURL=config.js.map

package/dist/storage/telemetry/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../src/storage/telemetry/config.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,6DAA6D;AAC7D,8CAA8C;AAC9C,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAIlC,oFAAoF;AACpF,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC;AAE1C,SAAS,OAAO;IACd,OAAO,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE,WAAW,CAAC,CAAC;AAC1E,CAAC;AAED,MAAM,UAAU,aAAa;IAC3B,OAAO,IAAI,CAAC,OAAO,EAAE,EAAE,aAAa,CAAC,CAAC;AACxC,CAAC;AAMD,kEAAkE;AAClE,MAAM,UAAU,gBAAgB;IAC9B,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,YAAY,CAAC,aAAa,EAAE,EAAE,OAAO,CAAC,CAAC;QACnD,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACxC,IAAI,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ;YAAE,OAAO,MAAsB,CAAC;IAC1E,CAAC;IAAC,MAAM,CAAC;QACP,oCAAoC;IACtC,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,SAAS,cAAc,CAAC,CAAU;IAChC,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACvC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACjC,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,OAAO,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC1E,IAAI,CAAC,KAAK,MAAM;QAAE,OAAO,MAAM,CAAC;IAChC,IAAI,CAAC,KAAK,MAAM,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,MAAM,IAAI,CAAC,KAAK,WAAW;QAAE,OAAO,MAAM,CAAC;IAChG,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,WAAW,CAAC,CAAqB;IACxC,IAAI,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IACrB,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACjC,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,OAAO,IAAI,CAAC,KAAK,IAAI,CAAC;AAC9D,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB;IACnC,IAAI,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IAE3D,MAAM,OAAO,GAAG,cAAc,CAAC,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAC,CAAC;IAClE,IAAI,OAAO;QAAE,OAAO,OAAO,CAAC;IAE5B,MAAM,MAAM,GAAG,gBAAgB,EAAE,CAAC,SAAS,CAAC;IAC5C,MAAM,SAAS,GAAG,cAAc,CAC9B,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CACtE,CAAC;IACF,IAAI,SAAS;QAAE,OAAO,SAAS,CAAC;IAEhC,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,yBAAyB,CAAC,KAAqB;IAC7D,MAAM,IAAI,GAAG,aAAa,EAAE,CAAC;IAC7B,IAAI,GAAG,GAA4B,EAAE,CAAC;IACtC,IAAI,CAAC;QACH,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;QAChE,IAAI,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ;YAAE,GAAG,GAAG,MAAiC,CAAC;IACpF,CAAC;IAAC,MAAM,CAAC;QACP,oCAAoC;IACtC,CAAC;IACD,GAAG,CAAC,WAAW,CAAC,GAAG,EAAE,KAAK,EAAE,CAAC;IAC7B,SAAS,CAAC,OAAO,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1C,MAAM,GAAG,GAAG,IAAI,GAAG,MAAM,CAAC;IAC1B,aAAa,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,CAAC,CAAC;IACjE,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;AACxB,CAAC;AAED,SAAS,UAAU;IACjB,OAAO,IAAI,CAAC,OAAO,EAAE,EAAE,wBAAwB,CAAC,CAAC;AACnD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,wBAAwB;IACtC,IAAI,CAAC;QACH,IAAI,qBAAqB,EAAE,KAAK,MAAM;YAAE,OAAO;QAC/C,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;QAC5B,IAAI,CAAC;YACH,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;YAC9B,OAAO,CAAC,gBAAgB;QAC1B,CAAC;QAAC,MAAM,CAAC;YACP,mBAAmB;QACrB,CAAC;QACD,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,sFAAsF;YACtF,sFAAsF;YACtF,sFAAsF,CACvF,CAAC;QACF,SAAS,CAAC,OAAO,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1C,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,CAAC,CAAC;IAC5D,CAAC;IAAC,MAAM,CAAC;QACP,YAAY;IACd,CAAC;AACH,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,eAAe;IAC7B,IAAI,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC,EAAE,CAAC;QAC7C,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,yBAAyB,EAAE,CAAC;IAC7D,CAAC;IACD,MAAM,OAAO,GAAG,cAAc,CAAC,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAC,CAAC;IAClE,IAAI,OAAO;QAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,sBAAsB,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC,EAAE,EAAE,CAAC;IAE1G,MAAM,MAAM,GAAG,gBAAgB,EAAE,CAAC,SAAS,CAAC;IAC5C,MAAM,SAAS,GAAG,cAAc,CAC9B,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CACtE,CAAC;IACF,IAAI,SAAS;QAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,yBAAyB,SAAS,EAAE,EAAE,CAAC;IAEzF,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,8BAA8B,EAAE,CAAC;AACnE,CAAC"}

package/dist/storage/telemetry/env-profile.d.ts

@@ -0,0 +1,19 @@
+export interface EnvProfile {
+    platform: string;
+    arch: string;
+    ram_bucket: string;
+    cores: number;
+    node_ver: string;
+    codesift_ver: string;
+    repo_size_bucket?: string;
+    top3_ext?: string[];
+}
+export declare function repoSizeBucket(fileCount: number): string;
+export declare function getCodesiftVersion(): string;
+/** Build the environment profile. Repo dimensions are optional — omitted when
+ *  no repo is in scope (e.g. `telemetry show` outside a project). */
+export declare function buildEnvProfile(repo?: {
+    fileCount: number;
+    topExts: string[];
+}): EnvProfile;
+//# sourceMappingURL=env-profile.d.ts.map

package/dist/storage/telemetry/env-profile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-profile.d.ts","sourceRoot":"","sources":["../../../src/storage/telemetry/env-profile.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAWD,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAKxD;AAID,wBAAgB,kBAAkB,IAAI,MAAM,CAiB3C;AAED;qEACqE;AACrE,wBAAgB,eAAe,CAAC,IAAI,CAAC,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG,UAAU,CAe3F"}

package/dist/storage/telemetry/env-profile.js

@@ -0,0 +1,67 @@
+// Bucketed environment profile — coarse enough that it can never identify a
+// machine, precise enough to slice behaviour by config (spec §1). No hostnames,
+// no paths, no exact counts that could fingerprint.
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import * as os from "node:os";
+function ramBucket(bytes) {
+    const gb = bytes / 1024 ** 3;
+    if (gb < 8)
+        return "<8gb";
+    if (gb < 16)
+        return "8-16gb";
+    if (gb < 32)
+        return "16-32gb";
+    if (gb < 64)
+        return "32-64gb";
+    return ">=64gb";
+}
+export function repoSizeBucket(fileCount) {
+    if (fileCount < 1000)
+        return "<1k";
+    if (fileCount < 10_000)
+        return "1-10k";
+    if (fileCount < 50_000)
+        return "10-50k";
+    return ">50k";
+}
+let versionCache = null;
+export function getCodesiftVersion() {
+    if (versionCache)
+        return versionCache;
+    // package.json sits at the repo root; this module is src|dist/storage/telemetry/.
+    for (const rel of ["../../../package.json", "../../../../package.json"]) {
+        try {
+            const p = fileURLToPath(new URL(rel, import.meta.url));
+            const pkg = JSON.parse(readFileSync(p, "utf-8"));
+            if (pkg.name === "codesift-mcp" && typeof pkg.version === "string") {
+                versionCache = pkg.version;
+                return versionCache;
+            }
+        }
+        catch {
+            /* try next */
+        }
+    }
+    versionCache = "unknown";
+    return versionCache;
+}
+/** Build the environment profile. Repo dimensions are optional — omitted when
+ *  no repo is in scope (e.g. `telemetry show` outside a project). */
+export function buildEnvProfile(repo) {
+    const nodeMajor = process.versions.node.split(".")[0] ?? process.versions.node;
+    const profile = {
+        platform: os.platform(),
+        arch: os.arch(),
+        ram_bucket: ramBucket(os.totalmem()),
+        cores: os.cpus().length,
+        node_ver: nodeMajor,
+        codesift_ver: getCodesiftVersion(),
+    };
+    if (repo) {
+        profile.repo_size_bucket = repoSizeBucket(repo.fileCount);
+        profile.top3_ext = repo.topExts.slice(0, 3);
+    }
+    return profile;
+}
+//# sourceMappingURL=env-profile.js.map

package/dist/storage/telemetry/env-profile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-profile.js","sourceRoot":"","sources":["../../../src/storage/telemetry/env-profile.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,gFAAgF;AAChF,oDAAoD;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAa9B,SAAS,SAAS,CAAC,KAAa;IAC9B,MAAM,EAAE,GAAG,KAAK,GAAG,IAAI,IAAI,CAAC,CAAC;IAC7B,IAAI,EAAE,GAAG,CAAC;QAAE,OAAO,MAAM,CAAC;IAC1B,IAAI,EAAE,GAAG,EAAE;QAAE,OAAO,QAAQ,CAAC;IAC7B,IAAI,EAAE,GAAG,EAAE;QAAE,OAAO,SAAS,CAAC;IAC9B,IAAI,EAAE,GAAG,EAAE;QAAE,OAAO,SAAS,CAAC;IAC9B,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,SAAiB;IAC9C,IAAI,SAAS,GAAG,IAAI;QAAE,OAAO,KAAK,CAAC;IACnC,IAAI,SAAS,GAAG,MAAM;QAAE,OAAO,OAAO,CAAC;IACvC,IAAI,SAAS,GAAG,MAAM;QAAE,OAAO,QAAQ,CAAC;IACxC,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,IAAI,YAAY,GAAkB,IAAI,CAAC;AAEvC,MAAM,UAAU,kBAAkB;IAChC,IAAI,YAAY;QAAE,OAAO,YAAY,CAAC;IACtC,kFAAkF;IAClF,KAAK,MAAM,GAAG,IAAI,CAAC,uBAAuB,EAAE,0BAA0B,CAAC,EAAE,CAAC;QACxE,IAAI,CAAC;YACH,MAAM,CAAC,GAAG,aAAa,CAAC,IAAI,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;YACvD,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,EAAE,OAAO,CAAC,CAAwC,CAAC;YACxF,IAAI,GAAG,CAAC,IAAI,KAAK,cAAc,IAAI,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;gBACnE,YAAY,GAAG,GAAG,CAAC,OAAO,CAAC;gBAC3B,OAAO,YAAY,CAAC;YACtB,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,cAAc;QAChB,CAAC;IACH,CAAC;IACD,YAAY,GAAG,SAAS,CAAC;IACzB,OAAO,YAAY,CAAC;AACtB,CAAC;AAED;qEACqE;AACrE,MAAM,UAAU,eAAe,CAAC,IAA+C;IAC7E,MAAM,SAAS,GAAG,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC;IAC/E,MAAM,OAAO,GAAe;QAC1B,QAAQ,EAAE,EAAE,CAAC,QAAQ,EAAE;QACvB,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE;QACf,UAAU,EAAE,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC;QACpC,KAAK,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,MAAM;QACvB,QAAQ,EAAE,SAAS;QACnB,YAAY,EAAE,kBAAkB,EAAE;KACnC,CAAC;IACF,IAAI,IAAI,EAAE,CAAC;QACT,OAAO,CAAC,gBAAgB,GAAG,cAAc,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAC1D,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC9C,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/storage/telemetry/payload.d.ts

@@ -0,0 +1,8 @@
+import { type Level1Payload } from "./sanitizer.js";
+/**
+ * Build the exact Level-1 payload that would be sent right now, from the local
+ * usage.jsonl. Repo dimensions are omitted here (added per-context at push
+ * time). Runs the sanitizer guard so `telemetry show` proves the allowlist.
+ */
+export declare function buildCurrentLevel1Payload(now: number, sinceTs?: number): Promise<Level1Payload>;
+//# sourceMappingURL=payload.d.ts.map

package/dist/storage/telemetry/payload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payload.d.ts","sourceRoot":"","sources":["../../../src/storage/telemetry/payload.ts"],"names":[],"mappings":"AAKA,OAAO,EAAuC,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEzF;;;;GAIG;AACH,wBAAsB,yBAAyB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,SAAI,GAAG,OAAO,CAAC,aAAa,CAAC,CAShG"}

package/dist/storage/telemetry/payload.js

@@ -0,0 +1,22 @@
+// Convenience assembly used by `codesift telemetry show` and (Phase 3) the
+// uploader: local usage → aggregates → sanitized Level-1 payload.
+import { readLocalUsageEntries, aggregateToolMetrics, aggregateHintFunnel, aggregatePlanTurnFunnel } from "./aggregator.js";
+import { buildEnvProfile } from "./env-profile.js";
+import { getAnonId } from "./anon-id.js";
+import { buildLevel1Payload, assertSanitized } from "./sanitizer.js";
+/**
+ * Build the exact Level-1 payload that would be sent right now, from the local
+ * usage.jsonl. Repo dimensions are omitted here (added per-context at push
+ * time). Runs the sanitizer guard so `telemetry show` proves the allowlist.
+ */
+export async function buildCurrentLevel1Payload(now, sinceTs = 0) {
+    const entries = await readLocalUsageEntries(sinceTs);
+    const tools = aggregateToolMetrics(entries);
+    const hints = aggregateHintFunnel(entries);
+    const planTurn = aggregatePlanTurnFunnel(entries);
+    const env = buildEnvProfile();
+    const payload = buildLevel1Payload({ anonId: getAnonId(), env, tools, hints, planTurn, now });
+    assertSanitized(payload); // throws if the allowlist was ever violated
+    return payload;
+}
+//# sourceMappingURL=payload.js.map

package/dist/storage/telemetry/payload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"payload.js","sourceRoot":"","sources":["../../../src/storage/telemetry/payload.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,kEAAkE;AAClE,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAC5H,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAsB,MAAM,gBAAgB,CAAC;AAEzF;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAAC,GAAW,EAAE,OAAO,GAAG,CAAC;IACtE,MAAM,OAAO,GAAG,MAAM,qBAAqB,CAAC,OAAO,CAAC,CAAC;IACrD,MAAM,KAAK,GAAG,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAC5C,MAAM,KAAK,GAAG,mBAAmB,CAAC,OAAO,CAAC,CAAC;IAC3C,MAAM,QAAQ,GAAG,uBAAuB,CAAC,OAAO,CAAC,CAAC;IAClD,MAAM,GAAG,GAAG,eAAe,EAAE,CAAC;IAC9B,MAAM,OAAO,GAAG,kBAAkB,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,CAAC;IAC9F,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC,4CAA4C;IACtE,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/storage/telemetry/sanitizer.d.ts

@@ -0,0 +1,48 @@
+import type { EnvProfile } from "./env-profile.js";
+import type { ToolAggregate, HintEmission, PlanTurnFunnel } from "./aggregator.js";
+export interface Level1Payload {
+    schema_version: number;
+    ts: number;
+    anon_id: string;
+    env: EnvProfile;
+    tools: Level1ToolMetric[];
+    hints: Level1HintEmission[];
+    plan_turn: Level1PlanTurn[];
+}
+export interface Level1ToolMetric {
+    tool: string;
+    day: string;
+    count: number;
+    p50_ms: number;
+    p95_ms: number;
+    max_ms: number;
+    error_rate: number;
+    empty_result_rate: number;
+    cache_hit_rate: number;
+}
+export interface Level1HintEmission {
+    day: string;
+    hint_code: string;
+    emitted: number;
+    applied: number;
+}
+export interface Level1PlanTurn {
+    day: string;
+    recommended: number;
+    used: number;
+}
+export declare function buildLevel1Payload(input: {
+    anonId: string;
+    env: EnvProfile;
+    tools: ToolAggregate[];
+    hints?: HintEmission[];
+    planTurn?: PlanTurnFunnel[];
+    now: number;
+}): Level1Payload;
+/**
+ * Deep-scan a payload's KEYS for anything forbidden. Throws on violation.
+ * Called from tests and (dev builds) before send — cheap insurance that the
+ * allowlist is actually honoured end-to-end.
+ */
+export declare function assertSanitized(payload: unknown, pathTrace?: string): void;
+//# sourceMappingURL=sanitizer.d.ts.map

package/dist/storage/telemetry/sanitizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitizer.d.ts","sourceRoot":"","sources":["../../../src/storage/telemetry/sanitizer.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEnF,MAAM,WAAW,aAAa;IAC5B,cAAc,EAAE,MAAM,CAAC;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,UAAU,CAAC;IAChB,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAC1B,KAAK,EAAE,kBAAkB,EAAE,CAAC;IAC5B,SAAS,EAAE,cAAc,EAAE,CAAC;CAC7B;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;CACd;AAwCD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,UAAU,CAAC;IAChB,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,KAAK,CAAC,EAAE,YAAY,EAAE,CAAC;IACvB,QAAQ,CAAC,EAAE,cAAc,EAAE,CAAC;IAC5B,GAAG,EAAE,MAAM,CAAC;CACb,GAAG,aAAa,CAUhB;AAYD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,SAAM,GAAG,IAAI,CAavE"}

package/dist/storage/telemetry/sanitizer.js

@@ -0,0 +1,82 @@
+// The ONLY place a Level-1 (anonymous) payload is constructed. Allowlist, not
+// blocklist (spec §1): every field is assembled explicitly here, so adding a
+// new field to the wire format is a conscious edit to this file — never an
+// accidental spread of a raw entry. `assertSanitized` is a defense-in-depth
+// guard that fails loudly (in tests / dev) if a forbidden key ever leaks in.
+import { TELEMETRY_SCHEMA_VERSION } from "./config.js";
+/** Explicitly pick ONLY allowlisted fields from an aggregate. */
+function pickToolMetric(a) {
+    return {
+        tool: a.tool,
+        day: a.day,
+        count: a.count,
+        p50_ms: a.p50_ms,
+        p95_ms: a.p95_ms,
+        max_ms: a.max_ms,
+        error_rate: a.error_rate,
+        empty_result_rate: a.empty_result_rate,
+        cache_hit_rate: a.cache_hit_rate,
+    };
+}
+function pickHint(h) {
+    return { day: h.day, hint_code: h.hint_code, emitted: h.emitted, applied: h.applied };
+}
+function pickPlanTurn(p) {
+    return { day: p.day, recommended: p.recommended, used: p.used };
+}
+/** Explicitly pick ONLY allowlisted env fields (no hostname/paths). */
+function pickEnv(env) {
+    const picked = {
+        platform: env.platform,
+        arch: env.arch,
+        ram_bucket: env.ram_bucket,
+        cores: env.cores,
+        node_ver: env.node_ver,
+        codesift_ver: env.codesift_ver,
+    };
+    if (env.repo_size_bucket !== undefined)
+        picked.repo_size_bucket = env.repo_size_bucket;
+    if (env.top3_ext !== undefined)
+        picked.top3_ext = env.top3_ext.slice(0, 3);
+    return picked;
+}
+export function buildLevel1Payload(input) {
+    return {
+        schema_version: TELEMETRY_SCHEMA_VERSION,
+        ts: input.now,
+        anon_id: input.anonId,
+        env: pickEnv(input.env),
+        tools: input.tools.map(pickToolMetric),
+        hints: (input.hints ?? []).map(pickHint),
+        plan_turn: (input.planTurn ?? []).map(pickPlanTurn),
+    };
+}
+/**
+ * Keys that must NEVER appear anywhere in an L1 payload. Extension identifiers
+ * like ".ts" in top3_ext are fine (they're values, not keys); this checks KEYS.
+ */
+const FORBIDDEN_KEYS = new Set([
+    "query", "repo", "path", "file", "files", "args", "args_summary",
+    "symbol", "symbols", "hostname", "host", "username", "user", "ip",
+    "source", "content", "code", "name", "session_id",
+]);
+/**
+ * Deep-scan a payload's KEYS for anything forbidden. Throws on violation.
+ * Called from tests and (dev builds) before send — cheap insurance that the
+ * allowlist is actually honoured end-to-end.
+ */
+export function assertSanitized(payload, pathTrace = "$") {
+    if (Array.isArray(payload)) {
+        payload.forEach((v, i) => assertSanitized(v, `${pathTrace}[${i}]`));
+        return;
+    }
+    if (payload && typeof payload === "object") {
+        for (const [k, v] of Object.entries(payload)) {
+            if (FORBIDDEN_KEYS.has(k.toLowerCase())) {
+                throw new Error(`telemetry sanitizer: forbidden key "${k}" at ${pathTrace}`);
+            }
+            assertSanitized(v, `${pathTrace}.${k}`);
+        }
+    }
+}
+//# sourceMappingURL=sanitizer.js.map

package/dist/storage/telemetry/sanitizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitizer.js","sourceRoot":"","sources":["../../../src/storage/telemetry/sanitizer.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,6EAA6E;AAC7E,2EAA2E;AAC3E,4EAA4E;AAC5E,6EAA6E;AAC7E,OAAO,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAuCvD,iEAAiE;AACjE,SAAS,cAAc,CAAC,CAAgB;IACtC,OAAO;QACL,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,GAAG,EAAE,CAAC,CAAC,GAAG;QACV,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,UAAU,EAAE,CAAC,CAAC,UAAU;QACxB,iBAAiB,EAAE,CAAC,CAAC,iBAAiB;QACtC,cAAc,EAAE,CAAC,CAAC,cAAc;KACjC,CAAC;AACJ,CAAC;AAED,SAAS,QAAQ,CAAC,CAAe;IAC/B,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;AACxF,CAAC;AAED,SAAS,YAAY,CAAC,CAAiB;IACrC,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,WAAW,EAAE,CAAC,CAAC,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;AAClE,CAAC;AAED,uEAAuE;AACvE,SAAS,OAAO,CAAC,GAAe;IAC9B,MAAM,MAAM,GAAe;QACzB,QAAQ,EAAE,GAAG,CAAC,QAAQ;QACtB,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,UAAU,EAAE,GAAG,CAAC,UAAU;QAC1B,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,QAAQ,EAAE,GAAG,CAAC,QAAQ;QACtB,YAAY,EAAE,GAAG,CAAC,YAAY;KAC/B,CAAC;IACF,IAAI,GAAG,CAAC,gBAAgB,KAAK,SAAS;QAAE,MAAM,CAAC,gBAAgB,GAAG,GAAG,CAAC,gBAAgB,CAAC;IACvF,IAAI,GAAG,CAAC,QAAQ,KAAK,SAAS;QAAE,MAAM,CAAC,QAAQ,GAAG,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC3E,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,KAOlC;IACC,OAAO;QACL,cAAc,EAAE,wBAAwB;QACxC,EAAE,EAAE,KAAK,CAAC,GAAG;QACb,OAAO,EAAE,KAAK,CAAC,MAAM;QACrB,GAAG,EAAE,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC;QACvB,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC;QACtC,KAAK,EAAE,CAAC,KAAK,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC;QACxC,SAAS,EAAE,CAAC,KAAK,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC;KACpD,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC;IAC7B,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,cAAc;IAChE,QAAQ,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI;IACjE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY;CAClD,CAAC,CAAC;AAEH;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,OAAgB,EAAE,SAAS,GAAG,GAAG;IAC/D,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QAC3B,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,eAAe,CAAC,CAAC,EAAE,GAAG,SAAS,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;QACpE,OAAO;IACT,CAAC;IACD,IAAI,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;QAC3C,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;YAC7C,IAAI,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC;gBACxC,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,QAAQ,SAAS,EAAE,CAAC,CAAC;YAC/E,CAAC;YACD,eAAe,CAAC,CAAC,EAAE,GAAG,SAAS,IAAI,CAAC,EAAE,CAAC,CAAC;QAC1C,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/storage/telemetry/uploader.d.ts

@@ -0,0 +1,11 @@
+/**
+ * One flush cycle. Reads usage since the watermark, builds the level-appropriate
+ * payload, POSTs once (with a single retry), and advances the watermark ONLY on
+ * success. Best-effort; never throws.
+ */
+export declare function flushTelemetry(now: number): Promise<"off" | "empty" | "sent" | "failed">;
+/** Start the background flush timer. Called once at server startup. No-op when
+ *  telemetry is off or no endpoint is configured. */
+export declare function startTelemetryTimer(): void;
+export declare function stopTelemetryTimer(): void;
+//# sourceMappingURL=uploader.d.ts.map

package/dist/storage/telemetry/uploader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uploader.d.ts","sourceRoot":"","sources":["../../../src/storage/telemetry/uploader.ts"],"names":[],"mappings":"AA+EA;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAC,CAqC9F;AAID;qDACqD;AACrD,wBAAgB,mBAAmB,IAAI,IAAI,CAO1C;AAED,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC"}

package/dist/storage/telemetry/uploader.js

@@ -0,0 +1,140 @@
+// Telemetry uploader (spec §3). Runs on a timer, NEVER on the tool hot path.
+// Source of truth is the local usage.jsonl + a watermark (last-uploaded ts) —
+// no separate spool to keep in sync. Push happens ONLY when an endpoint is
+// configured (CODESIFT_TELEMETRY_URL); with no endpoint nothing leaves the
+// machine, which is the safe default until the public collector is exposed
+// (staged rollout: notice first, push later).
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { gzipSync } from "node:zlib";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { resolveTelemetryLevel } from "./config.js";
+import { readLocalUsageEntries, aggregateToolMetrics, aggregateHintFunnel, aggregatePlanTurnFunnel } from "./aggregator.js";
+import { buildEnvProfile } from "./env-profile.js";
+import { getAnonId } from "./anon-id.js";
+import { buildLevel1Payload, assertSanitized } from "./sanitizer.js";
+const FLUSH_TIMEOUT_MS = 2000; // hard cap per spec §3
+const INITIAL_FLUSH_DELAY_MS = 10_000;
+const FLUSH_INTERVAL_MS = 24 * 60 * 60 * 1000; // daily
+function dataDir() {
+    return process.env["CODESIFT_DATA_DIR"] ?? join(homedir(), ".codesift");
+}
+function watermarkPath() {
+    return join(dataDir(), "telemetry-watermark");
+}
+function readWatermark() {
+    try {
+        const n = Number(readFileSync(watermarkPath(), "utf-8").trim());
+        return Number.isFinite(n) ? n : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+function writeWatermark(ts) {
+    try {
+        mkdirSync(dataDir(), { recursive: true });
+        writeFileSync(watermarkPath(), String(ts), "utf-8");
+    }
+    catch {
+        /* ignore */
+    }
+}
+/** Baked default collector — anonymous ingest needs NO token (the endpoint is
+ *  open + validated + rate-limited). Full/fleet sets CODESIFT_TELEMETRY_TOKEN.
+ *  Both are env-overridable. */
+const DEFAULT_TELEMETRY_URL = "https://coding.tgmedit.com";
+function endpoint() {
+    const url = (process.env["CODESIFT_TELEMETRY_URL"] ?? DEFAULT_TELEMETRY_URL).replace(/\/$/, "");
+    const token = process.env["CODESIFT_TELEMETRY_TOKEN"] ?? "";
+    return { url, token };
+}
+async function postGzip(url, token, body) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), FLUSH_TIMEOUT_MS);
+    try {
+        const gz = gzipSync(Buffer.from(JSON.stringify(body), "utf-8"));
+        const res = await fetch(url, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                "content-encoding": "gzip",
+                "x-api-key": token,
+                "x-telemetry-client": "codesift-mcp",
+            },
+            body: gz,
+            signal: controller.signal,
+        });
+        return res.ok;
+    }
+    catch {
+        return false; // timeout / network / abort — fail-silent
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * One flush cycle. Reads usage since the watermark, builds the level-appropriate
+ * payload, POSTs once (with a single retry), and advances the watermark ONLY on
+ * success. Best-effort; never throws.
+ */
+export async function flushTelemetry(now) {
+    const level = resolveTelemetryLevel();
+    if (level === "off")
+        return "off";
+    const ep = endpoint();
+    const since = readWatermark();
+    const entries = await readLocalUsageEntries(since);
+    if (entries.length === 0)
+        return "empty";
+    const maxTs = entries.reduce((m, e) => (e.ts > m ? e.ts : m), since);
+    let body;
+    let path;
+    if (level === "full") {
+        // Level 2 (opt-in): raw entries, batched. Full detail — query/paths included.
+        path = "/ingest/codesift";
+        body = { schema_version: 1, level: "full", anon_id: getAnonId(), entries };
+    }
+    else {
+        // Level 1 (anon): aggregate-only, allowlisted, guarded.
+        path = "/ingest/codesift";
+        const payload = buildLevel1Payload({
+            anonId: getAnonId(),
+            env: buildEnvProfile(),
+            tools: aggregateToolMetrics(entries),
+            hints: aggregateHintFunnel(entries),
+            planTurn: aggregatePlanTurnFunnel(entries),
+            now,
+        });
+        assertSanitized(payload); // never send an unsanitized L1 payload
+        body = payload;
+    }
+    let ok = await postGzip(ep.url + path, ep.token, body);
+    if (!ok)
+        ok = await postGzip(ep.url + path, ep.token, body); // single retry
+    if (!ok)
+        return "failed"; // leave watermark — retry next flush
+    writeWatermark(maxTs);
+    return "sent";
+}
+let timer = null;
+/** Start the background flush timer. Called once at server startup. No-op when
+ *  telemetry is off or no endpoint is configured. */
+export function startTelemetryTimer() {
+    if (timer)
+        return;
+    if (resolveTelemetryLevel() === "off")
+        return;
+    const tick = () => { void flushTelemetry(Date.now()); };
+    setTimeout(tick, INITIAL_FLUSH_DELAY_MS).unref();
+    timer = setInterval(tick, FLUSH_INTERVAL_MS);
+    timer.unref?.();
+}
+export function stopTelemetryTimer() {
+    if (timer) {
+        clearInterval(timer);
+        timer = null;
+    }
+}
+//# sourceMappingURL=uploader.js.map

package/dist/storage/telemetry/uploader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uploader.js","sourceRoot":"","sources":["../../../src/storage/telemetry/uploader.ts"],"names":[],"mappings":"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"}

package/dist/storage/usage-tracker.d.ts

@@ -18,6 +18,15 @@ export interface UsageEntry {
     result_tokens_sent?: number;
     /** True when the handler threw — the logged result is the error message. */
     error?: boolean;
+    /** True when served from the response cache — excluded from latency/error/empty
+     *  aggregation, counted only toward cache_hit_rate. */
+    cache_hit?: boolean;
+    /** Response-hint codes emitted on this call (e.g. ["H1","H12"]) — powers the
+     *  hint-efficacy funnel. Codes only, never the hint text. */
+    hints_emitted?: string[];
+    /** Tool names plan_turn recommended on this call — powers the discovery funnel
+     *  (was a recommended tool actually used next?). Names only. */
+    recommended_tools?: string[];
 }
 export declare function getUsagePath(): string;
 /**
@@ -45,6 +54,7 @@ export declare function addSavings(tokens: number): void;
  * Non-blocking: errors are silently caught and logged to stderr.
  */
 export declare function trackUsage(entry: UsageEntry): Promise<void>;
+export declare function setPlanTurnRecommendations(names: string[]): void;
 /**
  * High-level helper: track a completed tool call.
  * Called at the end of each tool handler after the result is computed.
@@ -54,6 +64,10 @@ export declare function trackToolCall(tool: string, args: Record<string, unknown
     sentChars?: number;
     /** The handler threw — resultText is the error message. */
     error?: boolean;
+    /** Served from the response cache (excluded from latency/error/empty stats). */
+    cacheHit?: boolean;
+    /** Response-hint codes emitted on this call, e.g. ["H1","H12"]. */
+    hintsEmitted?: string[];
 }): void;
 /**
  * Get the current session ID (for testing or display).

package/dist/storage/usage-tracker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"usage-tracker.d.ts","sourceRoot":"","sources":["../../src/storage/usage-tracker.ts"],"names":[],"mappings":"AAoBA,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB;;yEAEqE;IACrE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;iEAE6D;IAC7D,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,4EAA4E;IAC5E,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAMD,wBAAgB,YAAY,IAAI,MAAM,CAGrC;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAG1C;AAED,2DAA2D;AAC3D,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAMD;uFACuF;AACvF,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC,CAAC,CAqB5F,CAAC;AAEF;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAyCzB;AAaD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CA+BzD;AAQD,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C;AAED,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAE/C;AAID;;;GAGG;AACH,wBAAsB,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBjE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,OAAO,EACnB,SAAS,EAAE,MAAM,EACjB,KAAK,CAAC,EAAE;IACN,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2DAA2D;IAC3D,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,GACA,IAAI,CAmBN;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAErC"}
+{"version":3,"file":"usage-tracker.d.ts","sourceRoot":"","sources":["../../src/storage/usage-tracker.ts"],"names":[],"mappings":"AAoBA,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB;;yEAEqE;IACrE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;iEAE6D;IAC7D,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,4EAA4E;IAC5E,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;2DACuD;IACvD,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;iEAC6D;IAC7D,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB;oEACgE;IAChE,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC9B;AAMD,wBAAgB,YAAY,IAAI,MAAM,CAGrC;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAG1C;AAED,2DAA2D;AAC3D,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAMD;uFACuF;AACvF,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC,CAAC,CAqB5F,CAAC;AAEF;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAyCzB;AAaD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CA+BzD;AAQD,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C;AAED,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAE/C;AAID;;;GAGG;AACH,wBAAsB,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBjE;AAYD,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CAEhE;AAuBD;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,OAAO,EACnB,SAAS,EAAE,MAAM,EACjB,KAAK,CAAC,EAAE;IACN,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2DAA2D;IAC3D,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,gFAAgF;IAChF,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,mEAAmE;IACnE,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB,GACA,IAAI,CA+BN;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAErC"}