@jagilber-org/index-server 1.22.1 → 1.26.1

package/dist/server/handshakeManager.d.ts

@@ -1,25 +1,25 @@
-export declare function isHandshakeTraceEnabled(): boolean;
-export declare function handshakeLog(stage: string, data?: Record<string, unknown>): void;
-export declare function isHandshakeFallbacksEnabled(): boolean;
-export declare const SUPPORTED_PROTOCOL_VERSIONS: string[];
-export interface HandshakeEvent {
-    seq: number;
-    ts: string;
-    stage: string;
-    extra?: Record<string, unknown>;
-}
-export declare function record(stage: string, extra?: Record<string, unknown>): void;
-export declare function isInitFrameDiagEnabled(): boolean;
-export declare function initFrameLog(stage: string, extra?: Record<string, unknown>): void;
-export declare function negotiateProtocolVersion(requested?: string): string;
-export declare function emitReadyGlobal(server: any, reason: string): void;
 /**
- * Pre-connect stdin sniffer: if we observe an initialize request but downstream logic fails
- * to emit server/ready, schedule a guarded fallback emission.
+ * Handshake/protocol negotiation facade for the MCP server.
+ *
+ * The historical implementation lived in this single file (~500 lines, ~20
+ * silent catch blocks — see issue #138). It has been decomposed into focused
+ * modules under `./handshake/` so each concern can be unit-tested in isolation:
+ *
+ *   - `handshake/tracing.ts`            stderr-safe logging + ring buffer
+ *   - `handshake/protocol.ts`           pure version negotiation
+ *   - `handshake/initializeDetector.ts` pure stdin scanning
+ *   - `handshake/fallbackFrames.ts`     pure JSON-RPC frame builders
+ *   - `handshake/readyEmitter.ts`       server/ready dispatch
+ *   - `handshake/stdinSniffer.ts`       stdin sniff + synthetic dispatch
+ *   - `handshake/safetyFallbacks.ts`    timer-driven last-resort fallbacks
+ *
+ * This file remains the public import surface for the rest of the server
+ * (`sdkServer.ts`, `mcpLogBridge.ts`, mocks in unit tests) and re-exports the
+ * full legacy API.
  */
-export declare function setupStdinSniffer(server: any): void;
-/**
- * Safety fallback timers for missed ready emissions, unconditional DIAG fallback,
- * and _oninitialize patch for protocol negotiation.
- */
-export declare function setupSafetyFallbacks(server: any): void;
+export { isHandshakeTraceEnabled, handshakeLog, record, initFrameLog, isInitFrameDiagEnabled, exposeGlobalEventsRef, getHandshakeEvents, } from './handshake/tracing';
+export type { HandshakeEvent } from './handshake/tracing';
+export { SUPPORTED_PROTOCOL_VERSIONS, negotiateProtocolVersion, isHandshakeFallbacksEnabled, } from './handshake/protocol';
+export { emitReadyGlobal } from './handshake/readyEmitter';
+export { setupStdinSniffer } from './handshake/stdinSniffer';
+export { setupSafetyFallbacks } from './handshake/safetyFallbacks';

package/dist/server/handshakeManager.js

