enpilink 1.0.2 → 1.0.4

package/dist/server/analytics.d.ts

@@ -1,18 +1,30 @@
+import { type CaptureGate } from "./capture-gate.js";
 import type { McpMiddlewareEntry, McpMiddlewareFn } from "./middleware.js";
 import { type OtelSink } from "./otel.js";
 import type { StorageAdapter } from "./storage/types.js";
 /**
- * Analytics + log capture (M2). Opt-in, env-gated, zero overhead when off.
+ * Analytics + log capture (M2) — now with a LIVE runtime toggle (bugfix).
  *
- * When enabled, a single {@link StorageAdapter} is resolved + `init()`ed at
- * server startup and shared in-process: the analytics middleware writes
- * `tool_call` events to it, the log sink mirrors server logs to it, and (M3)
- * the observability API reads from the very same instance via the
- * `server.storage` getter or {@link getActiveStorage}.
+ * A single {@link StorageAdapter} is shared in-process: the analytics
+ * middleware writes `tool_call` events to it, the log sink mirrors server logs
+ * to it, and the observability/config APIs read from the very same instance via
+ * the `server.storage` getter or {@link getActiveStorage}.
  *
- * Gating: OFF unless `ENPILINK_ANALYTICS` is `1` or `true` (case-insensitive).
- * When OFF, no adapter is resolved or initialized (so no `enpilink.db` is
- * created), no middleware is registered, and there is zero network activity.
+ * Storage activation (so the Configuration + observability UI always has a
+ * backing store) vs. capture gating (whether tool calls are recorded) are now
+ * DECOUPLED:
+ *
+ * - **Storage** is activated whenever the admin/config UI is reachable: always
+ *   in dev (default `memory`, honoring `ENPILINK_STORAGE`/`ENPILINK_DB_PATH`),
+ *   and in prod-admin (handled separately in `admin.ts`). It reuses any already
+ *   active adapter — never double-inits.
+ * - **Capture** is governed at runtime by the resolved `analytics.enabled`
+ *   config value (env > file > db > default) via the {@link CaptureGate}, so
+ *   toggling it in the UI takes effect WITHOUT a restart. `ENPILINK_ANALYTICS`
+ *   still works as an env override (env > db).
+ *
+ * The default `memory` adapter creates NO `enpilink.db` file and does zero
+ * network; OTel stays independently gated and off by default.
  */
 /** Options for {@link installAnalytics}. */
 export interface InstallAnalyticsOptions {
@@ -33,25 +45,53 @@ export declare function analyticsEnabled(): boolean;
  * NEVER touches disk and is never on by default.
  */
 export declare function mockEnabled(): boolean;
+/** Options controlling the live capture gate (injectable for tests). */
+export interface AnalyticsMiddlewareOptions {
+    /** Read the live capture gate. Defaults to the shared {@link getCaptureGate}. */
+    gate?: () => CaptureGate;
+    /** RNG for sampling `[0, 1)`. Defaults to `Math.random`. */
+    rng?: () => number;
+}
 /**
  * Build the analytics middleware entry. Times each request around `next()`,
- * records a `tool_call`-typed event (capturing the tool name for `tools/call`),
- * and ALWAYS swallows storage errors so a storage failure can never break or
- * slow a tool call. Recording is fire-and-forget (non-blocking).
+ * and — ONLY when the live capture gate says so — records a `tool_call`-typed
+ * event (capturing the tool name for `tools/call`). Always swallows storage
+ * errors so a storage failure can never break or slow a tool call. Recording is
+ * fire-and-forget (non-blocking).
+ *
+ * The gate is a cheap, synchronous in-memory snapshot of the resolved
+ * `analytics.enabled` / `analytics.sampleRate` config (see `capture-gate.ts`),
+ * so toggling analytics in the UI takes effect live without a restart and the
+ * hot path does no DB read. `next()` is ALWAYS awaited so the tool call runs
+ * identically whether capture is on or off; only the record/export at the end is
+ * gated.
  */
-export declare function createAnalyticsMiddleware(storage: StorageAdapter, now?: () => number, otel?: OtelSink | null): McpMiddlewareFn;
+export declare function createAnalyticsMiddleware(storage: StorageAdapter, now?: () => number, otel?: OtelSink | null, opts?: AnalyticsMiddlewareOptions): McpMiddlewareFn;
 /**
- * Install analytics on a server, ONLY when enabled (`ENPILINK_ANALYTICS`).
+ * Install analytics on a server.
  *
- * When enabled: resolves a {@link StorageAdapter} via `resolveStorageAdapter()`
- * (`ENPILINK_STORAGE` / `ENPILINK_DB_PATH`), `init()`s it, registers it as the
- * active storage for the log sink + `getActiveStorage()`, and returns the
- * built analytics middleware entry to splice into the chain.
+ * STORAGE activation (decoupled from capture):
+ * - Reuse any already-active adapter ({@link getActiveStorage}) — never
+ *   double-init.
+ * - In `--mock` mode, force a fresh in-memory adapter and seed it.
+ * - Otherwise, in DEV activate the configured adapter (default `memory`,
+ *   honoring `ENPILINK_STORAGE` / `ENPILINK_DB_PATH`) so the Configuration +
+ *   observability UI always has a backing store — removing the "no active
+ *   storage" 409 on the first config write. `memory` creates NO file and does
+ *   zero network.
+ * - In PRODUCTION WITHOUT mock, activate NOTHING here (the config UI isn't
+ *   reachable; prod-admin activates its own store in `admin.ts`). This preserves
+ *   the "no db / no network when off in prod" guarantee.
  *
- * When disabled: resolves/initializes NOTHING and returns `null` — zero
- * overhead, zero network, no `enpilink.db` created.
+ * CAPTURE gating: the returned middleware records events only when the live
+ * {@link CaptureGate} (resolved `analytics.enabled`/`analytics.sampleRate`, env
+ * > file > db > default) allows it — so the toggle is live (no restart). The
+ * gate is resolved once here and refreshed on config writes by the router. In
+ * `--mock` mode capture is force-enabled for the session.
  *
- * @returns the active storage + middleware entry, or `null` when disabled.
+ * @returns the active storage + middleware entry + otel sink, or `null` when no
+ * storage was activated (prod without mock/admin) — zero overhead, no file, no
+ * network, no middleware.
  */
 export declare function installAnalytics(opts?: InstallAnalyticsOptions): Promise<{
     storage: StorageAdapter;

package/dist/server/analytics.js

@@ -1,4 +1,5 @@
-import { setActiveStorage } from "./log-sink.js";
+import { getCaptureGate, refreshCaptureGate, setCaptureGate, } from "./capture-gate.js";
+import { getActiveStorage, setActiveStorage } from "./log-sink.js";
 import { seedMockData } from "./mock-seed.js";
 import { initOtel } from "./otel.js";
 import { resolveStorageAdapter } from "./storage/index.js";
@@ -11,6 +12,10 @@ import { MemoryStorageAdapter } from "./storage/memory.js";
 function resolveSessionStorage(mock) {
     return mock ? new MemoryStorageAdapter() : resolveStorageAdapter();
 }
+/** Whether the process is running in production (no dev admin plane). */
+function isProduction() {
+    return process.env.NODE_ENV === "production";
+}
 /** Truthy values that enable analytics via {@link analyticsEnabled}. */
 const TRUTHY = new Set(["1", "true", "yes", "on"]);
 /**
@@ -50,11 +55,21 @@ function toolNameOf(method, params) {
 }
 /**
  * Build the analytics middleware entry. Times each request around `next()`,
- * records a `tool_call`-typed event (capturing the tool name for `tools/call`),
- * and ALWAYS swallows storage errors so a storage failure can never break or
- * slow a tool call. Recording is fire-and-forget (non-blocking).
+ * and — ONLY when the live capture gate says so — records a `tool_call`-typed
+ * event (capturing the tool name for `tools/call`). Always swallows storage
+ * errors so a storage failure can never break or slow a tool call. Recording is
+ * fire-and-forget (non-blocking).
+ *
+ * The gate is a cheap, synchronous in-memory snapshot of the resolved
+ * `analytics.enabled` / `analytics.sampleRate` config (see `capture-gate.ts`),
+ * so toggling analytics in the UI takes effect live without a restart and the
+ * hot path does no DB read. `next()` is ALWAYS awaited so the tool call runs
+ * identically whether capture is on or off; only the record/export at the end is
+ * gated.
  */
-export function createAnalyticsMiddleware(storage, now = Date.now, otel = null) {
+export function createAnalyticsMiddleware(storage, now = Date.now, otel = null, opts = {}) {
+    const readGate = opts.gate ?? getCaptureGate;
+    const rng = opts.rng ?? Math.random;
     return async (request, _extra, next) => {
         const start = now();
         const tool = toolNameOf(request.method, request.params);
@@ -77,25 +92,31 @@ export function createAnalyticsMiddleware(storage, now = Date.now, otel = null)
             throw err;
         }
         finally {
-            const ms = now() - start;
-            const event = {
-                ts: start,
-                type: "tool_call",
-                tool,
-                method: request.method,
-                ms,
-                ok,
-                error,
-            };
-            // Fire-and-forget; never block or throw into the request path.
-            void recordSafely(storage, event);
-            // Optional OTel export — guarded, synchronous, error-swallowing.
-            if (otel) {
-                try {
-                    otel.record(event);
-                }
-                catch {
-                    // OTel export must never break or slow a tool call.
+            // Live gate: skip recording entirely when analytics is off, or when this
+            // call falls outside the sample rate. Cheap + synchronous + never throws.
+            const { enabled, sampleRate } = readGate();
+            const sampled = sampleRate >= 1 || (sampleRate > 0 && rng() < sampleRate);
+            if (enabled && sampled) {
+                const ms = now() - start;
+                const event = {
+                    ts: start,
+                    type: "tool_call",
+                    tool,
+                    method: request.method,
+                    ms,
+                    ok,
+                    error,
+                };
+                // Fire-and-forget; never block or throw into the request path.
+                void recordSafely(storage, event);
+                // Optional OTel export — guarded, synchronous, error-swallowing.
+                if (otel) {
+                    try {
+                        otel.record(event);
+                    }
+                    catch {
+                        // OTel export must never break or slow a tool call.
+                    }
                 }
             }
         }
@@ -111,40 +132,65 @@ async function recordSafely(storage, event) {
     }
 }
 /**
- * Install analytics on a server, ONLY when enabled (`ENPILINK_ANALYTICS`).
+ * Install analytics on a server.
  *
- * When enabled: resolves a {@link StorageAdapter} via `resolveStorageAdapter()`
- * (`ENPILINK_STORAGE` / `ENPILINK_DB_PATH`), `init()`s it, registers it as the
- * active storage for the log sink + `getActiveStorage()`, and returns the
- * built analytics middleware entry to splice into the chain.
+ * STORAGE activation (decoupled from capture):
+ * - Reuse any already-active adapter ({@link getActiveStorage}) — never
+ *   double-init.
+ * - In `--mock` mode, force a fresh in-memory adapter and seed it.
+ * - Otherwise, in DEV activate the configured adapter (default `memory`,
+ *   honoring `ENPILINK_STORAGE` / `ENPILINK_DB_PATH`) so the Configuration +
+ *   observability UI always has a backing store — removing the "no active
+ *   storage" 409 on the first config write. `memory` creates NO file and does
+ *   zero network.
+ * - In PRODUCTION WITHOUT mock, activate NOTHING here (the config UI isn't
+ *   reachable; prod-admin activates its own store in `admin.ts`). This preserves
+ *   the "no db / no network when off in prod" guarantee.
  *
- * When disabled: resolves/initializes NOTHING and returns `null` — zero
- * overhead, zero network, no `enpilink.db` created.
+ * CAPTURE gating: the returned middleware records events only when the live
+ * {@link CaptureGate} (resolved `analytics.enabled`/`analytics.sampleRate`, env
+ * > file > db > default) allows it — so the toggle is live (no restart). The
+ * gate is resolved once here and refreshed on config writes by the router. In
+ * `--mock` mode capture is force-enabled for the session.
  *
- * @returns the active storage + middleware entry, or `null` when disabled.
+ * @returns the active storage + middleware entry + otel sink, or `null` when no
+ * storage was activated (prod without mock/admin) — zero overhead, no file, no
+ * network, no middleware.
  */
 export async function installAnalytics(opts = {}) {
-    // `--mock` (ENPILINK_MOCK) force-enables analytics for the session even when
-    // the env-based gating is off, so demos work without setting both flags.
+    // `--mock` (ENPILINK_MOCK) force-enables capture for the session and uses a
+    // throwaway in-memory store so demos work with no real traffic and no disk.
     const mock = mockEnabled();
-    if (!mock && !analyticsEnabled()) {
-        return null;
-    }
-    let storage;
-    try {
-        storage = resolveSessionStorage(mock);
-        await storage.init();
-    }
-    catch (err) {
-        // Never let an analytics/storage failure break server startup.
-        console.error("[enpilink] analytics disabled: storage init failed:", err instanceof Error ? err.message : err);
-        return null;
+    // Reuse an already-active adapter if one exists (e.g. set elsewhere); never
+    // double-init. Otherwise decide whether to activate one.
+    let storage = getActiveStorage();
+    let ownedHere = false;
+    if (!storage) {
+        // In prod we don't activate storage here UNLESS analytics is explicitly
+        // enabled via env (the historical M2 behavior — capture to a resolved
+        // store). Otherwise the config UI isn't reachable (prod-admin handles its
+        // own store), so activating nothing preserves the "no db / no network when
+        // off" guarantee. In dev (or mock) we always activate so the UI works.
+        if (!mock && isProduction() && !analyticsEnabled()) {
+            return null;
+        }
+        try {
+            storage = resolveSessionStorage(mock);
+            await storage.init();
+            ownedHere = true;
+        }
+        catch (err) {
+            // Never let a storage failure break server startup.
+            console.error("[enpilink] analytics storage init failed:", err instanceof Error ? err.message : err);
+            return null;
+        }
+        setActiveStorage(storage);
     }
-    setActiveStorage(storage);
-    // In `--mock` mode, seed the in-memory storage with a deterministic demo
+    // In `--mock` mode, seed the (in-memory) storage with a deterministic demo
     // dataset so the Dashboard renders full immediately (no real traffic).
-    // Determinism: a fixed seed + a base timestamp captured once here.
-    if (mock) {
+    // Determinism: a fixed seed + a base timestamp captured once here. Only seed a
+    // store we just created here, never an adopted/pre-existing one.
+    if (mock && ownedHere) {
         const now = (opts.now ?? Date.now)();
         try {
             await seedMockData(storage, { now });
@@ -153,9 +199,18 @@ export async function installAnalytics(opts = {}) {
             // A seeding failure must never break server startup.
         }
     }
+    // Initialize the live capture gate. `--mock` force-enables capture for the
+    // session (full sample); otherwise resolve from env/file/db/default so the UI
+    // toggle (and any env override) governs capture live.
+    if (mock) {
+        setCaptureGate({ enabled: true, sampleRate: 1 });
+    }
+    else {
+        await refreshCaptureGate();
+    }
     // Optional OTel export (M6): off by default, zero network/imports when unset.
-    // Initialized once here and fed by the middleware alongside storage. Mock mode
-    // never exports (it's dev-only demo data); requires the explicit env opt-in.
+    // Mock mode never exports (it's dev-only demo data); requires the explicit env
+    // opt-in.
     const otel = mock ? null : await initOtel();
     const entry = {
         // "request" matches every (non-notification) request so non-tool methods

package/dist/server/analytics.js.map

@@ -1 +1 @@
-{"version":3,"file":"analytics.js","sourceRoot":"","sources":["../../src/server/analytics.ts"],"names":[],"mappings":"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","sourcesContent":["import { setActiveStorage } from \"./log-sink.js\";\nimport type { McpMiddlewareEntry, McpMiddlewareFn } from \"./middleware.js\";\nimport { seedMockData } from \"./mock-seed.js\";\nimport { initOtel, type OtelSink } from \"./otel.js\";\nimport { resolveStorageAdapter } from \"./storage/index.js\";\nimport { MemoryStorageAdapter } from \"./storage/memory.js\";\nimport type { StorageAdapter } from \"./storage/types.js\";\n\n/**\n * Analytics + log capture (M2). Opt-in, env-gated, zero overhead when off.\n *\n * When enabled, a single {@link StorageAdapter} is resolved + `init()`ed at\n * server startup and shared in-process: the analytics middleware writes\n * `tool_call` events to it, the log sink mirrors server logs to it, and (M3)\n * the observability API reads from the very same instance via the\n * `server.storage` getter or {@link getActiveStorage}.\n *\n * Gating: OFF unless `ENPILINK_ANALYTICS` is `1` or `true` (case-insensitive).\n * When OFF, no adapter is resolved or initialized (so no `enpilink.db` is\n * created), no middleware is registered, and there is zero network activity.\n */\n\n/** Options for {@link installAnalytics}. */\nexport interface InstallAnalyticsOptions {\n  /**\n   * Inject a clock for deterministic tests. Defaults to `Date.now`.\n   */\n  now?: () => number;\n}\n\n/**\n * Resolve a storage adapter for the session. In `--mock` mode we force an\n * in-memory adapter (the demo seed must never touch disk and must vanish on\n * exit); otherwise the configured `ENPILINK_STORAGE` adapter is used.\n */\nfunction resolveSessionStorage(mock: boolean): StorageAdapter {\n  return mock ? new MemoryStorageAdapter() : resolveStorageAdapter();\n}\n\n/** Truthy values that enable analytics via {@link analyticsEnabled}. */\nconst TRUTHY = new Set([\"1\", \"true\", \"yes\", \"on\"]);\n\n/**\n * Whether analytics is enabled. OFF by default; enable with\n * `ENPILINK_ANALYTICS=1` (also accepts `true`/`yes`/`on`, case-insensitive).\n */\nexport function analyticsEnabled(): boolean {\n  const raw = process.env.ENPILINK_ANALYTICS;\n  return raw !== undefined && TRUTHY.has(raw.trim().toLowerCase());\n}\n\n/**\n * Whether the `--mock` demo seed is enabled (`ENPILINK_MOCK`=1/true/yes/on).\n * Mock mode is opt-in only and IMPLIES analytics-on + in-memory storage for the\n * session, so the Dashboard renders full demo data with NO real traffic. It\n * NEVER touches disk and is never on by default.\n */\nexport function mockEnabled(): boolean {\n  // The demo seed is DEV-ONLY: it must never seed a real deployment. In\n  // production `ENPILINK_MOCK` is ignored entirely (read the literal so the\n  // guard survives DCE and is unambiguous).\n  if (process.env.NODE_ENV === \"production\") {\n    return false;\n  }\n  const raw = process.env.ENPILINK_MOCK;\n  return raw !== undefined && TRUTHY.has(raw.trim().toLowerCase());\n}\n\n/**\n * Extract the tool name from a `tools/call` request's params. Returns\n * `undefined` for non-`tools/call` methods or malformed params, never throws.\n */\nfunction toolNameOf(\n  method: string,\n  params: Record<string, unknown>,\n): string | undefined {\n  if (method !== \"tools/call\") {\n    return undefined;\n  }\n  const name = params?.name;\n  return typeof name === \"string\" ? name : undefined;\n}\n\n/**\n * Build the analytics middleware entry. Times each request around `next()`,\n * records a `tool_call`-typed event (capturing the tool name for `tools/call`),\n * and ALWAYS swallows storage errors so a storage failure can never break or\n * slow a tool call. Recording is fire-and-forget (non-blocking).\n */\nexport function createAnalyticsMiddleware(\n  storage: StorageAdapter,\n  now: () => number = Date.now,\n  otel: OtelSink | null = null,\n): McpMiddlewareFn {\n  return async (request, _extra, next) => {\n    const start = now();\n    const tool = toolNameOf(request.method, request.params);\n    let ok = true;\n    let error: string | undefined;\n\n    try {\n      const result = await next();\n      // A tool result with `isError: true` is a soft (handled) failure.\n      if (\n        result &&\n        typeof result === \"object\" &&\n        (result as { isError?: unknown }).isError === true\n      ) {\n        ok = false;\n      }\n      return result;\n    } catch (err) {\n      // Record the failure, then rethrow so behavior is unchanged.\n      ok = false;\n      error = err instanceof Error ? err.message : String(err);\n      throw err;\n    } finally {\n      const ms = now() - start;\n      const event = {\n        ts: start,\n        type: \"tool_call\",\n        tool,\n        method: request.method,\n        ms,\n        ok,\n        error,\n      } as const;\n      // Fire-and-forget; never block or throw into the request path.\n      void recordSafely(storage, event);\n      // Optional OTel export — guarded, synchronous, error-swallowing.\n      if (otel) {\n        try {\n          otel.record(event);\n        } catch {\n          // OTel export must never break or slow a tool call.\n        }\n      }\n    }\n  };\n}\n\n/** Record an event, swallowing any storage error. */\nasync function recordSafely(\n  storage: StorageAdapter,\n  event: Parameters<StorageAdapter[\"recordEvent\"]>[0],\n): Promise<void> {\n  try {\n    await storage.recordEvent(event);\n  } catch {\n    // A storage failure must never break or slow a tool call.\n  }\n}\n\n/**\n * Install analytics on a server, ONLY when enabled (`ENPILINK_ANALYTICS`).\n *\n * When enabled: resolves a {@link StorageAdapter} via `resolveStorageAdapter()`\n * (`ENPILINK_STORAGE` / `ENPILINK_DB_PATH`), `init()`s it, registers it as the\n * active storage for the log sink + `getActiveStorage()`, and returns the\n * built analytics middleware entry to splice into the chain.\n *\n * When disabled: resolves/initializes NOTHING and returns `null` — zero\n * overhead, zero network, no `enpilink.db` created.\n *\n * @returns the active storage + middleware entry, or `null` when disabled.\n */\nexport async function installAnalytics(\n  opts: InstallAnalyticsOptions = {},\n): Promise<{\n  storage: StorageAdapter;\n  entry: McpMiddlewareEntry;\n  otel: OtelSink | null;\n} | null> {\n  // `--mock` (ENPILINK_MOCK) force-enables analytics for the session even when\n  // the env-based gating is off, so demos work without setting both flags.\n  const mock = mockEnabled();\n  if (!mock && !analyticsEnabled()) {\n    return null;\n  }\n\n  let storage: StorageAdapter;\n  try {\n    storage = resolveSessionStorage(mock);\n    await storage.init();\n  } catch (err) {\n    // Never let an analytics/storage failure break server startup.\n    console.error(\n      \"[enpilink] analytics disabled: storage init failed:\",\n      err instanceof Error ? err.message : err,\n    );\n    return null;\n  }\n\n  setActiveStorage(storage);\n\n  // In `--mock` mode, seed the in-memory storage with a deterministic demo\n  // dataset so the Dashboard renders full immediately (no real traffic).\n  // Determinism: a fixed seed + a base timestamp captured once here.\n  if (mock) {\n    const now = (opts.now ?? Date.now)();\n    try {\n      await seedMockData(storage, { now });\n    } catch {\n      // A seeding failure must never break server startup.\n    }\n  }\n\n  // Optional OTel export (M6): off by default, zero network/imports when unset.\n  // Initialized once here and fed by the middleware alongside storage. Mock mode\n  // never exports (it's dev-only demo data); requires the explicit env opt-in.\n  const otel = mock ? null : await initOtel();\n\n  const entry: McpMiddlewareEntry = {\n    // \"request\" matches every (non-notification) request so non-tool methods\n    // are counted too; the handler captures the tool name for tools/call.\n    filter: \"request\",\n    handler: createAnalyticsMiddleware(storage, opts.now, otel),\n  };\n\n  return { storage, entry, otel };\n}\n"]}
+{"version":3,"file":"analytics.js","sourceRoot":"","sources":["../../src/server/analytics.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  type CaptureGate,\n  getCaptureGate,\n  refreshCaptureGate,\n  setCaptureGate,\n} from \"./capture-gate.js\";\nimport { getActiveStorage, setActiveStorage } from \"./log-sink.js\";\nimport type { McpMiddlewareEntry, McpMiddlewareFn } from \"./middleware.js\";\nimport { seedMockData } from \"./mock-seed.js\";\nimport { initOtel, type OtelSink } from \"./otel.js\";\nimport { resolveStorageAdapter } from \"./storage/index.js\";\nimport { MemoryStorageAdapter } from \"./storage/memory.js\";\nimport type { StorageAdapter } from \"./storage/types.js\";\n\n/**\n * Analytics + log capture (M2) — now with a LIVE runtime toggle (bugfix).\n *\n * A single {@link StorageAdapter} is shared in-process: the analytics\n * middleware writes `tool_call` events to it, the log sink mirrors server logs\n * to it, and the observability/config APIs read from the very same instance via\n * the `server.storage` getter or {@link getActiveStorage}.\n *\n * Storage activation (so the Configuration + observability UI always has a\n * backing store) vs. capture gating (whether tool calls are recorded) are now\n * DECOUPLED:\n *\n * - **Storage** is activated whenever the admin/config UI is reachable: always\n *   in dev (default `memory`, honoring `ENPILINK_STORAGE`/`ENPILINK_DB_PATH`),\n *   and in prod-admin (handled separately in `admin.ts`). It reuses any already\n *   active adapter — never double-inits.\n * - **Capture** is governed at runtime by the resolved `analytics.enabled`\n *   config value (env > file > db > default) via the {@link CaptureGate}, so\n *   toggling it in the UI takes effect WITHOUT a restart. `ENPILINK_ANALYTICS`\n *   still works as an env override (env > db).\n *\n * The default `memory` adapter creates NO `enpilink.db` file and does zero\n * network; OTel stays independently gated and off by default.\n */\n\n/** Options for {@link installAnalytics}. */\nexport interface InstallAnalyticsOptions {\n  /**\n   * Inject a clock for deterministic tests. Defaults to `Date.now`.\n   */\n  now?: () => number;\n}\n\n/**\n * Resolve a storage adapter for the session. In `--mock` mode we force an\n * in-memory adapter (the demo seed must never touch disk and must vanish on\n * exit); otherwise the configured `ENPILINK_STORAGE` adapter is used.\n */\nfunction resolveSessionStorage(mock: boolean): StorageAdapter {\n  return mock ? new MemoryStorageAdapter() : resolveStorageAdapter();\n}\n\n/** Whether the process is running in production (no dev admin plane). */\nfunction isProduction(): boolean {\n  return process.env.NODE_ENV === \"production\";\n}\n\n/** Truthy values that enable analytics via {@link analyticsEnabled}. */\nconst TRUTHY = new Set([\"1\", \"true\", \"yes\", \"on\"]);\n\n/**\n * Whether analytics is enabled. OFF by default; enable with\n * `ENPILINK_ANALYTICS=1` (also accepts `true`/`yes`/`on`, case-insensitive).\n */\nexport function analyticsEnabled(): boolean {\n  const raw = process.env.ENPILINK_ANALYTICS;\n  return raw !== undefined && TRUTHY.has(raw.trim().toLowerCase());\n}\n\n/**\n * Whether the `--mock` demo seed is enabled (`ENPILINK_MOCK`=1/true/yes/on).\n * Mock mode is opt-in only and IMPLIES analytics-on + in-memory storage for the\n * session, so the Dashboard renders full demo data with NO real traffic. It\n * NEVER touches disk and is never on by default.\n */\nexport function mockEnabled(): boolean {\n  // The demo seed is DEV-ONLY: it must never seed a real deployment. In\n  // production `ENPILINK_MOCK` is ignored entirely (read the literal so the\n  // guard survives DCE and is unambiguous).\n  if (process.env.NODE_ENV === \"production\") {\n    return false;\n  }\n  const raw = process.env.ENPILINK_MOCK;\n  return raw !== undefined && TRUTHY.has(raw.trim().toLowerCase());\n}\n\n/**\n * Extract the tool name from a `tools/call` request's params. Returns\n * `undefined` for non-`tools/call` methods or malformed params, never throws.\n */\nfunction toolNameOf(\n  method: string,\n  params: Record<string, unknown>,\n): string | undefined {\n  if (method !== \"tools/call\") {\n    return undefined;\n  }\n  const name = params?.name;\n  return typeof name === \"string\" ? name : undefined;\n}\n\n/** Options controlling the live capture gate (injectable for tests). */\nexport interface AnalyticsMiddlewareOptions {\n  /** Read the live capture gate. Defaults to the shared {@link getCaptureGate}. */\n  gate?: () => CaptureGate;\n  /** RNG for sampling `[0, 1)`. Defaults to `Math.random`. */\n  rng?: () => number;\n}\n\n/**\n * Build the analytics middleware entry. Times each request around `next()`,\n * and — ONLY when the live capture gate says so — records a `tool_call`-typed\n * event (capturing the tool name for `tools/call`). Always swallows storage\n * errors so a storage failure can never break or slow a tool call. Recording is\n * fire-and-forget (non-blocking).\n *\n * The gate is a cheap, synchronous in-memory snapshot of the resolved\n * `analytics.enabled` / `analytics.sampleRate` config (see `capture-gate.ts`),\n * so toggling analytics in the UI takes effect live without a restart and the\n * hot path does no DB read. `next()` is ALWAYS awaited so the tool call runs\n * identically whether capture is on or off; only the record/export at the end is\n * gated.\n */\nexport function createAnalyticsMiddleware(\n  storage: StorageAdapter,\n  now: () => number = Date.now,\n  otel: OtelSink | null = null,\n  opts: AnalyticsMiddlewareOptions = {},\n): McpMiddlewareFn {\n  const readGate = opts.gate ?? getCaptureGate;\n  const rng = opts.rng ?? Math.random;\n  return async (request, _extra, next) => {\n    const start = now();\n    const tool = toolNameOf(request.method, request.params);\n    let ok = true;\n    let error: string | undefined;\n\n    try {\n      const result = await next();\n      // A tool result with `isError: true` is a soft (handled) failure.\n      if (\n        result &&\n        typeof result === \"object\" &&\n        (result as { isError?: unknown }).isError === true\n      ) {\n        ok = false;\n      }\n      return result;\n    } catch (err) {\n      // Record the failure, then rethrow so behavior is unchanged.\n      ok = false;\n      error = err instanceof Error ? err.message : String(err);\n      throw err;\n    } finally {\n      // Live gate: skip recording entirely when analytics is off, or when this\n      // call falls outside the sample rate. Cheap + synchronous + never throws.\n      const { enabled, sampleRate } = readGate();\n      const sampled = sampleRate >= 1 || (sampleRate > 0 && rng() < sampleRate);\n      if (enabled && sampled) {\n        const ms = now() - start;\n        const event = {\n          ts: start,\n          type: \"tool_call\",\n          tool,\n          method: request.method,\n          ms,\n          ok,\n          error,\n        } as const;\n        // Fire-and-forget; never block or throw into the request path.\n        void recordSafely(storage, event);\n        // Optional OTel export — guarded, synchronous, error-swallowing.\n        if (otel) {\n          try {\n            otel.record(event);\n          } catch {\n            // OTel export must never break or slow a tool call.\n          }\n        }\n      }\n    }\n  };\n}\n\n/** Record an event, swallowing any storage error. */\nasync function recordSafely(\n  storage: StorageAdapter,\n  event: Parameters<StorageAdapter[\"recordEvent\"]>[0],\n): Promise<void> {\n  try {\n    await storage.recordEvent(event);\n  } catch {\n    // A storage failure must never break or slow a tool call.\n  }\n}\n\n/**\n * Install analytics on a server.\n *\n * STORAGE activation (decoupled from capture):\n * - Reuse any already-active adapter ({@link getActiveStorage}) — never\n *   double-init.\n * - In `--mock` mode, force a fresh in-memory adapter and seed it.\n * - Otherwise, in DEV activate the configured adapter (default `memory`,\n *   honoring `ENPILINK_STORAGE` / `ENPILINK_DB_PATH`) so the Configuration +\n *   observability UI always has a backing store — removing the \"no active\n *   storage\" 409 on the first config write. `memory` creates NO file and does\n *   zero network.\n * - In PRODUCTION WITHOUT mock, activate NOTHING here (the config UI isn't\n *   reachable; prod-admin activates its own store in `admin.ts`). This preserves\n *   the \"no db / no network when off in prod\" guarantee.\n *\n * CAPTURE gating: the returned middleware records events only when the live\n * {@link CaptureGate} (resolved `analytics.enabled`/`analytics.sampleRate`, env\n * > file > db > default) allows it — so the toggle is live (no restart). The\n * gate is resolved once here and refreshed on config writes by the router. In\n * `--mock` mode capture is force-enabled for the session.\n *\n * @returns the active storage + middleware entry + otel sink, or `null` when no\n * storage was activated (prod without mock/admin) — zero overhead, no file, no\n * network, no middleware.\n */\nexport async function installAnalytics(\n  opts: InstallAnalyticsOptions = {},\n): Promise<{\n  storage: StorageAdapter;\n  entry: McpMiddlewareEntry;\n  otel: OtelSink | null;\n} | null> {\n  // `--mock` (ENPILINK_MOCK) force-enables capture for the session and uses a\n  // throwaway in-memory store so demos work with no real traffic and no disk.\n  const mock = mockEnabled();\n\n  // Reuse an already-active adapter if one exists (e.g. set elsewhere); never\n  // double-init. Otherwise decide whether to activate one.\n  let storage = getActiveStorage();\n  let ownedHere = false;\n  if (!storage) {\n    // In prod we don't activate storage here UNLESS analytics is explicitly\n    // enabled via env (the historical M2 behavior — capture to a resolved\n    // store). Otherwise the config UI isn't reachable (prod-admin handles its\n    // own store), so activating nothing preserves the \"no db / no network when\n    // off\" guarantee. In dev (or mock) we always activate so the UI works.\n    if (!mock && isProduction() && !analyticsEnabled()) {\n      return null;\n    }\n    try {\n      storage = resolveSessionStorage(mock);\n      await storage.init();\n      ownedHere = true;\n    } catch (err) {\n      // Never let a storage failure break server startup.\n      console.error(\n        \"[enpilink] analytics storage init failed:\",\n        err instanceof Error ? err.message : err,\n      );\n      return null;\n    }\n    setActiveStorage(storage);\n  }\n\n  // In `--mock` mode, seed the (in-memory) storage with a deterministic demo\n  // dataset so the Dashboard renders full immediately (no real traffic).\n  // Determinism: a fixed seed + a base timestamp captured once here. Only seed a\n  // store we just created here, never an adopted/pre-existing one.\n  if (mock && ownedHere) {\n    const now = (opts.now ?? Date.now)();\n    try {\n      await seedMockData(storage, { now });\n    } catch {\n      // A seeding failure must never break server startup.\n    }\n  }\n\n  // Initialize the live capture gate. `--mock` force-enables capture for the\n  // session (full sample); otherwise resolve from env/file/db/default so the UI\n  // toggle (and any env override) governs capture live.\n  if (mock) {\n    setCaptureGate({ enabled: true, sampleRate: 1 });\n  } else {\n    await refreshCaptureGate();\n  }\n\n  // Optional OTel export (M6): off by default, zero network/imports when unset.\n  // Mock mode never exports (it's dev-only demo data); requires the explicit env\n  // opt-in.\n  const otel = mock ? null : await initOtel();\n\n  const entry: McpMiddlewareEntry = {\n    // \"request\" matches every (non-notification) request so non-tool methods\n    // are counted too; the handler captures the tool name for tools/call.\n    filter: \"request\",\n    handler: createAnalyticsMiddleware(storage, opts.now, otel),\n  };\n\n  return { storage, entry, otel };\n}\n"]}

package/dist/server/analytics.test.js

@@ -1,6 +1,7 @@
 import { existsSync } from "node:fs";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import { analyticsEnabled, createAnalyticsMiddleware, installAnalytics, } from "./analytics.js";
+import { getCaptureGate, setCaptureGate } from "./capture-gate.js";
 import { getActiveStorage, serverLog, setActiveStorage } from "./log-sink.js";
 import { MemoryStorageAdapter } from "./storage/memory.js";
 /** Flush the fire-and-forget recordEvent/appendLog microtasks. */
@@ -38,6 +39,8 @@ describe("analyticsEnabled", () => {
         }
     });
 });
+/** A gate that always records (analytics on, full sample) — for capture tests. */
+const onGate = () => ({ enabled: true, sampleRate: 1 });
 describe("createAnalyticsMiddleware", () => {
     let store;
     beforeEach(async () => {
@@ -45,7 +48,9 @@ describe("createAnalyticsMiddleware", () => {
         await store.init();
     });
     it("records a tool_call event on success with tool, ms, ok", async () => {
-        const mw = createAnalyticsMiddleware(store, fixedClock());
+        const mw = createAnalyticsMiddleware(store, fixedClock(), null, {
+            gate: onGate,
+        });
         const result = { content: [{ type: "text", text: "hi" }] };
         const ret = await mw({ method: "tools/call", params: { name: "greet" } }, undefined, async () => result);
         await flush();
@@ -62,14 +67,18 @@ describe("createAnalyticsMiddleware", () => {
         expect(e?.error).toBeUndefined();
     });
     it("records ok=false when the result has isError", async () => {
-        const mw = createAnalyticsMiddleware(store, fixedClock());
+        const mw = createAnalyticsMiddleware(store, fixedClock(), null, {
+            gate: onGate,
+        });
         await mw({ method: "tools/call", params: { name: "boom" } }, undefined, async () => ({ isError: true, content: [] }));
         await flush();
         const [e] = await store.queryEvents({});
         expect(e).toMatchObject({ tool: "boom", ok: false });
     });
     it("records the event AND rethrows on a thrown error", async () => {
-        const mw = createAnalyticsMiddleware(store, fixedClock());
+        const mw = createAnalyticsMiddleware(store, fixedClock(), null, {
+            gate: onGate,
+        });
         await expect(mw({ method: "tools/call", params: { name: "kaboom" } }, undefined, async () => {
             throw new Error("nope");
         })).rejects.toThrow("nope");
@@ -78,7 +87,9 @@ describe("createAnalyticsMiddleware", () => {
         expect(e).toMatchObject({ tool: "kaboom", ok: false, error: "nope" });
     });
     it("captures the method but no tool for non-tools/call requests", async () => {
-        const mw = createAnalyticsMiddleware(store, fixedClock());
+        const mw = createAnalyticsMiddleware(store, fixedClock(), null, {
+            gate: onGate,
+        });
         await mw({ method: "tools/list", params: {} }, undefined, async () => ({
             tools: [],
         }));
@@ -93,7 +104,9 @@ describe("createAnalyticsMiddleware", () => {
         broken.recordEvent = async () => {
             throw new Error("storage down");
         };
-        const mw = createAnalyticsMiddleware(broken, fixedClock());
+        const mw = createAnalyticsMiddleware(broken, fixedClock(), null, {
+            gate: onGate,
+        });
         const result = { content: [] };
         await expect(mw({ method: "tools/call", params: { name: "x" } }, undefined, async () => result)).resolves.toBe(result);
         await flush();
@@ -102,11 +115,13 @@ describe("createAnalyticsMiddleware", () => {
 describe("installAnalytics gating", () => {
     const originalAnalytics = process.env.ENPILINK_ANALYTICS;
     const originalStorage = process.env.ENPILINK_STORAGE;
+    const originalNodeEnv = process.env.NODE_ENV;
     beforeEach(() => {
         setActiveStorage(null);
     });
     afterEach(() => {
         setActiveStorage(null);
+        setCaptureGate({ enabled: false, sampleRate: 1 });
         if (originalAnalytics === undefined) {
             delete process.env.ENPILINK_ANALYTICS;
         }
@@ -119,33 +134,69 @@ describe("installAnalytics gating", () => {
         else {
             process.env.ENPILINK_STORAGE = originalStorage;
         }
+        if (originalNodeEnv === undefined) {
+            delete process.env.NODE_ENV;
+        }
+        else {
+            process.env.NODE_ENV = originalNodeEnv;
+        }
     });
-    it("returns null and creates no adapter when disabled", async () => {
+    it("activates a default (memory) storage in dev even when analytics is OFF", async () => {
         delete process.env.ENPILINK_ANALYTICS;
+        delete process.env.ENPILINK_STORAGE; // default = memory in dev
+        delete process.env.NODE_ENV; // dev
         const result = await installAnalytics();
-        expect(result).toBeNull();
-        expect(getActiveStorage()).toBeNull();
+        // Storage is activated (so the config/observability UI can persist) ...
+        expect(result).not.toBeNull();
+        expect(getActiveStorage()).toBe(result?.storage);
+        // ... but capture stays OFF until the runtime toggle / env enables it.
+        expect(getCaptureGate().enabled).toBe(false);
+        await result?.storage.close();
     });
-    it("does NOT create a sqlite db file when disabled", async () => {
+    it("does NOT create a sqlite db file in dev when storage is the default (memory)", async () => {
         delete process.env.ENPILINK_ANALYTICS;
-        process.env.ENPILINK_STORAGE = "sqlite";
+        delete process.env.ENPILINK_STORAGE; // default = memory => no file
+        delete process.env.NODE_ENV;
         const dbPath = `${process.cwd()}/enpilink.db`;
         const preexisting = existsSync(dbPath);
-        await installAnalytics();
+        const result = await installAnalytics();
         if (!preexisting) {
             expect(existsSync(dbPath)).toBe(false);
         }
+        await result?.storage.close();
     });
-    it("resolves + inits + registers the active storage when enabled", async () => {
+    it("activates NOTHING in prod when analytics is OFF (no admin)", async () => {
+        delete process.env.ENPILINK_ANALYTICS;
+        process.env.NODE_ENV = "production";
+        const result = await installAnalytics();
+        expect(result).toBeNull();
+        expect(getActiveStorage()).toBeNull();
+    });
+    it("sets capture ON from env (env override) when ENPILINK_ANALYTICS=1", async () => {
         process.env.ENPILINK_ANALYTICS = "1";
         process.env.ENPILINK_STORAGE = "memory";
+        delete process.env.NODE_ENV;
         const result = await installAnalytics();
         expect(result).not.toBeNull();
         expect(result?.entry.filter).toBe("request");
         expect(typeof result?.entry.handler).toBe("function");
         expect(getActiveStorage()).toBe(result?.storage);
+        // env override -> gate enabled regardless of any DB value.
+        expect(getCaptureGate().enabled).toBe(true);
         await result?.storage.close();
     });
+    it("REUSES an already-active storage and never double-inits", async () => {
+        const existing = new MemoryStorageAdapter();
+        await existing.init();
+        setActiveStorage(existing);
+        process.env.ENPILINK_ANALYTICS = "1";
+        delete process.env.NODE_ENV;
+        const result = await installAnalytics();
+        // Same instance reused; no second adapter created.
+        expect(result?.storage).toBe(existing);
+        expect(getActiveStorage()).toBe(existing);
+        await existing.close();
+    });
 });
 describe("serverLog capture", () => {
     beforeEach(() => setActiveStorage(null));