@adhisang/minecraft-modding-mcp 4.0.0 → 4.1.0

package/dist/stage-emitter.d.ts

@@ -0,0 +1,13 @@
+export type StageEmitter = (stage: string, meta?: Record<string, unknown>) => Promise<void>;
+export declare const NOOP_STAGE_EMITTER: StageEmitter;
+export type StageEmitterExtra = {
+    requestId?: string | number;
+    sendNotification?: (notification: {
+        method: string;
+        params?: unknown;
+    }) => Promise<void>;
+};
+export type StageEmitterOptions = {
+    disabled?: boolean;
+};
+export declare function makeStageEmitter(extra: StageEmitterExtra | undefined, options?: StageEmitterOptions): StageEmitter;

package/dist/stage-emitter.js

@@ -0,0 +1,30 @@
+import { performance } from "node:perf_hooks";
+const STAGE_PROGRESS_DISABLED = process.env.MIXIN_STAGE_PROGRESS_OFF === "1";
+export const NOOP_STAGE_EMITTER = async () => {
+    /* noop */
+};
+export function makeStageEmitter(extra, options = {}) {
+    if (options.disabled ?? STAGE_PROGRESS_DISABLED) {
+        return NOOP_STAGE_EMITTER;
+    }
+    if (!extra) {
+        return NOOP_STAGE_EMITTER;
+    }
+    const requestId = extra.requestId;
+    const sendNotification = extra.sendNotification;
+    if (requestId === undefined || typeof sendNotification !== "function") {
+        return NOOP_STAGE_EMITTER;
+    }
+    return async (stage, meta) => {
+        await sendNotification({
+            method: "$/stageUpdate",
+            params: {
+                stage,
+                meta: meta ?? null,
+                t: performance.now(),
+                requestId
+            }
+        });
+    };
+}
+//# sourceMappingURL=stage-emitter.js.map

package/dist/stdio-supervisor.d.ts

@@ -1,12 +1,72 @@
+import type { JSONRPCResponse } from "@modelcontextprotocol/sdk/types.js";
 type SupervisorOptions = {
     entryFile: string;
 };
