@newrelic/preflight 1.62.0 → 1.63.1

package/dist/transport/unforwarded-session-monitor.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Makes `--local`'s silent New Relic data loss visible (#479).
+ *
+ * `--local` drains every per-session buffer that has no live owning `--stdio`
+ * engine (`LocalStore.drainAllBuffers()` skips any buffer whose
+ * `active-<sessionId>.pid` heartbeat names a live PID). When `--local` has
+ * cloud credentials it forwards those sessions to New Relic itself. When the
+ * config asks for cloud export (mode `cloud`/`both`) but this process can't
+ * see the credentials — typically because they live only in a shell
+ * environment variable, which the dashboard LaunchAgent does not inherit —
+ * `--local` falls back to local mode and those sessions never reach New
+ * Relic. This monitor records each such session, warns once per session, and
+ * backs the `unforwardedSessions` field on `GET /api/health`. The fix-it
+ * hint is logged once, by the caller's startup warning, not per session.
+ */
+import { type Mode } from '../config.js';
+/** Which credential this process was missing when it fell back to local mode. */
+export type CloudForwardingGapReason = 'missing-license-key' | 'missing-account-id';
+export interface CloudForwardingGap {
+    readonly reason: CloudForwardingGapReason;
+    /** The config field named by `reason`. */
+    readonly missingField: 'licenseKey' | 'accountId';
+    /** The mode the config asked for before the fallback (`cloud` or `both`). */
+    readonly requestedMode: Mode;
+}
+export interface UnforwardedSessionEntry {
+    readonly sessionId: string;
+    readonly toolCalls: number;
+    readonly firstSeenMs: number;
+    readonly lastSeenMs: number;
+}
+export interface UnforwardedSessionsSnapshot {
+    readonly reason: CloudForwardingGapReason;
+    readonly requestedMode: Mode;
+    /**
+     * Distinct identified sessions drained without forwarding, among those
+     * still tracked: past the cap the least recently active are evicted.
+     */
+    readonly count: number;
+    /** Sessions evicted to stay under the cap. One seen again counts again. */
+    readonly evictedSessions: number;
+    /** Tool calls drained without forwarding, across every session. */
+    readonly toolCalls: number;
+    /** The share of `toolCalls` with no usable session id. Not in `count`. */
+    readonly untrackedToolCalls: number;
+    /** Up to 20 sessions, most recently active first. */
+    readonly sessions: readonly UnforwardedSessionEntry[];
+    /** True when `sessions` omits some of the `count` sessions. */
+    readonly truncated: boolean;
+    readonly hint: string;
+}
+export interface UnforwardedSessionMonitorOptions {
+    readonly gap: CloudForwardingGap;
+    /**
+     * Cap on per-session entries kept in memory. Default 500. Past it the least
+     * recently active entry is evicted, so a session losing data now is always
+     * listed however long the process has been up.
+     */
+    readonly maxTrackedSessions?: number;
+    /** Test seam for the one-per-session warning. */
+    readonly warn?: (message: string, fields: Record<string, unknown>) => void;
+    /** Test seam for the clock. */
+    readonly now?: () => number;
+}
+/** How to fix the gap. Log it once at startup; the per-session warnings omit it. */
+export declare const UNFORWARDED_SESSIONS_HINT: string;
+/**
+ * Read the config-load error `--local` catches before falling back to local
+ * mode: a `MissingCloudCredentialError`, thrown directly or carried as the
+ * `cause` of a wrapping error. Returns null for any other error, which
+ * `--local` rethrows.
+ */
+export declare function detectCloudForwardingGap(err: unknown): CloudForwardingGap | null;
+export declare class UnforwardedSessionMonitor {
+    private readonly gap;
+    private readonly maxTrackedSessions;
+    private readonly warn;
+    private readonly now;
+    /** Least recently active first: an update re-inserts its entry at the end. */
+    private readonly sessions;
+    private evictedSessions;
+    private untrackedToolCalls;
+    private totalToolCalls;
+    private warnedUntracked;
+    constructor(options: UnforwardedSessionMonitorOptions);
+    /**
+     * Record one tool call drained from an ownerless buffer and not forwarded.
+     * Warns the first time each session is seen, and again if it comes back
+     * after eviction. A missing or malformed session id is counted without an
+     * entry.
+     */
+    recordToolCall(sessionId: string | null | undefined): void;
+    getSnapshot(): UnforwardedSessionsSnapshot;
+}
+//# sourceMappingURL=unforwarded-session-monitor.d.ts.map

