@newrelic/preflight 1.18.1 → 1.18.3

package/dist/index.js

@@ -2,6 +2,7 @@
 import 'dotenv/config';
 import { Command, Option } from 'commander';
 import { readFileSync, realpathSync } from 'node:fs';
+import { timingSafeEqual } from 'node:crypto';
 import { resolve } from 'node:path';
 import { AlertLog } from './alerts/alert-log.js';
 import { AlertSnapshotCollector } from './alerts/alert-snapshot-collector.js';
@@ -24,7 +25,7 @@ import { migrateStoragePath } from './install/migrate.js';
 import { checkNodeVersion } from './install/node-version-check.js';
 import { localDateKey, todayPortionOfSessionCost } from './lib/date.js';
 import { AntiPatternDetector } from './metrics/anti-patterns.js';
-import { ApiFailureTracker } from './metrics/api-failure-tracker.js';
+import { ApiFailureTracker, mapClaudeCodeErrorType } from './metrics/api-failure-tracker.js';
 import { BudgetTracker } from './metrics/budget-tracker.js';
 import { ClaudeMdTracker } from './metrics/claudemd-tracker.js';
 import { CollaborationProfiler } from './metrics/collaboration-profile.js';
@@ -75,6 +76,7 @@ import { SessionSpan } from './tracing/session-span.js';
 import { TaskSpanTracker } from './tracing/task-span-tracker.js';
 import { emitToolCallSpan } from './tracing/tool-call-span.js';
 import { NrIngestManager } from './transport/nr-ingest.js';
+import { HomelabAccumulator, HomelabForwarder } from './homelab/index.js';
 import { VERSION } from './version.js';
 export { loadMcpConfig, redactSensitive } from './config.js';
 export { AmazonQAdapter, ClaudeCodeAdapter, ContinueAdapter, CopilotAdapter, createDefaultRegistry, CursorAdapter, GenericMcpAdapter, parseCopilotUsageResponse, PlatformRegistry, REPORT_SESSION_END_TOOL, REPORT_SESSION_START_TOOL, REPORT_TOOL_CALL_TOOL, validateReportToolCallInput, WindsurfAdapter, ZedAdapter, } from './platforms/index.js';
@@ -324,6 +326,7 @@ export function startDashboardRepoll(opts) {
 const SUBCOMMAND_NAMES = [
     'deploy-dashboards',
     'deploy-alerts',
+    'server',
     'install',
     'uninstall',
     'setup',
@@ -335,8 +338,8 @@ const SUBCOMMAND_NAMES = [
 ];
 // Install-CLI subcommands — a subset of SUBCOMMAND_NAMES routed to runInstallCli.
 // Derived from SUBCOMMAND_NAMES to ensure a single source of truth: deploy-*
-// commands are excluded and handled by the commander path in dispatchSubcommand.
-const INSTALL_CLI_SUBCOMMANDS = SUBCOMMAND_NAMES.filter((s) => s !== 'deploy-dashboards' && s !== 'deploy-alerts');
+// and server commands are excluded and handled by the commander path in dispatchSubcommand.
+const INSTALL_CLI_SUBCOMMANDS = SUBCOMMAND_NAMES.filter((s) => s !== 'deploy-dashboards' && s !== 'deploy-alerts' && s !== 'server');
 function isSubcommand(value) {
     return typeof value === 'string' && SUBCOMMAND_NAMES.includes(value);
 }
@@ -392,6 +395,76 @@ export async function dispatchSubcommand(argv) {
             process.exitCode = code;
         });
     }
