@adhisang/minecraft-modding-mcp 6.3.0 → 7.0.0-rc.1

package/dist/entry-tools/verify-mixin-target-service.d.ts

@@ -137,29 +137,13 @@ export declare class VerifyMixinTargetService {
      */
     private applyAutoRemap;
 }
-export declare const verifyMixinTargetMemberSchemaExport: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+export declare const verifyMixinTargetMemberSchemaExport: z.ZodDiscriminatedUnion<[z.ZodObject<{
     kind: z.ZodLiteral<"method">;
     name: z.ZodString;
     descriptor: z.ZodOptional<z.ZodString>;
-}, "strip", z.ZodTypeAny, {
-    name: string;
-    kind: "method";
-    descriptor?: string | undefined;
-}, {
-    name: string;
-    kind: "method";
-    descriptor?: string | undefined;
-}>, z.ZodObject<{
+}, z.core.$strip>, z.ZodObject<{
     kind: z.ZodLiteral<"field">;
     name: z.ZodString;
     descriptor: z.ZodOptional<z.ZodString>;
-}, "strip", z.ZodTypeAny, {
-    name: string;
-    kind: "field";
-    descriptor?: string | undefined;
-}, {
-    name: string;
-    kind: "field";
-    descriptor?: string | undefined;
-}>]>;
+}, z.core.$strip>], "kind">;
 export {};

package/dist/entry-tools/verify-mixin-target-service.js

@@ -221,7 +221,25 @@ export class VerifyMixinTargetService {
             throw createError({
                 code: ERROR_CODES.CONTEXT_UNRESOLVED,
                 message: `verify-mixin-target requires a binary jar but artifact "${resolved.artifactId}" has none.`,
-                details: { artifactId: resolved.artifactId, owner }
+                details: {
+                    artifactId: resolved.artifactId,
+                    owner,
+                    // `ERR_CONTEXT_UNRESOLVED` classifies as `code_issue` by code, which
+                    // is right for the sibling case (a caller naming a version no
+                    // artifact carries) and for a `target: { kind: "jar", ... }` request:
+                    // there the caller named the exact jar, and having none for its own
+                    // sources is exactly the input the caller can change. It is wrong
+                    // only when the artifact was picked by the TOOL from a non-jar target
+                    // (version/coordinate/workspace/dependency), where whether it ships a
+                    // binary jar is not something the request can express. Published as
+                    // caller-fixable in that case it invites an endless retry of an input
+                    // that was never at fault, so this site overrides the default only
+                    // then.
+                    issueOrigin: input.target?.kind === "jar" ? undefined : "tool_issue",
+                    nextAction: `verify-mixin-target reads the target's members from bytecode, so it needs an artifact with a binary jar. `
+                        + `Re-target with target: { kind: "jar", value: "<path to the jar>" }, or with a version whose artifact carries one `
+                        + `(resolve-artifact reports binaryJarPath for the target you pass).`
+                }
             });
         }
         let signature;

package/dist/era-classifier.d.ts

