@adhisang/minecraft-modding-mcp 4.0.0 → 4.1.1

package/dist/entry-tools/inspect-minecraft-service.js

@@ -1,104 +1,18 @@
 import { z } from "zod";
-import { createError, ERROR_CODES, isAppError } from "../errors.js";
+import { createError, ERROR_CODES } from "../errors.js";
 import { buildIncludeSchema, detailSchema, positiveIntSchema } from "./entry-tool-schema.js";
-import { buildEntryToolResult, buildEntryToolMeta, createNextAction, createSummarySubject, createTruncationMeta } from "./response-contract.js";
-import { capArray, nextActionsOrUndefined, resolveDetail, resolveInclude } from "./request-normalizers.js";
+import { resolveDetail, resolveInclude } from "./request-normalizers.js";
+import { TASKS, resolveTask, subjectSchema } from "./inspect-minecraft/internal.js";
+import { handleVersions } from "./inspect-minecraft/handlers/versions.js";
+import { handleArtifact } from "./inspect-minecraft/handlers/artifact.js";
+import { handleClassOverview } from "./inspect-minecraft/handlers/class-overview.js";
+import { handleClassSource } from "./inspect-minecraft/handlers/class-source.js";
+import { handleClassMembers } from "./inspect-minecraft/handlers/class-members.js";
+import { handleSearch } from "./inspect-minecraft/handlers/search.js";
+import { handleFile } from "./inspect-minecraft/handlers/file.js";
+import { handleListFiles } from "./inspect-minecraft/handlers/list-files.js";
 const INCLUDE_GROUPS = ["warnings", "provenance", "candidates", "members", "source", "files", "samples", "artifact", "timings"];
-const TASKS = ["auto", "versions", "artifact", "class-overview", "class-source", "class-members", "search", "file", "list-files"];
-const SUBJECT_KINDS = ["version", "artifact", "class", "file", "search", "workspace"];
 const nonEmptyString = z.string().trim().min(1);
-const resolveTargetSchema = z.object({
-    kind: z.enum(["version", "jar", "coordinate"]),
-    value: nonEmptyString
-});
-const artifactRefSchema = z.discriminatedUnion("type", [
-    z.object({
-        type: z.literal("resolved-id"),
-        artifactId: nonEmptyString
-    }),
-    z.object({
-        type: z.literal("resolve-target"),
-        target: resolveTargetSchema
-    })
-]);
-const workspaceFocusSchema = z.discriminatedUnion("kind", [
-    z.object({
-        kind: z.literal("class"),
-        className: nonEmptyString,
-        artifact: artifactRefSchema.optional()
-    }),
-    z.object({
-        kind: z.literal("file"),
-        filePath: nonEmptyString,
-        artifact: artifactRefSchema.optional()
-    }),
-    z.object({
-        kind: z.literal("search"),
-        query: nonEmptyString,
-        artifact: artifactRefSchema.optional(),
-        intent: z.enum(["symbol", "text", "path"]).optional(),
-        match: z.enum(["exact", "prefix", "contains", "regex"]).optional(),
-        symbolKind: z.enum(["class", "interface", "enum", "record", "method", "field"]).optional(),
-        packagePrefix: nonEmptyString.optional(),
-        fileGlob: nonEmptyString.optional(),
-        queryMode: z.enum(["auto", "token", "literal"]).default("auto")
-    })
-]);
-const subjectSchema = z.discriminatedUnion("kind", [
-    z.object({
-        kind: z.literal("version"),
-        version: nonEmptyString,
-        mapping: z.enum(["obfuscated", "mojang", "intermediary", "yarn"]).optional(),
-        scope: z.enum(["vanilla", "merged", "loader"]).optional(),
-        projectPath: nonEmptyString.optional(),
-        preferProjectVersion: z.boolean().optional(),
-        strictVersion: z.boolean().optional()
-    }),
-    z.object({
-        kind: z.literal("artifact"),
-        artifact: artifactRefSchema,
-        mapping: z.enum(["obfuscated", "mojang", "intermediary", "yarn"]).optional(),
-        scope: z.enum(["vanilla", "merged", "loader"]).optional(),
-        projectPath: nonEmptyString.optional(),
-        preferProjectVersion: z.boolean().optional(),
-        strictVersion: z.boolean().optional()
-    }),
-    z.object({
-        kind: z.literal("class"),
-        className: nonEmptyString,
-        artifact: artifactRefSchema.optional(),
-        mapping: z.enum(["obfuscated", "mojang", "intermediary", "yarn"]).optional(),
-        scope: z.enum(["vanilla", "merged", "loader"]).optional(),
-        projectPath: nonEmptyString.optional(),
-        preferProjectVersion: z.boolean().optional(),
-        strictVersion: z.boolean().optional()
-    }),
-    z.object({
-        kind: z.literal("file"),
-        filePath: nonEmptyString,
-        artifact: artifactRefSchema.optional()
-    }),
-    z.object({
-        kind: z.literal("search"),
-        query: nonEmptyString,
-        artifact: artifactRefSchema.optional(),
-        intent: z.enum(["symbol", "text", "path"]).optional(),
-        match: z.enum(["exact", "prefix", "contains", "regex"]).optional(),
-        symbolKind: z.enum(["class", "interface", "enum", "record", "method", "field"]).optional(),
-        packagePrefix: nonEmptyString.optional(),
-        fileGlob: nonEmptyString.optional(),
-        queryMode: z.enum(["auto", "token", "literal"]).default("auto")
-    }),
-    z.object({
-        kind: z.literal("workspace"),
-        projectPath: nonEmptyString,
-        mapping: z.enum(["obfuscated", "mojang", "intermediary", "yarn"]).optional(),
-        scope: z.enum(["vanilla", "merged", "loader"]).optional(),
-        preferProjectVersion: z.boolean().optional(),
-        strictVersion: z.boolean().optional(),
-        focus: workspaceFocusSchema.optional()
-    })
-]);
 export const inspectMinecraftShape = {
     task: z.enum(TASKS).optional(),
     subject: subjectSchema.optional(),
@@ -124,32 +38,6 @@ export const inspectMinecraftSchema = z.object(inspectMinecraftShape).superRefin
         });
     }
 });