package/dist/transport/unforwarded-session-monitor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unforwarded-session-monitor.d.ts","sourceRoot":"","sources":["../../src/transport/unforwarded-session-monitor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,EAA+B,KAAK,IAAI,EAAE,MAAM,cAAc,CAAC;AAStE,iFAAiF;AACjF,MAAM,MAAM,wBAAwB,GAAG,qBAAqB,GAAG,oBAAoB,CAAC;AAEpF,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,wBAAwB,CAAC;IAC1C,0CAA0C;IAC1C,QAAQ,CAAC,YAAY,EAAE,YAAY,GAAG,WAAW,CAAC;IAClD,6EAA6E;IAC7E,QAAQ,CAAC,aAAa,EAAE,IAAI,CAAC;CAC9B;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,MAAM,EAAE,wBAAwB,CAAC;IAC1C,QAAQ,CAAC,aAAa,EAAE,IAAI,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,2EAA2E;IAC3E,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,mEAAmE;IACnE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,0EAA0E;IAC1E,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,qDAAqD;IACrD,QAAQ,CAAC,QAAQ,EAAE,SAAS,uBAAuB,EAAE,CAAC;IACtD,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,GAAG,EAAE,kBAAkB,CAAC;IACjC;;;;OAIG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,iDAAiD;IACjD,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IAC3E,+BAA+B;IAC/B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAED,oFAAoF;AACpF,eAAO,MAAM,yBAAyB,QAGwC,CAAC;AAE/E;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,OAAO,GAAG,kBAAkB,GAAG,IAAI,CAahF;AAQD,qBAAa,yBAAyB;IACpC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAqB;IACzC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAS;IAC5C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA6D;IAClF,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,8EAA8E;IAC9E,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmC;IAC5D,OAAO,CAAC,eAAe,CAAK;IAC5B,OAAO,CAAC,kBAAkB,CAAK;IAC/B,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,eAAe,CAAS;gBAEpB,OAAO,EAAE,gCAAgC;IAOrD;;;;;OAKG;IACH,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI;IAmC1D,WAAW,IAAI,2BAA2B;CAiB3C"}

package/dist/transport/unforwarded-session-monitor.js

