@adhisang/minecraft-modding-mcp 6.2.0 → 7.0.0-rc.0

package/dist/stdio-supervisor.d.ts

@@ -1,8 +1,26 @@
 import { type ChildProcessWithoutNullStreams } from "node:child_process";
-import type { JSONRPCMessage, JSONRPCResponse } from "@modelcontextprotocol/sdk/types.js";
+import type { JSONRPCMessage, JSONRPCResponse } from "@modelcontextprotocol/server";
+import { type ConcreteFramingMode } from "./json-rpc-framing.js";
+import { type Era } from "./era-classifier.js";
 export declare function loadValidateProjectTimeoutMs(value?: string | undefined): number;
 export declare function computeWorkerStartupWatchdogMs(validateProjectTimeoutMs: number): number;
 export declare function computeRestartBackoffMs(retryIndex: number): number;
+/**
+ * How long an adopted worker must stay ready before a CLEAN voluntary
+ * stand-down counts as the end of a generation that actually served.
+ *
+ * A worker stands down on stdin EOF. On a host that hands every spawned child
+ * a stdin which closes immediately, that EOF arrives while the worker is still
+ * starting: it writes its ready marker, is adopted (which clears the restart
+ * backoff), and exits 0 in the same breath. Answering that with the 100 ms
+ * restart floor respawns a ~125 MB process ten times a second forever, so a
+ * stand-down inside this window escalates the backoff instead.
+ *
+ * A CRASH is deliberately not covered: it may be transient and keeps the
+ * prompt replacement the restart suites pin, whereas a clean stand-down means
+ * the host closed the pipe and will close the replacement's stdin the same way.
+ */
+export declare const MIN_HEALTHY_WORKER_READY_MS = 1000;
 export declare function terminatePosixProcessGroup(pid: number, kill?: (pid: number, signal: NodeJS.Signals) => void): boolean;
 export declare function buildWindowsTreeKillArgs(pid: number): string[];
 export declare function shouldRetainUnavailableNotification(method: string): boolean;
@@ -16,6 +34,16 @@ export declare class RestartBackoffState {
     private epoch;
     reserve(now: number): RestartReservation;
     reset(): void;
+    /**
+     * Raise the escalation level without reserving a restart.
+     *
+     * Adoption resets the index, so a generation that was adopted and then died
+     * without ever serving arrives here with the level already cleared. This
+     * restores the level that the repeated failure has earned, which is what
+     * stops a self-cancelling adopt/reset cycle from pinning every restart to
+     * the 100 ms floor.
+     */
+    escalateTo(level: number): void;
 }
 export declare function retryPosixTreeToken(pid: number, kill?: (pid: number, signal: NodeJS.Signals) => void): boolean;
 export declare function settleTreeCleanupWithin(operation: Promise<boolean>, timeoutMs: number, onTimeout?: () => void): Promise<boolean>;
