@adhisang/minecraft-modding-mcp 3.2.0 → 4.0.0

package/dist/mapping-pipeline-service.js

@@ -4,7 +4,8 @@ import { createError, ERROR_CODES } from "./errors.js";
  * Current implementation enforces explicit guarantees:
  * - obfuscated: always pass-through
  * - mojang: requires source-backed artifacts on legacy obfuscated versions,
- *   but unobfuscated runtime jars can pass through directly
+ *   but unobfuscated runtime jars can pass through directly,
+ *   or binary-only artifacts may be remapped + decompiled when allowBinaryRemap=true
  */
 export function applyMappingPipeline(input) {
     const transformChain = [];
@@ -51,6 +52,17 @@ export function applyMappingPipeline(input) {
     }
     const hasSource = Boolean(input.resolved.sourceJarPath);
     if (!hasSource) {
+        if (input.requestedMapping === "mojang" &&
+            input.allowBinaryRemap === true &&
+            Boolean(input.resolved.binaryJarPath)) {
+            transformChain.push("binary-remap:obf->mojang", "decompile:vineflower");
+            qualityFlags.push("binary-remapped", "decompiled");
+            return {
+                mappingApplied: "mojang",
+                qualityFlags,
+                transformChain
+            };
+        }
         throw createError({
             code: ERROR_CODES.MAPPING_NOT_APPLIED,
             message: `Requested ${input.requestedMapping} mapping cannot be guaranteed for this artifact because only decompile path is available.`,

package/dist/mapping-service.d.ts

@@ -148,6 +148,16 @@ export declare class MappingService {
     private readonly fetchFn;
     private readonly graphCache;
     private readonly buildLocks;
+    private readonly resolutionCache;
+    private static readonly RESOLUTION_CACHE_MAX;
+    private static readonly RESOLUTION_CACHE_TTL_MS;
+    private resolutionCacheHits;
+    private resolutionCacheMisses;
+    get resolutionCacheStats(): {
+        hits: number;
+        misses: number;
+        size: number;
+    };
     constructor(config: Config, versionService?: VersionMappingsResolver, fetchFn?: typeof fetch);
     findMapping(input: FindMappingInput): Promise<FindMappingOutput>;
     ensureMappingAvailable(input: EnsureMappingAvailableInput): Promise<EnsureMappingAvailableOutput>;
@@ -182,6 +192,8 @@ export declare class MappingService {
     private fetchYarnCoordinates;
     private trimGraphCache;
     releaseGraphCacheEntry(version: string, sourcePriority?: MappingSourcePriority): void;
+    private buildResolutionCacheKey;
+    private trimResolutionCache;
 }
 /**
  * Resolve and cache a Tiny v2 mapping file for the given Minecraft version.

package/dist/mapping-service.js

@@ -708,15 +708,93 @@ function normalizeMemberName(name) {
     }
     return normalized;
 }
+/**
+ * Validate a JVM method descriptor such as `(I)V`, `()Lfoo/Bar;`, `(Lfoo/Bar;[I)V`.
+ * Rejects empty strings, missing/mis-positioned parens, empty return type, and invalid base
+ * type tokens so "(" or "()" style half-descriptors surface as ERR_INVALID_INPUT instead of
+ * being silently accepted.
+ */
 function normalizeMethodDescriptor(descriptor) {
     const normalized = descriptor?.trim() ?? "";
-    if (!normalized || !normalized.startsWith("(") || !normalized.includes(")")) {
+    if (!normalized) {
+        throw invalidInputError("descriptor must be a valid JVM descriptor when kind=method.", {
+            descriptor
+        });
+    }
+    if (!isValidMethodDescriptor(normalized)) {
         throw invalidInputError("descriptor must be a valid JVM descriptor when kind=method.", {
             descriptor
         });
     }
     return normalized;
 }
+function isValidMethodDescriptor(descriptor) {
+    if (!descriptor.startsWith("("))
+        return false;
+    const closingIndex = descriptor.indexOf(")");
+    if (closingIndex < 0)
+        return false;
+    const argsSection = descriptor.slice(1, closingIndex);
+    const returnSection = descriptor.slice(closingIndex + 1);
+    if (returnSection.length === 0)
+        return false;
+    let cursor = 0;
+    while (cursor < argsSection.length) {
+        const next = consumeFieldType(argsSection, cursor, /*allowVoid*/ false);
+        if (next < 0)
+            return false;
+        cursor = next;
+    }
+    const returnEnd = consumeFieldType(returnSection, 0, /*allowVoid*/ true);
+    return returnEnd === returnSection.length;
+}
+/**
+ * JVM specification §4.3.2: "An array type descriptor is valid only if it represents a type
+ * with 255 or fewer dimensions." Matches the `multianewarray` / field-signature limit.
+ */
+const JVM_MAX_ARRAY_DIMENSIONS = 255;
+function consumeFieldType(descriptor, position, allowVoid) {
+    // Arrays are handled iteratively so pathological inputs such as `(` + "[".repeat(20000) + `I)V`
+    // cannot blow the call stack. After consuming every leading `[`, only the element type token
+    // is dispatched through the switch below. Dimensions above the JVM limit are rejected rather
+    // than merely accepted as "syntactically valid but semantically absurd" — clients must not be
+    // able to push a 20000-dimension descriptor through cache-key construction.
+    let cursor = position;
+    let arrayDimensions = 0;
+    while (cursor < descriptor.length && descriptor[cursor] === "[") {
+        cursor += 1;
+        arrayDimensions += 1;
+        if (arrayDimensions > JVM_MAX_ARRAY_DIMENSIONS)
+            return -1;
+    }
+    if (cursor >= descriptor.length)
+        return -1;
+    // Void is only valid at the outermost position — inside an array element it is illegal.
+    const elementAllowsVoid = cursor === position && allowVoid;
+    const token = descriptor[cursor];
+    switch (token) {
+        case "B":
+        case "C":
+        case "D":
+        case "F":
+        case "I":
+        case "J":
+        case "S":
+        case "Z":
+            return cursor + 1;
+        case "V":
+            return elementAllowsVoid ? cursor + 1 : -1;
+        case "L": {
+            const end = descriptor.indexOf(";", cursor);
+            // Reject empty class names like L; and unterminated references.
+            if (end < 0 || end === cursor + 1)
+                return -1;
+            return end + 1;
+        }
+        default:
+            return -1;
+    }
+}
 function normalizeQuerySymbol(input, signatureMode, options) {
     if (input.kind !== "class" && input.kind !== "field" && input.kind !== "method") {
         throw invalidInputError('kind must be one of "class", "field", or "method".', {
@@ -773,9 +851,19 @@ function normalizeQuerySymbol(input, signatureMode, options) {
             querySymbol: toSymbolReference(record)
         };
     }
-    const descriptor = signatureMode === "name-only"
-        ? (input.descriptor?.trim() || "")
-        : normalizeMethodDescriptor(input.descriptor);
+    let descriptor;
+    if (signatureMode === "name-only") {
+        // name-only matches by owner+name only; a supplied descriptor is validated (so malformed
+        // input still surfaces as ERR_INVALID_INPUT) but discarded afterwards so downstream
+        // projection / filtering treats the query as "no descriptor".
+        if (input.descriptor?.trim()) {
+            normalizeMethodDescriptor(input.descriptor);
+        }
+        descriptor = "";
+    }
+    else {
+        descriptor = normalizeMethodDescriptor(input.descriptor);
+    }
     const record = createMethodSymbolRecord(owner, normalizeMemberName(normalizedName), descriptor);
     return {
         record,
@@ -916,6 +1004,18 @@ export class MappingService {
     fetchFn;
     graphCache = new Map();
     buildLocks = new Map();
+    resolutionCache = new Map();
+    static RESOLUTION_CACHE_MAX = 512;
+    static RESOLUTION_CACHE_TTL_MS = 5 * 60 * 1000;
+    resolutionCacheHits = 0;
+    resolutionCacheMisses = 0;
+    get resolutionCacheStats() {
+        return {
+            hits: this.resolutionCacheHits,
+            misses: this.resolutionCacheMisses,
+            size: this.resolutionCache.size
+        };
+    }
     constructor(config, versionService = new VersionService(config), fetchFn = globalThis.fetch) {
         this.config = config;
         this.versionService = versionService;
@@ -932,9 +1032,25 @@ export class MappingService {
                 }
             });
         }
-        const { record: queryRecord, querySymbol } = normalizeQuerySymbol(input, input.signatureMode, {
+        // Normalize the effective signatureMode exactly once so every downstream path — query
+        // symbol normalization, the strict-overload filter, the cache key, and warning text —
+        // sees the same value. The public tool schema defaults to "name-only", so an omitted
+        // signatureMode reaching the service (e.g. internal callers, MCP resource handlers, the
+        // resolution cache) must default to "name-only" too, otherwise the service contradicts
+        // the advertised default and silently reverts to the old descriptor-required path.
+        // Callers that genuinely need strict descriptor matching pass `signatureMode: "exact"`
+        // explicitly.
+        const effectiveSignatureMode = input.signatureMode ?? "name-only";
+        const { record: queryRecord, querySymbol } = normalizeQuerySymbol(input, effectiveSignatureMode, {
             allowShortClassName: input.kind === "class" && input.sourceMapping === "obfuscated"
         });
+        const cacheKey = this.buildResolutionCacheKey(version, input, querySymbol, effectiveSignatureMode);
+        const cached = this.resolutionCache.get(cacheKey);
+        if (cached && Date.now() - cached.cachedAt < MappingService.RESOLUTION_CACHE_TTL_MS) {
+            this.resolutionCacheHits += 1;
+            return cached.result;
+        }
+        this.resolutionCacheMisses += 1;
         const sourceMapping = input.sourceMapping;
         const targetMapping = input.targetMapping;
         if (!SUPPORTED_MAPPINGS.has(sourceMapping) || !SUPPORTED_MAPPINGS.has(targetMapping)) {
@@ -992,13 +1108,51 @@ export class MappingService {
         const descriptorProjection = queryRecord.kind === "method" && queryRecord.descriptor
             ? this.projectMethodDescriptorToTarget(graph, path, queryRecord.descriptor)
             : undefined;
-        const projectedDescriptor = descriptorProjection?.complete ? descriptorProjection.descriptor : undefined;
-        const rawCandidates = this
+        // Partial projections are still useful for comparison: projectMethodDescriptorToTarget
+        // leaves unmapped `L...;` references unchanged, so JDK / external classes pass through
+        // while Minecraft class references get rewritten to the target namespace. Using the
+        // projected descriptor even when `complete === false` produces descriptors shaped like
+        // the stored records (`(Lnet/minecraft/class_1799;Ljava/lang/String;)V`) and avoids
+        // false negatives for the very common mixed MC + JDK descriptor shape.
+        const projectedDescriptor = descriptorProjection?.hadClassReferences ? descriptorProjection.descriptor : undefined;
+        let rawCandidates = this
             .mapCandidatesAlongPath(graph, path, queryRecord)
             .map((candidate) => queryRecord.kind === "method" && queryRecord.descriptor
             ? projectLookupCandidateDescriptor(candidate, queryRecord.descriptor, projectedDescriptor)
             : candidate);
         const warnings = [];
+        // signatureMode="exact" on kind=method must not return descriptorless fallback candidates
+        // (lookupCandidates adds owner+name fallbacks by design for the loose path). Without this
+        // filter a caller who supplied `foo(I)V` could be told `foo(Z)V` is the exact mapping,
+        // which would be wrong for migration tooling. Mirror resolveMethodMappingExact's strict
+        // behavior: keep only candidates whose descriptor equals the (projected) requested
+        // descriptor. If nothing passes, the normal "candidates.length === 0 -> not_found" path
+        // takes over. Partial projection is accepted here for the same reason as above — we do
+        // not reject mixed MC + JDK descriptors as mapping_unavailable just because the JDK
+        // class reference was not in the mapping graph.
+        if (queryRecord.kind === "method" &&
+            queryRecord.descriptor &&
+            effectiveSignatureMode === "exact") {
+            // Tiny v2 stores a single descriptor per method entry (typically in the obfuscated
+            // namespace) and shares it across every column, while client mappings attach a mojang
+            // descriptor on the mojang side and an obfuscated descriptor on the obfuscated side.
+            // In multi-hop paths (e.g. mojang -> obfuscated -> intermediary -> yarn) the final
+            // candidate's owner and name live in the target namespace but its descriptor can still
+            // be the obfuscated form that rode along the Tiny hop. A strict filter that compared
+            // only against the fully projected target descriptor dropped those valid candidates
+            // and produced false `not_found` for common Mojang -> Yarn lookups. Accept any
+            // candidate whose descriptor matches the caller's descriptor, the target-space
+            // projection, or the obfuscated-space projection — the three forms that actually
+            // appear in the mapping graph.
+            const strictDescriptor = projectedDescriptor ?? queryRecord.descriptor;
+            const acceptedDescriptors = new Set([queryRecord.descriptor, strictDescriptor]);
+            const toObfuscatedPath = namespacePath(graph, sourceMapping, "obfuscated");
+            if (toObfuscatedPath) {
+                const obfuscatedProjection = this.projectMethodDescriptorToTarget(graph, toObfuscatedPath, queryRecord.descriptor);
+                acceptedDescriptors.add(obfuscatedProjection.descriptor);
+            }
+            rawCandidates = rawCandidates.filter((candidate) => candidate.descriptor !== undefined && acceptedDescriptors.has(candidate.descriptor));
+        }
         const disambiguatedCandidates = applyDisambiguationHints(rawCandidates, input.disambiguation);
         if (rawCandidates.length > disambiguatedCandidates.length) {
             warnings.push(`Disambiguation hints narrowed candidates from ${rawCandidates.length} to ${disambiguatedCandidates.length}.`);
@@ -1016,12 +1170,21 @@ export class MappingService {
         }
         else if (candidates.length > 1) {
             warnings.push(`Ambiguous mapping: ${candidates.length} candidates matched. Provide a stricter symbol input or disambiguation hints.`);
+            if (queryRecord.kind === "method") {
+                // find-mapping defaults to signatureMode="name-only", which discards any supplied
+                // descriptor. Telling the caller to "add descriptor" would be ineffective unless they
+                // also switch mode, so we point to the exact alternatives instead.
+                warnings.push("Retry with signatureMode=\"exact\" plus a JVM descriptor, or pass disambiguation.descriptorHint, or raise maxCandidates up to 200 to inspect the full candidate list.");
+            }
+            else {
+                warnings.push("Raise maxCandidates up to 200 to inspect the full candidate list, or use disambiguation.ownerHint to narrow the search.");
+            }
         }
         const status = candidates.length === 0 ? "not_found" : candidates.length === 1 ? "resolved" : "ambiguous";
         const ambiguityReasons = candidates.length > 1
             ? inferAmbiguityReasons(candidates, pathUsesSource(graph.pairs, path, "mojang-client-mappings"))
             : undefined;
-        return {
+        const output = {
             querySymbol,
             mappingContext,
             resolved: status === "resolved",
@@ -1034,6 +1197,9 @@ export class MappingService {
             provenance: this.provenanceForPath(graph, path),
             ambiguityReasons
         };
+        this.resolutionCache.set(cacheKey, { result: output, cachedAt: Date.now() });
+        this.trimResolutionCache();
+        return output;
     }
     async ensureMappingAvailable(input) {
         const version = input.version.trim();
@@ -1193,6 +1359,9 @@ export class MappingService {
         }
         if (strictCandidates.length > 1) {
             warnings.push("Exact method mapping is ambiguous for owner+method+descriptor.");
+            if (limitedCandidates.candidatesTruncated) {
+                warnings.push("Raise maxCandidates up to 200 to inspect the full candidate list, or narrow the lookup via find-mapping disambiguation hints.");
+            }
             return {
                 querySymbol,
                 mappingContext,
@@ -1495,6 +1664,9 @@ export class MappingService {
         const buildOutput = (querySymbol, matched, status) => {
             const candidates = matched.map((record) => toResolutionCandidate(toLookupCandidate(record)));
             const limitedCandidates = limitResolutionCandidates(candidates, input.maxCandidates);
+            if (status === "ambiguous" && limitedCandidates.candidatesTruncated) {
+                warnings.push("Raise maxCandidates up to 200 to inspect the full candidate list.");
+            }
             return {
                 querySymbol,
                 mappingContext,
@@ -1537,11 +1709,40 @@ export class MappingService {
         if (input.signatureMode === "name-only") {
             const status = methodCandidates.length === 1 ? "resolved" : methodCandidates.length > 1 ? "ambiguous" : "not_found";
             if (status === "ambiguous") {
-                warnings.push(`Multiple method overloads matched name "${queryRecord.name}" in owner "${queryRecord.owner}". Provide descriptor for exact match.`);
+                // name-only discards any supplied descriptor, so telling the caller to "provide
+                // descriptor" would not disambiguate — they need to switch to signatureMode="exact".
+                warnings.push(`Multiple method overloads matched name "${queryRecord.name}" in owner "${queryRecord.owner}". Retry with signatureMode="exact" plus a JVM descriptor to pick one overload.`);
             }
             return buildOutput(querySymbol, methodCandidates, status);
         }
-        const descriptorMatched = methodCandidates.filter((record) => record.descriptor === queryRecord.descriptor);
+        // Tiny parsing stores a single descriptor per method entry (typically in the obfuscated
+        // namespace) and copies it into every namespace at load time. That means a descriptor
+        // supplied in `sourceMapping` coordinates will not string-compare equal to the record
+        // for any method whose descriptor references remapped Minecraft classes. Project the
+        // caller's descriptor to obfuscated coordinates first so class references line up with
+        // the stored record descriptors. The projection is accepted even when
+        // `projection.complete` is false: `projectMethodDescriptorToTarget` leaves every
+        // unresolvable `L...;` reference unchanged (JDK/external classes like
+        // `Ljava/lang/String;` are never in the mapping graph and pass through by design), so a
+        // partial projection still aligns the Minecraft class refs with the stored descriptor
+        // form while leaving external class refs identical to the user input. Falling back to
+        // verbatim comparison on `complete === false` would send mixed descriptors like
+        // `(Lnet/minecraft/world/item/ItemStack;Ljava/lang/String;)V` down the raw-compare path
+        // and produce false negatives in the most common lookup shape. When no class references
+        // exist at all (primitives-only descriptors such as `(I)V`) the projector marks
+        // `hadClassReferences === false` and we simply reuse the original descriptor.
+        const queryDescriptor = queryRecord.descriptor;
+        let effectiveDescriptor = queryDescriptor;
+        if (sourceMapping !== "obfuscated") {
+            const projectionPath = namespacePath(graph, sourceMapping, "obfuscated");
+            if (projectionPath) {
+                const projection = this.projectMethodDescriptorToTarget(graph, projectionPath, queryDescriptor);
+                if (projection.hadClassReferences) {
+                    effectiveDescriptor = projection.descriptor;
+                }
+            }
+        }
+        const descriptorMatched = methodCandidates.filter((record) => record.descriptor === effectiveDescriptor || record.descriptor === queryDescriptor);
         if (descriptorMatched.length === 1) {
             return buildOutput(querySymbol, descriptorMatched, "resolved");
         }
@@ -2094,6 +2295,11 @@ export class MappingService {
             this.graphCache.delete(oldestKey);
         }
     }
+    // Note: in-flight buildLocks may re-populate graphCache after release.
+    // Resolution cache entries created by concurrent findMapping() calls may also
+    // survive this invalidation. Both are bounded by TTL (5 min) and will expire
+    // naturally. A full epoch-based invalidation would add complexity for a rare
+    // user-initiated operation (manage-cache).
     releaseGraphCacheEntry(version, sourcePriority) {
         const normalizedVersion = version.trim();
         if (!normalizedVersion) {
@@ -2106,6 +2312,42 @@ export class MappingService {
                 this.graphCache.delete(key);
             }
         }
+        const resolutionPrefix = `${normalizedVersion}\0`;
+        for (const key of this.resolutionCache.keys()) {
+            if (key.startsWith(resolutionPrefix)) {
+                this.resolutionCache.delete(key);
+            }
+        }
+    }
+    buildResolutionCacheKey(version, input, querySymbol, effectiveSignatureMode) {
+        return [
+            version,
+            input.kind,
+            querySymbol.symbol,
+            querySymbol.descriptor ?? "",
+            input.sourceMapping,
+            input.targetMapping,
+            input.sourcePriority ?? "",
+            effectiveLoomSearchProjectPath(input.projectPath) ?? "",
+            effectiveSignatureMode,
+            String(input.maxCandidates ?? ""),
+            JSON.stringify(input.disambiguation ?? "")
+        ].join("\0");
+    }
+    trimResolutionCache() {
+        if (this.resolutionCache.size <= MappingService.RESOLUTION_CACHE_MAX)
+            return;
+        const now = Date.now();
+        for (const [key, entry] of this.resolutionCache) {
+            if (now - entry.cachedAt > MappingService.RESOLUTION_CACHE_TTL_MS) {
+                this.resolutionCache.delete(key);
+            }
+        }
+        while (this.resolutionCache.size > MappingService.RESOLUTION_CACHE_MAX) {
+            const firstKey = this.resolutionCache.keys().next().value;
+            if (firstKey !== undefined)
+                this.resolutionCache.delete(firstKey);
+        }
     }
 }
 // ---------------------------------------------------------------------------

package/dist/mixin-validator.js

@@ -225,11 +225,23 @@ function computeValidationStatus(summary) {
     }
     return "full";
 }
-function buildQuickSummary(status, summary) {
-    if (status === "full") {
-        return `${summary.membersValidated} member(s) validated successfully.`;
-    }
-    return `${summary.definiteErrors} error(s), ${summary.uncertainErrors} uncertain, ${summary.warnings} warning(s). ${summary.membersValidated} validated, ${summary.membersSkipped} member(s) skipped, ${summary.membersMissing} member(s) missing.`;
+function buildQuickSummary(status, summary, context) {
+    const base = status === "full"
+        ? `${summary.membersValidated} member(s) validated successfully.`
+        : `${summary.definiteErrors} error(s), ${summary.uncertainErrors} uncertain, ${summary.warnings} warning(s). ${summary.membersValidated} validated, ${summary.membersSkipped} member(s) skipped, ${summary.membersMissing} member(s) missing.`;
+    const notes = [];
+    const scopeFallback = context?.provenance?.scopeFallback;
+    if (scopeFallback) {
+        notes.push(`Scope fell back from "${scopeFallback.requested}" to "${scopeFallback.applied}" (${scopeFallback.reason}).`);
+    }
+    const healthReport = context?.healthReport;
+    if (healthReport && !healthReport.overallHealthy) {
+        const degradations = healthReport.degradations.length > 0
+            ? healthReport.degradations.join("; ")
+            : "mapping infrastructure degraded";
+        notes.push(`Mapping health degraded: ${degradations}.`);
+    }
+    return notes.length > 0 ? `${base} ${notes.join(" ")}` : base;
 }
 function addSkippedMembers(parsed, resolvedMembers) {
     for (const inj of parsed.injections) {
@@ -271,7 +283,10 @@ export function refreshMixinValidationOutcome(result) {
     };
     result.validationStatus = computeValidationStatus(result.summary);
     result.valid = result.summary.definiteErrors === 0;
-    result.quickSummary = buildQuickSummary(result.validationStatus, result.summary);
+    result.quickSummary = buildQuickSummary(result.validationStatus, result.summary, {
+        provenance: result.provenance,
+        healthReport: result.toolHealth
+    });
     return result;
 }
 function validateInjection(inj, targetMembers, targetNames, issues, resolvedMembers, confidence, confidenceReason, remapFailedMembers, signatureFailedTargets, healthReport) {
@@ -727,7 +742,7 @@ export function validateParsedMixin(parsed, targetMembers, warnings, provenance,
         parseWarnings: parseWarningCount
     };
     const validationStatus = computeValidationStatus(summary);
-    const quickSummary = buildQuickSummary(validationStatus, summary);
+    const quickSummary = buildQuickSummary(validationStatus, summary, { provenance, healthReport });
     return {
         className: parsed.className,
         targets: targetNames,

package/dist/observability.d.ts

@@ -22,6 +22,7 @@ export interface RuntimeMetricSnapshot {
     get_file_duration_ms: MetricTimingSnapshot;
     list_files_duration_ms: MetricTimingSnapshot;
     decompile_duration_ms: MetricTimingSnapshot;
+    binary_remap_duration_ms: MetricTimingSnapshot;
     search_intent_symbol_duration_ms: MetricTimingSnapshot;
     search_intent_text_duration_ms: MetricTimingSnapshot;
     search_intent_path_duration_ms: MetricTimingSnapshot;
@@ -47,8 +48,13 @@ export interface RuntimeMetricSnapshot {
     cache_artifact_bytes_lru: CacheArtifactByteAccountingRow[];
     cache_hit_rate: number;
     repo_failover_count: number;
+    tool_call_counts: Record<string, number>;
+    tool_call_duration_ms: Record<string, MetricTimingSnapshot>;
+    mapping_resolution_cache_hits: number;
+    mapping_resolution_cache_misses: number;
+    mapping_resolution_cache_size: number;
 }
-type DurationMetricName = keyof Pick<RuntimeMetricSnapshot, "resolve_duration_ms" | "search_duration_ms" | "get_file_duration_ms" | "list_files_duration_ms" | "decompile_duration_ms" | "search_intent_symbol_duration_ms" | "search_intent_text_duration_ms" | "search_intent_path_duration_ms">;
+type DurationMetricName = keyof Pick<RuntimeMetricSnapshot, "resolve_duration_ms" | "search_duration_ms" | "get_file_duration_ms" | "list_files_duration_ms" | "decompile_duration_ms" | "binary_remap_duration_ms" | "search_intent_symbol_duration_ms" | "search_intent_text_duration_ms" | "search_intent_path_duration_ms">;
 export declare class RuntimeMetrics {
     private readonly timings;
     private cacheHits;
@@ -74,6 +80,11 @@ export declare class RuntimeMetrics {
     private cacheEntries;
     private cacheTotalContentBytes;
     private cacheArtifactBytesLruRef;
+    private toolCallCounts;
+    private toolCallTimings;
+    private mappingResolutionCacheHits;
+    private mappingResolutionCacheMisses;
+    private mappingResolutionCacheSize;
     constructor();
     recordDuration(name: DurationMetricName, durationMs: number): void;
     recordArtifactCacheHit(): void;
@@ -97,6 +108,12 @@ export declare class RuntimeMetrics {
     setCacheEntries(entries: number): void;
     setCacheTotalContentBytes(totalBytes: number): void;
     setCacheArtifactByteAccountingRef(entries: ReadonlyArray<CacheArtifactByteAccountingRefRow>): void;
+    recordToolCall(tool: string, durationMs: number): void;
+    setMappingResolutionCacheStats(stats: {
+        hits: number;
+        misses: number;
+        size: number;
+    }): void;
     snapshot(): RuntimeMetricSnapshot;
     private toSnapshot;
     private resolveCacheHitRate;

package/dist/observability.js

@@ -32,6 +32,11 @@ export class RuntimeMetrics {
     cacheEntries = 0;
     cacheTotalContentBytes = 0;
     cacheArtifactBytesLruRef = [];
+    toolCallCounts = new Map();
+    toolCallTimings = new Map();
+    mappingResolutionCacheHits = 0;
+    mappingResolutionCacheMisses = 0;
+    mappingResolutionCacheSize = 0;
     constructor() {
         const names = [
             "resolve_duration_ms",
@@ -39,6 +44,7 @@ export class RuntimeMetrics {
             "get_file_duration_ms",
             "list_files_duration_ms",
             "decompile_duration_ms",
+            "binary_remap_duration_ms",
             "search_intent_symbol_duration_ms",
             "search_intent_text_duration_ms",
             "search_intent_path_duration_ms"
@@ -140,6 +146,27 @@ export class RuntimeMetrics {
     setCacheArtifactByteAccountingRef(entries) {
         this.cacheArtifactBytesLruRef = entries;
     }
+    recordToolCall(tool, durationMs) {
+        this.toolCallCounts.set(tool, (this.toolCallCounts.get(tool) ?? 0) + 1);
+        let timing = this.toolCallTimings.get(tool);
+        if (!timing) {
+            timing = { count: 0, totalMs: 0, lastMs: 0, samples: [] };
+            this.toolCallTimings.set(tool, timing);
+        }
+        const normalizedDuration = Math.max(0, Math.trunc(durationMs));
+        timing.count += 1;
+        timing.totalMs += normalizedDuration;
+        timing.lastMs = normalizedDuration;
+        timing.samples.push(normalizedDuration);
+        if (timing.samples.length > MAX_TIMING_SAMPLES) {
+            timing.samples.shift();
+        }
+    }
+    setMappingResolutionCacheStats(stats) {
+        this.mappingResolutionCacheHits = stats.hits;
+        this.mappingResolutionCacheMisses = stats.misses;
+        this.mappingResolutionCacheSize = stats.size;
+    }
     snapshot() {
         return {
             resolve_duration_ms: this.toSnapshot("resolve_duration_ms"),
@@ -147,6 +174,7 @@ export class RuntimeMetrics {
             get_file_duration_ms: this.toSnapshot("get_file_duration_ms"),
             list_files_duration_ms: this.toSnapshot("list_files_duration_ms"),
             decompile_duration_ms: this.toSnapshot("decompile_duration_ms"),
+            binary_remap_duration_ms: this.toSnapshot("binary_remap_duration_ms"),
             search_intent_symbol_duration_ms: this.toSnapshot("search_intent_symbol_duration_ms"),
             search_intent_text_duration_ms: this.toSnapshot("search_intent_text_duration_ms"),
             search_intent_path_duration_ms: this.toSnapshot("search_intent_path_duration_ms"),
@@ -175,7 +203,22 @@ export class RuntimeMetrics {
                 updated_at: entry.updatedAt
             })),
             cache_hit_rate: this.resolveCacheHitRate(),
-            repo_failover_count: this.repoFailoverCount
+            repo_failover_count: this.repoFailoverCount,
+            tool_call_counts: Object.fromEntries(this.toolCallCounts),
+            tool_call_duration_ms: Object.fromEntries([...this.toolCallTimings].map(([tool, timing]) => [
+                tool,
+                {
+                    count: timing.count,
+                    totalMs: timing.totalMs,
+                    avgMs: timing.count > 0 ? timing.totalMs / timing.count : 0,
+                    lastMs: timing.lastMs,
+                    p95Ms: percentile(timing.samples, 95),
+                    p99Ms: percentile(timing.samples, 99)
+                }
+            ])),
+            mapping_resolution_cache_hits: this.mappingResolutionCacheHits,
+            mapping_resolution_cache_misses: this.mappingResolutionCacheMisses,
+            mapping_resolution_cache_size: this.mappingResolutionCacheSize
         };
     }
     toSnapshot(name) {