@adhisang/minecraft-modding-mcp 3.0.0 → 3.1.1

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

@@ -1,7 +1,7 @@
 import { z } from "zod";
-import { createError, ERROR_CODES } from "../errors.js";
+import { createError, ERROR_CODES, isAppError } from "../errors.js";
 import { buildIncludeSchema, detailSchema, positiveIntSchema } from "./entry-tool-schema.js";
-import { buildEntryToolResult, buildEntryToolMeta, createNextAction, createTruncationMeta } from "./response-contract.js";
+import { buildEntryToolResult, buildEntryToolMeta, createNextAction, createSummarySubject, createTruncationMeta } from "./response-contract.js";
 import { capArray, nextActionsOrUndefined, resolveDetail, resolveInclude } from "./request-normalizers.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"];
@@ -41,7 +41,7 @@ const workspaceFocusSchema = z.discriminatedUnion("kind", [
         symbolKind: z.enum(["class", "interface", "enum", "record", "method", "field"]).optional(),
         packagePrefix: nonEmptyString.optional(),
         fileGlob: nonEmptyString.optional(),
-        queryMode: z.enum(["auto", "token", "literal"]).optional()
+        queryMode: z.enum(["auto", "token", "literal"]).default("auto")
     })
 ]);
 const subjectSchema = z.discriminatedUnion("kind", [
@@ -87,7 +87,7 @@ const subjectSchema = z.discriminatedUnion("kind", [
         symbolKind: z.enum(["class", "interface", "enum", "record", "method", "field"]).optional(),
         packagePrefix: nonEmptyString.optional(),
         fileGlob: nonEmptyString.optional(),
-        queryMode: z.enum(["auto", "token", "literal"]).optional()
+        queryMode: z.enum(["auto", "token", "literal"]).default("auto")
     }),
     z.object({
         kind: z.literal("workspace"),
@@ -102,7 +102,7 @@ const subjectSchema = z.discriminatedUnion("kind", [
 export const inspectMinecraftShape = {
     task: z.enum(TASKS).optional(),
     subject: subjectSchema.optional(),
-    includeSnapshots: z.boolean().optional(),
+    includeSnapshots: z.boolean().default(false),
     detail: detailSchema.optional(),
     include: buildIncludeSchema(INCLUDE_GROUPS),
     limit: positiveIntSchema.optional(),
@@ -116,7 +116,7 @@ export const inspectMinecraftSchema = z.object(inspectMinecraftShape).superRefin
             message: "subject is required unless task=versions."
         });
     }
-    if (value.includeSnapshots !== undefined && value.task && value.task !== "versions") {
+    if (value.includeSnapshots && value.task && value.task !== "versions") {
         ctx.addIssue({
             code: z.ZodIssueCode.custom,
             path: ["includeSnapshots"],
@@ -124,6 +124,32 @@ 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) {
@@ -200,11 +226,11 @@ export class InspectMinecraftService {
             strictVersion: subject.strictVersion
         };
     }
-    async resolveClassArtifactReference(subject, classSubject) {
+    async resolveClassArtifactReference(subject, classSubject, task) {
         if (subject.kind === "workspace") {
             return this.resolveWorkspaceArtifactReference(subject, classSubject.artifact);
         }
-        return this.resolveArtifactReference(classSubject);
+        return this.resolveArtifactReference(classSubject, task);
     }
     async resolveWorkspaceArtifactReference(subject, artifactRef) {
         if (!artifactRef) {
@@ -260,15 +286,150 @@ export class InspectMinecraftService {
                 return "search";
         }
     }
-    async resolveArtifactReference(subject) {
+    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.`
+                    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);
@@ -341,6 +502,12 @@ export class InspectMinecraftService {
         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
@@ -379,6 +546,10 @@ export class InspectMinecraftService {
             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",
@@ -408,6 +579,12 @@ export class InspectMinecraftService {
         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
             }
@@ -443,18 +620,20 @@ export class InspectMinecraftService {
     }
     async handleClassOverview(subject, detail, include) {
         if (subject.kind !== "class" && !(subject.kind === "workspace" && subject.focus?.kind === "class")) {
-            throw createError({
-                code: ERROR_CODES.INVALID_INPUT,
-                message: "class-overview requires a class or workspace focus subject."
-            });
+            this.invalidTaskSubjectError("class-overview", subject);
         }
         const classSubject = this.buildClassSubject(subject);
         const className = classSubject.className;
-        const artifact = await this.resolveClassArtifactReference(subject, classSubject);
+        const artifact = await this.resolveClassArtifactReference(subject, classSubject, "class-overview");
         if (!artifact.artifactId) {
             const summary = {
                 status: "blocked",
-                headline: `Could not resolve artifact context for ${className}.`
+                headline: `Could not resolve artifact context for ${className}.`,
+                subject: createSummarySubject({
+                    task: "class-overview",
+                    requested: subject,
+                    className
+                })
             };
             return {
                 ...buildEntryToolResult({
@@ -478,9 +657,78 @@ export class InspectMinecraftService {
             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}.`
+                headline: `No class match was found for ${className}.`,
+                subject: createSummarySubject({
+                    task: "class-overview",
+                    requested: subject,
+                    className,
+                    artifactId: artifact.artifactId
+                })
             };
             return {
                 ...buildEntryToolResult({
@@ -517,6 +765,12 @@ export class InspectMinecraftService {
             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
                 },
@@ -551,6 +805,12 @@ export class InspectMinecraftService {
         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
             },
@@ -604,14 +864,11 @@ export class InspectMinecraftService {
     }
     async handleClassSource(subject, detail, include) {
         if (subject.kind !== "class" && !(subject.kind === "workspace" && subject.focus?.kind === "class")) {
-            throw createError({
-                code: ERROR_CODES.INVALID_INPUT,
-                message: "class-source requires a class or workspace focus subject."
-            });
+            this.invalidTaskSubjectError("class-source", subject);
         }
         const classSubject = this.buildClassSubject(subject);
         const className = classSubject.className;
-        const artifactContext = await this.resolveClassArtifactReference(subject, classSubject);
+        const artifactContext = await this.resolveClassArtifactReference(subject, classSubject, "class-source");
         const source = await this.deps.getClassSource({
             className,
             artifactId: artifactContext.artifactId || undefined,
@@ -625,6 +882,12 @@ export class InspectMinecraftService {
         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
             }
@@ -658,13 +921,10 @@ export class InspectMinecraftService {
     }
     async handleClassMembers(subject, detail, include, limit) {
         if (subject.kind !== "class" && !(subject.kind === "workspace" && subject.focus?.kind === "class")) {
-            throw createError({
-                code: ERROR_CODES.INVALID_INPUT,
-                message: "class-members requires a class or workspace focus subject."
-            });
+            this.invalidTaskSubjectError("class-members", subject);
         }
         const classSubject = this.buildClassSubject(subject);
-        const artifact = await this.resolveClassArtifactReference(subject, classSubject);
+        const artifact = await this.resolveClassArtifactReference(subject, classSubject, "class-members");
         const members = await this.deps.getClassMembers({
             className: classSubject.className,
             artifactId: artifact.artifactId || undefined,
@@ -678,6 +938,12 @@ export class InspectMinecraftService {
         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 {
@@ -727,21 +993,20 @@ export class InspectMinecraftService {
     }
     async handleSearch(subject, detail, include, limit, cursor) {
         if (subject.kind !== "search" && !(subject.kind === "workspace" && subject.focus?.kind === "search")) {
-            throw createError({
-                code: ERROR_CODES.INVALID_INPUT,
-                message: "search requires a search or workspace focus subject."
-            });
+            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)
+            ? 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: searchSubject.queryMode,
+            queryMode,
             limit,
             cursor,
             scope: searchSubject.packagePrefix || searchSubject.fileGlob || searchSubject.symbolKind
@@ -752,15 +1017,106 @@ export class InspectMinecraftService {
                 }
                 : undefined
         });
-        const sampledHits = capArray(search.hits, 5);
+        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: search.hits.length > 0 ? "ok" : "not_found",
-            headline: search.hits.length > 0
-                ? `Found ${search.hits.length} source hits for ${searchSubject.query}.`
+            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: search.hits.length
-            }
+                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({
@@ -770,32 +1126,29 @@ export class InspectMinecraftService {
                 include,
                 blocks: {
                     subject: {
-                        requested: subject,
+                        requested: requestedSubject,
                         resolved: {
                             artifactId: artifact.artifactId
                         }
                     },
                     search: {
                         query: searchSubject.query,
-                        hits: detail === "summary" ? sampledHits.items : search.hits,
+                        hits: detail === "summary" ? sampledHits.items : effectiveHits,
                         nextCursor: search.nextCursor
                     }
                 },
                 alwaysBlocks: ["subject"]
             }),
-            warnings: [...artifact.warnings]
+            warnings: [...artifact.warnings, ...(binaryBackedClassHit?.warnings ?? [])]
         };
     }
     async handleFile(subject, detail, include) {
         if (subject.kind !== "file" && !(subject.kind === "workspace" && subject.focus?.kind === "file")) {
-            throw createError({
-                code: ERROR_CODES.INVALID_INPUT,
-                message: "file task requires a file or workspace focus subject."
-            });
+            this.invalidTaskSubjectError("file", subject);
         }
         const fileSubject = subject.kind === "file" ? subject : this.requireWorkspaceFileFocus(subject);
         const artifact = subject.kind === "file"
-            ? await this.resolveArtifactReference(subject)
+            ? await this.resolveArtifactReference(subject, "file")
             : await this.resolveWorkspaceArtifactReference(subject, fileSubject.artifact);
         const file = await this.deps.getArtifactFile({
             artifactId: artifact.artifactId,
@@ -804,6 +1157,12 @@ export class InspectMinecraftService {
         const summary = {
             status: "ok",
             headline: `Read ${file.filePath}.`,
+            subject: createSummarySubject({
+                task: "file",
+                requested: subject,
+                filePath: file.filePath,
+                artifactId: artifact.artifactId
+            }),
             counts: {
                 bytes: file.contentBytes
             }
@@ -835,19 +1194,69 @@ export class InspectMinecraftService {
         };
     }
     async handleListFiles(subject, detail, include, limit, cursor) {
-        const artifact = await this.resolveArtifactReference(subject);
+        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: "ok",
+            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({
@@ -864,7 +1273,15 @@ export class InspectMinecraftService {
                     },
                     files: {
                         items: detail === "summary" ? sampled.items : files.items,
-                        nextCursor: files.nextCursor
+                        nextCursor: files.nextCursor,
+                        ...(partialCoverage
+                            ? {
+                                coverage: {
+                                    sourceCoverage: "partial",
+                                    missingNamespaces: ["net.minecraft"]
+                                }
+                            }
+                            : {})
                     }
                 },
                 alwaysBlocks: ["subject"]