@@ -0,0 +1,161 @@
+import { type JSONRPCMessage, type JSONRPCResponse } from "@modelcontextprotocol/server";
+/**
+ * Era classification for the dual-era stdio supervisor.
+ *
+ * The process serves TWO protocol eras: the legacy
+ * initialize/notifications/initialized handshake (five protocol versions) and
+ * the modern stateless era (protocol revision 2026-07-28) whose requests carry
+ * a per-request `_meta` envelope. The SUPERVISOR is the sole era gatekeeper at
+ * admission — the worker's own era classification is unreliable for gating (a
+ * claim-less frame silently pins the worker connection legacy) — so the
+ * shallow envelope check, the era types, and the machine-readable rejection
+ * builders live here.
+ */
+/** Reserved `_meta` key carrying the per-request protocol version claim. */
+export declare const PROTOCOL_VERSION_META_KEY = "io.modelcontextprotocol/protocolVersion";
+/** Reserved `_meta` key carrying the per-request client capabilities. */
+export declare const CLIENT_CAPABILITIES_META_KEY = "io.modelcontextprotocol/clientCapabilities";
+/**
+ * Reserved `_meta` key carrying the OPTIONAL per-request client
+ * implementation info. NOT part of the era-signal check; only captured (as-is)
+ * into request snapshots when present on a shallow-valid modern signal.
+ */
+export declare const CLIENT_INFO_META_KEY = "io.modelcontextprotocol/clientInfo";
+/** The five legacy handshake protocol versions the worker supports. */
+export declare const LEGACY_PROTOCOL_VERSIONS: readonly ["2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05", "2024-10-07"];
+/** The modern per-request `_meta` protocol revision. */
+export declare const MODERN_PROTOCOL_VERSION = "2026-07-28";
+/** All protocol versions this process serves, across both eras. */
+export declare const ERA_SUPPORTED_PROTOCOL_VERSIONS: readonly string[];
+/** Process-lifetime era state. The lock is one-way and survives worker restarts. */
+export type Era = "unselected" | "legacy" | "modern";
+export type EraSignalClassification = "modern-signal" | "claim-less" | "claim-shaped-invalid";
+export type EraSignal = {
+    classification: EraSignalClassification;
+    /** Absent required io.modelcontextprotocol/* keys. */
+    missing: string[];
+    /** Present-but-wrong-shallow-type required io.modelcontextprotocol/* keys. */
+    invalid: string[];
+};
+type RequestId = string | number;
+/**
+ * Shallow era-signal classification of a request's (or notification's)
+ * params. Mirrors the SDK RequestMetaEnvelopeSchema's REQUIREDNESS without
+ * deep value validation: `params._meta` must be an object carrying a string
+ * `io.modelcontextprotocol/protocolVersion` and a non-null non-array object
+ * `io.modelcontextprotocol/clientCapabilities`. `io.modelcontextprotocol/clientInfo`
+ * is optional and NOT part of the check.
+ *
+ * A shallow-VALID envelope is the modern era signal even when the version
+ * VALUE is unsupported (e.g. "2027-01-01") — deep value validation belongs to
+ * the worker, which answers -32022 with {supported, requested}.
+ *
+ * claim-less: params/_meta missing, `_meta` not a plain object, or `_meta`
+ * carrying NEITHER required key. claim-shaped-invalid: at least one required
+ * key present but the shallow check fails (`missing` = absent required keys,
+ * `invalid` = present-but-wrong-shallow-type keys).
+ */
+export declare function classifyEraSignal(params: unknown): EraSignal;
+/**
+ * Per-request modern protocol context, captured SHALLOW from `params._meta`
+ * at supervisor admission. Values are copied as-is (no deep validation — the
+ * worker validates values, e.g. answering -32022 for an unsupported
+ * protocolVersion). `clientInfo` is present only when the optional
+ * io.modelcontextprotocol/clientInfo key is present, and is passed through
+ * verbatim even when it is not Implementation-shaped.
+ */
+export type ModernRequestContext = {
+    protocolVersion: string;
+    clientCapabilities: Record<string, unknown>;
+    clientInfo?: unknown;
+};
+/**
+ * Shallow extraction of the {@link ModernRequestContext} from a request's
+ * params. Returns undefined unless the params classify as a shallow-valid
+ * modern signal — the guard is the same pure {@link classifyEraSignal} check
+ * the admission gate runs, so it cannot diverge from an admission-time
+ * classification of the same params object. The returned values ALIAS the
+ * inbound params._meta objects (no clone): callers must never mutate an
+ * inbound params graph after admission, or captured snapshots would change
+ * retroactively.
+ */
+export declare function extractModernRequestContext(params: unknown): ModernRequestContext | undefined;
+/**
+ * Strips the modern era-claim keys from a request's `params._meta` IN PLACE,
+ * deleting `_meta` entirely when nothing else remains. Used by the supervisor
+ * for accepted legacy `initialize` frames: the admission rule classifies every
+ * initialize as the legacy era signal regardless of its envelope, but the
+ * SDK's opening classifier treats an initialize carrying a valid modern claim
+ * as MODERN — the strip keeps the worker's classification aligned with the
+ * admission decision. Mutation is in place deliberately: the framing-mode
+ * registry is keyed by the exact inbound frame object, and no
+ * {@link ModernRequestContext} ever aliases an initialize's `_meta` (an
+ * initialize never classifies as a modern signal at admission).
+ */
+export declare function stripModernEraClaimInPlace(params: unknown): void;
+export declare const ERA_CONFLICT_MODERN_MESSAGE: string;
+export declare const ERA_CONFLICT_LEGACY_MESSAGE: string;
+export declare const MISSING_META_UNSELECTED_MESSAGE: string;
+export declare const MISSING_META_MODERN_MESSAGE: string;
+/**
+ * One-way era conflict rejection. selectedEra "modern" rejects a legacy
+ * initialize with -32601; selectedEra "legacy" rejects a modern-signal
+ * request with -32600. Machine-readable discrimination is by code +
+ * data.kind/selectedEra/requestedEra/supported only.
+ */
+export declare function buildEraConflictRejection(id: RequestId, selectedEra: "legacy" | "modern"): JSONRPCResponse;
+/**
+ * Rejection for a request carrying no valid era signal: in the unselected
+ * state (era stays UNSELECTED; the message names both recovery paths) or in
+ * the modern era (the message names the required envelope). `invalid` is
+ * included only when non-empty; `missing` is always present.
+ */
+export declare function buildMissingMetaRejection(id: RequestId, signal: EraSignal, era: "unselected" | "modern"): JSONRPCResponse;
+/**
+ * Whether a frame is a COMPLETE, schema-valid MCP `initialize` request.
+ *
+ * Admission classifies any frame whose method is `initialize` as the legacy
+ * era signal, and that lock is one-way for the process lifetime. Generic
+ * JSON-RPC parsing is far too weak a basis for a permanent decision: a frame
+ * as empty as `{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}`
+ * passes it while carrying none of the fields the handshake needs. Burning the
+ * lock on such a frame left the process legacy-locked with NO valid era
+ * opening ever completed, and the modern era permanently unreachable.
+ *
+ * The check is the SDK's own public `isInitializeRequest` — the exact
+ * `InitializeRequestSchema` the worker would apply — so admission and the
+ * worker can never disagree about what an initialize is. Extra params
+ * (including a `_meta` envelope) are tolerated; `protocolVersion` (string),
+ * `capabilities` (object) and `clientInfo` ({name, version}) are required.
+ * Version VALUES are not judged here: an unknown legacy version negotiates
+ * down at the worker, exactly as documented.
+ */
+export declare function isCompleteInitializeRequest(message: JSONRPCMessage): boolean;
+export declare const INVALID_INITIALIZE_MESSAGE: string;
+/**
+ * Rejection for a frame that claims to be an `initialize` but fails the MCP
+ * initialize schema. Answered at admission, BEFORE the legacy lock is
+ * committed, so the era stays UNSELECTED and every recovery path — including
+ * the modern era — remains open.
+ */
+export declare function buildInvalidInitializeRejection(id: RequestId): JSONRPCResponse;
+/**
+ * Unsupported modern `protocolVersion` VALUE rejection (`-32022` with
+ * `data.supported` / `data.requested`).
+ *
+ * Built from the SDK's own {@link UnsupportedProtocolVersionError} so the
+ * code, message and data stay byte-identical to the worker-produced answer
+ * clients already receive on the pre-pin path — the supervisor merely makes
+ * the check apply to EVERY modern request instead of only the one that
+ * happened to open the connection.
+ */
+export declare function buildUnsupportedProtocolVersionRejection(id: RequestId, requested: string): JSONRPCResponse;
+/**
+ * Plain -32601 admission rejection for subscriptions/listen in the modern era
+ * (no data.kind — deliberately indistinguishable from an ordinary unknown
+ * method). Defense in depth: if admission were ever bypassed, the worker
+ * (maxSubscriptions: 0) would answer -32603 "Subscription limit reached";
+ * intercepting at admission keeps that internal detail off the wire.
+ */
+export declare function buildMethodNotFoundRejection(id: RequestId): JSONRPCResponse;
+export {};