@@ -1,470 +1,40 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SUPPORTED_PROTOCOL_VERSIONS = void 0;
-exports.isHandshakeTraceEnabled = isHandshakeTraceEnabled;
-exports.handshakeLog = handshakeLog;
-exports.isHandshakeFallbacksEnabled = isHandshakeFallbacksEnabled;
-exports.record = record;
-exports.isInitFrameDiagEnabled = isInitFrameDiagEnabled;
-exports.initFrameLog = initFrameLog;
-exports.negotiateProtocolVersion = negotiateProtocolVersion;
-exports.emitReadyGlobal = emitReadyGlobal;
-exports.setupStdinSniffer = setupStdinSniffer;
-exports.setupSafetyFallbacks = setupSafetyFallbacks;
-/* eslint-disable @typescript-eslint/no-explicit-any */
+exports.setupSafetyFallbacks = exports.setupStdinSniffer = exports.emitReadyGlobal = exports.isHandshakeFallbacksEnabled = exports.negotiateProtocolVersion = exports.SUPPORTED_PROTOCOL_VERSIONS = exports.getHandshakeEvents = exports.exposeGlobalEventsRef = exports.isInitFrameDiagEnabled = exports.initFrameLog = exports.record = exports.handshakeLog = exports.isHandshakeTraceEnabled = void 0;
 /**
- * Handshake/protocol negotiation logic for the MCP server.
- * Manages protocol version negotiation, handshake tracing, ready notification
- * emission, stdin sniffing for initialize detection, and safety fallbacks.
+ * Handshake/protocol negotiation facade for the MCP server.
+ *
+ * The historical implementation lived in this single file (~500 lines, ~20
+ * silent catch blocks — see issue #138). It has been decomposed into focused
+ * modules under `./handshake/` so each concern can be unit-tested in isolation:
+ *
+ *   - `handshake/tracing.ts`            stderr-safe logging + ring buffer
+ *   - `handshake/protocol.ts`           pure version negotiation
+ *   - `handshake/initializeDetector.ts` pure stdin scanning
+ *   - `handshake/fallbackFrames.ts`     pure JSON-RPC frame builders
+ *   - `handshake/readyEmitter.ts`       server/ready dispatch
+ *   - `handshake/stdinSniffer.ts`       stdin sniff + synthetic dispatch
+ *   - `handshake/safetyFallbacks.ts`    timer-driven last-resort fallbacks
+ *
+ * This file remains the public import surface for the rest of the server
+ * (`sdkServer.ts`, `mcpLogBridge.ts`, mocks in unit tests) and re-exports the
+ * full legacy API.
  */