@@ -25,6 +53,8 @@ export type SupervisorOptions = {
     clientWriter?: (message: JSONRPCMessage) => void;
     treeTokenRetrier?: (pid: number) => boolean | Promise<boolean>;
     treeCleanupTimeoutMs?: number;
+    cleanupTokenRetryBaseMs?: number;
+    cleanupTokenRetryCapMs?: number;
     eventWriter?: (level: "warn" | "error" | "info", event: string, details?: Record<string, unknown>) => void;
     monotonicNow?: () => number;
     timerScheduler?: (callback: () => void, delayMs: number) => NodeJS.Timeout;
@@ -58,10 +88,58 @@ export type PendingRequestSnapshot = {
     /** `true` when toolArgsRedacted contains sentinel placeholders (truncate/redact/overflow). */
     toolArgsRedactedModified?: boolean;
     startedAt: number;
+    /**
+     * Framing mode of the inbound frame that carried this request, captured at
+     * admission. Every terminal client-bound write for this request (forwarded
+     * worker response, timeout/queue-limit/restart synthesis) uses THIS mode —
+     * never the connection's latest inbound mode. Retained for the pending
+     * entry's whole lifetime (including client-cancelled tombstones) until the
+     * entry is discarded.
+     */
+    mode?: ConcreteFramingMode;
+    /**
+     * The supervisor's era at this request's admission ("unselected" occurs
+     * only for era-neutral server/discover admitted before any lock). Always
+     * set at runtime by createPendingRequest, the sole constructor; optional at
+     * the type level for tolerant synthetic-builder inputs and exported-type
+     * compatibility — no reply BUILDER may read it. Carve-out: the terminal
+     * synthetic-decoration step (writeSyntheticReply → decorateSyntheticReply)
+     * reads `era` — and ONLY `era` — to gate modern-era decoration; the three
+     * captured context fields below remain unread everywhere.
+     */
+    era?: Era;
+    /**
+     * Per-request modern protocol context, captured SHALLOW (values aliased
+     * as-is from params._meta — nothing may mutate an inbound params graph
+     * after admission, or captured snapshots would change retroactively) for
+     * shallow-valid modern-signal requests only; undefined for claim-less
+     * legacy traffic and for every initialize (initialize envelopes are
+     * ignored). Captured for downstream consumers; the supervisor itself must
+     * never read these three fields — no reply, synthesis, decoration, or
+     * forwarded frame may depend on them (the no-leak tests pin that).
+     * Synthetic decoration reads the snapshot's `era` alone, and the identity
+     * it stamps comes from src/server-identity.ts, never from request context.
+     */
+    protocolVersion?: string;
+    clientCapabilities?: Record<string, unknown>;
+    clientInfo?: unknown;
     lastStage?: string;
     lastStageStartedAt?: number;
     lastStageMeta?: unknown;
 };
+/**
+ * Frozen premigration reply for a tools/call whose name is not registered
+ * (typo OR flag-disabled tool — indistinguishable, exactly as the v1 SDK
+ * answered): a SUCCESSFUL CallToolResult with isError:true and one text
+ * content entry embedding the v1 error string. The v2 SDK throws a raw
+ * -32602 instead, so the supervisor synthesizes this envelope for
+ * LEGACY-era registry misses (see handleClientMessage) to keep the legacy
+ * wire byte-identical to the premigration baseline
+ * (tests/fixtures/premigration/error-code-inventory.json, disabled-tool
+ * row). The modern era keeps the raw -32602 (sanctioned: tool absence is a
+ * params problem on 2026-07-28, mirroring the SDK's own not-found mapping).
+ */
+export declare function buildUnknownToolNotFoundReply(id: RequestId, toolName: string): JSONRPCResponse;
 export declare function buildLegacyJsonRpcError(id: RequestId): JSONRPCResponse;
 export type RedactedToolArgs = {
     args: Record<string, unknown>;
@@ -106,6 +184,8 @@ export declare class StdioSupervisor {
     private readonly clientWriter;
     private readonly treeTokenRetrier;
     private readonly treeCleanupTimeoutMs;
+    private readonly cleanupTokenRetryBaseMs;
+    private readonly cleanupTokenRetryCapMs;
     private readonly eventWriter;
     private readonly monotonicNow;
     private readonly timerScheduler;
@@ -124,10 +204,59 @@ export declare class StdioSupervisor {
     private readonly unresolvedTreeTokens;
     private readonly restartBackoff;
     private readonly terminalChildren;
+    /**
+     * Monotonic worker-generation counter (incremented per successful spawn).
+     * Recorded into finality tombstones so retention can be bounded per
+     * generation; hand-injected children in tests that bypass spawnWorker run
+     * as generation 0.
+     */
+    private workerGeneration;
+    /**
+     * Response-finality tombstones: request key → {originating worker
+     * generation, originating framing mode}, recorded by writeSyntheticReply
+     * the moment a synthetic response is written. While a tombstone exists, any
+     * worker RESPONSE for that id is discarded (with a logged
+     * `supervisor.late_response_discarded` event) instead of being forwarded —
+     * the synthesized response was terminal, and exactly one response per id
+     * must reach the client. A tombstone is cleared when its id is re-forwarded
+     * to a worker (forwardRequest), because a client may legally retry with the
+     * same id; finality is per request INSTANCE, not per id forever.
+     *
+     * `mode` is retained deliberately even though discard writes nothing today:
+     * a tombstoned id keeps its originating framing mode until discard, so any
+     * future terminal write for that id — should the discard policy ever gain
+     * one — answers in the originating framing.
+     *
+     * Retention bound: entries with generation ≤ G are dropped when the
+     * generation-G child emits "close" (process ended AND its stdio streams
+     * closed — Node's guarantee for that event). This is safe: worker frames
+     * only enter handleWorkerMessage from the CURRENT child, the supervisor
+     * only forwards ids with live pending entries, and forwarding clears the
+     * id's tombstone — so once every generation that could have seen a
+     * tombstoned id is gone with streams closed, no current child can ever
+     * deliver a frame for it. Also cleared wholesale on shutdown.
+     */
+    private readonly syntheticTombstones;
     private child;
     private childReady;
+    /**
+     * Monotonic timestamp of the current generation's adoption, or undefined
+     * while no generation is adopted. Read once at exit to tell a generation
+     * that served from one that stood down the moment it came up.
+     */
+    private childReadyAt;
+    /**
+     * Consecutive adopted generations that stood down CLEANLY before they had
+     * been ready for MIN_HEALTHY_WORKER_READY_MS. Any other outcome — a crash, a
+     * signal, a generation that served — clears it.
+     */
+    private consecutiveImmediateStandDowns;
     private shuttingDown;
     private restartTimer;
+    private cleanupRetryTimer;
+    private cleanupRetryIndex;
+    private readonly cleanupRetryAttempts;
+    private readonly cleanupRetriesInFlight;
     private startupWatchdog;
     private validateBarrierKey;
     private runningValidateKey;
@@ -136,24 +265,173 @@ export declare class StdioSupervisor {
     private currentRetryReservation;
     private retryPaused;
     private workerStderrBuffer;
-    private clientMode;
+    /**
+     * Framing mode of the most recently detected inbound client frame. NOT used
+     * for request-correlated writes (those use the originating request's
+     * captured mode); this is only the documented fallback for client-bound
+     * writes that correlate to no request id (worker-originated notifications
+     * and server->client requests forwarded at handleWorkerMessage, and
+     * untracked-id responses with no finality tombstone — tombstoned ids are
+     * discarded, never forwarded).
+     */
+    private lastInboundClientMode;
+    /**
+     * Per-frame framing mode of every inbound client message, keyed by message
+     * object identity. Lets admission (createPendingRequest), queued-message
+     * flushes, and initialize replay recover the ORIGINATING frame's mode long
+     * after the frame was parsed.
+     */
+    private readonly inboundFrameModes;
     private initializeRequest;
     private initializedNotification;
+    /**
+     * Number of queued requests that arrived before an initial initialize while
+     * the worker was unavailable. Only era-neutral modern discovers can occupy
+     * this prefix; readiness forwards it before initialize, then keeps the queue
+     * suffix gated until the initialization response.
+     */
+    private initializePredecessorCount;
     private clientInitialized;
     private replayingInitialization;
     private initializeSentToWorker;
+    /**
+     * Process-lifetime era state. The supervisor is the SOLE era gatekeeper:
+     * classification happens at admission (handleClientMessage), in stdin
+     * order. The first valid NON-discover era signal locks the era (initialize
+     * → legacy; shallow-valid modern `_meta` request → modern); the lock is
+     * one-way and survives worker restarts.
+     */
+    private era;
+    /**
+     * Whether `start()` attached this instance to the real process stdio. Only
+     * then may a teardown touch process-wide state (the framing-fatal exit
+     * code); white-box suites construct supervisors without starting them and
+     * must never have their own runner's exit status rewritten.
+     */
+    private ownsProcessStdio;
+    /**
+     * Whether a fatal fault has already armed the explicit process exit. A
+     * second fault must not stack another watchdog or cut the first teardown
+     * short.
+     */
+    private fatalExitScheduled;
+    /** Memoized teardown; see shutdown(). */
+    private shutdownRun;
     constructor(options: SupervisorOptions);
     start(): Promise<void>;
     private readonly handleClientData;
+    /** The captured per-frame mode of an inbound client message, if known. */
+    private modeForMessage;
     private readonly handleClientError;
     private readonly handleClientClosed;
     private readonly handleTerminateSignal;
+    /**
+     * Terminal fault in the supervisor process. Reported through the injected
+     * event writer, then routed into the ordinary shutdown so the detached
+     * worker group is reaped rather than orphaned by a crash.
+     */
+    private readonly handleFatalError;
     private handleClientMessage;
+    /**
+     * Era-aware notification dispatch. notifications/cancelled stays
+     * supervisor-side in ALL eras/states; notifications/initialized is captured
+     * and forwarded only within a legacy flow; every other notification is
+     * gated by the era rules before reaching the original forwarding path.
+     * Dropped variants emit NO response and never affect subsequent traffic.
+     */
+    private handleClientNotification;
+    /**
+     * Era rules for non-initialize requests, applied at admission in stdin
+     * order. Returns undefined when the request was terminally rejected here (a
+     * supervisor-produced response was written; nothing may be forwarded or
+     * queued). On admission it returns the admission-time era signal, which the
+     * caller hands to createPendingRequest so snapshot capture uses the same
+     * result as the gating decision (extractModernRequestContext re-checks the
+     * same immutable params graph defensively — a pure re-evaluation, not a
+     * second authority); the caller then proceeds through the original era-less
+     * admission path unchanged.
+     */
+    private admitEraRequest;
+    /**
+     * Deep validation of a shallow-valid modern claim's protocolVersion VALUE,
+     * applied to EVERY modern request at admission. Returns whether the request
+     * was terminally answered here.
+     *
+     * The version check used to be delegated entirely to the worker, and the SDK
+     * only performs it while the connection is still OPENING: once an instance
+     * is pinned, `processMessage` delivers straight to it without re-reading the
+     * envelope. So the contract ("any unsupported version string answers -32022
+     * with data.supported/data.requested") held for exactly one request per
+     * process — and whether it held at all depended on which method the client
+     * happened to send first, since the era-neutral `server/discover` does not
+     * pin. Every later request with `"1999-12-31"` was SERVED, tool handlers
+     * included.
+     *
+     * Ordering is deliberate and matches the SDK's own listen path: the envelope
+     * shape is checked first (era gating above), the era lock is committed
+     * BEFORE this check — an unsupported version still locks modern, exactly as
+     * documented — and only then is the value judged, ahead of any method-level
+     * rejection. The reply is built from the SDK's own
+     * UnsupportedProtocolVersionError, so it stays byte-identical to the answer
+     * the worker gives on the still-opening path.
+     */
+    private rejectUnsupportedProtocolVersion;
+    /**
+     * One-way modern lock. Purges the cached legacy lifecycle state so no
+     * initialize/notifications/initialized can ever reach a worker in a
+     * modern-locked process — across ALL later worker generations.
+     */
+    private lockModernEra;
+    /**
+     * `eraSignal` is the ADMISSION-time classification handed back by
+     * admitEraRequest — the initialize/replay/flush call sites omit it (an
+     * initialize snapshot is always era "legacy" with no modern context, even
+     * when the initialize carries a _meta envelope). Context is captured only
+     * for shallow-valid modern signals; this.era already reflects any lock
+     * admitEraRequest applied, so it IS the era at admission on every path.
+     */
     private createPendingRequest;
     private canDispatchImmediately;
     private forwardRequest;
     private writeToWorker;
     private handleCancellation;
+    /**
+     * Terminal release of a FORWARDED request the client cancelled.
+     *
+     * MCP cancellation semantics forbid a response for a cancelled id, so the
+     * supervisor stops waiting on the worker the moment the cancellation is
+     * admitted — and a worker is under no obligation to ever answer a cancelled
+     * request. Keeping the entry in `pendingRequests` as a suppression marker
+     * (the pre-repair behavior) therefore stranded EVERY dispatch barrier the
+     * map gates — canDispatchImmediately's empty-map requirement, drainQueue's
+     * validate release — for the life of the process whenever the worker never
+     * answered, and let a client grow the map without bound by pairing fresh
+     * ids with cancellations.
+     *
+     * Suppression is instead recorded as an ordinary response-finality
+     * tombstone, which already carries exactly the needed semantics: a late
+     * worker answer for the id is discarded with a logged event, and
+     * re-forwarding the id (a legal retry) clears it. The result is one
+     * mechanism for "this request instance is over" rather than two.
+     *
+     * Carve-out: an in-flight `initialize` is NOT released. Its pending entry is
+     * owned by the legacy handshake lifecycle (replay correlation,
+     * isInitializationResponse, the preserved-key rule in
+     * failPendingRequestsOnWorkerExit), which has its own recovery paths
+     * (startup watchdog, worker exit, clearInitialInitializationState) and never
+     * consulted the cancellation marker anyway — so handshake behavior is
+     * unchanged, byte for byte.
+     *
+     * Returns whether an entry was actually released.
+     */
+    private releaseCancelledRequest;
+    /**
+     * Era gating for a cancellation notification. Extracted from
+     * handleCancellation so supervisor-side bookkeeping (releasing the cancelled
+     * request) stays independent of whether the frame may reach the worker — a
+     * DROPPED cancellation still cancels, exactly as documented.
+     */
+    private shouldForwardCancellation;
     private handleValidateProjectDeadline;
     private drainQueue;
     private spawnWorker;
@@ -162,15 +440,81 @@ export declare class StdioSupervisor {
     private handleWorkerStderr;
     private handleWorkerProcessError;
     private handleWorkerExit;
+    /**
+     * Decide whether the generation that just ended counts as a start that
+     * succeeded.
+     *
+     * A worker stands down on stdin EOF, and it replays an EOF that arrived
+     * while it was still starting. On a host that closes a spawned child's stdin
+     * immediately, every generation therefore signals ready, is adopted — which
+     * clears the restart backoff — and exits 0 in the same breath. Left at the
+     * 100 ms floor that is an unbounded hot respawn loop, so a clean stand-down
+     * inside the healthy window re-escalates the backoff the adoption cleared.
+     *
+     * Only a CLEAN exit qualifies: a non-zero code or a signal is a crash, which
+     * may be transient and keeps its prompt replacement.
+     */
+    private accountForReadyGenerationExit;
     private handleWorkerMessage;
     private applyStageUpdate;
     private handleWorkerReady;
     private isInitializationResponse;
     private flushQueue;
     private failPendingRequestsOnWorkerExit;
+    /**
+     * The single terminal-synthesis writer: EVERY supervisor-synthesized
+     * response (queue-limit, validate-project timeout, worker-restart in all
+     * variants incl. the structured-restart toggle, startup-failure
+     * terminalization, initialize-failure -32603) routes through here.
+     * Responsibilities, in order:
+     *  1. settle the pending entry,
+     *  2. record the finality tombstone (id + originating worker generation +
+     *     framing mode) so a late worker response for the id is discarded —
+     *     ONLY when the id was actually FORWARDED to a worker (i.e. the entry
+     *     in pendingRequests at the id IS the snapshot instance being
+     *     answered; an id-colliding DIFFERENT live entry is left untouched).
+     *     Never-forwarded
+     *     rejections (queue-limit at admission and at the forward fallback,
+     *     queue-phase validate timeout, cap-blocked replies, startup-failure
+     *     terminalization of queued work, the retained-initialize error) record
+     *     NO tombstone: no worker ever saw those ids, so no worker can answer
+     *     them, and tombstoning them would let a client grow the map without
+     *     bound inside a healthy generation,
+     *  3. apply modern-era decoration — `snapshot.era` is the ONLY
+     *     captured-context field read; raw error envelopes and non-modern eras
+     *     pass through byte-identical — and
+     *  4. write in the ORIGINATING request's framing.
+     * Admission-time era rejections (era_conflict/missing_meta/-32601) do NOT
+     * route through here: they reject before any forwarding could happen, so
+     * no worker can ever answer those ids. The initialize-error synthesis also
+     * records no tombstone: isInitializationResponse settles its pending entry
+     * before synthesizing, the answering generation is terminated, and the
+     * replay cache is cleared — no late-response channel remains.
+     */
+    private writeSyntheticReply;
+    /**
+     * Records a response-finality tombstone for a request instance the
+     * supervisor has terminally settled (synthesized reply or client
+     * cancellation). Insertion-order eviction at MAX_SYNTHETIC_TOMBSTONES keeps
+     * the map bounded even inside one healthy worker generation, where the
+     * per-generation purge cannot fire.
+     */
+    private recordFinalityTombstone;
+    /**
+     * Retention bound for finality tombstones: generation `generation` is gone
+     * with streams closed, so every tombstone recorded at or before it is
+     * unreachable (see syntheticTombstones doc) and may be dropped.
+     */
+    private purgeTombstonesThroughGeneration;
+    /**
+     * Writes one client-bound message. `mode` is the ORIGINATING REQUEST's
+     * captured framing; callers omit it only for writes that correlate to no
+     * request id, which fall back to the last-detected inbound mode.
+     */
     private writeToClient;
     private clearInitialInitializationState;
     private liveCapOccupancy;
+    get unresolvedTreeTokenCount(): number;
     private clearStartupWatchdog;
     private adoptActiveChild;
     private invalidateCurrentChild;
@@ -178,13 +522,24 @@ export declare class StdioSupervisor {
     private recoverTimedOutWorker;
     private beginTreeTermination;
     private finishTreeTermination;
+    private scheduleCleanupTokenRetry;
+    private runCleanupTokenRetries;
+    private stopCleanupTokenRetryIfIdle;
     private retryUnresolvedTreeToken;
+    private performUnresolvedTreeTokenRetry;
     private handleStartupFailure;
     private failQueuedRequestsOnStartupFailure;
     private scheduleRestart;
     private armRestartReservation;
     private resumePausedRestart;
+    /**
+     * Idempotent teardown. Every caller receives the SAME promise, so a caller
+     * that needs to know when cleanup is really finished — the fatal handler,
+     * which then ends the process — cannot be handed an already-resolved promise
+     * while another teardown is still collecting the worker's process group.
+     */
     private shutdown;
+    private runShutdown;
 }
 export declare const STDIO_WORKER_MODE_ENV = "MCP_STDIO_WORKER_MODE";
 export {};