@adhisang/minecraft-modding-mcp 4.2.1 → 5.0.0

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

@@ -11,7 +11,7 @@ import { handleClassMembers } from "./inspect-minecraft/handlers/class-members.j
 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 INCLUDE_GROUPS = ["warnings", "provenance", "candidates", "members", "descriptors", "source", "files", "samples", "artifact", "timings"];
 const nonEmptyString = z.string().trim().min(1);
 export const inspectMinecraftShape = {
     task: z.enum(TASKS).optional(),

package/dist/entry-tools/manage-cache-service.d.ts

@@ -82,9 +82,9 @@ export declare const manageCacheSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     limit: number;
     executionMode: "preview" | "apply";
-    action: "list" | "summary" | "inspect" | "verify" | "delete" | "prune" | "rebuild";
+    action: "summary" | "list" | "inspect" | "verify" | "delete" | "prune" | "rebuild";
     cursor?: string | undefined;
-    detail?: "full" | "summary" | "standard" | undefined;
+    detail?: "summary" | "standard" | "full" | undefined;
     include?: string[] | undefined;
     cacheKinds?: ("workspace" | "artifact-index" | "downloads" | "mapping" | "registry" | "decompiled-source" | "mod-remap" | "binary-remap")[] | undefined;
     selector?: {
@@ -99,10 +99,10 @@ export declare const manageCacheSchema: z.ZodObject<{
         olderThan?: string | undefined;
     } | undefined;
 }, {
-    action: "list" | "summary" | "inspect" | "verify" | "delete" | "prune" | "rebuild";
+    action: "summary" | "list" | "inspect" | "verify" | "delete" | "prune" | "rebuild";
     limit?: number | undefined;
     cursor?: string | undefined;
-    detail?: "full" | "summary" | "standard" | undefined;
+    detail?: "summary" | "standard" | "full" | undefined;
     include?: string[] | undefined;
     executionMode?: "preview" | "apply" | undefined;
     cacheKinds?: ("workspace" | "artifact-index" | "downloads" | "mapping" | "registry" | "decompiled-source" | "mod-remap" | "binary-remap")[] | undefined;

package/dist/entry-tools/response-contract.d.ts

@@ -1,6 +1,6 @@
 export declare const DETAIL_LEVELS: readonly ["summary", "standard", "full"];
 export type DetailLevel = (typeof DETAIL_LEVELS)[number];
-export declare const CANONICAL_INCLUDE_GROUPS: readonly ["warnings", "provenance", "candidates", "members", "source", "files", "samples", "diff", "issues", "timeline", "matrix", "entries", "workspace", "health", "recovery", "paths", "owners", "preview", "cacheEntries", "timings", "artifact", "classes", "registry"];
+export declare const CANONICAL_INCLUDE_GROUPS: readonly ["warnings", "provenance", "candidates", "members", "descriptors", "source", "files", "samples", "diff", "issues", "timeline", "matrix", "entries", "workspace", "health", "recovery", "paths", "owners", "preview", "cacheEntries", "timings", "artifact", "classes", "registry"];
 export type IncludeGroup = (typeof CANONICAL_INCLUDE_GROUPS)[number];
 export type SummaryStatus = "ok" | "partial" | "ambiguous" | "not_found" | "invalid" | "blocked" | "changed" | "unchanged";
 export type NextAction = {

package/dist/entry-tools/response-contract.js

@@ -4,6 +4,7 @@ export const CANONICAL_INCLUDE_GROUPS = [
     "provenance",
     "candidates",
     "members",
+    "descriptors",
     "source",
     "files",
     "samples",

package/dist/entry-tools/validate-project/cases/mixin.js

@@ -48,7 +48,8 @@ export async function handleMixin(deps, input, detail, include) {
         warningMode: input.warningMode,
         warningCategoryFilter: input.warningCategoryFilter,
         treatInfoAsWarning: input.treatInfoAsWarning,
-        includeIssues: input.includeIssues
+        includeIssues: input.includeIssues,
+        reportMode: input.reportMode
     });
     const summary = output.summary;
     const invalidCount = summary?.invalid ?? 0;

package/dist/entry-tools/validate-project/cases/project-summary.js

@@ -45,12 +45,13 @@ export async function handleProjectSummary(deps, input, detail, include, options
                         tool: "validate-project",
                         params: {
                             task: "project-summary",
-                            subject: input.subject
+                            subject: input.subject,
+                            preferProjectVersion: true
                         }
                     }
                 ],
                 notes: [
-                    "Pass version explicitly, or retry with preferProjectVersion=true when gradle.properties declares the Minecraft version."
+                    "Pass version explicitly, or retry with preferProjectVersion=true when gradle.properties declares the Minecraft version. The suggested retry sets preferProjectVersion=true for you."
                 ]
             },
             blocks: {
@@ -225,7 +226,8 @@ export async function handleProjectSummary(deps, input, detail, include, options
                 warningMode: input.warningMode,
                 warningCategoryFilter: input.warningCategoryFilter,
                 treatInfoAsWarning: input.treatInfoAsWarning,
-                includeIssues: input.includeIssues
+                includeIssues: input.includeIssues,
+                reportMode: input.reportMode
             }, {
                 stageEmitter: wrappedEmitter
             });

package/dist/entry-tools/validate-project-service.d.ts

@@ -57,13 +57,13 @@ export declare const validateProjectShape: {
     }, "strip", z.ZodTypeAny, {
         kind: "workspace";
         projectPath: string;
-        gradleUserHome?: string | undefined;
         discover?: ("mixins" | "access-wideners" | "access-transformers")[] | undefined;
+        gradleUserHome?: string | undefined;
     }, {
         kind: "workspace";
         projectPath: string;
-        gradleUserHome?: string | undefined;
         discover?: ("mixins" | "access-wideners" | "access-transformers")[] | undefined;
+        gradleUserHome?: string | undefined;
     }>, z.ZodObject<{
         kind: z.ZodLiteral<"mixin">;
         input: z.ZodDiscriminatedUnion<"mode", [z.ZodObject<{
@@ -245,6 +245,7 @@ export declare const validateProjectShape: {
     warningCategoryFilter: z.ZodOptional<z.ZodArray<z.ZodEnum<["mapping", "configuration", "validation", "resolution", "parse"]>, "many">>;
     treatInfoAsWarning: z.ZodDefault<z.ZodBoolean>;
     includeIssues: z.ZodDefault<z.ZodBoolean>;
+    reportMode: z.ZodDefault<z.ZodEnum<["compact", "full", "summary-first"]>>;
 };
 export declare const validateProjectSchema: z.ZodEffects<z.ZodObject<{
     task: z.ZodEnum<["project-summary", "mixin", "access-widener", "access-transformer"]>;
@@ -256,13 +257,13 @@ export declare const validateProjectSchema: z.ZodEffects<z.ZodObject<{
     }, "strip", z.ZodTypeAny, {
         kind: "workspace";
         projectPath: string;
-        gradleUserHome?: string | undefined;
         discover?: ("mixins" | "access-wideners" | "access-transformers")[] | undefined;
+        gradleUserHome?: string | undefined;
     }, {
         kind: "workspace";
         projectPath: string;
-        gradleUserHome?: string | undefined;
         discover?: ("mixins" | "access-wideners" | "access-transformers")[] | undefined;
+        gradleUserHome?: string | undefined;
     }>, z.ZodObject<{
         kind: z.ZodLiteral<"mixin">;
         input: z.ZodDiscriminatedUnion<"mode", [z.ZodObject<{
@@ -444,19 +445,21 @@ export declare const validateProjectSchema: z.ZodEffects<z.ZodObject<{
     warningCategoryFilter: z.ZodOptional<z.ZodArray<z.ZodEnum<["mapping", "configuration", "validation", "resolution", "parse"]>, "many">>;
     treatInfoAsWarning: z.ZodDefault<z.ZodBoolean>;
     includeIssues: z.ZodDefault<z.ZodBoolean>;
+    reportMode: z.ZodDefault<z.ZodEnum<["compact", "full", "summary-first"]>>;
 }, "strip", z.ZodTypeAny, {
-    minSeverity: "all" | "error" | "warning";
     hideUncertain: boolean;
     explain: boolean;
     preferProjectMapping: boolean;
+    minSeverity: "all" | "error" | "warning";
+    reportMode: "full" | "summary-first" | "compact";
     treatInfoAsWarning: boolean;
     includeIssues: boolean;
-    task: "mixin" | "project-summary" | "access-widener" | "access-transformer";
+    task: "project-summary" | "mixin" | "access-widener" | "access-transformer";
     subject: {
         kind: "workspace";
         projectPath: string;
-        gradleUserHome?: string | undefined;
         discover?: ("mixins" | "access-wideners" | "access-transformers")[] | undefined;
+        gradleUserHome?: string | undefined;
     } | {
         kind: "mixin";
         input: {
@@ -497,22 +500,22 @@ export declare const validateProjectSchema: z.ZodEffects<z.ZodObject<{
     version?: string | undefined;
     mapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
     scope?: "vanilla" | "merged" | "loader" | undefined;
-    sourcePriority?: "loom-first" | "maven-first" | undefined;
-    sourceRoots?: string[] | undefined;
     preferProjectVersion?: boolean | undefined;
+    sourcePriority?: "loom-first" | "maven-first" | undefined;
     warningMode?: "full" | "aggregated" | undefined;
+    sourceRoots?: string[] | undefined;
     warningCategoryFilter?: ("mapping" | "parse" | "validation" | "configuration" | "resolution")[] | undefined;
     configPaths?: string[] | undefined;
-    atNamespace?: "obfuscated" | "mojang" | "srg" | undefined;
-    detail?: "full" | "summary" | "standard" | undefined;
+    detail?: "summary" | "standard" | "full" | undefined;
     include?: string[] | undefined;
+    atNamespace?: "obfuscated" | "mojang" | "srg" | undefined;
 }, {
-    task: "mixin" | "project-summary" | "access-widener" | "access-transformer";
+    task: "project-summary" | "mixin" | "access-widener" | "access-transformer";
     subject: {
         kind: "workspace";
         projectPath: string;
-        gradleUserHome?: string | undefined;
         discover?: ("mixins" | "access-wideners" | "access-transformers")[] | undefined;
+        gradleUserHome?: string | undefined;
     } | {
         kind: "mixin";
         input: {
@@ -553,34 +556,36 @@ export declare const validateProjectSchema: z.ZodEffects<z.ZodObject<{
     version?: string | undefined;
     mapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
     scope?: "vanilla" | "merged" | "loader" | undefined;
-    sourcePriority?: "loom-first" | "maven-first" | undefined;
-    sourceRoots?: string[] | undefined;
     preferProjectVersion?: boolean | undefined;
-    minSeverity?: "all" | "error" | "warning" | undefined;
     hideUncertain?: boolean | undefined;
     explain?: boolean | undefined;
-    warningMode?: "full" | "aggregated" | undefined;
     preferProjectMapping?: boolean | undefined;
-    warningCategoryFilter?: ("mapping" | "parse" | "validation" | "configuration" | "resolution")[] | undefined;
+    minSeverity?: "all" | "error" | "warning" | undefined;
+    reportMode?: "full" | "summary-first" | "compact" | undefined;
     treatInfoAsWarning?: boolean | undefined;
     includeIssues?: boolean | undefined;
+    sourcePriority?: "loom-first" | "maven-first" | undefined;
+    warningMode?: "full" | "aggregated" | undefined;
+    sourceRoots?: string[] | undefined;
+    warningCategoryFilter?: ("mapping" | "parse" | "validation" | "configuration" | "resolution")[] | undefined;
     configPaths?: string[] | undefined;
-    atNamespace?: "obfuscated" | "mojang" | "srg" | undefined;
-    detail?: "full" | "summary" | "standard" | undefined;
+    detail?: "summary" | "standard" | "full" | undefined;
     include?: string[] | undefined;
+    atNamespace?: "obfuscated" | "mojang" | "srg" | undefined;
 }>, {
-    minSeverity: "all" | "error" | "warning";
     hideUncertain: boolean;
     explain: boolean;
     preferProjectMapping: boolean;
+    minSeverity: "all" | "error" | "warning";
+    reportMode: "full" | "summary-first" | "compact";
     treatInfoAsWarning: boolean;
     includeIssues: boolean;
-    task: "mixin" | "project-summary" | "access-widener" | "access-transformer";
+    task: "project-summary" | "mixin" | "access-widener" | "access-transformer";
     subject: {
         kind: "workspace";
         projectPath: string;
-        gradleUserHome?: string | undefined;
         discover?: ("mixins" | "access-wideners" | "access-transformers")[] | undefined;
+        gradleUserHome?: string | undefined;
     } | {
         kind: "mixin";
         input: {
@@ -621,22 +626,22 @@ export declare const validateProjectSchema: z.ZodEffects<z.ZodObject<{
     version?: string | undefined;
     mapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
     scope?: "vanilla" | "merged" | "loader" | undefined;
-    sourcePriority?: "loom-first" | "maven-first" | undefined;
-    sourceRoots?: string[] | undefined;
     preferProjectVersion?: boolean | undefined;
+    sourcePriority?: "loom-first" | "maven-first" | undefined;
     warningMode?: "full" | "aggregated" | undefined;
+    sourceRoots?: string[] | undefined;
     warningCategoryFilter?: ("mapping" | "parse" | "validation" | "configuration" | "resolution")[] | undefined;
     configPaths?: string[] | undefined;
-    atNamespace?: "obfuscated" | "mojang" | "srg" | undefined;
-    detail?: "full" | "summary" | "standard" | undefined;
+    detail?: "summary" | "standard" | "full" | undefined;
     include?: string[] | undefined;
+    atNamespace?: "obfuscated" | "mojang" | "srg" | undefined;
 }, {
-    task: "mixin" | "project-summary" | "access-widener" | "access-transformer";
+    task: "project-summary" | "mixin" | "access-widener" | "access-transformer";
     subject: {
         kind: "workspace";
         projectPath: string;
-        gradleUserHome?: string | undefined;
         discover?: ("mixins" | "access-wideners" | "access-transformers")[] | undefined;
+        gradleUserHome?: string | undefined;
     } | {
         kind: "mixin";
         input: {
@@ -677,21 +682,22 @@ export declare const validateProjectSchema: z.ZodEffects<z.ZodObject<{
     version?: string | undefined;
     mapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
     scope?: "vanilla" | "merged" | "loader" | undefined;
-    sourcePriority?: "loom-first" | "maven-first" | undefined;
-    sourceRoots?: string[] | undefined;
     preferProjectVersion?: boolean | undefined;
-    minSeverity?: "all" | "error" | "warning" | undefined;
     hideUncertain?: boolean | undefined;
     explain?: boolean | undefined;
-    warningMode?: "full" | "aggregated" | undefined;
     preferProjectMapping?: boolean | undefined;
-    warningCategoryFilter?: ("mapping" | "parse" | "validation" | "configuration" | "resolution")[] | undefined;
+    minSeverity?: "all" | "error" | "warning" | undefined;
+    reportMode?: "full" | "summary-first" | "compact" | undefined;
     treatInfoAsWarning?: boolean | undefined;
     includeIssues?: boolean | undefined;
+    sourcePriority?: "loom-first" | "maven-first" | undefined;
+    warningMode?: "full" | "aggregated" | undefined;
+    sourceRoots?: string[] | undefined;
+    warningCategoryFilter?: ("mapping" | "parse" | "validation" | "configuration" | "resolution")[] | undefined;
     configPaths?: string[] | undefined;
-    atNamespace?: "obfuscated" | "mojang" | "srg" | undefined;
-    detail?: "full" | "summary" | "standard" | undefined;
+    detail?: "summary" | "standard" | "full" | undefined;
     include?: string[] | undefined;
+    atNamespace?: "obfuscated" | "mojang" | "srg" | undefined;
 }>;
 export type ValidateProjectInput = z.infer<typeof validateProjectSchema>;
 export type ValidateProjectExecuteOptions = {

package/dist/entry-tools/validate-project-service.js

@@ -67,7 +67,9 @@ export const validateProjectShape = {
     warningMode: z.enum(["full", "aggregated"]).optional(),
     warningCategoryFilter: z.array(z.enum(["mapping", "configuration", "validation", "resolution", "parse"])).optional(),
     treatInfoAsWarning: z.boolean().default(true),
-    includeIssues: z.boolean().default(true)
+    includeIssues: z.boolean().default(true),
+    reportMode: z.enum(["compact", "full", "summary-first"]).default("summary-first")
+        .describe("Mixin report shape forwarded to validate-mixin. Default 'summary-first'; pass 'full' (or explain=true) for per-result resolvedMembers/toolHealth/resolutionTrace.")
 };
 export const validateProjectSchema = z.object(validateProjectShape).superRefine((value, ctx) => {
     if (value.task === "project-summary" && value.subject.kind !== "workspace") {

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

@@ -14,6 +14,7 @@ export type VerifyMixinTargetInput = {
     };
     mixinMemberName?: string;
     mapping?: SourceMapping;
+    autoRemap?: boolean;
     sourcePriority?: MappingSourcePriority;
     projectPath?: string;
     gradleUserHome?: string;
@@ -91,6 +92,7 @@ export type VerifyMixinTargetDeps = {
         artifactId: string;
         mappingApplied: SourceMapping;
         binaryJarPath?: string;
+        version?: string;
         provenance?: ArtifactProvenance;
         warnings?: string[];
     }>;
@@ -101,11 +103,39 @@ export type VerifyMixinTargetDeps = {
         includeSynthetic: boolean;
         includeInherited: boolean;
     }) => Promise<ExplorerSignatureOutput>;
+    /**
+     * Optional mapping translator used by autoRemap to convert owner/member names
+     * from the request namespace into the artifact namespace. When absent,
+     * autoRemap is unavailable and a namespace mismatch surfaces as an error.
+     */
+    findMapping?: (input: {
+        version: string;
+        kind: "class" | "field" | "method";
+        name: string;
+        owner?: string;
+        descriptor?: string;
+        sourceMapping: SourceMapping;
+        targetMapping: SourceMapping;
+    }) => Promise<{
+        resolved: boolean;
+        resolvedSymbol?: {
+            name: string;
+            owner?: string;
+            descriptor?: string;
+        };
+    }>;
 };
 export declare class VerifyMixinTargetService {
     private readonly deps;
     constructor(deps: VerifyMixinTargetDeps);
     execute(input: VerifyMixinTargetInput): Promise<VerifyMixinTargetOutput>;
+    /**
+     * Translate owner + member from the request namespace into the artifact
+     * namespace via find-mapping, so a caller looking at yarn/intermediary
+     * sources can verify against an obfuscated artifact in one call. Throws a
+     * namespace-mismatch (or invalid-input) error when translation is impossible.
+     */
+    private applyAutoRemap;
 }
 export declare const verifyMixinTargetMemberSchemaExport: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
     kind: z.ZodLiteral<"method">;

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

@@ -166,14 +166,15 @@ export class VerifyMixinTargetService {
                 details: { fieldErrors: [{ path: "target", message: "target is required" }] }
             });
         }
-        const owner = input.owner.trim();
+        let owner = input.owner.trim();
         if (!owner) {
             throw createError({
                 code: ERROR_CODES.INVALID_INPUT,
                 message: "owner must be non-empty."
             });
         }
-        const memberName = input.member.name.trim();
+        let member = input.member;
+        let memberName = member.name.trim();
         if (!memberName) {
             throw createError({
                 code: ERROR_CODES.INVALID_INPUT,
@@ -192,21 +193,29 @@ export class VerifyMixinTargetService {
         });
         const warnings = [...(resolved.warnings ?? [])];
         if (input.mapping && input.mapping !== resolved.mappingApplied) {
-            throw createError({
-                code: ERROR_CODES.NAMESPACE_MISMATCH,
-                message: `verify-mixin-target requires owner and member.name to be in the artifact's namespace `
-                    + `("${resolved.mappingApplied}"), but the request supplied mapping="${input.mapping}". `
-                    + `Automatic name/descriptor translation is not yet supported; supply owner+member in the artifact namespace, `
-                    + `or omit the mapping argument so the resolver picks the namespace automatically.`,
-                details: {
-                    owner,
-                    requestedMapping: input.mapping,
-                    mappingApplied: resolved.mappingApplied,
-                    artifactId: resolved.artifactId,
-                    nextAction: `Retry with mapping="${resolved.mappingApplied}" and owner/member translated to that namespace, `
-                        + `or use find-mapping to translate before calling verify-mixin-target.`
-                }
-            });
+            if (input.autoRemap) {
+                const remapped = await this.applyAutoRemap(input, resolved, owner, member, warnings);
+                owner = remapped.owner;
+                member = remapped.member;
+                memberName = member.name;
+            }
+            else {
+                throw createError({
+                    code: ERROR_CODES.NAMESPACE_MISMATCH,
+                    message: `verify-mixin-target requires owner and member.name to be in the artifact's namespace `
+                        + `("${resolved.mappingApplied}"), but the request supplied mapping="${input.mapping}". `
+                        + `Set autoRemap=true to translate names automatically, supply owner+member in the artifact namespace, `
+                        + `or omit the mapping argument so the resolver picks the namespace automatically.`,
+                    details: {
+                        owner,
+                        requestedMapping: input.mapping,
+                        mappingApplied: resolved.mappingApplied,
+                        artifactId: resolved.artifactId,
+                        nextAction: `Retry with autoRemap=true, or with mapping="${resolved.mappingApplied}" and owner/member already in that namespace, `
+                            + `or use find-mapping to translate before calling verify-mixin-target.`
+                    }
+                });
+            }
         }
         if (!resolved.binaryJarPath) {
             throw createError({
@@ -248,15 +257,15 @@ export class VerifyMixinTargetService {
             throw error;
         }
         warnings.push(...(signature.warnings ?? []));
-        const memberPool = input.member.kind === "method"
+        const memberPool = member.kind === "method"
             ? [...signature.constructors, ...signature.methods]
             : [...signature.fields];
         const allMemberNames = memberPool.map((m) => m.name);
         const exactNameHits = memberPool.filter((m) => m.name === memberName);
         let matches;
         let candidates = [];
-        if (input.member.descriptor) {
-            const descriptorHits = exactNameHits.filter((m) => m.jvmDescriptor === input.member.descriptor);
+        if (member.descriptor) {
+            const descriptorHits = exactNameHits.filter((m) => m.jvmDescriptor === member.descriptor);
             if (descriptorHits.length > 0) {
                 matches = descriptorHits.map(buildMatch);
             }
@@ -265,7 +274,7 @@ export class VerifyMixinTargetService {
                 candidates = exactNameHits.map((m) => ({
                     name: m.name,
                     descriptor: m.jvmDescriptor,
-                    reason: `name match, descriptor ${m.jvmDescriptor} differs from requested ${input.member.descriptor}`
+                    reason: `name match, descriptor ${m.jvmDescriptor} differs from requested ${member.descriptor}`
                 }));
             }
         }
@@ -285,7 +294,7 @@ export class VerifyMixinTargetService {
         const exists = matches.length > 0;
         let accessorAdvice;
         if (matches.length === 1) {
-            accessorAdvice = inferAnnotation(input.member, matches[0], input.mixinMemberName);
+            accessorAdvice = inferAnnotation(member, matches[0], input.mixinMemberName);
         }
         return {
             exists,
@@ -306,6 +315,88 @@ export class VerifyMixinTargetService {
             }
         };
     }
+    /**
+     * Translate owner + member from the request namespace into the artifact
+     * namespace via find-mapping, so a caller looking at yarn/intermediary
+     * sources can verify against an obfuscated artifact in one call. Throws a
+     * namespace-mismatch (or invalid-input) error when translation is impossible.
+     */
+    async applyAutoRemap(input, resolved, owner, member, warnings) {
+        const sourceMapping = input.mapping;
+        const targetMapping = resolved.mappingApplied;
+        const mismatchDetails = {
+            owner,
+            member: member.name,
+            requestedMapping: sourceMapping,
+            mappingApplied: targetMapping,
+            artifactId: resolved.artifactId
+        };
+        if (!this.deps.findMapping) {
+            throw createError({
+                code: ERROR_CODES.NAMESPACE_MISMATCH,
+                message: `autoRemap is unavailable (no mapping translator configured); supply owner/member in the artifact namespace ("${targetMapping}").`,
+                details: mismatchDetails
+            });
+        }
+        const version = resolved.version ?? (input.target?.kind === "version" ? input.target.value : undefined);
+        if (!version) {
+            throw createError({
+                code: ERROR_CODES.INVALID_INPUT,
+                message: `autoRemap needs a Minecraft version to translate names; use target.kind="version" or a workspace that resolves one.`,
+                details: mismatchDetails
+            });
+        }
+        const classResult = await this.deps.findMapping({
+            version,
+            kind: "class",
+            name: owner,
+            sourceMapping,
+            targetMapping
+        });
+        if (!classResult.resolved || !classResult.resolvedSymbol) {
+            throw createError({
+                code: ERROR_CODES.NAMESPACE_MISMATCH,
+                message: `autoRemap could not translate owner "${owner}" from ${sourceMapping} to ${targetMapping}.`,
+                details: {
+                    ...mismatchDetails,
+                    nextAction: `Confirm "${owner}" exists in ${sourceMapping} for ${version}, or supply owner/member already in ${targetMapping}.`
+                }
+            });
+        }
+        const translatedOwner = classResult.resolvedSymbol.name;
+        // Look the member up by its source-namespace owner so find-mapping can
+        // locate it, then take the translated name/descriptor.
+        const memberResult = await this.deps.findMapping({
+            version,
+            kind: member.kind,
+            name: member.name,
+            owner,
+            descriptor: member.descriptor,
+            sourceMapping,
+            targetMapping
+        });
+        if (!memberResult.resolved || !memberResult.resolvedSymbol) {
+            throw createError({
+                code: ERROR_CODES.NAMESPACE_MISMATCH,
+                message: `autoRemap could not translate ${member.kind} "${member.name}" of "${owner}" from ${sourceMapping} to ${targetMapping}.`,
+                details: mismatchDetails
+            });
+        }
+        // Use the translated (target-namespace) descriptor only. Never fall back to
+        // the request descriptor: it is still in the source namespace and would
+        // never match the artifact's jvmDescriptor, turning a real member into a
+        // false exists=false. When no descriptor could be translated, match by name.
+        const translatedDescriptor = memberResult.resolvedSymbol.descriptor;
+        if (member.descriptor && !translatedDescriptor) {
+            warnings.push(`autoRemap could not translate the descriptor for ${member.kind} "${member.name}" into ${targetMapping}; matching by name only.`);
+        }
+        const translatedMember = (member.kind === "method"
+            ? { kind: "method", name: memberResult.resolvedSymbol.name, ...(translatedDescriptor ? { descriptor: translatedDescriptor } : {}) }
+            : { kind: "field", name: memberResult.resolvedSymbol.name, ...(translatedDescriptor ? { descriptor: translatedDescriptor } : {}) });
+        warnings.push(`autoRemap translated the target from ${sourceMapping} to ${targetMapping} (artifact namespace): `
+            + `${owner}#${member.name} -> ${translatedOwner}#${translatedMember.name}.`);
+        return { owner: translatedOwner, member: translatedMember };
+    }
 }
 const memberDescriptorSchema = z.string().trim().min(1).optional();
 const verifyMixinTargetMemberSchema = z.discriminatedUnion("kind", [

package/dist/error-mapping.d.ts

@@ -13,6 +13,31 @@ export type ExampleCall = {
     params: Record<string, unknown>;
     reason: string;
 };
+/**
+ * Whether retrying the same call can help, and why if not:
+ * - `transient`: a temporary failure (network, rate limit, timeout); retrying
+ *   the same call later may succeed.
+ * - `permanent`: the requested thing does not exist or cannot be produced;
+ *   retrying the same call will keep failing.
+ * - `server`: a non-recoverable internal server fault (programming bug, DB
+ *   corruption); retrying the identical call cannot help. Distinct from
+ *   `permanent`, which is about an absent/unproducible target rather than a
+ *   server defect. Treat like `permanent` for retry posture (do not retry).
+ * - `environment`: the server lacks a capability (Java, decompiler, remapper);
+ *   retrying will not help until the environment is fixed.
+ * - `input`: the caller's input is wrong; fix the input, then retry.
+ */
+export type RetryClass = "transient" | "permanent" | "server" | "environment" | "input";
+/**
+ * Where the failure originates, so an agent knows whether to fix its own
+ * request or stop retrying this tool:
+ * - `code_issue`: the caller's input is wrong or names something that does not
+ *   exist; fix the request.
+ * - `tool_issue`: the tool could not produce a result for valid input (mapping
+ *   gap, upstream fetch, internal limit).
+ * - `environment`: a server capability is missing (Java, decompiler, remapper).
+ */
+export type IssueOrigin = "code_issue" | "tool_issue" | "environment";
 export type ProblemDetails = {
     type: string;
     title: string;
@@ -20,13 +45,39 @@ export type ProblemDetails = {
     status: number;
     code: string;
     instance: string;
+    retryClass: RetryClass;
+    issueOrigin: IssueOrigin;
     fieldErrors?: ProblemFieldError[];
     hints?: string[];
     suggestedCall?: SuggestedCall;
     exampleCalls?: ExampleCall[];
     failedStage?: string;
+    context?: Record<string, string | number | boolean>;
 };
 export declare function statusForErrorCode(code: string): number;
+/**
+ * Single source of truth mapping an error code to its {@link RetryClass}. Used
+ * by every public problem builder so callers can branch on recovery strategy
+ * without parsing prose. Non-recoverable server faults (`ERR_INTERNAL`,
+ * `ERR_DB_FAILURE`) classify as `server`. Codes not explicitly classified
+ * (genuinely-transient failures such as `ERR_REPO_FETCH_FAILED` and unknown
+ * codes) default to `transient`: a temporary failure where one retry is
+ * reasonable.
+ */
+export declare function retryClassForErrorCode(code: string): RetryClass;
+/**
+ * Single source of truth mapping an error code to its {@link IssueOrigin}.
+ * Environment failures reuse the retry classifier; the input-family above is
+ * `code_issue`; everything else is a `tool_issue` (valid input the tool could
+ * not satisfy).
+ */
+export declare function issueOriginForErrorCode(code: string): IssueOrigin;
+/**
+ * Pick the allowlisted, primitive-valued fields out of an AppError's `details`
+ * so the public envelope can carry structured repair context without leaking
+ * paths, parser internals, or other sensitive data.
+ */
+export declare function extractAllowlistedContext(details: unknown): Record<string, string | number | boolean> | undefined;
 /**
  * Per-entry subset of `mapErrorToProblem` for batch tools. ZodErrors are not
  * handled here (per-entry input has already cleared the batch tool's schema