@@ -0,0 +1,120 @@
+/**
+ * Makes `--local`'s silent New Relic data loss visible (#479).
+ *
+ * `--local` drains every per-session buffer that has no live owning `--stdio`
+ * engine (`LocalStore.drainAllBuffers()` skips any buffer whose
+ * `active-<sessionId>.pid` heartbeat names a live PID). When `--local` has
+ * cloud credentials it forwards those sessions to New Relic itself. When the
+ * config asks for cloud export (mode `cloud`/`both`) but this process can't
+ * see the credentials — typically because they live only in a shell
+ * environment variable, which the dashboard LaunchAgent does not inherit —
+ * `--local` falls back to local mode and those sessions never reach New
+ * Relic. This monitor records each such session, warns once per session, and
+ * backs the `unforwardedSessions` field on `GET /api/health`. The fix-it
+ * hint is logged once, by the caller's startup warning, not per session.
+ */
+import { createLogger } from '../shared/index.js';
+import { MissingCloudCredentialError } from '../config.js';
+const logger = createLogger('unforwarded-session-monitor');
+const SESSION_ID_RE = /^[a-zA-Z0-9_-]{1,128}$/;
+const DEFAULT_MAX_TRACKED_SESSIONS = 500;
+/** How many sessions `getSnapshot()` lists, newest activity first. */
+const SNAPSHOT_SESSION_LIMIT = 20;
+/** How to fix the gap. Log it once at startup; the per-session warnings omit it. */
+export const UNFORWARDED_SESSIONS_HINT = 'This dashboard process is not forwarding to New Relic because it cannot see your cloud ' +
+    'credentials. Add licenseKey and accountId to the config file (the dashboard LaunchAgent ' +
+    'does not inherit shell environment variables), then restart the dashboard.';
+/**
+ * Read the config-load error `--local` catches before falling back to local
+ * mode: a `MissingCloudCredentialError`, thrown directly or carried as the
+ * `cause` of a wrapping error. Returns null for any other error, which
+ * `--local` rethrows.
+ */
+export function detectCloudForwardingGap(err) {
+    const source = err instanceof MissingCloudCredentialError
+        ? err
+        : err instanceof Error && err.cause instanceof MissingCloudCredentialError
+            ? err.cause
+            : undefined;
+    if (!source)
+        return null;
+    return {
+        reason: source.missingField === 'licenseKey' ? 'missing-license-key' : 'missing-account-id',
+        missingField: source.missingField,
+        requestedMode: source.mode,
+    };
+}
+export class UnforwardedSessionMonitor {
+    gap;
+    maxTrackedSessions;
+    warn;
+    now;
+    /** Least recently active first: an update re-inserts its entry at the end. */
+    sessions = new Map();
+    evictedSessions = 0;
+    untrackedToolCalls = 0;
+    totalToolCalls = 0;
+    warnedUntracked = false;
+    constructor(options) {
+        this.gap = options.gap;
+        this.maxTrackedSessions = options.maxTrackedSessions ?? DEFAULT_MAX_TRACKED_SESSIONS;
+        this.warn = options.warn ?? ((message, fields) => logger.warn(message, fields));
+        this.now = options.now ?? Date.now;
+    }
+    /**
+     * Record one tool call drained from an ownerless buffer and not forwarded.
+     * Warns the first time each session is seen, and again if it comes back
+     * after eviction. A missing or malformed session id is counted without an
+     * entry.
+     */
+    recordToolCall(sessionId) {
+        this.totalToolCalls++;
+        const nowMs = this.now();
+        const existing = typeof sessionId === 'string' ? this.sessions.get(sessionId) : undefined;
+        if (typeof sessionId === 'string' && existing) {
+            existing.toolCalls++;
+            existing.lastSeenMs = nowMs;
+            this.sessions.delete(sessionId);
+            this.sessions.set(sessionId, existing);
+            return;
+        }
+        if (typeof sessionId !== 'string' || !SESSION_ID_RE.test(sessionId)) {
+            this.untrackedToolCalls++;
+            if (!this.warnedUntracked) {
+                this.warnedUntracked = true;
+                this.warn('Tool calls with no trackable session id are not reaching New Relic; counting them as untrackedToolCalls', { reason: this.gap.reason, requestedMode: this.gap.requestedMode });
+            }
+            return;
+        }
+        if (this.sessions.size >= this.maxTrackedSessions) {
+            const leastRecent = this.sessions.keys().next().value;
+            if (leastRecent !== undefined)
+                this.sessions.delete(leastRecent);
+            this.evictedSessions++;
+        }
+        this.sessions.set(sessionId, { toolCalls: 1, firstSeenMs: nowMs, lastSeenMs: nowMs });
+        this.warn('Session has no owning --stdio engine and is not reaching New Relic', {
+            sessionId,
+            reason: this.gap.reason,
+            requestedMode: this.gap.requestedMode,
+        });
+    }
+    getSnapshot() {
+        const sessions = [...this.sessions]
+            .slice(-SNAPSHOT_SESSION_LIMIT)
+            .reverse()
+            .map(([sessionId, e]) => ({ sessionId, ...e }));
+        return {
+            reason: this.gap.reason,
+            requestedMode: this.gap.requestedMode,
+            count: this.sessions.size,
+            evictedSessions: this.evictedSessions,
+            toolCalls: this.totalToolCalls,
+            untrackedToolCalls: this.untrackedToolCalls,
+            sessions,
+            truncated: sessions.length < this.sessions.size,
+            hint: UNFORWARDED_SESSIONS_HINT,
+        };
+    }
+}
+//# sourceMappingURL=unforwarded-session-monitor.js.map

package/dist/transport/unforwarded-session-monitor.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@newrelic/preflight",
-  "version": "1.62.0",
+  "version": "1.63.1",
   "mcpName": "io.github.newrelic-experimental/preflight",
   "type": "module",
   "license": "Apache-2.0",