-const runtimeConfig_1 = require("../config/runtimeConfig");
-// ---------------------------------------------------------------------------
-// Optional handshake tracing (enable via INDEX_SERVER_TRACE=handshake)
-// Emits structured JSON lines to stderr prefixed with [handshake].
-// Each event receives a monotonic sequence number.
-// ---------------------------------------------------------------------------
-function isHandshakeTraceEnabled() { return (0, runtimeConfig_1.getRuntimeConfig)().trace.has('handshake'); }
-let HANDSHAKE_SEQ = 0;
-function handshakeLog(stage, data) {
-    if (!isHandshakeTraceEnabled())
-        return; // fast path
-    try {
-        const payload = { handshake: true, seq: ++HANDSHAKE_SEQ, ts: new Date().toISOString(), stage, ...(data || {}) };
-        process.stderr.write(`[handshake] ${JSON.stringify(payload)}\n`);
-    }
-    catch { /* ignore */ }
-}
-// Central gating flag: by default we disable ALL non-primary ready fallbacks (watchdogs, safety timeouts,
-// stdin sniff synthetic initialize, unconditional init fallbacks, etc.). Enable via
-// INDEX_SERVER_INIT_FEATURES=handshakeFallbacks to re-enable the safety nets.
-function isHandshakeFallbacksEnabled() { return (0, runtimeConfig_1.getRuntimeConfig)().initFeatures.has('handshakeFallbacks'); }
-// Supported protocol versions (ordered descending preference – first is default)
-exports.SUPPORTED_PROTOCOL_VERSIONS = ['2025-06-18', '2024-11-05', '2024-10-07'];
-const HANDSHAKE_EVENTS = [];
-function record(stage, extra) {
-    const evt = { seq: ++HANDSHAKE_SEQ, ts: new Date().toISOString(), stage, extra };
-    HANDSHAKE_EVENTS.push(evt);
-    if (HANDSHAKE_EVENTS.length > 50)
-        HANDSHAKE_EVENTS.shift();
-    if (isHandshakeTraceEnabled()) {
-        try {
-            process.stderr.write(`[handshake] ${JSON.stringify(evt)}\n`);
-        }
-        catch { /* ignore */ }
-    }
-}
-// ---------------------------------------------------------------------------
-// Initialize frame instrumentation (opt-in via INDEX_SERVER_TRACE=initFrame)
-// Provides high-fidelity breadcrumbs to stderr with prefix [init-frame]
-// ---------------------------------------------------------------------------
-function isInitFrameDiagEnabled() { return (0, runtimeConfig_1.getRuntimeConfig)().trace.has('initFrame'); }
-function initFrameLog(stage, extra) {
-    if (!isInitFrameDiagEnabled())
-        return;
-    try {
-        const payload = { stage, t: Date.now(), ...(extra || {}) };
-        process.stderr.write(`[init-frame] ${JSON.stringify(payload)}\n`);
-    }
-    catch { /* ignore */ }
-}
-// Expose reference for diagnostics_handshake tool (read-only access)
-try {
-    global.HANDSHAKE_EVENTS_REF = HANDSHAKE_EVENTS;
-}
-catch { /* ignore */ }
-// Helper: negotiate a protocol version with graceful fallback
-function negotiateProtocolVersion(requested) {
-    if (!requested)
-        return exports.SUPPORTED_PROTOCOL_VERSIONS[0];
-    if (exports.SUPPORTED_PROTOCOL_VERSIONS.includes(requested))
-        return requested;
-    // Future: could attempt minor compatibility mapping. For now choose latest supported.
-    return exports.SUPPORTED_PROTOCOL_VERSIONS[0];
-}
-// Module-level idempotent ready emitter so both createSdkServer and startSdkServer dynamic paths can use it.
-function emitReadyGlobal(server, reason) {
-    // Unified, ordering-safe emission of server/ready. Invoked ONLY after the
-    // initialize response has been (or is about to be) flushed.
-    try {
-        if (!server)
-            return;
-        if (server.__readyNotified)
-            return;
-        // Ordering gate: ONLY allow emission if initialize response actually flushed
-        if (!server.__initResponseSent) {
-            if (!isHandshakeFallbacksEnabled()) {
-                return; // strict mode: never emit early
-            }
-            const allowReasons = new Set(['unconditional-init-fallback', 'unconditional-init-fallback-direct', 'forced-init-fallback']);
-            if (!allowReasons.has(reason))
-                return;
-        }
-        const v = server.__declaredVersion || server.version || '0.0.0';
-        // Mark before sending to avoid re-entrancy
-        server.__readyNotified = true;
-        record('ready_emitted', { reason, version: v });
-        try {
-            process.stderr.write(`[ready] emit reason=${reason} version=${v}\n`);
-        }
-        catch { /* ignore */ }
-        const msg = { jsonrpc: '2.0', method: 'server/ready', params: { version: v } };
-        let dispatched = false;
-        // Prefer raw transport to bypass any SDK notification filtering.
-        try {
-            const t = server._transport;
-            if (t?.send) {
-                t.send(msg)?.catch?.(() => { });
-                dispatched = true;
-            }
-        }
-        catch { /* ignore */ }
-        if (!dispatched) {
-            try {
-                server.sendNotification?.({ method: 'server/ready', params: { version: v } });
-                dispatched = true;
-            }
-            catch { /* ignore */ }
-        }
-        if (!dispatched) {
-            // Final fallback direct stdout (rare path)
-            try {
-                process.stdout.write(JSON.stringify(msg) + '\n');
-            }
-            catch { /* ignore */ }
-        }
-        // Always follow with tools/list_changed AFTER ready to guarantee ordering.
-        try {
-            if (typeof server.sendToolListChanged === 'function') {
-                server.sendToolListChanged();
-                record('list_changed_after_ready');
-            }
-        }
-        catch { /* ignore */ }
-    }
-    catch { /* ignore */ }
-}
-/**
- * Pre-connect stdin sniffer: if we observe an initialize request but downstream logic fails
- * to emit server/ready, schedule a guarded fallback emission.
- */
-function setupStdinSniffer(server) {
-    try {
-        const disableInitSniff = (0, runtimeConfig_1.getRuntimeConfig)().initFeatures.has('disableSniff');
-        if (!server || disableInitSniff)
-            return;
-        const INIT_FALLBACK_ENABLED = (0, runtimeConfig_1.getRuntimeConfig)().initFeatures.has('initFallback');
-        let __sniffBuf = '';
-        if ((0, runtimeConfig_1.getRuntimeConfig)().trace.has('healthMixed')) {
-            try {
-                if (!server.__diagRQMap) {
-                    server.__diagRQMap = new Map();
-                    server.__diagQueueDepthSniff = 0;
-                }
-            }
-            catch { /* ignore */ }
-        }
-        process.stdin.on('data', (chunk) => {
-            try {
-                // Log first chunk (sanitized) once for corruption triage
-                if ((0, runtimeConfig_1.getRuntimeConfig)().trace.has('healthMixed') && !server.__diagFirstChunkLogged) {
-                    server.__diagFirstChunkLogged = true;
-                    const raw = chunk.toString('utf8');
-                    const snippet = raw.replace(/\r/g, ' ').replace(/\n/g, '\\n').slice(0, 240);
-                    process.stderr.write(`[diag] ${Date.now()} stdin_first_chunk size=${chunk.length} snippet="${snippet}"\n`);
-                }
-                __sniffBuf += chunk.toString('utf8');
-                // Fast substring / subsequence search instead of full JSON parse
-                if (!(server.__sniffedInit)) {
-                    const bufForScan = __sniffBuf.slice(-8000); // bound work
-                    const direct = /"method"\s*:\s*"initialize"/.test(bufForScan);
-                    let fuzzy = false;
-                    let subseq = false;
-                    if (!direct) {
-                        // Fuzzy reconstruction (bounded gaps) scoped near a method sentinel
-                        const target = 'initialize';
-                        const methodIdx = bufForScan.indexOf('"method"');
-                        const sliceA = methodIdx !== -1 ? bufForScan.slice(methodIdx, methodIdx + 1200) : '';
-                        const trySlices = sliceA ? [sliceA] : [];
-                        if (!sliceA && (0, runtimeConfig_1.getRuntimeConfig)().trace.has('healthMixed'))
-                            trySlices.push(bufForScan.slice(-2000));
-                        for (const slice of trySlices) {
-                            let ti = 0;
-                            let gaps = 0;
-                            for (let i = 0; i < slice.length && ti < target.length; i++) {
-                                const ch = slice[i];
-                                if (ch.toLowerCase?.() === target[ti]) {
-                                    ti++;
-                                    gaps = 0;
-                                    continue;
-                                }
-                                if (gaps < 3) {
-                                    gaps++;
-                                    continue;
-                                }
-                                ti = 0;
-                                gaps = 0;
-                                if (ch.toLowerCase?.() === target[ti]) {
-                                    ti++;
-                                }
-                            }
-                            if (ti === target.length) {
-                                fuzzy = true;
-                                break;
-                            }
-                        }
-                        // Subsequence (very tolerant) – strip non-letters and search contiguous
-                        if (!fuzzy) {
-                            const letters = bufForScan.replace(/[^a-zA-Z]/g, '').toLowerCase();
-                            let ti = 0;
-                            for (let i = 0; i < letters.length && ti < target.length; i++) {
-                                if (letters[i] === target[ti])
-                                    ti++;
-                            }
-                            if (ti === target.length)
-                                subseq = true;
-                        }
-                    }
-                    if (direct || fuzzy || subseq) {
-                        server.__sniffedInit = true;
-                        const mode = direct ? 'direct' : (fuzzy ? 'fuzzy' : 'subseq');
-                        if ((0, runtimeConfig_1.getRuntimeConfig)().trace.has('healthMixed')) {
-                            try {
-                                const norm = bufForScan.slice(0, 400).replace(/\r/g, ' ').replace(/\n/g, '\\n');
-                                process.stderr.write(`[diag] ${Date.now()} sniff_init_${mode}_detect buffer_bytes=${__sniffBuf.length} preview="${norm}"\n`);
-                            }
-                            catch { /* ignore */ }
-                        }
-                        // Schedule marking + optional synthetic dispatch if initialize not parsed normally
-                        setTimeout(() => {
-                            try {
-                                if (!server.__sawInitializeRequest) {
-                                    server.__sawInitializeRequest = true;
-                                    if ((0, runtimeConfig_1.getRuntimeConfig)().trace.has('healthMixed')) {
-                                        try {
-                                            process.stderr.write(`[diag] ${Date.now()} sniff_init_mark_sawInit mode=${mode}\n`);
-                                        }
-                                        catch { /* ignore */ }
-                                    }
-                                }
-                                if (INIT_FALLBACK_ENABLED && !server.__initResponseSent) {
-                                    setTimeout(() => {
-                                        try {
-                                            if (server.__initResponseSent || server.__syntheticInitDispatched)
-                                                return;
-                                            let id = 1;
-                                            const idMatch = /"id"\s*:\s*(\d{1,6})/.exec(bufForScan);
-                                            if (idMatch)
-                                                id = parseInt(idMatch[1], 10);
-                                            const req = { jsonrpc: '2.0', id, method: 'initialize', params: {} };
-                                            server.__syntheticInitDispatched = true;
-                                            const dispatch = server._onRequest || server._onrequest;
-                                            if (typeof dispatch === 'function') {
-                                                if ((0, runtimeConfig_1.getRuntimeConfig)().trace.has('healthMixed')) {
-                                                    try {
-                                                        process.stderr.write(`[diag] ${Date.now()} sniff_init_synthetic_dispatch id=${id}\n`);
-                                                    }
-                                                    catch { /* ignore */ }
-                                                }
-                                                try {
-                                                    dispatch.call(server, req);
-                                                }
-                                                catch { /* ignore */ }
-                                            }
-                                        }
-                                        catch { /* ignore */ }
-                                    }, 40).unref?.();
-                                    if (INIT_FALLBACK_ENABLED) {
-                                        // Forced result fallback if still not sent after additional grace
-                                        setTimeout(() => {
-                                            try {
-                                                if (server.__initResponseSent)
-                                                    return;
-                                                const tr = server._transport || server.__transportRef;
-                                                if (tr && typeof tr.send === 'function') {
-                                                    let negotiated = '2024-11-05';
-                                                    try {
-                                                        negotiated = negotiateProtocolVersion('2024-11-05') || negotiated;
-                                                    }
-                                                    catch { /* ignore */ }
-                                                    const frame = { jsonrpc: '2.0', id: 1, result: { protocolVersion: negotiated, capabilities: {}, instructions: 'Use initialize -> tools/list -> tools/call { name, arguments }. (forced-init-fallback)' } };
-                                                    server.__initResponseSent = true;
-                                                    if ((0, runtimeConfig_1.getRuntimeConfig)().trace.has('healthMixed')) {
-                                                        try {
-                                                            process.stderr.write(`[diag] ${Date.now()} sniff_init_forced_result_emit id=1 negotiated=${negotiated}\n`);
-                                                        }
-                                                        catch { /* ignore */ }
-                                                    }
-                                                    Promise.resolve(tr.send(frame)).then(() => {
-                                                        if (!server.__readyNotified) {
-                                                            emitReadyGlobal(server, 'forced-init-fallback');
-                                                        }
-                                                    }).catch(() => { });
-                                                }
-                                            }
-                                            catch { /* ignore */ }
-                                        }, 140).unref?.();
-                                    }
-                                    else if ((0, runtimeConfig_1.getRuntimeConfig)().trace.has('healthMixed')) {
-                                        try {
-                                            process.stderr.write(`[diag] ${Date.now()} sniff_init_forced_result_skip gating_off\n`);
-                                        }
-                                        catch { /* ignore */ }
-                                    }
-                                }
-                                if (isHandshakeFallbacksEnabled()) {
-                                    if (server.__initResponseSent && !server.__readyNotified) {
-                                        emitReadyGlobal(server, 'stdin-sniff-fallback');
-                                    }
-                                }
-                            }
-                            catch { /* ignore */ }
-                        }, 60).unref?.();
-                    }
-                }
-                // Fallback rq_* enqueue capture (only if diag flag set AND dispatcher override not active)
-                if ((0, runtimeConfig_1.getRuntimeConfig)().trace.has('healthMixed') && !server.__dispatcherOverrideActive) {
-                    try {
-                        let idx;
-                        while ((idx = __sniffBuf.indexOf('\n')) !== -1) {
-                            const line = __sniffBuf.slice(0, idx).trim();
-                            __sniffBuf = __sniffBuf.slice(idx + 1);
-                            if (!line)
-                                continue;
-                            let obj;
-                            try {
-                                obj = JSON.parse(line);
-                            }
-                            catch (e) {
-                                if (/jsonrpc|method/i.test(line)) {
-                                    const frag = line.replace(/\r/g, ' ').replace(/\n/g, ' ').slice(0, 200);
-                                    process.stderr.write(`[diag] ${Date.now()} malformed_json_line len=${line.length} frag="${frag}" err=${e.message || e}\n`);
-                                }
-                                continue;
-                            }
-                            if (obj && obj.jsonrpc === '2.0' && obj.method && Object.prototype.hasOwnProperty.call(obj, 'id')) {
-                                const metaName = obj.method === 'tools/call' ? obj?.params?.name : '';
-                                const category = (() => {
-                                    if (obj.method === 'initialize')
-                                        return 'init';
-                                    if (obj.method === 'health_check' || metaName === 'health_check')
-                                        return 'health';
-                                    if (obj.method === 'metrics_snapshot' || metaName === 'metrics_snapshot')
-                                        return 'metrics';
-                                    if (metaName === 'meta_tools')
-                                        return 'meta';
-                                    return 'other';
-                                })();
-                                if (category === 'health' || category === 'metrics' || category === 'meta' || category === 'init') {
-                                    try {
-                                        server.__diagQueueDepthSniff++;
-                                        server.__diagRQMap.set(obj.id, { start: Date.now(), cat: category, method: obj.method });
-                                        process.stderr.write(`[diag] ${Date.now()} rq_enqueue method=${obj.method} cat=${category} id=${obj.id} qdepth=${server.__diagQueueDepthSniff} src=sniff\n`);
-                                    }
-                                    catch { /* ignore */ }
-                                }
-                            }
-                        }
-                    }
-                    catch { /* ignore */ }
-                }
-                // Truncate buffer to avoid unbounded growth
-                if (__sniffBuf.length > 10_000) {
-                    __sniffBuf = __sniffBuf.slice(-2048);
-                }
-            }
-            catch { /* ignore */ }
-        });
-    }
-    catch { /* ignore */ }
-}
-/**
- * Safety fallback timers for missed ready emissions, unconditional DIAG fallback,
- * and _oninitialize patch for protocol negotiation.
- */
-function setupSafetyFallbacks(server) {
-    // Safety fallback: if server/ready not emitted within 100ms of start
-    if (isHandshakeFallbacksEnabled()) {
-        setTimeout(() => {
-            try {
-                // Only emit via safety-timeout if initialize response was already sent (ordering guarantee)
-                if (server.__sawInitializeRequest && server.__initResponseSent && !server.__readyNotified) {
-                    handshakeLog('safety_timeout_emit_attempt', { label: 'safety-timeout-100ms', sawInit: true, initRespSent: true });
-                    emitReadyGlobal(server, 'safety-timeout-100ms');
-                }
-            }
-            catch { /* ignore */ }
-        }, 100).unref?.();
-    }
-    // Unconditional DIAG fallback (gated): if no initialize request OR response observed very early
-    if (isHandshakeFallbacksEnabled()) {
-        setTimeout(() => {
-            try {
-                const INIT_FALLBACK_ENABLED = (0, runtimeConfig_1.getRuntimeConfig)().initFeatures.has('initFallback');
-                if ((0, runtimeConfig_1.getRuntimeConfig)().trace.has('healthMixed') && !server.__initResponseSent) {
-                    if (!INIT_FALLBACK_ENABLED) {
-                        try {
-                            process.stderr.write(`[diag] ${Date.now()} init_unconditional_fallback_skip gating_off\n`);
-                        }
-                        catch { /* ignore */ }
-                        return;
-                    }
-                    if (!server.__sawInitializeRequest) {
-                        if (process.stderr && !server.__diagForcedInitLogged) {
-                            server.__diagForcedInitLogged = true;
-                            try {
-                                process.stderr.write(`[diag] ${Date.now()} init_unconditional_fallback_emit id=1 reason=no_init_seen_150ms\n`);
-                            }
-                            catch { /* ignore */ }
-                        }
-                    }
-                    else {
-                        try {
-                            process.stderr.write(`[diag] ${Date.now()} init_unconditional_fallback_emit id=1 reason=init_seen_no_response_150ms\n`);
-                        }
-                        catch { /* ignore */ }
-                    }
-                    const negotiated = '2024-11-05';
-                    const frame = { jsonrpc: '2.0', id: 1, result: { protocolVersion: negotiated, capabilities: {}, instructions: 'Use initialize -> tools/list -> tools/call { name, arguments }. (unconditional-init-fallback)' } };
-                    const tr = server._transport || server.__transportRef;
-                    server.__initResponseSent = true;
-                    if (tr && typeof tr.send === 'function') {
-                        Promise.resolve(tr.send(frame)).then(() => { if (!server.__readyNotified)
-                            emitReadyGlobal(server, 'unconditional-init-fallback'); }).catch(() => { });
-                    }
-                    else {
-                        try {
-                            process.stdout.write(JSON.stringify(frame) + '\n');
-                        }
-                        catch { /* ignore */ }
-                        if (!server.__readyNotified)
-                            emitReadyGlobal(server, 'unconditional-init-fallback-direct');
-                    }
-                }
-            }
-            catch { /* ignore */ }
-        }, 150).unref?.();
-    }
-    // Patch initialize result for instructions (SDK internal property)
-    const originalInit = server._oninitialize;
-    if (originalInit && !server.__initPatched) {
-        server.__initPatched = true;
-        server._oninitialize = async function (request) {
-            try {
-                this.__sawInitializeRequest = true;
-                handshakeLog('oninitialize_enter', { sawInit: true, ready: !!this.__readyNotified, initRespSent: !!server.__initResponseSent });
-            }
-            catch { /* ignore */ }
-            const result = await originalInit.call(this, request);
-            try {
-                const negotiated = negotiateProtocolVersion(request?.params?.protocolVersion);
-                result.protocolVersion = negotiated;
-                if (result && typeof result === 'object' && !('instructions' in result)) {
-                    result.instructions = 'Use initialize -> tools/list -> tools/call { name, arguments }. Health: tools/call health_check. Metrics: tools/call metrics_snapshot. Ping: ping.';
-                }
-                // Do NOT emit server/ready here; ordering handled strictly by transport send hook.
-            }
-            catch { /* ignore */ }
-            return result;
-        };
-    }
-}
+var tracing_1 = require("./handshake/tracing");
+Object.defineProperty(exports, "isHandshakeTraceEnabled", { enumerable: true, get: function () { return tracing_1.isHandshakeTraceEnabled; } });
+Object.defineProperty(exports, "handshakeLog", { enumerable: true, get: function () { return tracing_1.handshakeLog; } });
+Object.defineProperty(exports, "record", { enumerable: true, get: function () { return tracing_1.record; } });
+Object.defineProperty(exports, "initFrameLog", { enumerable: true, get: function () { return tracing_1.initFrameLog; } });
+Object.defineProperty(exports, "isInitFrameDiagEnabled", { enumerable: true, get: function () { return tracing_1.isInitFrameDiagEnabled; } });
+Object.defineProperty(exports, "exposeGlobalEventsRef", { enumerable: true, get: function () { return tracing_1.exposeGlobalEventsRef; } });
+Object.defineProperty(exports, "getHandshakeEvents", { enumerable: true, get: function () { return tracing_1.getHandshakeEvents; } });
+var protocol_1 = require("./handshake/protocol");
+Object.defineProperty(exports, "SUPPORTED_PROTOCOL_VERSIONS", { enumerable: true, get: function () { return protocol_1.SUPPORTED_PROTOCOL_VERSIONS; } });
+Object.defineProperty(exports, "negotiateProtocolVersion", { enumerable: true, get: function () { return protocol_1.negotiateProtocolVersion; } });
+Object.defineProperty(exports, "isHandshakeFallbacksEnabled", { enumerable: true, get: function () { return protocol_1.isHandshakeFallbacksEnabled; } });
+var readyEmitter_1 = require("./handshake/readyEmitter");
+Object.defineProperty(exports, "emitReadyGlobal", { enumerable: true, get: function () { return readyEmitter_1.emitReadyGlobal; } });
+var stdinSniffer_1 = require("./handshake/stdinSniffer");
+Object.defineProperty(exports, "setupStdinSniffer", { enumerable: true, get: function () { return stdinSniffer_1.setupStdinSniffer; } });
+var safetyFallbacks_1 = require("./handshake/safetyFallbacks");
+Object.defineProperty(exports, "setupSafetyFallbacks", { enumerable: true, get: function () { return safetyFallbacks_1.setupSafetyFallbacks; } });