+    else if (sub === 'server') {
+        program
+            .command('server')
+            .description('Start Preflight in homelab server mode — receives events forwarded from remote clients and accumulates them to disk (no dashboard yet — see docs/homelab.md)')
+            .option('--port <port>', 'Port to bind to (default: 7777 or NEW_RELIC_AI_HOMELAB_SERVER_PORT)')
+            .option('--token <token>', 'Bearer token for /ingest auth (default: NEW_RELIC_AI_HOMELAB_TOKEN)')
+            .option('--bind <address>', 'Bind address (default: 0.0.0.0 or NEW_RELIC_AI_HOMELAB_BIND_ADDRESS)')
+            .option('--config <path>', 'Path to config file')
+            .action(async (opts) => {
+            if (opts.port)
+                process.env.NEW_RELIC_AI_HOMELAB_SERVER_PORT = opts.port;
+            if (opts.token)
+                process.env.NEW_RELIC_AI_HOMELAB_TOKEN = opts.token;
+            if (opts.bind)
+                process.env.NEW_RELIC_AI_HOMELAB_BIND_ADDRESS = opts.bind;
+            // server mode never needs cloud credentials — force local so loadMcpConfig
+            // doesn't require licenseKey/accountId.
+            process.env.NR_AI_MODE = 'local';
+            const config = loadConfigOrDie({ config: opts.config });
+            const token = config.homelabToken;
+            if (!token) {
+                process.stderr.write('[preflight] error: homelab server requires a token. Set --token or NEW_RELIC_AI_HOMELAB_TOKEN.\n');
+                process.exit(1);
+            }
+            const accumulator = new HomelabAccumulator({ storagePath: config.storagePath });
+            accumulator.start();
+            const bus = new LiveEventBus();
+            const dashboardServer = new DashboardServer({
+                port: config.homelabServer.port,
+                host: config.homelabServer.bindAddress,
+                bus,
+                serverMode: true,
+                ingestHandler: (authHeader, body) => {
+                    const expected = `Bearer ${token}`;
+                    const isAuthed = authHeader !== undefined &&
+                        authHeader.length === expected.length &&
+                        timingSafeEqual(Buffer.from(authHeader), Buffer.from(expected));
+                    if (!isAuthed)
+                        return 401;
+                    const result = accumulator.handleIngest(body);
+                    return result === 'ok' ? 204 : 400;
+                },
+            });
+            await dashboardServer.start();
+            logger.info('Homelab server ready', {
+                port: config.homelabServer.port,
+                bind: config.homelabServer.bindAddress,
+            });
+            // Keep the action (and therefore program.parseAsync) alive until a
+            // signal fires — without this, the action returns immediately and
+            // dispatchSubcommand exits the process.
+            await new Promise((resolve) => {
+                let shutting = false;
+                const shutdown = async () => {
+                    if (shutting)
+                        return;
+                    shutting = true;
+                    accumulator.stop();
+                    await dashboardServer.stop();
+                    resolve();
+                };
+                process.on('SIGTERM', () => {
+                    void shutdown();
+                });
+                process.on('SIGINT', () => {
+                    void shutdown();
+                });
+            });
+        });
+    }
     else {
         program
             .command('deploy-alerts')
@@ -582,6 +655,7 @@ async function main() {
         }, getPendingConfirmationCapMs());
         pendingConfirmationCapTimer.unref?.();
     };
+    let homelabForwarder = null;
     let shuttingDown = false;
     const shutdown = async () => {
         if (shuttingDown)
@@ -652,6 +726,7 @@ async function main() {
                 nrIngest ? nrIngest.stop() : Promise.resolve(),
                 mcpServer ? mcpServer.close() : Promise.resolve(),
                 proxyManager ? proxyManager.stop() : Promise.resolve(),
+                homelabForwarder ? homelabForwarder.stop() : Promise.resolve(),
             ]);
             for (const r of stopResults) {
                 if (r.status === 'rejected') {
@@ -818,11 +893,12 @@ async function main() {
         });
         const toolSelectionScorer = new ToolSelectionScorer();
         const qualityProxyTracker = new QualityProxyTracker();
-        // ApiFailureTracker is instantiated but never fed: recordRequest()/recordFailure()
-        // require visibility into model-API-level traffic (LLM provider rate limits,
-        // timeouts, auth errors), which is not observable in either stdio mode (hooks
-        // only see Claude Code's own tool calls) or proxy mode (which forwards to MCP
-        // servers, not the model API). Kept dormant for a future LLM-facing proxy.
+        // Fed via Claude Code's StopFailure hook (see the onApiFailure callback on
+        // eventProcessor below) through recordFailure(). recordRequest() still has
+        // no caller — request-level latency/throughput stays unobservable — and
+        // recordFailure()'s tokensInFlight/recoveryMs/retryCount/totalRequests
+        // inputs stay at their "unknown" defaults for the same reason. See
+        // api-failure-tracker.ts's API_FAILURE_PARTIAL_DATA_NOTE for the full story.
         const apiFailureTracker = new ApiFailureTracker();
         liveSessionRegistry = new LiveSessionRegistry();
         liveSessionRegistry.startSampling();
@@ -1350,6 +1426,7 @@ async function main() {
                     },
                     antiPatternDetector,
                     retryDetector,
+                    apiFailureTracker,
                     instructionDriftTracker,
                     decisionTracker,
                     turnCostAttributor,
@@ -1541,11 +1618,34 @@ async function main() {
                 costTracker,
                 efficiencyScorer,
                 feedbackCollector,
+                apiFailureTracker,
                 turnCostAttributor,
                 sessionTraceId,
             });
             capturedNrIngest = nrIngest;
         }