package/dist/era-classifier.js

@@ -0,0 +1,292 @@
+import { UnsupportedProtocolVersionError, isInitializeRequest } from "@modelcontextprotocol/server";
+/**
+ * Era classification for the dual-era stdio supervisor.
+ *
+ * The process serves TWO protocol eras: the legacy
+ * initialize/notifications/initialized handshake (five protocol versions) and
+ * the modern stateless era (protocol revision 2026-07-28) whose requests carry
+ * a per-request `_meta` envelope. The SUPERVISOR is the sole era gatekeeper at
+ * admission — the worker's own era classification is unreliable for gating (a
+ * claim-less frame silently pins the worker connection legacy) — so the
+ * shallow envelope check, the era types, and the machine-readable rejection
+ * builders live here.
+ */
+/** Reserved `_meta` key carrying the per-request protocol version claim. */
+export const PROTOCOL_VERSION_META_KEY = "io.modelcontextprotocol/protocolVersion";
+/** Reserved `_meta` key carrying the per-request client capabilities. */
+export const CLIENT_CAPABILITIES_META_KEY = "io.modelcontextprotocol/clientCapabilities";
+/**
+ * Reserved `_meta` key carrying the OPTIONAL per-request client
+ * implementation info. NOT part of the era-signal check; only captured (as-is)
+ * into request snapshots when present on a shallow-valid modern signal.
+ */
+export const CLIENT_INFO_META_KEY = "io.modelcontextprotocol/clientInfo";
+/** The five legacy handshake protocol versions the worker supports. */
+export const LEGACY_PROTOCOL_VERSIONS = [
+    "2025-11-25",
+    "2025-06-18",
+    "2025-03-26",
+    "2024-11-05",
+    "2024-10-07"
+];
+/** The modern per-request `_meta` protocol revision. */
+export const MODERN_PROTOCOL_VERSION = "2026-07-28";
+/** All protocol versions this process serves, across both eras. */
+export const ERA_SUPPORTED_PROTOCOL_VERSIONS = [
+    ...LEGACY_PROTOCOL_VERSIONS,
+    MODERN_PROTOCOL_VERSION
+];
+const REQUIRED_META_KEYS = [PROTOCOL_VERSION_META_KEY, CLIENT_CAPABILITIES_META_KEY];
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Shallow era-signal classification of a request's (or notification's)
+ * params. Mirrors the SDK RequestMetaEnvelopeSchema's REQUIREDNESS without
+ * deep value validation: `params._meta` must be an object carrying a string
+ * `io.modelcontextprotocol/protocolVersion` and a non-null non-array object
+ * `io.modelcontextprotocol/clientCapabilities`. `io.modelcontextprotocol/clientInfo`
+ * is optional and NOT part of the check.
+ *
+ * A shallow-VALID envelope is the modern era signal even when the version
+ * VALUE is unsupported (e.g. "2027-01-01") — deep value validation belongs to
+ * the worker, which answers -32022 with {supported, requested}.
+ *
+ * claim-less: params/_meta missing, `_meta` not a plain object, or `_meta`
+ * carrying NEITHER required key. claim-shaped-invalid: at least one required
+ * key present but the shallow check fails (`missing` = absent required keys,
+ * `invalid` = present-but-wrong-shallow-type keys).
+ */
+export function classifyEraSignal(params) {
+    const meta = isPlainObject(params) ? params._meta : undefined;
+    if (!isPlainObject(meta)) {
+        return { classification: "claim-less", missing: [...REQUIRED_META_KEYS], invalid: [] };
+    }
+    const versionPresent = PROTOCOL_VERSION_META_KEY in meta;
+    const capabilitiesPresent = CLIENT_CAPABILITIES_META_KEY in meta;
+    if (!versionPresent && !capabilitiesPresent) {
+        return { classification: "claim-less", missing: [...REQUIRED_META_KEYS], invalid: [] };
+    }
+    const missing = [];
+    const invalid = [];
+    if (!versionPresent) {
+        missing.push(PROTOCOL_VERSION_META_KEY);
+    }
+    else if (typeof meta[PROTOCOL_VERSION_META_KEY] !== "string") {
+        invalid.push(PROTOCOL_VERSION_META_KEY);
+    }
+    if (!capabilitiesPresent) {
+        missing.push(CLIENT_CAPABILITIES_META_KEY);
+    }
+    else if (!isPlainObject(meta[CLIENT_CAPABILITIES_META_KEY])) {
+        invalid.push(CLIENT_CAPABILITIES_META_KEY);
+    }
+    if (missing.length === 0 && invalid.length === 0) {
+        return { classification: "modern-signal", missing, invalid };
+    }
+    return { classification: "claim-shaped-invalid", missing, invalid };
+}
+/**
+ * Shallow extraction of the {@link ModernRequestContext} from a request's
+ * params. Returns undefined unless the params classify as a shallow-valid
+ * modern signal — the guard is the same pure {@link classifyEraSignal} check
+ * the admission gate runs, so it cannot diverge from an admission-time
+ * classification of the same params object. The returned values ALIAS the
+ * inbound params._meta objects (no clone): callers must never mutate an
+ * inbound params graph after admission, or captured snapshots would change
+ * retroactively.
+ */
+export function extractModernRequestContext(params) {
+    if (classifyEraSignal(params).classification !== "modern-signal") {
+        return undefined;
+    }
+    const meta = params._meta;
+    const context = {
+        protocolVersion: meta[PROTOCOL_VERSION_META_KEY],
+        clientCapabilities: meta[CLIENT_CAPABILITIES_META_KEY]
+    };
+    if (CLIENT_INFO_META_KEY in meta) {
+        context.clientInfo = meta[CLIENT_INFO_META_KEY];
+    }
+    return context;
+}
+/**
+ * Strips the modern era-claim keys from a request's `params._meta` IN PLACE,
+ * deleting `_meta` entirely when nothing else remains. Used by the supervisor
+ * for accepted legacy `initialize` frames: the admission rule classifies every
+ * initialize as the legacy era signal regardless of its envelope, but the
+ * SDK's opening classifier treats an initialize carrying a valid modern claim
+ * as MODERN — the strip keeps the worker's classification aligned with the
+ * admission decision. Mutation is in place deliberately: the framing-mode
+ * registry is keyed by the exact inbound frame object, and no
+ * {@link ModernRequestContext} ever aliases an initialize's `_meta` (an
+ * initialize never classifies as a modern signal at admission).
+ */
+export function stripModernEraClaimInPlace(params) {
+    if (!isPlainObject(params))
+        return;
+    const meta = params._meta;
+    if (!isPlainObject(meta))
+        return;
+    delete meta[PROTOCOL_VERSION_META_KEY];
+    delete meta[CLIENT_CAPABILITIES_META_KEY];
+    delete meta[CLIENT_INFO_META_KEY];
+    if (Object.keys(meta).length === 0) {
+        delete params._meta;
+    }
+}
+const SUPPORTED_VERSIONS_SENTENCE = `Supported protocol versions: ${LEGACY_PROTOCOL_VERSIONS.join(", ")} (legacy initialize handshake) ` +
+    `and ${MODERN_PROTOCOL_VERSION} (modern per-request _meta).`;
+/** Launcher-neutral fresh-process recovery preamble shared by both era-conflict messages. */
+const FRESH_PROCESS_RECOVERY = "start a fresh process: close this transport, terminate and respawn the configured server command " +
+    "as a fresh stdio process, discard or re-issue any pending request ids, then";
+export const ERA_CONFLICT_MODERN_MESSAGE = `initialize rejected: this server process is era-locked to protocol revision ${MODERN_PROTOCOL_VERSION} ` +
+    "(modern per-request _meta era), so the legacy initialize handshake can no longer be accepted. " +
+    `${SUPPORTED_VERSIONS_SENTENCE} ` +
+    `To use the legacy handshake, ${FRESH_PROCESS_RECOVERY} send initialize followed by notifications/initialized.`;
+// Claim-agnostic wording: ANY string protocolVersion value classifies as the
+// modern signal, so the message names the envelope, not a specific revision.
+export const ERA_CONFLICT_LEGACY_MESSAGE = "Modern per-request _meta request rejected: this server process is era-locked to the legacy initialize handshake, " +
+    "so requests carrying the modern per-request _meta envelope can no longer be accepted. " +
+    `${SUPPORTED_VERSIONS_SENTENCE} ` +
+    `To use the modern era, ${FRESH_PROCESS_RECOVERY} send a request carrying the required io.modelcontextprotocol/* _meta envelope.`;
+const REQUIRED_KEYS_SENTENCE = `the required io.modelcontextprotocol/* keys (${PROTOCOL_VERSION_META_KEY} and ${CLIENT_CAPABILITIES_META_KEY}) in params._meta`;
+export const MISSING_META_UNSELECTED_MESSAGE = "Request rejected: no protocol era is selected yet and this request carries no valid era signal. " +
+    "Either send initialize followed by notifications/initialized to select the legacy handshake, " +
+    `or include ${REQUIRED_KEYS_SENTENCE} to select protocol revision ${MODERN_PROTOCOL_VERSION}.`;
+export const MISSING_META_MODERN_MESSAGE = `Request rejected: this server process is era-locked to protocol revision ${MODERN_PROTOCOL_VERSION} ` +
+    "and the request lacks the required per-request _meta envelope. " +
+    `Include ${REQUIRED_KEYS_SENTENCE}.`;
+/**
+ * One-way era conflict rejection. selectedEra "modern" rejects a legacy
+ * initialize with -32601; selectedEra "legacy" rejects a modern-signal
+ * request with -32600. Machine-readable discrimination is by code +
+ * data.kind/selectedEra/requestedEra/supported only.
+ */
+export function buildEraConflictRejection(id, selectedEra) {
+    const modernSelected = selectedEra === "modern";
+    return {
+        jsonrpc: "2.0",
+        id,
+        error: {
+            code: modernSelected ? -32601 : -32600,
+            message: modernSelected ? ERA_CONFLICT_MODERN_MESSAGE : ERA_CONFLICT_LEGACY_MESSAGE,
+            data: {
+                kind: "era_conflict",
+                selectedEra,
+                requestedEra: modernSelected ? "legacy" : "modern",
+                supported: [...ERA_SUPPORTED_PROTOCOL_VERSIONS]
+            }
+        }
+    };
+}
+/**
+ * Rejection for a request carrying no valid era signal: in the unselected
+ * state (era stays UNSELECTED; the message names both recovery paths) or in
+ * the modern era (the message names the required envelope). `invalid` is
+ * included only when non-empty; `missing` is always present.
+ */
+export function buildMissingMetaRejection(id, signal, era) {
+    const data = { kind: "missing_meta", missing: [...signal.missing] };
+    if (signal.invalid.length > 0) {
+        data.invalid = [...signal.invalid];
+    }
+    return {
+        jsonrpc: "2.0",
+        id,
+        error: {
+            code: -32602,
+            message: era === "modern" ? MISSING_META_MODERN_MESSAGE : MISSING_META_UNSELECTED_MESSAGE,
+            data
+        }
+    };
+}
+/**
+ * Whether a frame is a COMPLETE, schema-valid MCP `initialize` request.
+ *
+ * Admission classifies any frame whose method is `initialize` as the legacy
+ * era signal, and that lock is one-way for the process lifetime. Generic
+ * JSON-RPC parsing is far too weak a basis for a permanent decision: a frame
+ * as empty as `{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}`
+ * passes it while carrying none of the fields the handshake needs. Burning the
+ * lock on such a frame left the process legacy-locked with NO valid era
+ * opening ever completed, and the modern era permanently unreachable.
+ *
+ * The check is the SDK's own public `isInitializeRequest` — the exact
+ * `InitializeRequestSchema` the worker would apply — so admission and the
+ * worker can never disagree about what an initialize is. Extra params
+ * (including a `_meta` envelope) are tolerated; `protocolVersion` (string),
+ * `capabilities` (object) and `clientInfo` ({name, version}) are required.
+ * Version VALUES are not judged here: an unknown legacy version negotiates
+ * down at the worker, exactly as documented.
+ */
+export function isCompleteInitializeRequest(message) {
+    return isInitializeRequest(message);
+}
+const INITIALIZE_REQUIRED_FIELDS = ["protocolVersion", "capabilities", "clientInfo"];
+export const INVALID_INITIALIZE_MESSAGE = "initialize rejected: the request is not a valid MCP initialize request. params must carry " +
+    "protocolVersion (string), capabilities (object) and clientInfo ({ name, version }). " +
+    "No protocol era has been selected, so this is fully recoverable: retry with a well-formed " +
+    `initialize, or select protocol revision ${MODERN_PROTOCOL_VERSION} by including ` +
+    "the required io.modelcontextprotocol/* keys in params._meta.";
+/**
+ * Rejection for a frame that claims to be an `initialize` but fails the MCP
+ * initialize schema. Answered at admission, BEFORE the legacy lock is
+ * committed, so the era stays UNSELECTED and every recovery path — including
+ * the modern era — remains open.
+ */
+export function buildInvalidInitializeRejection(id) {
+    return {
+        jsonrpc: "2.0",
+        id,
+        error: {
+            code: -32602,
+            message: INVALID_INITIALIZE_MESSAGE,
+            data: {
+                kind: "invalid_initialize",
+                required: [...INITIALIZE_REQUIRED_FIELDS],
+                eraSelected: false
+            }
+        }
+    };
+}
+/**
+ * Unsupported modern `protocolVersion` VALUE rejection (`-32022` with
+ * `data.supported` / `data.requested`).
+ *
+ * Built from the SDK's own {@link UnsupportedProtocolVersionError} so the
+ * code, message and data stay byte-identical to the worker-produced answer
+ * clients already receive on the pre-pin path — the supervisor merely makes
+ * the check apply to EVERY modern request instead of only the one that
+ * happened to open the connection.
+ */
+export function buildUnsupportedProtocolVersionRejection(id, requested) {
+    const error = new UnsupportedProtocolVersionError({
+        supported: [MODERN_PROTOCOL_VERSION],
+        requested
+    });
+    return {
+        jsonrpc: "2.0",
+        id,
+        error: {
+            code: error.code,
+            message: error.message,
+            data: error.data
+        }
+    };
+}
+/**
+ * Plain -32601 admission rejection for subscriptions/listen in the modern era
+ * (no data.kind — deliberately indistinguishable from an ordinary unknown
+ * method). Defense in depth: if admission were ever bypassed, the worker
+ * (maxSubscriptions: 0) would answer -32603 "Subscription limit reached";
+ * intercepting at admission keeps that internal detail off the wire.
+ */
+export function buildMethodNotFoundRejection(id) {
+    return {
+        jsonrpc: "2.0",
+        id,
+        error: { code: -32601, message: "Method not found" }
+    };
+}
+//# sourceMappingURL=era-classifier.js.map

