@adhisang/minecraft-modding-mcp 5.0.0 → 6.0.0

package/dist/source-service.js

@@ -141,7 +141,15 @@ export class SourceService {
     }
     async checkSymbolExists(input) {
         const result = await this.mappingService.checkSymbolExists(input);
-        if (result.status !== "mapping_unavailable" ||
+        // On unobfuscated versions the mapping graph is empty, so the mapping service can
+        // only ever report symbols as missing. We then validate against runtime bytecode.
+        // Classes/fields surface as `mapping_unavailable` when the graph yields nothing, but
+        // a method query with a non-empty graph returns `not_found` (empty member lookup) —
+        // which previously skipped the runtime fallback and produced false negatives for
+        // methods that genuinely exist (B1). Treat `not_found` methods as fallback-eligible.
+        const fallbackEligible = result.status === "mapping_unavailable" ||
+            (result.status === "not_found" && input.kind === "method");
+        if (!fallbackEligible ||
             !isUnobfuscatedVersion(input.version) ||
             (input.sourceMapping !== "mojang" && input.sourceMapping !== "obfuscated")) {
             return result;

package/dist/stdio-supervisor.d.ts

@@ -90,8 +90,8 @@ export declare class StdioSupervisor {
     private readonly handleWorkerData;
     private readonly handleWorkerStdinError;
     private readonly handleWorkerStderr;
-    private readonly handleWorkerProcessError;
-    private readonly handleWorkerExit;
+    private handleWorkerProcessError;
+    private handleWorkerExit;
     private handleWorkerMessage;
     private applyStageUpdate;
     private handleWorkerReady;

package/dist/stdio-supervisor.js

@@ -408,6 +408,13 @@ export class StdioSupervisor {
         if (this.shuttingDown) {
             return;
         }
+        const stale = this.child;
+        if (stale) {
+            this.detachChild();
+            if (stale.exitCode === null) {
+                stale.kill("SIGTERM");
+            }
+        }
         const child = spawn(process.execPath, [...process.execArgv, this.entryFile], {
             env: {
                 ...process.env,
@@ -423,8 +430,8 @@ export class StdioSupervisor {
         child.stdout.on("data", this.handleWorkerData);
         child.stderr.on("data", this.handleWorkerStderr);
         child.stdin.on("error", this.handleWorkerStdinError);
-        child.once("error", this.handleWorkerProcessError);
-        child.once("exit", this.handleWorkerExit);
+        child.once("error", (error) => this.handleWorkerProcessError(child, error));
+        child.once("exit", (code, signal) => this.handleWorkerExit(child, code, signal));
         log("info", "supervisor.worker_spawn", { pid: child.pid });
     }
     handleWorkerData = (chunk) => {
@@ -455,10 +462,23 @@ export class StdioSupervisor {
             process.stderr.write(`${line}\n`);
         }
     };
-    handleWorkerProcessError = (error) => {
+    handleWorkerProcessError(child, error) {
         log("error", "supervisor.worker_process_error", { message: error.message });
-    };
-    handleWorkerExit = (code, signal) => {
+        if (child !== this.child) {
+            return;
+        }
+        if (child.exitCode === null && child.signalCode === null) {
+            child.kill("SIGTERM");
+        }
+        this.handleWorkerExit(child, null, null);
+    }
+    handleWorkerExit(child, code, signal) {
+        if (child !== this.child) {
+            if (child.exitCode === null && child.signalCode === null) {
+                child.kill("SIGTERM");
+            }
+            return;
+        }
         const childPid = this.child?.pid;
         this.detachChild();
         if (this.shuttingDown) {
@@ -472,7 +492,7 @@ export class StdioSupervisor {
         });
         this.failPendingRequestsOnWorkerExit({ code, signal });
         this.scheduleRestart();
-    };
+    }
     handleWorkerMessage(message) {
         debugSupervisor("worker_message", {
             hasMethod: "method" in message,
@@ -580,7 +600,7 @@ export class StdioSupervisor {
         }
     }
     failPendingRequestsOnWorkerExit(exit) {
-        const preservedInitializeKey = this.initializeRequest && !this.clientInitialized
+        const preservedInitializeKey = this.initializeRequest
             ? requestKey(this.initializeRequest.id)
             : undefined;
         const now = performance.now();
@@ -635,8 +655,8 @@ export class StdioSupervisor {
         child.stdout.off("data", this.handleWorkerData);
         child.stderr.off("data", this.handleWorkerStderr);
         child.stdin.off("error", this.handleWorkerStdinError);
-        child.off("error", this.handleWorkerProcessError);
-        child.off("exit", this.handleWorkerExit);
+        child.removeAllListeners("error");
+        child.removeAllListeners("exit");
         this.child = undefined;
         this.childReady = false;
     }

package/dist/storage/db.js

@@ -14,7 +14,7 @@ function runIntegrityCheck(db) {
         throw createError({
             code: ERROR_CODES.DB_FAILURE,
             message: "SQLite integrity check failed.",
-            details: { integrityCheck: result }
+            details: { reason: "integrity_check_failed", integrityCheck: result }
         });
     }
 }
@@ -47,6 +47,22 @@ function isSchemaVersionMismatchError(error) {
     return (error.details?.reason === "schema_version_unsupported" ||
         error.details?.reason === "schema_version_invalid");
 }
+const SQLITE_CORRUPT_ERRCODE = 11;
+const SQLITE_NOTADB_ERRCODE = 26;
+function isCorruptionError(error) {
+    if (isAppError(error)) {
+        return (error.code === ERROR_CODES.DB_FAILURE && error.details?.reason === "integrity_check_failed");
+    }
+    const sqliteError = error;
+    if (sqliteError?.code === "SQLITE_CORRUPT" || sqliteError?.code === "SQLITE_NOTADB") {
+        return true;
+    }
+    if (typeof sqliteError?.errcode !== "number") {
+        return false;
+    }
+    const primaryErrcode = sqliteError.errcode & 0xff;
+    return primaryErrcode === SQLITE_CORRUPT_ERRCODE || primaryErrcode === SQLITE_NOTADB_ERRCODE;
+}
 function buildDefaultLogger() {
     return {
         warn: (message, details) => {
@@ -104,6 +120,13 @@ export function openDatabase(config, logger = buildDefaultLogger()) {
             throw caughtError;
         }
         if (!isMissingPath(config.sqlitePath)) {
+            if (!isCorruptionError(caughtError)) {
+                logger.error("SQLite initialization failed", {
+                    path: config.sqlitePath,
+                    reason: errorMessage
+                });
+                throw caughtError;
+            }
             const backupPath = backupCorruptedDb(config.sqlitePath);
             logger.warn("SQLite database integrity check failed. Recreated database after backup", {
                 sqlitePath: config.sqlitePath,

package/dist/storage/files-repo.d.ts

@@ -51,7 +51,10 @@ export declare class FilesRepo {
     private readonly searchFtsStmt;
     private readonly getByPathsStmtCache;
     private readonly classLookupStmtCache;
+    private readonly dynamicStmtCache;
+    private static readonly DYNAMIC_STMT_CACHE_MAX;
     constructor(db: SqliteDatabase);
+    private prepareCached;
     clearFilesForArtifact(artifactId: string): void;
     insertFilesForArtifact(artifactId: string, files: IndexedFile[]): void;
     replaceFilesForArtifact(artifactId: string, files: IndexedFile[]): void;

package/dist/storage/files-repo.js

@@ -67,18 +67,21 @@ function parseSearchCursor(cursor) {
         });
     }
 }
-function nextCursorFromRows(rows) {
-    if (rows.length === 0) {
+function nextCursorFromRows(rows, limit) {
+    if (rows.length === 0 || rows.length < limit) {
         return undefined;
     }
     const last = rows[rows.length - 1];
     return buildCursor(last.file_path);
 }
+function compareFilePaths(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
 function compareSearchOrdering(left, right) {
     if (right.score !== left.score) {
         return right.score - left.score;
     }
-    return left.filePath.localeCompare(right.filePath);
+    return compareFilePaths(left.filePath, right.filePath);
 }
 function isAfterSearchCursor(hit, cursor) {
     if (hit.score < cursor.score) {
@@ -87,7 +90,7 @@ function isAfterSearchCursor(hit, cursor) {
     if (hit.score > cursor.score) {
         return false;
     }
-    return hit.filePath.localeCompare(cursor.filePath) > 0;
+    return compareFilePaths(hit.filePath, cursor.filePath) > 0;
 }
 function buildPreview(content, query) {
     const normalizedQuery = query.toLowerCase();
@@ -137,6 +140,10 @@ export class FilesRepo {
     searchFtsStmt;
     getByPathsStmtCache = new Map();
     classLookupStmtCache = new Map();
+    // Fixed-SQL statements built outside the constructor; cached (LRU by SQL text)
+    // so hot paths do not re-prepare per call.
+    dynamicStmtCache = new Map();
+    static DYNAMIC_STMT_CACHE_MAX = 64;
     constructor(db) {
         this.db = db;
         this.deleteStmt = this.db.prepare(`
@@ -155,14 +162,14 @@ export class FilesRepo {
         this.listStmt = this.db.prepare(`
       SELECT artifact_id, file_path
       FROM files
-      WHERE artifact_id = ? AND file_path > ? AND (? IS NULL OR file_path LIKE ? || '%')
+      WHERE artifact_id = ? AND file_path > ? AND (? IS NULL OR file_path LIKE ? ESCAPE '\\')
       ORDER BY file_path ASC
       LIMIT ?
     `);
         this.listRowsStmt = this.db.prepare(`
       SELECT artifact_id, file_path, content, content_bytes, content_hash
       FROM files
-      WHERE artifact_id = ? AND file_path > ? AND (? IS NULL OR file_path LIKE ? || '%')
+      WHERE artifact_id = ? AND file_path > ? AND (? IS NULL OR file_path LIKE ? ESCAPE '\\')
       ORDER BY file_path ASC
       LIMIT ?
     `);
@@ -188,6 +195,23 @@ export class FilesRepo {
       LIMIT ?
     `);
     }
+    prepareCached(sql) {
+        const cached = this.dynamicStmtCache.get(sql);
+        if (cached) {
+            // Refresh recency so hot statements survive eviction.
+            this.dynamicStmtCache.delete(sql);
+            this.dynamicStmtCache.set(sql, cached);
+            return cached;
+        }
+        const stmt = this.db.prepare(sql);
+        this.dynamicStmtCache.set(sql, stmt);
+        if (this.dynamicStmtCache.size > FilesRepo.DYNAMIC_STMT_CACHE_MAX) {
+            const oldest = this.dynamicStmtCache.keys().next().value;
+            if (oldest !== undefined)
+                this.dynamicStmtCache.delete(oldest);
+        }
+        return stmt;
+    }
     clearFilesForArtifact(artifactId) {
         this.deleteStmt.run([artifactId]);
     }
@@ -231,15 +255,15 @@ export class FilesRepo {
     }
     listFiles(artifactId, options) {
         const cursor = parseCursor(options.cursor);
-        const rows = this.listStmt.all(artifactId, cursor?.sortKey ?? "", options.prefix ?? null, options.prefix ?? "", Math.max(1, options.limit));
+        const rows = this.listStmt.all(artifactId, cursor?.sortKey ?? "", options.prefix ?? null, options.prefix != null ? `${escapeLikeNeedle(options.prefix)}%` : "", Math.max(1, options.limit));
         return {
             items: rows.map((row) => row.file_path),
-            nextCursor: nextCursorFromRows(rows)
+            nextCursor: nextCursorFromRows(rows, Math.max(1, options.limit))
         };
     }
     listFileRows(artifactId, options) {
         const cursor = parseCursor(options.cursor);
-        const rows = this.listRowsStmt.all(artifactId, cursor?.sortKey ?? "", options.prefix ?? null, options.prefix ?? "", Math.max(1, options.limit));
+        const rows = this.listRowsStmt.all(artifactId, cursor?.sortKey ?? "", options.prefix ?? null, options.prefix != null ? `${escapeLikeNeedle(options.prefix)}%` : "", Math.max(1, options.limit));
         return {
             items: rows.map((row) => ({
                 artifactId: row.artifact_id,
@@ -248,7 +272,7 @@ export class FilesRepo {
                 contentBytes: row.content_bytes,
                 contentHash: row.content_hash
             })),
-            nextCursor: nextCursorFromRows(rows)
+            nextCursor: nextCursorFromRows(rows, Math.max(1, options.limit))
         };
     }
     /**
@@ -288,7 +312,7 @@ export class FilesRepo {
             return { items: [], nextCursor: undefined, scannedRows: 0, dbRoundtrips: 0 };
         }
         const cursor = parseSearchCursor(options.cursor);
-        const likeQuery = `%${normalized}%`;
+        const likeQuery = `%${escapeLikeNeedle(normalized)}%`;
         const ftsQuery = buildIndexedMatchQuery(normalized, options.match);
         const mode = options.mode ?? "mixed";
         // Cursor-adaptive fetch limit: when no cursor, use a generous limit;
@@ -298,28 +322,11 @@ export class FilesRepo {
         const fetchLimit = baseFetchLimit;
         // When cursor score is below all possible bands, skip both queries
         const cursorExhausted = cursor != null && cursor.score < 100;
-        // Skip path query entirely when cursor is within the content-only tier
-        const cursorPastPath = cursor != null && cursor.score < 120;
-        const includePath = mode !== "text" && !cursorExhausted && !cursorPastPath;
+        const includePath = mode !== "text" && !cursorExhausted;
         const includeContent = mode !== "path" && !cursorExhausted;
-        // Path query: push cursor into SQL when cursor.score == 120 (within path tier)
-        let pathRows;
-        if (includePath && cursor && cursor.score === 120) {
-            // Cursor is within the path tier — only fetch paths after cursor.filePath
-            pathRows = this.db.prepare(`
-        SELECT file_path
-        FROM files
-        WHERE artifact_id = ? AND file_path LIKE ? ESCAPE '\\' AND file_path > ?
-        ORDER BY file_path ASC
-        LIMIT ?
-      `).all(artifactId, likeQuery, cursor.filePath, fetchLimit);
-        }
-        else if (includePath) {
-            pathRows = this.searchPathStmt.all(artifactId, likeQuery, fetchLimit);
-        }
-        else {
-            pathRows = [];
-        }
+        const pathRows = includePath
+            ? this.searchPathStmt.all(artifactId, likeQuery, fetchLimit)
+            : [];
         const merged = pathRows.map((row) => ({
             filePath: row.file_path,
             score: 120,
@@ -417,7 +424,7 @@ export class FilesRepo {
             return 0;
         }
         try {
-            const row = this.db.prepare(`SELECT COUNT(*) AS cnt FROM files_fts WHERE artifact_id = ? AND files_fts MATCH ?`).get(artifactId, ftsQuery);
+            const row = this.prepareCached(`SELECT COUNT(*) AS cnt FROM files_fts WHERE artifact_id = ? AND files_fts MATCH ?`).get(artifactId, ftsQuery);
             return row?.cnt ?? 0;
         }
         catch {
@@ -433,8 +440,8 @@ export class FilesRepo {
         if (!normalized) {
             return 0;
         }
-        const likeQuery = `%${normalized}%`;
-        const row = this.db.prepare(`SELECT COUNT(*) AS cnt FROM files WHERE artifact_id = ? AND file_path LIKE ? ESCAPE '\\'`).get(artifactId, likeQuery);
+        const likeQuery = `%${escapeLikeNeedle(normalized)}%`;
+        const row = this.prepareCached(`SELECT COUNT(*) AS cnt FROM files WHERE artifact_id = ? AND file_path LIKE ? ESCAPE '\\'`).get(artifactId, likeQuery);
         return row?.cnt ?? 0;
     }
     findFirstFilePathByName(artifactId, fileName) {
@@ -442,8 +449,7 @@ export class FilesRepo {
         if (!normalized) {
             return undefined;
         }
-        const row = this.db
-            .prepare(`
+        const row = this.prepareCached(`
         SELECT file_path
         FROM files
         WHERE artifact_id = ?

package/dist/storage/symbols-repo.d.ts

@@ -46,12 +46,21 @@ export declare class SymbolsRepo {
     private readonly listByArtifactStmt;
     private readonly listByArtifactKindStmt;
     private readonly listByFileStmt;
+    private readonly dynamicStmtCache;
+    private static readonly DYNAMIC_STMT_CACHE_MAX;
     constructor(db: SqliteDatabase);
+    private prepareCached;
     clearSymbolsForArtifact(artifactId: string): void;
     insertSymbolsForArtifact(artifactId: string, symbols: IndexedSymbol[]): void;
     replaceSymbolsForArtifact(artifactId: string, symbols: IndexedSymbol[]): void;
     findSymbols(options: FindSymbolsOptions): PagedResult<SymbolRow>;
     listSymbolsForArtifact(artifactId: string, symbolKind?: string): SymbolRow[];
+    /**
+     * Streaming variant of listSymbolsForArtifact: rows are mapped lazily so callers
+     * that filter (e.g. regex symbol search) never materialize the full symbol set.
+     * Do not run other statements on this connection while consuming the iterator.
+     */
+    iterateSymbolsForArtifact(artifactId: string, symbolKind?: string): IterableIterator<SymbolRow>;
     listSymbolsForFile(artifactId: string, filePath: string): SymbolRow[];
     listSymbolsForFiles(artifactId: string, filePaths: string[], symbolKind?: string): Map<string, SymbolRow[]>;
     findBySymbolNames(artifactId: string, symbolNames: string[]): SymbolRow[];

package/dist/storage/symbols-repo.js

@@ -60,6 +60,10 @@ export class SymbolsRepo {
     listByArtifactStmt;
     listByArtifactKindStmt;
     listByFileStmt;
+    // Dynamic WHERE-clause builders produce a small bounded set of SQL strings;
+    // cache their prepared statements (LRU by SQL text) instead of re-preparing per call.
+    dynamicStmtCache = new Map();
+    static DYNAMIC_STMT_CACHE_MAX = 64;
     constructor(db) {
         this.db = db;
         this.deleteStmt = this.db.prepare(`
@@ -106,6 +110,23 @@ export class SymbolsRepo {
       ORDER BY line ASC, symbol_name ASC
     `);
     }
+    prepareCached(sql) {
+        const cached = this.dynamicStmtCache.get(sql);
+        if (cached) {
+            // Refresh recency so hot statements survive eviction.
+            this.dynamicStmtCache.delete(sql);
+            this.dynamicStmtCache.set(sql, cached);
+            return cached;
+        }
+        const stmt = this.db.prepare(sql);
+        this.dynamicStmtCache.set(sql, stmt);
+        if (this.dynamicStmtCache.size > SymbolsRepo.DYNAMIC_STMT_CACHE_MAX) {
+            const oldest = this.dynamicStmtCache.keys().next().value;
+            if (oldest !== undefined)
+                this.dynamicStmtCache.delete(oldest);
+        }
+        return stmt;
+    }
     clearSymbolsForArtifact(artifactId) {
         this.deleteStmt.run([artifactId]);
     }
@@ -150,7 +171,7 @@ export class SymbolsRepo {
         LIMIT ?
       `;
             const nameParam = options.exact ? symbolName : `${symbolName}%`;
-            rows = this.db.prepare(sql).all(options.artifactId, options.symbolKind ?? "", options.symbolKind ?? "", nameParam, cursor.symbolName, cursor.symbolName, cursor.filePath, cursor.symbolName, cursor.filePath, cursor.line, Math.max(1, fetchLimit));
+            rows = this.prepareCached(sql).all(options.artifactId, options.symbolKind ?? "", options.symbolKind ?? "", nameParam, cursor.symbolName, cursor.symbolName, cursor.filePath, cursor.symbolName, cursor.filePath, cursor.line, Math.max(1, fetchLimit));
         }
         else {
             const queryRows = options.exact ? this.searchExactStmt : this.searchStmt;
@@ -173,16 +194,26 @@ export class SymbolsRepo {
         };
     }
     listSymbolsForArtifact(artifactId, symbolKind) {
+        return [...this.iterateSymbolsForArtifact(artifactId, symbolKind)];
+    }
+    /**
+     * Streaming variant of listSymbolsForArtifact: rows are mapped lazily so callers
+     * that filter (e.g. regex symbol search) never materialize the full symbol set.
+     * Do not run other statements on this connection while consuming the iterator.
+     */
+    *iterateSymbolsForArtifact(artifactId, symbolKind) {
         const rows = (symbolKind
-            ? this.listByArtifactKindStmt.all(artifactId, symbolKind)
-            : this.listByArtifactStmt.all(artifactId));
-        return rows.map((row) => toSymbolRow(artifactId, {
-            filePath: row.file_path,
-            symbolKind: row.symbol_kind,
-            symbolName: row.symbol_name,
-            qualifiedName: row.qualified_name ?? undefined,
-            line: row.line
-        }));
+            ? this.listByArtifactKindStmt.iterate(artifactId, symbolKind)
+            : this.listByArtifactStmt.iterate(artifactId));
+        for (const row of rows) {
+            yield toSymbolRow(artifactId, {
+                filePath: row.file_path,
+                symbolKind: row.symbol_kind,
+                symbolName: row.symbol_name,
+                qualifiedName: row.qualified_name ?? undefined,
+                line: row.line
+            });
+        }
     }
     listSymbolsForFile(artifactId, filePath) {
         const rows = this.listByFileStmt.all(artifactId, filePath);
@@ -209,7 +240,7 @@ export class SymbolsRepo {
       ORDER BY file_path ASC, line ASC, symbol_name ASC
     `;
         const params = symbolKind ? [artifactId, ...uniqueFilePaths, symbolKind] : [artifactId, ...uniqueFilePaths];
-        const rows = this.db.prepare(sql).all(...params);
+        const rows = this.prepareCached(sql).all(...params);
         const byFile = new Map();
         for (const row of rows) {
             const bucket = byFile.get(row.file_path) ?? [];
@@ -230,8 +261,7 @@ export class SymbolsRepo {
             return [];
         }
         const placeholders = unique.map(() => "?").join(", ");
-        const rows = this.db
-            .prepare(`
+        const rows = this.prepareCached(`
         SELECT file_path, symbol_kind, symbol_name, qualified_name, line
         FROM symbols
         WHERE artifact_id = ?
@@ -306,7 +336,7 @@ export class SymbolsRepo {
       ORDER BY symbol_name ASC, file_path ASC, line ASC
       LIMIT ?
     `;
-        const rows = this.db.prepare(sql).all(...params);
+        const rows = this.prepareCached(sql).all(...params);
         const hasMore = rows.length > rawLimit;
         const page = hasMore ? rows.slice(0, rawLimit) : rows;
         const lastRow = page.length > 0 ? page[page.length - 1] : undefined;
@@ -360,12 +390,11 @@ export class SymbolsRepo {
       WHERE artifact_id = ?
       ${where.length > 0 ? `AND ${where.join("\n      AND ")}` : ""}
     `;
-        const row = this.db.prepare(sql).get(...params);
+        const row = this.prepareCached(sql).get(...params);
         return row?.cnt ?? 0;
     }
     listDistinctFilePathsByKind(artifactId, symbolKind) {
-        const rows = this.db
-            .prepare(`
+        const rows = this.prepareCached(`
         SELECT DISTINCT file_path
         FROM symbols
         WHERE artifact_id = ? AND symbol_kind = ?
@@ -380,8 +409,7 @@ export class SymbolsRepo {
         if (!normalizedClassName || !normalizedSimpleName) {
             return undefined;
         }
-        const row = this.db
-            .prepare(`
+        const row = this.prepareCached(`
         SELECT file_path
         FROM symbols
         WHERE artifact_id = ?

package/dist/symbols/symbol-extractor.js

@@ -1,7 +1,7 @@
 // A type token may carry spaced generics (Map<String, Integer>), arrays (int[][]),
 // wildcards (List<? extends Foo>), and FQNs (java.util.Map). It must not contain "=".
 const TYPE_TOKEN = "[\\w.$][\\w.$<>\\[\\],?\\s]*";
-const MODIFIER = "(?:public|private|protected|abstract|final|static|native|synchronized|default|strictfp|transient|volatile)";
+const MODIFIER = "(?:public|private|protected|abstract|final|static|native|synchronized|default|strictfp|transient|volatile|sealed|non-sealed)";
 const MODIFIER_OR_ANNOTATION_RUN = `(?:(?:@[\\w.]+|${MODIFIER})\\s+)*`;
 const TYPE_PARAMS = "(?:<[^>]+>\\s*)?";
 const THROWS_CLAUSE = "(?:\\s+throws\\s+[\\w.$,\\s]+)?";

package/dist/tool-guidance.d.ts

@@ -6,7 +6,8 @@ export type ToolMeta = {
     requestId: string;
     tool: string;
     durationMs: number;
-    warnings: string[];
+    /** Omitted entirely when there are no warnings (token efficiency). */
+    warnings?: string[];
     /** Structured companion to `warnings`: one classified entry per warning string, referencing its text via `warnings[detail.index]`. */
     warningDetails?: WarningDetail[];
     detailApplied?: "summary" | "standard" | "full";

package/dist/tool-guidance.js

@@ -317,7 +317,22 @@ export function buildValidateMixinSuggestedParams(normalizedInput) {
             version
         };
     }
-    const path = asNonEmptyString(inputRecord?.path) ??
+    if (inputRecord?.mode === "project") {
+        const projectInputPath = asNonEmptyString(inputRecord.path);
+        if (projectInputPath) {
+            return {
+                ...shared,
+                input: {
+                    mode: "project",
+                    path: projectInputPath
+                },
+                version
+            };
+        }
+    }
+    const path = (inputRecord?.mode === "path" || inputRecord?.mode === undefined
+        ? asNonEmptyString(inputRecord?.path)
+        : undefined) ??
         asNonEmptyString(record.sourcePath);
     if (path) {
         return {
@@ -600,6 +615,16 @@ export function buildValidateProjectSuggestedParams(normalizedInput) {
         return result;
     }
     const inputRecord = asObjectRecord(subjectRecord?.input) ?? asObjectRecord(record.input);
+    if (task === "access-transformer") {
+        result.subject = {
+            kind: "access-transformer",
+            input: inputRecord ?? {
+                mode: "inline",
+                content: "<access transformer contents>"
+            }
+        };
+        return result;
+    }
     result.subject = {
         kind: "access-widener",
         input: inputRecord ?? {

package/dist/tool-schemas.d.ts

@@ -211,11 +211,11 @@ export declare const sourceLookupTargetSchema: z.ZodDiscriminatedUnion<"kind", [
     kind: "artifact";
     artifactId: string;
 }>]>;
-export declare const RESOLVE_ARTIFACT_TARGET_DESCRIPTION = "Object with kind. Examples: {\"kind\":\"version\",\"value\":\"1.21.10\"}, {\"kind\":\"workspace\"} (uses projectPath), or {\"kind\":\"dependency\",\"group\":\"dev.architectury\",\"name\":\"architectury\"}. Must be an object, not a string.";
-export declare const SOURCE_LOOKUP_TARGET_DESCRIPTION = "Object with kind (same shape as resolve-artifact). Examples: {\"kind\":\"version\",\"value\":\"1.21.10\"}, {\"kind\":\"workspace\"} (uses projectPath), {\"kind\":\"dependency\",\"group\":\"...\",\"name\":\"...\"}, or {\"kind\":\"artifact\",\"artifactId\":\"...\"} to reuse an already-resolved artifact. Must be an object, not a string.";
-export declare const SOURCE_SCOPE_DESCRIPTION = "vanilla = Mojang client jar only; merged = source-oriented merged runtime discovery; loader = loader/runtime artifact discovery when the workspace exposes transformed runtime jars.";
+export declare const RESOLVE_ARTIFACT_TARGET_DESCRIPTION = "Object, not string. e.g. {\"kind\":\"version\",\"value\":\"1.21.10\"}, {\"kind\":\"workspace\"}, {\"kind\":\"dependency\",\"group\":\"g\",\"name\":\"n\"}.";
+export declare const SOURCE_LOOKUP_TARGET_DESCRIPTION = "Same shape as resolve-artifact target, plus {\"kind\":\"artifact\",\"artifactId\":\"...\"} to reuse a resolved artifact. Object, not string.";
+export declare const SOURCE_SCOPE_DESCRIPTION = "vanilla = Mojang client jar only; merged = merged runtime discovery; loader = loader-transformed runtime jars.";
 export declare const SIGNATURE_MODE_DESCRIPTION = "exact: descriptor required for kind=method; name-only (default): match by owner+name only.";
-export declare const NAME_MODE_DESCRIPTION = "auto (default): accept a fully-qualified name, or a dotless name where the tool allows it; fqcn: require a fully-qualified name.";
+export declare const NAME_MODE_DESCRIPTION = "auto (default): FQCN, or dotless name where allowed; fqcn: require FQCN.";
 export declare const listVersionsShape: {
     includeSnapshots: z.ZodDefault<z.ZodBoolean>;
     limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;