package/dist/server/index-server.d.ts

@@ -12,6 +12,7 @@
  * - Read-only interface for status, tools, and metrics
  * - Not for MCP client communication - admin use only
  */
+import '../services/mcpLogBridge';
 import '../services/logPrefix';
 import '../services/logger';
 import '../services/toolHandlers';
@@ -26,6 +27,28 @@ interface CliConfig {
     dashboardTlsCert?: string;
     dashboardTlsKey?: string;
     dashboardTlsCa?: string;
+    /** Trigger TLS cert generation on startup. */
+    initCert?: boolean;
+    /** Output directory for generated cert/key. Defaults to <home>/.index-server/certs. */
+    certDir?: string;
+    /** Override path for generated certificate file. */
+    certFile?: string;
+    /** Override path for generated private key file. */
+    keyFile?: string;
+    /** CommonName for the generated certificate. */
+    certCn?: string;
+    /** Comma-separated SAN entries (DNS:/IP: prefixed). */
+    certSan?: string;
+    /** Validity period in days (1..3650). */
+    certDays?: number;
+    /** RSA key size in bits (2048 or 4096). */
+    certKeyBits?: number;
+    /** Overwrite existing cert/key files. */
+    certForce?: boolean;
+    /** Print env-var lines after generation. true=auto, or 'posix'|'powershell'|'both'. */
+    certPrintEnv?: boolean | string;
+    /** Continue normal server startup after cert-init (composes with --init-cert). */
+    start?: boolean;
 }
 declare function parseArgs(argv: string[]): CliConfig;
 declare function findPackageVersion(): string;