package/dist/error-mapping.d.ts

@@ -57,6 +57,14 @@ export type ProblemDetails = {
     exampleCalls?: ExampleCall[];
     /** Ranked near-miss candidates for a class/symbol that was not found. */
     didYouMean?: DidYouMeanCandidate[];
+    /**
+     * Nested-jar inventory of the shell jar the lookup ran against, as jar-entry
+     * names (e.g. "META-INF/jars/api.jar"). A shell jar holds no classes of its
+     * own, so a class-not-found error on one is only actionable with the list of
+     * inner jars the caller can target next. Like `didYouMean`, it travels as a
+     * dedicated typed field: `context` is primitive-only and can never carry it.
+     */
+    nestedJars?: string[];
     failedStage?: string;
     context?: Record<string, string | number | boolean>;
 };
@@ -67,6 +75,34 @@ export type ProblemDetails = {
  * whole rather than partially published.
  */
 export declare function extractDidYouMean(details: unknown): DidYouMeanCandidate[] | undefined;
+/**
+ * Validates and extracts a `nestedJars` inventory from error details.
+ * `buildClassSourceNotFoundError` records it whenever the lookup ran against a
+ * shell jar, but `context` is primitive-only, so without this the inventory
+ * never left the process. Malformed payloads are dropped whole rather than
+ * partially published, matching {@link extractDidYouMean}. An empty inventory
+ * is dropped too: the producing site omits the key entirely in that case, so an
+ * empty array carries no information a caller could act on.
+ */
+export declare function extractNestedJars(details: unknown): string[] | undefined;
+/**
+ * Per-throw-site {@link IssueOrigin} override carried on an AppError's
+ * `details.issueOrigin`.
+ *
+ * The default classification is keyed purely on the error CODE, which is right
+ * for codes whose every throw site shares one origin. A few codes do not:
+ * `ERR_CONTEXT_UNRESOLVED` covers both a caller naming a version no artifact
+ * carries (genuinely `code_issue`) and the tool resolving an artifact with no
+ * binary jar behind the caller's back (`tool_issue`). Publishing the latter as
+ * caller-fixable sends an agent into a retry loop over input it cannot repair.
+ *
+ * This override is deliberately opt-in and per-error: `issueOriginForErrorCode`
+ * and its default sets stay untouched, so the exhaustive classification map in
+ * tests/runtime/error-mapping.test.ts keeps forcing a conscious decision for
+ * every new code. The key is not in `CONTEXT_ALLOWLIST`, so it cannot leak into
+ * the public `context` blob.
+ */
+export declare function extractIssueOriginOverride(details: unknown): IssueOrigin | undefined;
 export declare function statusForErrorCode(code: string): number;
 /**
  * Single source of truth mapping an error code to its {@link RetryClass}. Used
@@ -85,6 +121,46 @@ export declare function retryClassForErrorCode(code: string): RetryClass;
  * not satisfy).
  */
 export declare function issueOriginForErrorCode(code: string): IssueOrigin;
+/**
+ * The single source of truth for a ProblemDetails classification pair, and the
+ * ONLY supported way to compute one for an error the server caught. Every site
+ * that turns a caught error into a published envelope spreads this result — the
+ * tool envelope (`mapErrorToProblem`), batch entries, the batch-aborted
+ * sentinel, and the `mc://` resource read — so one failure always publishes the
+ * same `{ retryClass, issueOrigin }` no matter which access path the caller
+ * used.
+ *
+ * KNOWN EXCEPTION — the synthetic supervisor replies in `src/stdio-supervisor.ts`
+ * (`buildSupervisorQueueLimitReply`, `buildValidateProjectTimeoutReply`) write
+ * the pair as literals and never import this builder. They are not emission
+ * sites for a caught error at all: the supervisor answers a request the worker
+ * never got to run, so there is no source `AppError` whose `details` could carry
+ * an override and nothing to pass as the required `details` argument. Their
+ * literals are `transient` / `tool_issue`, which is exactly what this function
+ * returns for `ERR_LIMIT_EXCEEDED` and `ERR_TOOL_TIMEOUT` today — but that is a
+ * duplicated value held in agreement by hand, not a second call into this
+ * classifier. Reclassifying either code here must be mirrored there.
+ *
+ * It exists because that pair used to be assembled by hand at each site. The
+ * `issueOrigin` half has a per-throw-site override (see
+ * {@link extractIssueOriginOverride}), and honouring it was copy-pasted into
+ * some sites and forgotten in others — which is exactly how one identical
+ * AppError came to publish `tool_issue` through a tool call and `code_issue`
+ * through a resource read. Composing the pair here removes the opportunity:
+ * emission modules import this function and no longer reach the component
+ * classifiers at all.
+ *
+ * `details` is REQUIRED, deliberately without a default. A site that genuinely
+ * has no AppError behind it (a ZodError, a sanitized non-AppError, the
+ * batch-aborted sentinel) must pass `undefined` explicitly, so skipping the
+ * override can only ever be a written-down decision rather than an omission.
+ *
+ * Only `issueOrigin` is overridable per throw site. `retryClass` stays purely
+ * code-derived: it is a documented wire contract, and changing the value an
+ * existing code publishes is a Breaking change, so a `retryClass` override seam
+ * was deliberately deferred rather than added alongside this one.
+ */
+export declare function problemClassification(code: string, details: unknown): Pick<ProblemDetails, "retryClass" | "issueOrigin">;
 /**
  * Pick the allowlisted, primitive-valued fields out of an AppError's `details`
  * so the public envelope can carry structured repair context without leaking