+        // Start homelab forwarder if configured. Construction validates
+        // homelabServerUrl (scheme + cloud-metadata-endpoint check) and can
+        // throw — caught here so a bad/malicious URL only disables forwarding,
+        // matching the "forwarding failures are non-fatal" contract in
+        // docs/homelab.md, rather than crashing MCP startup.
+        if (config.homelabServerUrl && config.homelabToken) {
+            try {
+                homelabForwarder = new HomelabForwarder({
+                    serverUrl: config.homelabServerUrl,
+                    token: config.homelabToken,
+                    developer: config.developer,
+                    sessionId: sessionTraceId ?? 'unknown',
+                });
+                homelabForwarder.start();
+            }
+            catch (err) {
+                homelabForwarder = null;
+                logger.error('Homelab forwarder failed to start — continuing without it', {
+                    error: String(err),
+                });
+            }
+        }
         const capturedAlertEngine = alertEngine;
         const capturedAlertSnapshotCollector = alertSnapshotCollector;
         budgetTracker.setOnThreshold((event) => {
@@ -1774,6 +1874,7 @@ async function main() {
                         });
                     }
                 }
+                homelabForwarder?.enqueue(record);
             },
             onTokenEvent: (tokenEvent) => {
                 if (!costTracker || !config)
@@ -1939,6 +2040,31 @@ async function main() {
                         : {}),
                 });
             },
+            onApiFailure: (frame) => {
+                if (!config)
+                    return;
+                const errorType = mapClaudeCodeErrorType(frame.rawErrorType);
+                // Prefer a model already learned from real token events over the
+                // config default, mirroring the estimateModel fallback above.
+                const model = costTracker.getMetrics().model ?? config.model ?? 'unknown';
+                const turnNumber = turnTracker.getCurrentTurnNumber();
+                // totalTurnsInSession is left unspecified: there is no reliable
+                // "total turns for this session" figure available at failure time
+                // (the session may still be ongoing), and recordFailure() already
+                // defaults it sensibly for sessionPhase bucketing.
+                const duringToolExecution = eventProcessor !== undefined && eventProcessor.pendingCount > 0;
+                apiFailureTracker.recordFailure({
+                    errorType,
+                    model,
+                    turnNumber,
+                    // Unobservable from StopFailure; see api-failure-tracker.ts's note constant.
+                    tokensInFlight: 0,
+                    // Known, not a placeholder: StopFailure only fires after Claude
+                    // Code's own retries are exhausted with no successful recovery.
+                    recoverySucceeded: false,
+                    duringToolExecution,
+                });
+            },
         });
         persistSession = (opts) => {
             if (!sessionStore || !sessionTracker || !taskDetector || !config)
@@ -2305,6 +2431,7 @@ async function main() {
                     costTracker,
                     efficiencyScorer,
                     feedbackCollector,
+                    apiFailureTracker,
                     turnCostAttributor,
                     sessionTraceId: realId,
                 });
@@ -2606,6 +2733,13 @@ async function main() {
             // proxied traffic instead of silently living in memory only.
             const proxyLocalStore = new LocalStore(config.storagePath);
             proxyLocalStore.initialize();
+            // Proxy mode never constructs a HookEventProcessor, so nothing ever
+            // calls recordFailure() on this instance (StopFailure is a Claude
+            // Code-side hook, not something proxied traffic can surface) — passed
+            // in anyway so NrIngestManager's emitMetrics() call is uniform across
+            // modes, legitimately reporting zero failures rather than being asked
+            // to handle a missing tracker.
+            const apiFailureTracker = new ApiFailureTracker();
             nrIngest = new NrIngestManager({
                 licenseKey: config.licenseKey,
                 transportOptions: {
@@ -2621,6 +2755,7 @@ async function main() {
                 localStore: proxyLocalStore,
                 eventHarvestIntervalMs: config.harvestIntervalMs.events,
                 metricHarvestIntervalMs: config.harvestIntervalMs.metrics,
+                apiFailureTracker,
                 sessionTraceId,
                 // Proxy mode has no single coherent session — sessionTracker above is
                 // never fed per-client activity, so the ai.session.* gauges would