-function hasPartialVanillaCoverage(artifact) {
-    return artifact?.qualityFlags.includes("partial-source-no-net-minecraft") === true
-        || artifact?.artifactContents.sourceCoverage === "partial";
-}
-function looksLikeClassQuery(query) {
-    const trimmed = query.trim();
-    if (!/^[A-Za-z_$][A-Za-z0-9_$.]*$/.test(trimmed)) {
-        return false;
-    }
-    const simpleName = trimmed.split(".").at(-1) ?? trimmed;
-    return /^[A-Z_$]/.test(simpleName) || /^class_\d+(?:\$class_\d+)*$/.test(simpleName);
-}
-function classNameToFilePath(className) {
-    const topLevelClassName = className.split("$")[0] ?? className;
-    return `${topLevelClassName.replace(/\./g, "/")}.java`;
-}
-function isVanillaNamespacePath(filePath) {
-    return filePath.startsWith("net/minecraft/") || filePath.startsWith("com/mojang/");
-}
-function hitTargetsVanillaNamespace(hit) {
-    if (isVanillaNamespacePath(hit.filePath)) {
-        return true;
-    }
-    const qualifiedName = hit.symbol?.qualifiedName;
-    return qualifiedName?.startsWith("net.minecraft.") === true || qualifiedName?.startsWith("com.mojang.") === true;
-}
 export class InspectMinecraftService {
     deps;
     constructor(deps) {
@@ -158,24 +46,24 @@ export class InspectMinecraftService {
     async execute(input) {
         const detail = resolveDetail(input.detail);
         const include = resolveInclude(input.include);
-        const task = this.resolveTask(input.task, input.subject);
+        const task = resolveTask(input.task, input.subject);
         switch (task) {
             case "versions":
-                return this.handleVersions(input, detail, include);
+                return handleVersions(this.deps, input, detail, include);
             case "artifact":
-                return this.handleArtifact(input.subject, detail, include);
+                return handleArtifact(this.deps, input.subject, detail, include);
             case "class-overview":
-                return this.handleClassOverview(input.subject, detail, include);
+                return handleClassOverview(this.deps, input.subject, detail, include);
             case "class-source":
-                return this.handleClassSource(input.subject, detail, include);
+                return handleClassSource(this.deps, input.subject, detail, include);
             case "class-members":
-                return this.handleClassMembers(input.subject, detail, include, input.limit);
+                return handleClassMembers(this.deps, input.subject, detail, include, input.limit);
             case "search":
-                return this.handleSearch(input.subject, detail, include, input.limit, input.cursor);
+                return handleSearch(this.deps, input.subject, detail, include, input.limit, input.cursor);
             case "file":
-                return this.handleFile(input.subject, detail, include);
+                return handleFile(this.deps, input.subject, detail, include);
             case "list-files":
-                return this.handleListFiles(input.subject, detail, include, input.limit, input.cursor);
+                return handleListFiles(this.deps, input.subject, detail, include, input.limit, input.cursor);
             default:
                 throw createError({
                     code: ERROR_CODES.INVALID_INPUT,
@@ -183,1117 +71,5 @@ export class InspectMinecraftService {
                 });
         }
     }
-    requireWorkspaceClassFocus(subject) {
-        if (subject.kind !== "workspace" || subject.focus?.kind !== "class") {
-            throw createError({
-                code: ERROR_CODES.INVALID_INPUT,
-                message: "Workspace focus must be kind=class for this task."
-            });
-        }
-        return subject.focus;
-    }
-    requireWorkspaceSearchFocus(subject) {
-        if (subject.kind !== "workspace" || subject.focus?.kind !== "search") {
-            throw createError({
-                code: ERROR_CODES.INVALID_INPUT,
-                message: "Workspace focus must be kind=search for this task."
-            });
-        }
-        return subject.focus;
-    }
-    requireWorkspaceFileFocus(subject) {
-        if (subject.kind !== "workspace" || subject.focus?.kind !== "file") {
-            throw createError({
-                code: ERROR_CODES.INVALID_INPUT,
-                message: "Workspace focus must be kind=file for this task."
-            });
-        }
-        return subject.focus;
-    }
-    buildClassSubject(subject) {
-        if (subject.kind === "class") {
-            return subject;
-        }
-        const workspaceFocus = this.requireWorkspaceClassFocus(subject);
-        return {
-            kind: "class",
-            className: workspaceFocus.className,
-            artifact: workspaceFocus.artifact,
-            projectPath: subject.projectPath,
-            mapping: subject.mapping,
-            scope: subject.scope,
-            preferProjectVersion: subject.preferProjectVersion,
-            strictVersion: subject.strictVersion
-        };
-    }
-    async resolveClassArtifactReference(subject, classSubject, task) {
-        if (subject.kind === "workspace") {
-            return this.resolveWorkspaceArtifactReference(subject, classSubject.artifact);
-        }
-        return this.resolveArtifactReference(classSubject, task);
-    }
-    async resolveWorkspaceArtifactReference(subject, artifactRef) {
-        if (!artifactRef) {
-            return this.resolveArtifactReference(subject);
-        }
-        if (artifactRef.type === "resolved-id") {
-            return {
-                artifactId: artifactRef.artifactId,
-                warnings: []
-            };
-        }
-        const artifact = await this.deps.resolveArtifact({
-            target: artifactRef.target,
-            mapping: subject.mapping,
-            scope: subject.scope,
-            projectPath: subject.projectPath,
-            preferProjectVersion: subject.preferProjectVersion,
-            strictVersion: subject.strictVersion
-        });
-        return {
-            artifactId: artifact.artifactId,
-            artifact,
-            warnings: [...artifact.warnings]
-        };
-    }
-    resolveTask(task, subject) {
-        if (task && task !== "auto") {
-            return task;
-        }
-        if (!subject) {
-            return "versions";
-        }
-        switch (subject.kind) {
-            case "version":
-            case "artifact":
-                return "artifact";
-            case "workspace":
-                switch (subject.focus?.kind) {
-                    case "class":
-                        return "class-overview";
-                    case "search":
-                        return "search";
-                    case "file":
-                        return "file";
-                    default:
-                        return "artifact";
-                }
-            case "class":
-                return "class-overview";
-            case "file":
-                return "file";
-            case "search":
-                return "search";
-        }
-    }
-    summarizeRequestedSubject(subject) {
-        if (subject.kind === "search") {
-            if (subject.queryMode !== "auto") {
-                return subject;
-            }
-            const { queryMode: _queryMode, ...requestedSubject } = subject;
-            return requestedSubject;
-        }
-        if (subject.kind === "workspace" && subject.focus?.kind === "search") {
-            if (subject.focus.queryMode !== "auto") {
-                return subject;
-            }
-            const { queryMode: _queryMode, ...requestedFocus } = subject.focus;
-            return {
-                ...subject,
-                focus: requestedFocus
-            };
-        }
-        return subject;
-    }
-    async exampleVersionForSubject(subject) {
-        if ("projectPath" in subject && typeof subject.projectPath === "string") {
-            const detectedVersion = await this.deps.detectProjectMinecraftVersion(subject.projectPath);
-            if (detectedVersion) {
-                return detectedVersion;
-            }
-        }
-        return "<version>";
-    }
-    async buildArtifactContextSuggestedCall(task, subject) {
-        return {
-            tool: "inspect-minecraft",
-            params: {
-                task,
-                subject: {
-                    ...subject,
-                    artifact: {
-                        type: "resolve-target",
-                        target: {
-                            kind: "version",
-                            value: await this.exampleVersionForSubject(subject)
-                        }
-                    }
-                }
-            }
-        };
-    }
-    taskForSubject(subject) {
-        return this.resolveTask(undefined, subject);
-    }
-    invalidTaskSubjectError(task, subject) {
-        if (task === "class-source" && subject.kind === "version") {
-            throw createError({
-                code: ERROR_CODES.INVALID_INPUT,
-                message: "class-source requires a class subject; version subjects resolve artifacts, not class names.",
-                details: {
-                    nextAction: "Retry class-source with subject.kind=class and attach artifact context, or use task=artifact to inspect the version first.",
-                    suggestedCall: {
-                        tool: "inspect-minecraft",
-                        params: {
-                            task: "class-source",
-                            subject: {
-                                kind: "class",
-                                className: "net.minecraft.world.item.Item",
-                                artifact: {
-                                    type: "resolve-target",
-                                    target: {
-                                        kind: "version",
-                                        value: subject.version
-                                    }
-                                }
-                            }
-                        }
-                    }
-                }
-            });
-        }
-        const suggestedTask = this.taskForSubject(subject);
-        throw createError({
-            code: ERROR_CODES.INVALID_INPUT,
-            message: `${task} is not compatible with subject.kind="${subject.kind}".`,
-            details: {
-                nextAction: suggestedTask === "artifact"
-                    ? `Retry with task=artifact for this ${subject.kind} subject, or reshape the subject so it supplies the input that ${task} needs.`
-                    : `Retry with task=${suggestedTask} for this subject, or reshape the subject so it supplies the input that ${task} needs.`,
-                suggestedCall: {
-                    tool: "inspect-minecraft",
-                    params: {
-                        task: suggestedTask,
-                        subject
-                    }
-                }
-            }
-        });
-    }
-    async resolveBinaryBackedClass(className, input) {
-        if (!this.deps.checkSymbolExists || !input.version) {
-            return undefined;
-        }
-        let lookup;
-        try {
-            lookup = await this.deps.checkSymbolExists({
-                version: input.version,
-                kind: "class",
-                name: className,
-                sourceMapping: input.mapping ?? "obfuscated",
-                nameMode: className.includes(".") ? "fqcn" : "auto",
-                maxCandidates: 10
-            });
-        }
-        catch (caughtError) {
-            if (isAppError(caughtError)) {
-                return undefined;
-            }
-            throw caughtError;
-        }
-        const resolvedClassName = lookup.resolvedSymbol?.name;
-        if (!resolvedClassName) {
-            return undefined;
-        }
-        return {
-            className: resolvedClassName,
-            warnings: lookup.warnings
-        };
-    }
-    async resolveArtifactReference(subject, task) {
-        if (subject.kind === "artifact") {
-            return this.resolveArtifactRef(subject.artifact, subject);
-        }
-        if (subject.kind === "class" || subject.kind === "file" || subject.kind === "search") {
-            if (!subject.artifact) {
-                const suggestedTask = task
-                    ?? (subject.kind === "class"
-                        ? "class-overview"
-                        : subject.kind === "search"
-                            ? "search"
-                            : "file");
-                throw createError({
-                    code: ERROR_CODES.INVALID_INPUT,
-                    message: `${subject.kind} subject requires artifact context.`,
-                    details: {
-                        nextAction: "Add subject.artifact or use subject.kind=workspace so inspect-minecraft can resolve the artifact first.",
-                        suggestedCall: await this.buildArtifactContextSuggestedCall(suggestedTask, subject)
-                    }
-                });
-            }
-            return this.resolveArtifactRef(subject.artifact, subject);
-        }
-        if (subject.kind === "version") {
-            const artifact = await this.deps.resolveArtifact({
-                target: { kind: "version", value: subject.version },
-                mapping: subject.mapping,
-                scope: subject.scope,
-                projectPath: subject.projectPath,
-                preferProjectVersion: subject.preferProjectVersion,
-                strictVersion: subject.strictVersion
-            });
-            return {
-                artifactId: artifact.artifactId,
-                artifact,
-                version: subject.version,
-                warnings: [...artifact.warnings]
-            };
-        }
-        const version = await this.deps.detectProjectMinecraftVersion(subject.projectPath);
-        if (!version) {
-            return {
-                artifactId: "",
-                version: undefined,
-                warnings: [`Could not infer Minecraft version from ${subject.projectPath}.`]
-            };
-        }
-        const artifact = await this.deps.resolveArtifact({
-            target: { kind: "version", value: version },
-            mapping: subject.mapping,
-            scope: subject.scope,
-            projectPath: subject.projectPath,
-            preferProjectVersion: subject.preferProjectVersion ?? true,
-            strictVersion: subject.strictVersion
-        });
-        return {
-            artifactId: artifact.artifactId,
-            artifact,
-            version,
-            warnings: [...artifact.warnings]
-        };
-    }
-    async resolveArtifactRef(ref, subject) {
-        if (ref.type === "resolved-id") {
-            return {
-                artifactId: ref.artifactId,
-                warnings: []
-            };
-        }
-        const artifact = await this.deps.resolveArtifact({
-            target: ref.target,
-            mapping: "mapping" in subject ? subject.mapping : undefined,
-            scope: "scope" in subject ? subject.scope : undefined,
-            projectPath: "projectPath" in subject ? subject.projectPath : undefined,
-            preferProjectVersion: "preferProjectVersion" in subject ? subject.preferProjectVersion : undefined,
-            strictVersion: "strictVersion" in subject ? subject.strictVersion : undefined
-        });
-        return {
-            artifactId: artifact.artifactId,
-            artifact,
-            warnings: [...artifact.warnings]
-        };
-    }
-    async handleVersions(input, detail, include) {
-        const versions = await this.deps.listVersions({
-            includeSnapshots: input.includeSnapshots,
-            limit: input.limit
-        });
-        const summary = {
-            status: "ok",
-            headline: `Found ${versions.totalAvailable} Minecraft versions.`,
-            subject: createSummarySubject({
-                task: "versions",
-                kind: "versions",
-                includeSnapshots: input.includeSnapshots === false ? undefined : input.includeSnapshots,
-                limit: input.limit
-            }),
-            counts: {
-                releases: versions.releases.length,
-                snapshots: versions.snapshots?.length ?? 0
-            },
-            nextActions: nextActionsOrUndefined([
-                createNextAction("inspect-minecraft", {
-                    task: "artifact",
-                    subject: {
-                        kind: "version",
-                        version: versions.latest.release ?? versions.releases[0]?.id
-                    }
-                })
-            ])
-        };
-        return {
-            ...buildEntryToolResult({
-                task: "versions",
-                summary,
-                detail,
-                include,
-                blocks: {
-                    versions: {
-                        latest: versions.latest,
-                        releases: detail === "summary" ? versions.releases.slice(0, 5) : versions.releases,
-                        snapshots: input.includeSnapshots ? versions.snapshots : undefined,
-                        cached: versions.cached
-                    }
-                }
-            }),
-            warnings: []
-        };
-    }
-    async handleArtifact(subject, detail, include) {
-        const resolved = await this.resolveArtifactReference(subject);
-        if (!resolved.artifactId) {
-            const summary = {
-                status: "blocked",
-                headline: "Could not resolve an artifact without a Minecraft version.",
-                subject: createSummarySubject({
-                    task: "artifact",
-                    requested: subject
-                }),
-                nextActions: nextActionsOrUndefined([
-                    createNextAction("inspect-minecraft", {
-                        task: "artifact",
-                        subject: {
-                            kind: "version",
-                            version: "1.21.10"
-                        }
-                    })
-                ])
-            };
-            return {
-                ...buildEntryToolResult({
-                    task: "artifact",
-                    summary,
-                    detail,
-                    include,
-                    blocks: {
-                        subject: {
-                            requested: subject
-                        }
-                    },
-                    alwaysBlocks: ["subject"]
-                }),
-                warnings: resolved.warnings
-            };
-        }
-        const summary = {
-            status: "ok",
-            headline: `Resolved artifact ${resolved.artifactId}.`,
-            subject: createSummarySubject({
-                task: "artifact",
-                requested: subject,
-                artifactId: resolved.artifactId,
-                version: resolved.version
-            }),
-            counts: {
-                warnings: resolved.warnings.length
-            }
-        };
-        return {
-            ...buildEntryToolResult({
-                task: "artifact",
-                summary,
-                detail,
-                include,
-                blocks: {
-                    subject: {
-                        requested: subject,
-                        resolved: {
-                            artifactId: resolved.artifactId,
-                            version: resolved.version
-                        }
-                    },
-                    artifact: resolved.artifact
-                        ? {
-                            artifactId: resolved.artifact.artifactId,
-                            artifactAlias: resolved.artifact.artifactAlias,
-                            origin: resolved.artifact.origin,
-                            mappingApplied: resolved.artifact.mappingApplied,
-                            version: resolved.artifact.version,
-                            artifactContents: resolved.artifact.artifactContents
-                        }
-                        : { artifactId: resolved.artifactId }
-                },
-                alwaysBlocks: ["subject"]
-            }),
-            warnings: resolved.warnings
-        };
-    }
-    async handleClassOverview(subject, detail, include) {
-        if (subject.kind !== "class" && !(subject.kind === "workspace" && subject.focus?.kind === "class")) {
-            this.invalidTaskSubjectError("class-overview", subject);
-        }
-        const classSubject = this.buildClassSubject(subject);
-        const className = classSubject.className;
-        const artifact = await this.resolveClassArtifactReference(subject, classSubject, "class-overview");
-        if (!artifact.artifactId) {
-            const summary = {
-                status: "blocked",
-                headline: `Could not resolve artifact context for ${className}.`,
-                subject: createSummarySubject({
-                    task: "class-overview",
-                    requested: subject,
-                    className
-                })
-            };
-            return {
-                ...buildEntryToolResult({
-                    task: "class-overview",
-                    summary,
-                    detail,
-                    include,
-                    blocks: {
-                        subject: {
-                            requested: subject
-                        }
-                    },
-                    alwaysBlocks: ["subject"]
-                }),
-                warnings: artifact.warnings
-            };
-        }
-        const matches = await this.deps.findClass({
-            artifactId: artifact.artifactId,
-            className,
-            limit: 10
-        });
-        if (matches.total === 0) {
-            const partialSourceFallback = subject.kind === "workspace" && hasPartialVanillaCoverage(artifact.artifact)
-                ? await this.resolveBinaryBackedClass(className, {
-                    version: artifact.version,
-                    mapping: classSubject.mapping
-                })
-                : undefined;
-            if (partialSourceFallback) {
-                const metadata = await this.deps.getClassSource({
-                    className: partialSourceFallback.className,
-                    artifactId: artifact.artifactId,
-                    mapping: classSubject.mapping,
-                    scope: classSubject.scope,
-                    projectPath: classSubject.projectPath,
-                    preferProjectVersion: classSubject.preferProjectVersion,
-                    strictVersion: classSubject.strictVersion,
-                    mode: "metadata"
-                });
-                const summary = {
-                    status: "ok",
-                    headline: `Resolved class overview for ${partialSourceFallback.className}.`,
-                    subject: createSummarySubject({
-                        task: "class-overview",
-                        requested: subject,
-                        className: partialSourceFallback.className,
-                        artifactId: metadata.artifactId
-                    }),
-                    counts: {
-                        totalLines: metadata.totalLines
-                    },
-                    notes: [
-                        "Source coverage was partial, so inspect-minecraft confirmed the vanilla class through binary-backed symbol lookup."
-                    ]
-                };
-                return {
-                    ...buildEntryToolResult({
-                        task: "class-overview",
-                        summary,
-                        detail,
-                        include,
-                        blocks: {
-                            subject: {
-                                requested: subject,
-                                resolved: {
-                                    artifactId: metadata.artifactId,
-                                    className: partialSourceFallback.className
-                                }
-                            },
-                            class: {
-                                className: partialSourceFallback.className,
-                                totalLines: metadata.totalLines,
-                                returnedNamespace: metadata.returnedNamespace
-                            }
-                        },
-                        alwaysBlocks: ["subject"]
-                    }),
-                    warnings: [
-                        ...artifact.warnings,
-                        ...matches.warnings,
-                        ...partialSourceFallback.warnings,
-                        ...metadata.warnings
-                    ]
-                };
-            }
-            const summary = {
-                status: "not_found",
-                headline: `No class match was found for ${className}.`,
-                subject: createSummarySubject({
-                    task: "class-overview",
-                    requested: subject,
-                    className,
-                    artifactId: artifact.artifactId
-                })
-            };
-            return {
-                ...buildEntryToolResult({
-                    task: "class-overview",
-                    summary,
-                    detail,
-                    include,
-                    blocks: {
-                        subject: {
-                            requested: subject,
-                            resolved: {
-                                artifactId: artifact.artifactId
-                            }
-                        }
-                    },
-                    alwaysBlocks: ["subject"]
-                }),
-                warnings: [...artifact.warnings, ...matches.warnings]
-            };
-        }
-        if (matches.total > 1) {
-            const candidateActions = matches.matches.slice(0, 3).map((match) => createNextAction("inspect-minecraft", {
-                task: "class-source",
-                subject: {
-                    kind: "class",
-                    className: match.qualifiedName,
-                    artifact: {
-                        type: "resolved-id",
-                        artifactId: artifact.artifactId
-                    }
-                },
-                include: ["source"]
-            }));
-            const summary = {
-                status: "ambiguous",
-                headline: `Found ${matches.total} class matches for ${className}.`,
-                subject: createSummarySubject({
-                    task: "class-overview",
-                    requested: subject,
-                    className,
-                    artifactId: artifact.artifactId
-                }),
-                counts: {
-                    matches: matches.total
-                },
-                nextActions: nextActionsOrUndefined(candidateActions)
-            };
-            return {
-                ...buildEntryToolResult({
-                    task: "class-overview",
-                    summary,
-                    detail,
-                    include,
-                    blocks: {
-                        subject: {
-                            requested: subject,
-                            resolved: {
-                                artifactId: artifact.artifactId
-                            }
-                        },
-                        candidates: matches.matches
-                    },
-                    alwaysBlocks: ["subject"]
-                }),
-                warnings: [...artifact.warnings, ...matches.warnings]
-            };
-        }
-        const match = matches.matches[0];
-        const metadata = await this.deps.getClassSource({
-            className: match.qualifiedName,
-            artifactId: artifact.artifactId,
-            mode: "metadata"
-        });
-        const summary = {
-            status: "ok",
-            headline: `Resolved class overview for ${match.qualifiedName}.`,
-            subject: createSummarySubject({
-                task: "class-overview",
-                requested: subject,
-                className: match.qualifiedName,
-                artifactId: artifact.artifactId
-            }),
-            counts: {
-                totalLines: metadata.totalLines
-            },
-            nextActions: nextActionsOrUndefined([
-                createNextAction("inspect-minecraft", {
-                    task: "class-source",
-                    subject: {
-                        kind: "class",
-                        className: match.qualifiedName,
-                        artifact: {
-                            type: "resolved-id",
-                            artifactId: artifact.artifactId
-                        }
-                    },
-                    include: ["source"]
-                })
-            ])
-        };
-        return {
-            ...buildEntryToolResult({
-                task: "class-overview",
-                summary,
-                detail,
-                include,
-                blocks: {
-                    subject: {
-                        requested: subject,
-                        resolved: {
-                            artifactId: artifact.artifactId,
-                            className: match.qualifiedName
-                        }
-                    },
-                    artifact: artifact.artifact
-                        ? {
-                            artifactId: artifact.artifact.artifactId,
-                            version: artifact.artifact.version,
-                            origin: artifact.artifact.origin
-                        }
-                        : { artifactId: artifact.artifactId },
-                    class: {
-                        className: match.qualifiedName,
-                        filePath: match.filePath,
-                        totalLines: metadata.totalLines,
-                        returnedNamespace: metadata.returnedNamespace
-                    }
-                },
-                alwaysBlocks: ["subject"]
-            }),
-            warnings: [...artifact.warnings, ...matches.warnings, ...metadata.warnings]
-        };
-    }
-    async handleClassSource(subject, detail, include) {
-        if (subject.kind !== "class" && !(subject.kind === "workspace" && subject.focus?.kind === "class")) {
-            this.invalidTaskSubjectError("class-source", subject);
-        }
-        const classSubject = this.buildClassSubject(subject);
-        const className = classSubject.className;
-        const artifactContext = await this.resolveClassArtifactReference(subject, classSubject, "class-source");
-        const source = await this.deps.getClassSource({
-            className,
-            artifactId: artifactContext.artifactId || undefined,
-            mapping: classSubject.mapping,
-            scope: classSubject.scope,
-            projectPath: classSubject.projectPath,
-            preferProjectVersion: classSubject.preferProjectVersion,
-            strictVersion: classSubject.strictVersion,
-            mode: include.includes("source") || detail === "full" ? "snippet" : "metadata"
-        });
-        const summary = {
-            status: "ok",
-            headline: `Resolved source for ${source.className}.`,
-            subject: createSummarySubject({
-                task: "class-source",
-                requested: subject,
-                className: source.className,
-                artifactId: source.artifactId
-            }),
-            counts: {
-                totalLines: source.totalLines
-            }
-        };
-        return {
-            ...buildEntryToolResult({
-                task: "class-source",
-                summary,
-                detail,
-                include,
-                blocks: {
-                    subject: {
-                        requested: subject,
-                        resolved: {
-                            artifactId: source.artifactId,
-                            className: source.className
-                        }
-                    },
-                    source: {
-                        className: source.className,
-                        mode: source.mode,
-                        returnedRange: source.returnedRange,
-                        totalLines: source.totalLines,
-                        sourceText: source.sourceText
-                    }
-                },
-                alwaysBlocks: ["subject"]
-            }),
-            warnings: [...artifactContext.warnings, ...source.warnings]
-        };
-    }
-    async handleClassMembers(subject, detail, include, limit) {
-        if (subject.kind !== "class" && !(subject.kind === "workspace" && subject.focus?.kind === "class")) {
-            this.invalidTaskSubjectError("class-members", subject);
-        }
-        const classSubject = this.buildClassSubject(subject);
-        const artifact = await this.resolveClassArtifactReference(subject, classSubject, "class-members");
-        const members = await this.deps.getClassMembers({
-            className: classSubject.className,
-            artifactId: artifact.artifactId || undefined,
-            mapping: classSubject.mapping,
-            scope: classSubject.scope,
-            projectPath: classSubject.projectPath,
-            preferProjectVersion: classSubject.preferProjectVersion,
-            strictVersion: classSubject.strictVersion,
-            maxMembers: limit
-        });
-        const summary = {
-            status: members.truncated ? "partial" : "ok",
-            headline: `Collected ${members.counts.total} members for ${members.className}.`,
-            subject: createSummarySubject({
-                task: "class-members",
-                requested: subject,
-                className: members.className,
-                artifactId: members.artifactId
-            }),
-            counts: members.counts
-        };
-        return {
-            ...buildEntryToolResult({
-                task: "class-members",
-                summary,
-                detail,
-                include,
-                blocks: {
-                    subject: {
-                        requested: subject,
-                        resolved: {
-                            artifactId: members.artifactId,
-                            className: members.className
-                        }
-                    },
-                    members: include.includes("members") || detail !== "summary"
-                        ? {
-                            ...members.members,
-                            ...(members.decompiledFallback ? { decompiledFallback: members.decompiledFallback } : {}),
-                            ...(members.decompiledMemberCounts ? { decompiledMemberCounts: members.decompiledMemberCounts } : {})
-                        }
-                        : {
-                            counts: members.counts,
-                            ...(members.decompiledMemberCounts ? { decompiledMemberCounts: members.decompiledMemberCounts } : {})
-                        }
-                },
-                alwaysBlocks: ["subject"]
-            }),
-            warnings: [...artifact.warnings, ...members.warnings],
-            ...(members.truncated
-                ? {
-                    meta: buildEntryToolMeta({
-                        detail,
-                        include,
-                        warnings: [...artifact.warnings, ...members.warnings],
-                        truncated: createTruncationMeta({
-                            omittedGroups: ["members"],
-                            nextActions: [
-                                createNextAction("inspect-minecraft", {
-                                    task: "class-members",
-                                    detail: "full",
-                                    include: ["members"],
-                                    subject
-                                })
-                            ]
-                        })
-                    })
-                }
-                : {})
-        };
-    }
-    async handleSearch(subject, detail, include, limit, cursor) {
-        if (subject.kind !== "search" && !(subject.kind === "workspace" && subject.focus?.kind === "search")) {
-            this.invalidTaskSubjectError("search", subject);
-        }
-        const searchSubject = subject.kind === "search" ? subject : this.requireWorkspaceSearchFocus(subject);
-        const requestedSubject = this.summarizeRequestedSubject(subject);
-        const queryMode = searchSubject.queryMode ?? "auto";
-        const artifact = subject.kind === "search"
-            ? await this.resolveArtifactReference(subject, "search")
-            : await this.resolveWorkspaceArtifactReference(subject, searchSubject.artifact);
-        const search = await this.deps.searchClassSource({
-            artifactId: artifact.artifactId,
-            query: searchSubject.query,
-            intent: searchSubject.intent,
-            match: searchSubject.match,
-            queryMode,
-            limit,
-            cursor,
-            scope: searchSubject.packagePrefix || searchSubject.fileGlob || searchSubject.symbolKind
-                ? {
-                    packagePrefix: searchSubject.packagePrefix,
-                    fileGlob: searchSubject.fileGlob,
-                    symbolKind: searchSubject.symbolKind
-                }
-                : undefined
-        });
-        const needsBinaryBackedClassHit = subject.kind === "workspace" &&
-            hasPartialVanillaCoverage(artifact.artifact) &&
-            looksLikeClassQuery(searchSubject.query) &&
-            !search.hits.some((hit) => hitTargetsVanillaNamespace(hit));
-        const binaryBackedClassHit = needsBinaryBackedClassHit
-            ? await this.resolveBinaryBackedClass(searchSubject.query, {
-                version: artifact.version,
-                mapping: subject.mapping
-            })
-            : undefined;
-        const binaryBackedHitRecord = binaryBackedClassHit == null
-            ? undefined
-            : {
-                filePath: classNameToFilePath(binaryBackedClassHit.className),
-                score: 100,
-                matchedIn: "symbol",
-                reasonCodes: ["binary-class-lookup"],
-                symbol: {
-                    symbolKind: "class",
-                    symbolName: binaryBackedClassHit.className.split(".").at(-1) ?? binaryBackedClassHit.className,
-                    qualifiedName: binaryBackedClassHit.className,
-                    line: 1
-                }
-            };
-        const effectiveHits = binaryBackedHitRecord == null
-            ? search.hits
-            : [
-                binaryBackedHitRecord,
-                ...search.hits.filter((hit) => hit.filePath !== binaryBackedHitRecord.filePath)
-            ];
-        const sampledHits = capArray(effectiveHits, 5);
-        const isAutoSeparatorMiss = effectiveHits.length === 0 &&
-            queryMode === "auto" &&
-            /[._$]/.test(searchSubject.query);
-        const literalRetrySubject = subject.kind === "search"
-            ? {
-                ...subject,
-                queryMode: "literal"
-            }
-            : {
-                ...subject,
-                focus: {
-                    ...searchSubject,
-                    kind: "search",
-                    queryMode: "literal"
-                }
-            };
-        const summary = {
-            status: effectiveHits.length > 0 ? "ok" : "not_found",
-            headline: effectiveHits.length > 0
-                ? `Found ${effectiveHits.length} source hits for ${searchSubject.query}.`
-                : `No source hits were found for ${searchSubject.query}.`,
-            subject: createSummarySubject({
-                task: "search",
-                requested: requestedSubject,
-                query: searchSubject.query,
-                artifactId: artifact.artifactId
-            }),
-            counts: {
-                hits: effectiveHits.length
-            },
-            nextActions: nextActionsOrUndefined([
-                ...(effectiveHits.length > 0
-                    ? [
-                        createNextAction("inspect-minecraft", {
-                            task: "file",
-                            subject: {
-                                kind: "file",
-                                filePath: effectiveHits[0].filePath,
-                                artifact: {
-                                    type: "resolved-id",
-                                    artifactId: artifact.artifactId
-                                }
-                            },
-                            include: ["source"]
-                        })
-                    ]
-                    : []),
-                ...(isAutoSeparatorMiss
-                    ? [
-                        createNextAction("inspect-minecraft", {
-                            task: "search",
-                            subject: literalRetrySubject
-                        })
-                    ]
-                    : [])
-            ]),
-            ...(isAutoSeparatorMiss
-                ? {
-                    notes: [
-                        "Separator query returned no indexed hits. Retry with queryMode=\"literal\" for an explicit full substring scan."
-                    ]
-                }
-                : binaryBackedClassHit
-                    ? {
-                        notes: [
-                            "Source coverage was partial, so inspect-minecraft returned a binary-backed class match for the vanilla symbol."
-                        ]
-                    }
-                    : {})
-        };
-        return {
-            ...buildEntryToolResult({
-                task: "search",
-                summary,
-                detail,
-                include,
-                blocks: {
-                    subject: {
-                        requested: requestedSubject,
-                        resolved: {
-                            artifactId: artifact.artifactId
-                        }
-                    },
-                    search: {
-                        query: searchSubject.query,
-                        hits: detail === "summary" ? sampledHits.items : effectiveHits,
-                        nextCursor: search.nextCursor
-                    }
-                },
-                alwaysBlocks: ["subject"]
-            }),
-            warnings: [...artifact.warnings, ...(binaryBackedClassHit?.warnings ?? [])]
-        };
-    }
-    async handleFile(subject, detail, include) {
-        if (subject.kind !== "file" && !(subject.kind === "workspace" && subject.focus?.kind === "file")) {
-            this.invalidTaskSubjectError("file", subject);
-        }
-        const fileSubject = subject.kind === "file" ? subject : this.requireWorkspaceFileFocus(subject);
-        const artifact = subject.kind === "file"
-            ? await this.resolveArtifactReference(subject, "file")
-            : await this.resolveWorkspaceArtifactReference(subject, fileSubject.artifact);
-        const file = await this.deps.getArtifactFile({
-            artifactId: artifact.artifactId,
-            filePath: fileSubject.filePath
-        });
-        const summary = {
-            status: "ok",
-            headline: `Read ${file.filePath}.`,
-            subject: createSummarySubject({
-                task: "file",
-                requested: subject,
-                filePath: file.filePath,
-                artifactId: artifact.artifactId
-            }),
-            counts: {
-                bytes: file.contentBytes
-            }
-        };
-        return {
-            ...buildEntryToolResult({
-                task: "file",
-                summary,
-                detail,
-                include,
-                blocks: {
-                    subject: {
-                        requested: subject,
-                        resolved: {
-                            artifactId: artifact.artifactId,
-                            filePath: file.filePath
-                        }
-                    },
-                    file: {
-                        filePath: file.filePath,
-                        contentBytes: file.contentBytes,
-                        truncated: file.truncated,
-                        content: include.includes("source") || detail !== "summary" ? file.content : undefined
-                    }
-                },
-                alwaysBlocks: ["subject"]
-            }),
-            warnings: [...artifact.warnings]
-        };
-    }
-    async handleListFiles(subject, detail, include, limit, cursor) {
-        const artifact = await this.resolveArtifactReference(subject, "list-files");
-        const files = await this.deps.listArtifactFiles({
-            artifactId: artifact.artifactId,
-            limit,
-            cursor
-        });
-        const sampled = capArray(files.items, 10);
-        const partialCoverage = subject.kind === "workspace" && hasPartialVanillaCoverage(artifact.artifact);
-        const nextActions = [
-            ...(files.items.length > 0
-                ? [
-                    createNextAction("inspect-minecraft", {
-                        task: "file",
-                        subject: {
-                            kind: "file",
-                            filePath: files.items[0],
-                            artifact: {
-                                type: "resolved-id",
-                                artifactId: artifact.artifactId
-                            }
-                        }
-                    })
-                ]
-                : []),
-            ...(partialCoverage
-                ? [
-                    createNextAction("inspect-minecraft", {
-                        task: "class-source",
-                        subject: {
-                            kind: "workspace",
-                            projectPath: subject.projectPath,
-                            mapping: subject.mapping,
-                            scope: subject.scope,
-                            preferProjectVersion: subject.preferProjectVersion,
-                            strictVersion: subject.strictVersion,
-                            focus: {
-                                kind: "class",
-                                className: "net.minecraft.world.item.Item"
-                            }
-                        }
-                    })
-                ]
-                : [])
-        ];
-        const summary = {
-            status: partialCoverage ? "partial" : "ok",
-            headline: `Listed ${files.items.length} files for ${artifact.artifactId}.`,
-            subject: createSummarySubject({
-                task: "list-files",
-                requested: subject,
-                artifactId: artifact.artifactId
-            }),
-            counts: {
-                files: files.items.length
-            },
-            nextActions: nextActionsOrUndefined(nextActions),
-            ...(partialCoverage
-                ? {
-                    notes: [
-                        "This listing is partial because the resolved source artifact does not contain net.minecraft entries."
-                    ]
-                }
-                : {})
-        };
-        return {
-            ...buildEntryToolResult({
-                task: "list-files",
-                summary,
-                detail,
-                include,
-                blocks: {
-                    subject: {
-                        requested: subject,
-                        resolved: {
-                            artifactId: artifact.artifactId
-                        }
-                    },
-                    files: {
-                        items: detail === "summary" ? sampled.items : files.items,
-                        nextCursor: files.nextCursor,
-                        ...(partialCoverage
-                            ? {
-                                coverage: {
-                                    sourceCoverage: "partial",
-                                    missingNamespaces: ["net.minecraft"]
-                                }
-                            }
-                            : {})
-                    }
-                },
-                alwaysBlocks: ["subject"]
-            }),
-            warnings: [...artifact.warnings, ...files.warnings]
-        };
-    }
 }
 //# sourceMappingURL=inspect-minecraft-service.js.map