+type RequestId = string | number;
+export type ExitInfo = {
+    code: number | null;
+    signal: NodeJS.Signals | null;
+};
+export type RetryRecommendation = "narrow-query" | "clear-cache" | "report-bug" | "same-request";
+export type RestartContext = {
+    toolName: string | undefined;
+    durationMs: number;
+    lastStage: string | undefined;
+    lastStageElapsedMs: number | undefined;
+    lastStageMeta: unknown;
+    exit: ExitInfo;
+    toolArgsRedacted: Record<string, unknown> | undefined;
+    /** `true` when redaction replaced any value with a sentinel placeholder; the synthetic envelope omits `suggestedCall` in that case. */
+    toolArgsRedactedModified: boolean;
+    retryRecommendation: RetryRecommendation;
+};
+export type PendingRequestSnapshot = {
+    id: RequestId;
+    method?: string;
+    toolName?: string;
+    toolArgsRedacted?: Record<string, unknown>;
+    /** `true` when toolArgsRedacted contains sentinel placeholders (truncate/redact/overflow). */
+    toolArgsRedactedModified?: boolean;
+    startedAt: number;
+    lastStage?: string;
+    lastStageStartedAt?: number;
+    lastStageMeta?: unknown;
+};
+export declare function buildLegacyJsonRpcError(id: RequestId): JSONRPCResponse;
+export type RedactedToolArgs = {
+    args: Record<string, unknown>;
+    /** `true` when redaction replaced any value with a sentinel; supervisor uses this to decide whether to surface `suggestedCall`. */
+    modified: boolean;
+};
+export declare function redactToolArgs(args: unknown): RedactedToolArgs;
+export declare function decideRetryRecommendation(ctx: Pick<RestartContext, "toolName" | "lastStage" | "lastStageMeta" | "exit">, recentRestartTimestamps: number[]): RetryRecommendation;
+export declare function buildSyntheticCallToolResult(id: RequestId, ctx: RestartContext): JSONRPCResponse;
+export declare function pruneRestartTimestamps(timestamps: number[], now: number, windowMs?: number): number[];
+/**
+ * Group a worker-exit batch by toolName and produce the per-tool pruned
+ * timestamp set plus the post-exit snapshot. Grouping ensures one exit
+ * counts as one death per tool regardless of how many concurrent pending
+ * requests it killed. `prunedByTool` feeds `buildWorkerRestartReply`;
+ * `updatedByTool` is what the caller writes back to `recentRestarts`.
+ */
+export declare function buildExitTimestampGroups(pendingToolNames: Iterable<string | undefined>, recentRestarts: Map<string, number[]>, now: number): {
+    prunedByTool: Map<string, number[]>;
+    updatedByTool: Map<string, number[]>;
+};
+export type BuildWorkerRestartReplyOptions = {
+    structuredRestartDisabled?: boolean;
+};
+export declare function buildWorkerRestartReply(req: PendingRequestSnapshot, exit: ExitInfo, now: number, recentRestartTimestamps: number[], options?: BuildWorkerRestartReplyOptions): {
+    reply: JSONRPCResponse;
+    updatedTimestamps: number[];
+};
 export declare class StdioSupervisor {
     private readonly entryFile;
     private readonly clientReader;
     private readonly workerReader;
     private readonly queuedMessages;
     private readonly pendingRequests;
+    private readonly recentRestarts;
     private child;
     private childReady;
     private shuttingDown;
@@ -33,6 +93,7 @@ export declare class StdioSupervisor {
     private readonly handleWorkerProcessError;
     private readonly handleWorkerExit;
     private handleWorkerMessage;
+    private applyStageUpdate;
     private handleWorkerReady;
     private isInitializationResponse;
     private flushQueue;

package/dist/stdio-supervisor.js

@@ -2,10 +2,20 @@ import { spawn } from "node:child_process";
 import process from "node:process";
 import { encodeJsonRpcMessage, JsonRpcFrameReader } from "./json-rpc-framing.js";
 import { log } from "./logger.js";
+import { buildSuggestedCall } from "./build-suggested-call.js";
+import { getToolSchema } from "./tool-schema-registry.js";
 const DEFAULT_CLIENT_MODE = "line";
 const WORKER_MODE_ENV = "MCP_STDIO_WORKER_MODE";
 const WORKER_READY_MARKER = "__MCP_STDIO_WORKER_READY__";
 const SUPERVISOR_DEBUG_ENABLED = process.env.MCP_SUPERVISOR_DEBUG === "1";
+const STRUCTURED_RESTART_DISABLED = process.env.SUPERVISOR_STRUCTURED_RESTART_OFF === "1";
+const RESTART_WINDOW_MS = 60_000;
+const RESTART_REPEAT_THRESHOLD = 3;
+const REDACT_KEY_PATTERNS = [/secret/i, /token/i, /apikey/i, /password/i];
+const PRESERVED_PATH_KEYS = new Set(["projectPath", "sourcePath", "mixinConfigPath"]);
+const MAX_STRING_BYTES = 256;
+const MAX_ARRAY_LENGTH = 8;
+const MAX_OBJECT_KEYS = 16;
 function isRequest(message) {
     return "method" in message && "id" in message;
 }
@@ -23,7 +33,7 @@ function getTrackedRequestId(message) {
 function requestKey(id) {
     return `${typeof id}:${String(id)}`;
 }
-function buildWorkerRestartError(id) {
+export function buildLegacyJsonRpcError(id) {
     return {
         jsonrpc: "2.0",
         id,
@@ -33,6 +43,252 @@ function buildWorkerRestartError(id) {
         }
     };
 }
+function byteLengthUtf8(value) {
+    return Buffer.byteLength(value, "utf8");
+}
+function isRedactKey(key) {
+    return REDACT_KEY_PATTERNS.some((re) => re.test(key));
+}
+function redactValue(value, counter, keyName) {
+    if (keyName !== undefined && !PRESERVED_PATH_KEYS.has(keyName) && isRedactKey(keyName)) {
+        counter.modified = true;
+        return "<redacted>";
+    }
+    if (value === null || value === undefined) {
+        return value;
+    }
+    const valueType = typeof value;
+    if (valueType === "string") {
+        const str = value;
+        if (keyName !== undefined && PRESERVED_PATH_KEYS.has(keyName)) {
+            return str;
+        }
+        const byteLen = byteLengthUtf8(str);
+        if (byteLen > MAX_STRING_BYTES) {
+            counter.modified = true;
+            return `<truncated:${byteLen} bytes>`;
+        }
+        return str;
+    }
+    if (valueType === "number" || valueType === "boolean") {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        if (value.length > MAX_ARRAY_LENGTH) {
+            counter.modified = true;
+            const head = value
+                .slice(0, MAX_ARRAY_LENGTH)
+                .map((item) => redactValue(item, counter));
+            head.push(`<+${value.length - MAX_ARRAY_LENGTH} more>`);
+            return head;
+        }
+        return value.map((item) => redactValue(item, counter));
+    }
+    if (valueType === "object") {
+        const entries = Object.entries(value);
+        const limited = entries.slice(0, MAX_OBJECT_KEYS);
+        const result = {};
+        for (const [key, child] of limited) {
+            result[key] = redactValue(child, counter, key);
+        }
+        if (entries.length > MAX_OBJECT_KEYS) {
+            counter.modified = true;
+            result["<+more>"] = `<+${entries.length - MAX_OBJECT_KEYS} more keys>`;
+        }
+        return result;
+    }
+    return undefined;
+}
+export function redactToolArgs(args) {
+    if (args === null || args === undefined || typeof args !== "object" || Array.isArray(args)) {
+        return { args: {}, modified: false };
+    }
+    const counter = { modified: false };
+    const redacted = redactValue(args, counter);
+    if (redacted && typeof redacted === "object" && !Array.isArray(redacted)) {
+        return { args: redacted, modified: counter.modified };
+    }
+    return { args: {}, modified: counter.modified };
+}
+export function decideRetryRecommendation(ctx, recentRestartTimestamps) {
+    if (ctx.lastStage === "target-lookup") {
+        const meta = ctx.lastStageMeta;
+        const targetTotal = typeof meta?.targetTotal === "number" ? meta.targetTotal : undefined;
+        if (targetTotal !== undefined && targetTotal > 5) {
+            return "narrow-query";
+        }
+    }
+    if (ctx.exit.signal === "SIGABRT" || ctx.exit.signal === "SIGSEGV" || ctx.exit.signal === "SIGKILL") {
+        return "clear-cache";
+    }
+    if (recentRestartTimestamps.length >= RESTART_REPEAT_THRESHOLD) {
+        return "report-bug";
+    }
+    return "same-request";
+}
+export function buildSyntheticCallToolResult(id, ctx) {
+    const tool = ctx.toolName ?? "unknown";
+    const hints = [];
+    if (ctx.lastStage) {
+        const indexNote = (() => {
+            const meta = ctx.lastStageMeta;
+            if (meta &&
+                typeof meta.targetIndex === "number" &&
+                typeof meta.targetTotal === "number") {
+                return `at index ${meta.targetIndex}/${meta.targetTotal}`;
+            }
+            return "";
+        })();
+        const recommendation = (() => {
+            switch (ctx.retryRecommendation) {
+                case "narrow-query":
+                    return "narrow mixinConfigPath to one file and retry";
+                case "clear-cache":
+                    return "clear cache and retry";
+                case "report-bug":
+                    return "report a bug — repeated worker exits";
+                case "same-request":
+                default:
+                    return "retry the same request";
+            }
+        })();
+        hints.push(`lastStage=${ctx.lastStage}${indexNote ? ` ${indexNote}` : ""} — ${recommendation}`);
+    }
+    else {
+        hints.push("worker exited before stage tracking began");
+    }
+    const error = {
+        type: "about:blank/mcp/worker-restart",
+        title: "MCP worker restarted",
+        detail: `The worker process exited while handling tools/call (${tool}).`,
+        status: 503,
+        code: "ERR_WORKER_RESTART",
+        instance: `urn:mcp:request:${String(id)}`,
+        hints
+    };
+    // Mutated args carry sentinel placeholders (`<truncated:…>`, `<redacted>`)
+    // that are not safe to retry. Surface them on `meta.restart.redactedToolArgs`
+    // for diagnostics instead.
+    if (ctx.toolArgsRedacted !== undefined && !ctx.toolArgsRedactedModified) {
+        // Only emit `suggestedCall` when the resolved tool name is a
+        // currently-registered public tool. The "unknown" fallback above and
+        // unregistered names (typo, disabled tool, version-skewed) cannot
+        // produce a re-callable payload; buildSuggestedCall fails open for
+        // unregistered names so the registration check belongs here. The
+        // diagnostic `restart.redactedToolArgs` field below still surfaces the
+        // args.
+        if (ctx.toolName !== undefined &&
+            ctx.toolName.length > 0 &&
+            getToolSchema(ctx.toolName) !== undefined) {
+            const gated = buildSuggestedCall({
+                tool: ctx.toolName,
+                params: ctx.toolArgsRedacted
+            });
+            if (gated.suggestedCall) {
+                error.suggestedCall = gated.suggestedCall;
+            }
+        }
+    }
+    if (ctx.lastStage !== undefined) {
+        error.failedStage = ctx.lastStage;
+    }
+    const restart = {
+        tool,
+        durationMs: ctx.durationMs,
+        lastStage: ctx.lastStage ?? null,
+        lastStageElapsedMs: ctx.lastStageElapsedMs ?? null,
+        lastStageMeta: ctx.lastStageMeta ?? null,
+        exit: {
+            code: ctx.exit.code,
+            signal: ctx.exit.signal
+        },
+        retryRecommendation: ctx.retryRecommendation
+    };
+    // Diagnostic echo (paired with the modified flag); not retryable.
+    if (ctx.toolArgsRedacted !== undefined) {
+        restart.redactedToolArgs = ctx.toolArgsRedacted;
+        restart.redactedToolArgsModified = ctx.toolArgsRedactedModified;
+    }
+    const meta = {
+        synthetic: true,
+        syntheticSource: "supervisor",
+        restart
+    };
+    const structuredContent = { error, meta };
+    return {
+        jsonrpc: "2.0",
+        id,
+        result: {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(structuredContent)
+                }
+            ],
+            isError: true,
+            structuredContent
+        }
+    };
+}
+export function pruneRestartTimestamps(timestamps, now, windowMs = RESTART_WINDOW_MS) {
+    const cutoff = now - windowMs;
+    return timestamps.filter((t) => t >= cutoff);
+}
+/**
+ * Group a worker-exit batch by toolName and produce the per-tool pruned
+ * timestamp set plus the post-exit snapshot. Grouping ensures one exit
+ * counts as one death per tool regardless of how many concurrent pending
+ * requests it killed. `prunedByTool` feeds `buildWorkerRestartReply`;
+ * `updatedByTool` is what the caller writes back to `recentRestarts`.
+ */
+export function buildExitTimestampGroups(pendingToolNames, recentRestarts, now) {
+    const prunedByTool = new Map();
+    const updatedByTool = new Map();
+    for (const raw of pendingToolNames) {
+        const toolName = raw ?? "unknown";
+        if (prunedByTool.has(toolName))
+            continue;
+        const pruned = pruneRestartTimestamps(recentRestarts.get(toolName) ?? [], now);
+        prunedByTool.set(toolName, pruned);
+        updatedByTool.set(toolName, [...pruned, now]);
+    }
+    return { prunedByTool, updatedByTool };
+}
+export function buildWorkerRestartReply(req, exit, now, recentRestartTimestamps, options = {}) {
+    if (options.structuredRestartDisabled || req.method !== "tools/call") {
+        return {
+            reply: buildLegacyJsonRpcError(req.id),
+            updatedTimestamps: recentRestartTimestamps
+        };
+    }
+    const pruned = pruneRestartTimestamps(recentRestartTimestamps, now);
+    // Include the current restart in the count so "3 deaths in 60s →
+    // report-bug" fires on the third event, not the fourth.
+    const updatedTimestamps = [...pruned, now];
+    const recommendation = decideRetryRecommendation({
+        toolName: req.toolName,
+        lastStage: req.lastStage,
+        lastStageMeta: req.lastStageMeta,
+        exit
+    }, updatedTimestamps);
+    const ctx = {
+        toolName: req.toolName,
+        durationMs: Math.max(0, now - req.startedAt),
+        lastStage: req.lastStage,
+        lastStageElapsedMs: req.lastStageStartedAt !== undefined
+            ? Math.max(0, now - req.lastStageStartedAt)
+            : undefined,
+        lastStageMeta: req.lastStageMeta,
+        exit,
+        toolArgsRedacted: req.toolArgsRedacted,
+        toolArgsRedactedModified: req.toolArgsRedactedModified ?? false,
+        retryRecommendation: recommendation
+    };
+    return {
+        reply: buildSyntheticCallToolResult(req.id, ctx),
+        updatedTimestamps
+    };
+}
 function debugSupervisor(event, details) {
     if (!SUPERVISOR_DEBUG_ENABLED) {
         return;
@@ -45,6 +301,7 @@ export class StdioSupervisor {
     workerReader = new JsonRpcFrameReader();
     queuedMessages = [];
     pendingRequests = new Map();
+    recentRestarts = new Map();
     child;
     childReady = false;
     shuttingDown = false;
@@ -121,10 +378,21 @@ export class StdioSupervisor {
         if (isRequest(message)) {
             const id = getTrackedRequestId(message);
             if (id !== undefined) {
-                this.pendingRequests.set(requestKey(id), {
+                const pending = {
                     id,
-                    method: message.method
-                });
+                    method: message.method,
+                    startedAt: performance.now()
+                };
+                if (message.method === "tools/call") {
+                    const params = (message.params ?? {});
+                    if (typeof params.name === "string") {
+                        pending.toolName = params.name;
+                    }
+                    const redacted = redactToolArgs(params.arguments);
+                    pending.toolArgsRedacted = redacted.args;
+                    pending.toolArgsRedactedModified = redacted.modified;
+                }
+                this.pendingRequests.set(requestKey(id), pending);
             }
             if (message.method === "initialize") {
                 this.initializeSentToWorker = true;
@@ -202,7 +470,7 @@ export class StdioSupervisor {
             signal,
             pendingRequests: this.pendingRequests.size
         });
-        this.failPendingRequestsOnWorkerExit();
+        this.failPendingRequestsOnWorkerExit({ code, signal });
         this.scheduleRestart();
     };
     handleWorkerMessage(message) {
@@ -212,6 +480,12 @@ export class StdioSupervisor {
             id: "id" in message ? message.id : undefined,
             replayingInitialization: this.replayingInitialization
         });
+        if (isNotification(message) && typeof message.method === "string" && message.method.startsWith("$/")) {
+            if (message.method === "$/stageUpdate") {
+                this.applyStageUpdate(message.params);
+            }
+            return;
+        }
         if (this.isInitializationResponse(message)) {
             const id = getTrackedRequestId(message);
             if (id !== undefined) {
@@ -240,6 +514,33 @@ export class StdioSupervisor {
         }
         this.writeToClient(message);
     }
+    applyStageUpdate(params) {
+        if (params === null || params === undefined || typeof params !== "object") {
+            return;
+        }
+        const p = params;
+        const requestId = typeof p.requestId === "string" || typeof p.requestId === "number"
+            ? p.requestId
+            : undefined;
+        if (requestId === undefined)
+            return;
+        const pending = this.pendingRequests.get(requestKey(requestId));
+        if (!pending)
+            return;
+        // Refresh `lastStageStartedAt` only on stage transitions so
+        // `lastStageElapsedMs` measures from stage entry, not from the latest
+        // per-target emit. `lastStageMeta` still updates on every emit so
+        // restart envelopes carry the latest progress payload.
+        if (typeof p.stage === "string" && p.stage !== pending.lastStage) {
+            pending.lastStage = p.stage;
+            pending.lastStageStartedAt = performance.now();
+        }
+        else if (pending.lastStageStartedAt === undefined) {
+            // First emit for this request; bootstrap the stage timer.
+            pending.lastStageStartedAt = performance.now();
+        }
+        pending.lastStageMeta = p.meta;
+    }
     handleWorkerReady() {
         debugSupervisor("worker_ready", {
             hasInitializeRequest: this.initializeRequest !== undefined,
@@ -278,16 +579,32 @@ export class StdioSupervisor {
             this.forwardToWorker(message);
         }
     }
-    failPendingRequestsOnWorkerExit() {
+    failPendingRequestsOnWorkerExit(exit) {
         const preservedInitializeKey = this.initializeRequest && !this.clientInitialized
             ? requestKey(this.initializeRequest.id)
             : undefined;
+        const now = performance.now();
+        // Record this exit once per toolName regardless of how many concurrent
+        // pending requests it killed; per-request recording would inflate the
+        // count to N and falsely escalate retryRecommendation to "report-bug".
+        const pendingToolNames = [];
+        for (const [key, pending] of this.pendingRequests.entries()) {
+            if (key === preservedInitializeKey)
+                continue;
+            pendingToolNames.push(pending.toolName);
+        }
+        const { prunedByTool, updatedByTool } = buildExitTimestampGroups(pendingToolNames, this.recentRestarts, now);
+        for (const [toolName, updated] of updatedByTool) {
+            this.recentRestarts.set(toolName, updated);
+        }
         for (const [key, pending] of [...this.pendingRequests.entries()]) {
-            if (key === preservedInitializeKey) {
+            if (key === preservedInitializeKey)
                 continue;
-            }
             this.pendingRequests.delete(key);
-            this.writeToClient(buildWorkerRestartError(pending.id));
+            const toolName = pending.toolName ?? "unknown";
+            const pruned = prunedByTool.get(toolName) ?? [];
+            const { reply } = buildWorkerRestartReply(pending, exit, now, pruned, { structuredRestartDisabled: STRUCTURED_RESTART_DISABLED });
+            this.writeToClient(reply);
         }
     }
     writeToClient(message) {

package/dist/tool-contract-manifest.d.ts

@@ -1,4 +1,4 @@
-export declare const TOOL_SURFACE_SECTION_IDS: readonly ["v3-entry-tools", "source-exploration", "version-comparison-symbol-tracking", "mapping-symbols", "nbt-utilities", "mod-analysis", "validation", "registry-diagnostics"];
+export declare const TOOL_SURFACE_SECTION_IDS: readonly ["v3-entry-tools", "source-exploration", "version-comparison-symbol-tracking", "mapping-symbols", "nbt-utilities", "mod-analysis", "validation", "registry-diagnostics", "batch-lookup"];
 export type ToolSurfaceSectionId = (typeof TOOL_SURFACE_SECTION_IDS)[number];
 export type ToolSurfaceLocale = "en" | "ja";
 export declare function renderToolSurfaceSection(locale: ToolSurfaceLocale, sectionId: ToolSurfaceSectionId): string;

package/dist/tool-contract-manifest.js

@@ -6,7 +6,8 @@ export const TOOL_SURFACE_SECTION_IDS = [
     "nbt-utilities",
     "mod-analysis",
     "validation",
-    "registry-diagnostics"
+    "registry-diagnostics",
+    "batch-lookup"
 ];
 const SECTION_ROWS = {
     "v3-entry-tools": {
@@ -109,14 +110,16 @@ const SECTION_ROWS = {
     },
     "validation": {
         en: [
-            "| `validate-mixin` | Validate Mixin source against a target Minecraft version |",
+            "| `validate-mixin` | Validate Mixin source against a target Minecraft version (returns `validationStatus: \"partial\"` with `targetOutcomes` when a stage budget defers work) |",
             "| `validate-access-widener` | Validate Access Widener content against a target Minecraft version, optionally using runtime-aware Loom artifacts |",
-            "| `validate-access-transformer` | Validate Access Transformer content against a target Minecraft version, optionally using Forge/NeoForge runtime artifacts |"
+            "| `validate-access-transformer` | Validate Access Transformer content against a target Minecraft version, optionally using Forge/NeoForge runtime artifacts |",
+            "| `verify-mixin-target` | Single-call probe for owner / member existence with `@Shadow` / `@Accessor` / `@Invoker` advice |"
         ],
         ja: [
-            "| `validate-mixin` | 対象 Minecraft バージョンに対して Mixin ソースを検証する |",
-            "| `validate-access-widener` | 対象 Minecraft バージョンに対して Access Widener の内容を検証し、必要に応じて Loom runtime artifact も使う |",
-            "| `validate-access-transformer` | 対象 Minecraft バージョンに対して Access Transformer の内容を検証し、必要に応じて Forge / NeoForge runtime artifact も使う |"
+            "| `validate-mixin` | 対象 Minecraft バージョンに対して Mixin ソースを検証する (段階別予算で一部作業を後回しにした場合は `validationStatus: \"partial\"` と `targetOutcomes` を含む) |",
+            "| `validate-access-widener` | 対象 Minecraft バージョンに対して Access Widener の内容を検証し、必要に応じて Loom ランタイムアーティファクトも使う |",
+            "| `validate-access-transformer` | 対象 Minecraft バージョンに対して Access Transformer の内容を検証し、必要に応じて Forge / NeoForge ランタイムアーティファクトも使う |",
+            "| `verify-mixin-target` | owner / member の存在確認と `@Shadow` / `@Accessor` / `@Invoker` 助言を 1 回の確認で返す |"
         ]
     },
     "registry-diagnostics": {
@@ -128,6 +131,20 @@ const SECTION_ROWS = {
             "| `get-registry-data` | 生成済みレジストリスナップショットを読み取り、必要に応じてエントリデータも含める |",
             "| `get-runtime-metrics` | ランタイムメトリクスとレイテンシスナップショットを確認する |"
         ]
+    },
+    "batch-lookup": {
+        en: [
+            "| `batch-class-source` | Read source for many classes against one shared resolved artifact (1..50 entries per call) |",
+            "| `batch-class-members` | List members for many classes against one shared resolved artifact (1..50 entries per call) |",
+            "| `batch-symbol-exists` | Probe symbol existence for many entries against one shared Minecraft-version artifact (workspace / version targets only) |",
+            "| `batch-mappings` | Translate many symbols across mapping namespaces with one shared Minecraft version (no shared artifact) |"
+        ],
+        ja: [
+            "| `batch-class-source` | 共有解決した 1 つのアーティファクトに対して最大 50 件のクラスソースを読み取る |",
+            "| `batch-class-members` | 共有解決した 1 つのアーティファクトに対して最大 50 件のクラスメンバーを列挙する |",
+            "| `batch-symbol-exists` | 共有解決した 1 つの Minecraft バージョンアーティファクトに対して最大 50 件のシンボル存在確認を行う (ワークスペースまたはバージョン対象のみ) |",
+            "| `batch-mappings` | 1 つの Minecraft バージョンで最大 50 件のシンボルを名前空間横断で変換する (共有アーティファクトなし) |"
+        ]
     }
 };
 export function renderToolSurfaceSection(locale, sectionId) {

package/dist/tool-guidance.d.ts

@@ -0,0 +1,82 @@
+import { ZodError } from "zod";
+import { type ExampleCall, type ProblemDetails, type ProblemFieldError, type SuggestedCall } from "./error-mapping.js";
+import type { SourceTargetInput } from "./types.js";
+export type ToolMeta = {
+    requestId: string;
+    tool: string;
+    durationMs: number;
+    warnings: string[];
+    detailApplied?: "summary" | "standard" | "full";
+    includeApplied?: string[];
+    truncated?: Record<string, unknown>;
+    pagination?: Record<string, unknown>;
+    /** Set to `true` on ERR_STAGE_BUDGET_PRE_PARSE error envelopes to signal a budget-driven failure. */
+    stageBudgetExhausted?: boolean;
+    /** Stage budget (ms) that was exceeded; populated alongside `stageBudgetExhausted`. */
+    budgetMs?: number;
+    /** Actual stage elapsed time (ms); populated alongside `stageBudgetExhausted`. */
+    elapsedMs?: number;
+};
+export declare const SUGGESTED_CALL_DEFAULTS: {
+    readonly allowDecompile: true;
+    readonly preferProjectVersion: false;
+    readonly strictVersion: false;
+    readonly mode: "metadata";
+    readonly access: "public";
+    readonly includeSynthetic: false;
+    readonly includeInherited: false;
+    readonly hideUncertain: false;
+    readonly explain: false;
+    readonly preferProjectMapping: false;
+    readonly minSeverity: "all";
+    readonly reportMode: "full";
+    readonly treatInfoAsWarning: true;
+    readonly includeIssues: true;
+};
+export declare function isSuggestedCallDefault(field: keyof typeof SUGGESTED_CALL_DEFAULTS, value: unknown): boolean;
+export declare const ANALYZE_MOD_INCLUDE_GROUPS: readonly ["warnings", "files", "source", "samples", "timings"];
+export declare const ANALYZE_MOD_LEGACY_METADATA_INCLUDES: readonly ["metadata", "entrypoints", "mixins", "dependencies"];
+export declare const VALIDATE_PROJECT_INCLUDE_GROUPS: readonly ["warnings", "issues", "workspace", "recovery"];
+export declare const VALIDATE_PROJECT_LEGACY_WORKSPACE_INCLUDES: readonly ["detectedConfig", "mixins", "accessWideners"];
+export declare const VALIDATION_FALLBACK_HINT = "suggested call payload failed schema validation; using fallback examples";
+export declare function toFieldErrorsFromZod(error: ZodError): ProblemFieldError[];
+export declare function toHints(details: unknown): string[] | undefined;
+export declare function extractValidatedSuggestionAndExamples(details: unknown): {
+    suggestedCall?: SuggestedCall;
+    exampleCalls?: ExampleCall[];
+    primaryDropped: boolean;
+};
+export declare function extractFailedStageFromDetails(details: unknown): string | undefined;
+export declare function extractFieldErrorsFromDetails(details: unknown): ProblemFieldError[] | undefined;
+export declare function asObjectRecord(value: unknown): Record<string, unknown> | undefined;
+export declare function asNonEmptyString(value: unknown): string | undefined;
+export declare function asStringArray(value: unknown): string[] | undefined;
+export declare function truncateSuggestionText(value: string, maxLength?: number): string;
+export declare function parseJsonObjectString(value: string): Record<string, unknown> | undefined;
+export declare function inferTargetKindFromString(value: string): SourceTargetInput["kind"];
+export declare function copySourceLookupSuggestionFields(tool: "get-class-source" | "get-class-members", source: Record<string, unknown>): Record<string, unknown>;
+export declare function copyValidateMixinSharedParams(source: Record<string, unknown>): Record<string, unknown>;
+export declare function buildValidateMixinSuggestedParams(normalizedInput: unknown): Record<string, unknown>;
+export declare function buildResolveArtifactSuggestedParams(normalizedInput: unknown): Record<string, unknown>;
+export declare function buildSourceLookupSuggestedParams(tool: "get-class-source" | "get-class-members", normalizedInput: unknown): Record<string, unknown>;
+export declare function filterAllowedIncludeValues(values: string[] | undefined, allowed: readonly string[]): string[];
+export declare function buildAnalyzeModSuggestedParams(normalizedInput: unknown): Record<string, unknown>;
+export declare function buildValidateProjectSuggestedParams(normalizedInput: unknown): Record<string, unknown>;
+type InvalidInputGuidance = {
+    hints?: string[];
+    suggestedCall?: SuggestedCall;
+    exampleCalls?: ExampleCall[];
+    primaryDropped?: boolean;
+};
+export declare function buildInvalidInputGuidance(tool: string, normalizedInput: unknown): InvalidInputGuidance | undefined;
+export declare function mapErrorToProblem(caughtError: unknown, requestId: string, context?: {
+    tool?: string;
+    normalizedInput?: unknown;
+}): ProblemDetails;
+/**
+ * Copy documented error-only meta fields from AppError.details into the
+ * public envelope. Scoped to `ERR_STAGE_BUDGET_PRE_PARSE` per
+ * docs/tool-reference.md §Meta fields.
+ */
+export declare function applyErrorMetaExtensions(meta: ToolMeta, error: unknown): void;
+export {};