@herbertgao/pi-extensions 2026.8.5 → 2026.8.7

package/node_modules/pi-lens/dist/clients/tool-event.js

@@ -33,13 +33,19 @@
  *    enumerate the built-ins only; pi-lens's `tool_call`/`tool_result` paths
  *    also key off `lsp_navigation` and pi-lens's own registered tools, which no
  *    host discriminator names.
- * 4. **Narrowing to the host union would LOSE fields pi-lens reads.** The host
+ * 4. **The host union is narrower than the events pi-lens handles.** The host
  *    `ToolResultEvent` declares `toolCallId`/`input`/`content`/`isError`/
  *    `details`/`usage`; pi-lens's local `ToolResultEvent`
- *    (`clients/runtime-tool-result.ts`) additionally carries
- *    `id`/`callId`/`requestId`/`provider`/`model`/`sessionId`/`session`, which
- *    the telemetry-identity path reads. A guard that narrowed to
- *    `EditToolResultEvent` would drop them.
+ *    (`clients/runtime-tool-result.ts`) declares the subset it reads. It used
+ *    to additionally carry `id`/`callId`/`requestId`/`provider`/`model`/
+ *    `sessionId`/`session` "for the telemetry-identity path" — #1655 item 2
+ *    deleted all seven, because pi's `afterToolCall` builds the event with
+ *    exactly `type`/`toolName`/`toolCallId`/`input`/`content`/`details`/
+ *    `isError`/`usage` (`dist/core/agent-session.js:243-256`, source
+ *    `src/core/agent-session.ts:502-516`), so the branch reading them was dead
+ *    code. The standing reason not to narrow is point 3: pi-lens also
+ *    synthesizes its OWN `tool_result` payloads (bash-derived writes,
+ *    partial-apply) that no host discriminator would admit.
  *
  * What IS consolidated is the part that costs nothing: the host's `details`
  * SHAPES are type-only exports, so `EditToolDetails` & co. are imported as
@@ -47,8 +53,53 @@
  * payloads (`searchReads`, `piLensPartialApply`) stay hand-declared — no host
  * type describes them.
  */
+import { sanitizeCorrelationId } from "./read-guard-logger.js";
 export function isToolCallEventType(toolName, event) {
     return (!!event &&
         typeof event === "object" &&
         event.toolName === toolName);
 }
+/**
+ * Resolve a STABLE correlation id shared between a `tool_call` and its
+ * paired `tool_result`, checking every field name a host is known to use
+ * (#1642 F4) — the SDK declares `toolCallId` (see the file header above for
+ * why pi-lens can't import the SDK's own type at runtime), but
+ * `read-guard-logger.ts`'s `getReadGuardCorrelationId` already had to widen
+ * to `callId`/`requestId`/`id` for hosts that populate one of those instead.
+ * Single source of truth for that field list — do not hand-roll a narrower
+ * `event.toolCallId` read at a new call site.
+ *
+ * Deliberately does NOT fall back to a generated id the way
+ * `getReadGuardCorrelationId` does: that fallback is minted fresh on EVERY
+ * call (a bare per-invocation counter), which is exactly right for grouping
+ * one call's own log lines but useless — actively misleading — for
+ * correlating two SEPARATE events (a `tool_call` and its `tool_result`)
+ * against each other. `undefined` means the host supplies no stable
+ * identity at all under any known field; callers decide their own safe
+ * default for that case rather than treat a generated id as a match.
+ */
+export function resolveToolCallCorrelationId(event) {
+    const value = (event ?? {});
+    for (const candidate of [
+        value.toolCallId,
+        value.callId,
+        value.requestId,
+        // Widest rung, only reached when toolCallId/callId/requestId are all
+        // absent (#1678 item 2): this assumes a host's `id` field identifies
+        // one TOOL CALL. A host that instead populates `id` per MESSAGE (one
+        // id shared by every tool call in that message) would cross two
+        // parallel calls in the same turn under the same id. Stated plainly:
+        // real pi builds `tool_call`/`tool_result` events with exactly
+        // `toolCallId` and no bare `id` field at all (see the file header
+        // above, #1655 item 2, `src/core/agent-session.ts:502-516`), so this
+        // rung is dead code against today's host — kept only in case a
+        // different host shape needs it; drop it once #1655's audit confirms
+        // none does.
+        value.id,
+    ]) {
+        const sanitized = sanitizeCorrelationId(candidate);
+        if (sanitized)
+            return sanitized;
+    }
+    return undefined;
+}

package/node_modules/pi-lens/dist/clients/tool-policy.js

@@ -3,7 +3,7 @@ import * as path from "node:path";
 import { TERRAGRUNT_FILENAMES } from "./file-kinds.js";
 import { logLatency } from "./latency-logger.js";
 import { resolvePackagePath } from "./package-root.js";
-import { findNearestContaining, walkUpDirs } from "./path-utils.js";
+import { findNearestContaining, normalizeMapKey, walkUpDirs, } from "./path-utils.js";
 import { loadProjectSnapshotWithoutWordIndex } from "./project-snapshot.js";
 // Extension → formatter policy. This map, `FORMATTER_POLICY_BY_FILENAME`, and
 // `AUTO_INSTALLABLE_DEFAULT_FORMATTERS` are the inverse of the formatter
@@ -272,7 +272,7 @@ const FORMATTER_POLICY_BY_EXTENSION = new Map([
             formatterNames: ["swiftformat"],
             defaultFormatter: "swiftformat",
             defaultWhenUnconfigured: false,
-            gate: "smart-default",
+            gate: "config-first",
         },
     ],
     [
@@ -281,7 +281,7 @@ const FORMATTER_POLICY_BY_EXTENSION = new Map([
             formatterNames: ["fantomas"],
             defaultFormatter: "fantomas",
             defaultWhenUnconfigured: false,
-            gate: "smart-default",
+            gate: "config-first",
         },
     ],
     [
@@ -290,7 +290,7 @@ const FORMATTER_POLICY_BY_EXTENSION = new Map([
             formatterNames: ["fantomas"],
             defaultFormatter: "fantomas",
             defaultWhenUnconfigured: false,
-            gate: "smart-default",
+            gate: "config-first",
         },
     ],
     [
@@ -299,7 +299,7 @@ const FORMATTER_POLICY_BY_EXTENSION = new Map([
             formatterNames: ["fantomas"],
             defaultFormatter: "fantomas",
             defaultWhenUnconfigured: false,
-            gate: "smart-default",
+            gate: "config-first",
         },
     ],
     [
@@ -317,7 +317,7 @@ const FORMATTER_POLICY_BY_EXTENSION = new Map([
             formatterNames: ["mix"],
             defaultFormatter: "mix",
             defaultWhenUnconfigured: false,
-            gate: "smart-default",
+            gate: "config-first",
         },
     ],
     [
@@ -326,7 +326,7 @@ const FORMATTER_POLICY_BY_EXTENSION = new Map([
             formatterNames: ["mix"],
             defaultFormatter: "mix",
             defaultWhenUnconfigured: false,
-            gate: "smart-default",
+            gate: "config-first",
         },
     ],
     [
@@ -335,7 +335,7 @@ const FORMATTER_POLICY_BY_EXTENSION = new Map([
             formatterNames: ["mix"],
             defaultFormatter: "mix",
             defaultWhenUnconfigured: false,
-            gate: "smart-default",
+            gate: "config-first",
         },
     ],
     [
@@ -344,7 +344,7 @@ const FORMATTER_POLICY_BY_EXTENSION = new Map([
             formatterNames: ["mix"],
             defaultFormatter: "mix",
             defaultWhenUnconfigured: false,
-            gate: "smart-default",
+            gate: "config-first",
         },
     ],
     [
@@ -353,7 +353,7 @@ const FORMATTER_POLICY_BY_EXTENSION = new Map([
             formatterNames: ["mix"],
             defaultFormatter: "mix",
             defaultWhenUnconfigured: false,
-            gate: "smart-default",
+            gate: "config-first",
         },
     ],
     [
@@ -443,7 +443,7 @@ const FORMATTER_POLICY_BY_EXTENSION = new Map([
             formatterNames: ["csharpier"],
             defaultFormatter: "csharpier",
             defaultWhenUnconfigured: false,
-            gate: "smart-default",
+            gate: "config-first",
         },
     ],
     [
@@ -461,7 +461,7 @@ const FORMATTER_POLICY_BY_EXTENSION = new Map([
             formatterNames: ["ormolu"],
             defaultFormatter: "ormolu",
             defaultWhenUnconfigured: false,
-            gate: "smart-default",
+            gate: "config-first",
         },
     ],
     [
@@ -470,7 +470,7 @@ const FORMATTER_POLICY_BY_EXTENSION = new Map([
             formatterNames: ["ormolu"],
             defaultFormatter: "ormolu",
             defaultWhenUnconfigured: false,
-            gate: "smart-default",
+            gate: "config-first",
         },
     ],
     [
@@ -533,7 +533,7 @@ const FORMATTER_POLICY_BY_EXTENSION = new Map([
             formatterNames: ["taplo"],
             defaultFormatter: "taplo",
             defaultWhenUnconfigured: false,
-            gate: "smart-default",
+            gate: "config-first",
         },
     ],
     [
@@ -542,7 +542,7 @@ const FORMATTER_POLICY_BY_EXTENSION = new Map([
             formatterNames: ["terraform"],
             defaultFormatter: "terraform",
             defaultWhenUnconfigured: false,
-            gate: "smart-default",
+            gate: "config-first",
         },
     ],
     [
@@ -551,7 +551,7 @@ const FORMATTER_POLICY_BY_EXTENSION = new Map([
             formatterNames: ["terraform"],
             defaultFormatter: "terraform",
             defaultWhenUnconfigured: false,
-            gate: "smart-default",
+            gate: "config-first",
         },
     ],
     [
@@ -653,6 +653,15 @@ const FORMATTER_POLICY_BY_EXTENSION = new Map([
             gate: "smart-default",
         },
     ],
+    [
+        ".cue",
+        {
+            formatterNames: ["cue"],
+            defaultFormatter: "cue",
+            defaultWhenUnconfigured: true,
+            gate: "smart-default",
+        },
+    ],
 ]);
 // oxfmt supports these extensions — registered as a candidate formatter for each.
 // Using a post-processing pass avoids repeating the same modification across
@@ -1453,6 +1462,7 @@ export function getAutofixPolicyForFile(filePath, context = {}) {
             defaultWhenUnconfigured: true,
             gate: "smart-default",
             safe: true,
+            scope: "cargo-project",
         };
     }
     if ([".json", ".jsonc"].includes(ext)) {
@@ -1595,6 +1605,7 @@ export function getAutofixPolicyForFile(filePath, context = {}) {
             defaultWhenUnconfigured: true,
             gate: "smart-default",
             safe: true,
+            scope: "dart-project",
         };
     }
     return undefined;
@@ -2023,10 +2034,17 @@ export function ruffConfigArgs(cwd) {
  * `config/biome/core.jsonc` fallback — applies on `lint --write` too.
  */
 export function biomeConfigArgs(cwd) {
+    // A project config wins outright (#1731, discipline A): passing
+    // `--config-path` even when the project ships `biome.json(c)` pinned
+    // biome's config resolution to that ONE file, so a monorepo package
+    // underneath `cwd` with its own `biome.json` never got to extend/override
+    // the root config the way biome's own nested-config resolution allows. No
+    // flag at all lets biome discover it unaided, exactly like the ruff/
+    // markdownlint fallbacks above skip `--config` under the same condition.
+    if (getBiomeConfigPath(cwd))
+        return [];
     return [
-        "--config-path=" +
-            (getBiomeConfigPath(cwd) ??
-                resolvePackagePath(import.meta.url, "config/biome/core.jsonc")),
+        "--config-path=" + resolvePackagePath(import.meta.url, "config/biome/core.jsonc"),
     ];
 }
 export function hasGolangciConfig(cwd) {
@@ -2077,6 +2095,89 @@ export function hasCmakeFormatConfig(cwd) {
         "cmake-format.yml",
     ]) !== undefined);
 }
+// PSScriptAnalyzerSettings.psd1 is the conventional settings file PowerShell
+// projects use to configure `Invoke-Formatter`/`Invoke-ScriptAnalyzer` (passed
+// via `-Settings`); `ScriptAnalyzerSettings.psd1` is the same convention minus
+// the "PS" prefix and shows up in some repos too. Either one opting a project
+// into explicit PSScriptAnalyzer config is enough to select the formatter
+// (#1572 — `psscriptanalyzer-format` had no case here at all, so it could
+// never be selected regardless of project config).
+const PSSCRIPTANALYZER_SETTINGS_FILES = [
+    "PSScriptAnalyzerSettings.psd1",
+    "ScriptAnalyzerSettings.psd1",
+];
+/**
+ * The nearest PSScriptAnalyzer settings file's full path, or `undefined`.
+ * `formatters.ts`'s `resolveCommand` passes this straight to
+ * `Invoke-Formatter -Settings` (#1572 review F2) — gating on the file's
+ * PRESENCE without ever reading its RULES would run the project's file
+ * through the stock `CodeFormatting` ruleset regardless of what it declared,
+ * the same stock-style imposition #1144 banned for the other formatters.
+ */
+export function findPSScriptAnalyzerConfigPath(cwd) {
+    for (const dir of walkUpDirs(cwd)) {
+        for (const name of PSSCRIPTANALYZER_SETTINGS_FILES) {
+            const candidate = path.join(dir, name);
+            if (fs.existsSync(candidate))
+                return candidate;
+        }
+    }
+    return undefined;
+}
+export function hasPSScriptAnalyzerConfig(cwd) {
+    return findPSScriptAnalyzerConfigPath(cwd) !== undefined;
+}
+// #1595 sweep — 7 of the 8 formatters #1572 left unreachable (038cd1df flipped
+// defaultWhenUnconfigured to false for these without adding an explicit-config
+// check; see EXPLICIT_FORMATTER_CONFIG_CHECKS in formatters.ts). nixfmt is the
+// 8th and stays unreachable: it is deliberately unconfigurable (no rc file,
+// no CLI flag surface) and has no project-level manifest marker analogous to
+// `terraform init`'s lock file, so there is no honest "explicit opt-in" signal
+// to gate on — see the KNOWN_UNREACHABLE_FORMATTERS comment in
+// formatter-policy-consistency.test.ts.
+export function hasCsharpierConfig(cwd) {
+    return (findNearestContaining(cwd, [
+        ".csharpierrc",
+        ".csharpierrc.json",
+        ".csharpierrc.yaml",
+        ".csharpierrc.yml",
+    ]) !== undefined);
+}
+// Ormolu has no general settings file, but it does read a project `.ormolu`
+// file for custom operator fixity declarations (the only file-based config
+// surface Ormolu supports) — real, if narrow, per its own docs.
+export function hasOrmoluConfig(cwd) {
+    return findNearestContaining(cwd, [".ormolu"]) !== undefined;
+}
+export function hasTaploConfig(cwd) {
+    return findNearestContaining(cwd, ["taplo.toml", ".taplo.toml"]) !== undefined;
+}
+// `terraform fmt` itself is deliberately unconfigurable (no rc file, no
+// per-project options — HashiCorp's own docs call this out). The nearest
+// thing to an explicit per-project opt-in is `.terraform.lock.hcl`, written
+// only by `terraform init`: it marks a directory the user has deliberately
+// set up as a Terraform root, as opposed to a stray `.tf`/`.tfvars` file
+// dropped into an unrelated repo. A manifest marker, per #1595's own guidance
+// for formatters with no dedicated config-file convention.
+export function hasTerraformConfig(cwd) {
+    return findNearestContaining(cwd, [".terraform.lock.hcl"]) !== undefined;
+}
+export function hasSwiftformatConfig(cwd) {
+    return findNearestContaining(cwd, [".swiftformat"]) !== undefined;
+}
+// Fantomas has no dedicated rc file; its documented config surface is
+// `.editorconfig` (fsharp_*-prefixed keys) or a `.fantomasignore` file (the
+// one Fantomas-specific marker it does ship). Mirrors hasGoogleJavaFormatConfig's
+// precedent for formatters whose only config surface is .editorconfig.
+export function hasFantomasConfig(cwd) {
+    return (findNearestContaining(cwd, [".fantomasignore", ".editorconfig"]) !==
+        undefined);
+}
+// `.formatter.exs` is THE convention `mix format` reads project config from
+// (inputs, line_length, plugins) — universal in Elixir projects that use it.
+export function hasMixFormatConfig(cwd) {
+    return findNearestContaining(cwd, [".formatter.exs"]) !== undefined;
+}
 export function hasPhpstanConfig(cwd) {
     return findNearestContaining(cwd, PHPSTAN_CONFIGS) !== undefined;
 }
@@ -2281,10 +2382,16 @@ const COMPILED_CLASSES_DIRS = [
     path.join("out", "production"),
     path.join("bin", "main"),
 ];
-export function hasJavaBuildDescriptor(cwd) {
+export function hasJavaBuildDescriptor(cwd, ceiling) {
+    const normalizedCeiling = ceiling
+        ? normalizeMapKey(path.resolve(ceiling))
+        : undefined;
     for (const dir of walkUpDirs(cwd)) {
         if (JAVA_BUILD_DESCRIPTORS.some((d) => fs.existsSync(path.join(dir, d))))
             return true;
+        if (normalizedCeiling &&
+            normalizeMapKey(path.resolve(dir)) === normalizedCeiling)
+            break;
     }
     return false;
 }

package/node_modules/pi-lens/dist/clients/tool-set-policy.js

@@ -0,0 +1,76 @@
+import { logLatency } from "./latency-logger.js";
+/**
+ * Whether the host will send this model deferred (searchable) tool
+ * definitions rather than the full inline list.
+ *
+ * Read the host's own decision off `ctx.model.compat` — pi resolves that
+ * flag from the model config (`core/model-config`, `compat.supportsToolReferences`)
+ * and it is the only capability signal a consumer can honestly observe.
+ * A missing flag means "unknown", which we report as false: this value only
+ * annotates the `tool_set_mutation` log line, so guessing high would make the
+ * log lie, while guessing low merely under-claims.
+ */
+export function supportsDeferredTools(model) {
+    return model?.compat?.supportsToolReferences === true;
+}
+/**
+ * A fresh logical conversation — the only reasons that start with an empty
+ * activation memory. `undefined` is included because older hosts fire
+ * `session_start` with no `reason` at all.
+ *
+ * Every OTHER reason (fork/reload/resume) is a session REBUILD: the host
+ * constructs a brand-new AgentSession with `includeAllExtensionTools: true`
+ * (pi `core/agent-session.js`), so every registered pi-lens tool is active
+ * again by the time our handler runs, while pi-lens's own extension closure
+ * state survives. Those reasons must RESTORE the previous posture, not skip.
+ */
+export function isFreshSessionStart(reason) {
+    return reason === undefined || reason === "startup" || reason === "new";
+}
+/**
+ * Compute the active-tool set pi-lens wants: everything currently active that
+ * is not a lazy tool, plus exactly the lazy tools the model activated in this
+ * logical session (`remembered`).
+ *
+ * On startup/new `remembered` is empty and this is the plain baseline shrink.
+ * On fork/reload/resume the host has just re-activated all registered tools,
+ * and this restores the parent's posture character-for-character — which both
+ * preserves the model's activations and keeps the advertised tool list equal
+ * to the one the prompt cache prefix was built from.
+ */
+export function planToolSet(active, lazyNames, remembered) {
+    const desired = active.filter(
+    // Lazy tools are dropped here and re-appended below in REMEMBERED
+    // (= activation) order. Keeping them in the host's registration
+    // position would restore the right SET in the wrong ARRAY order, and
+    // the active-tools array is what serializes into the request's tool
+    // block — a transposition is a changed prefix, i.e. a cache miss.
+    (name) => !lazyNames.has(name));
+    // A remembered tool the host did not list as active still belongs in the
+    // set (defensive: the host controls what `getActiveTools` returns).
+    const desiredSet = new Set(desired);
+    for (const name of remembered) {
+        if (!desiredSet.has(name)) {
+            desired.push(name);
+            desiredSet.add(name);
+        }
+    }
+    const activeSet = new Set(active);
+    const removedCount = active.filter((name) => !desiredSet.has(name)).length;
+    const addedCount = desired.filter((name) => !activeSet.has(name)).length;
+    return {
+        desired,
+        addedCount,
+        removedCount,
+        changed: addedCount > 0 || removedCount > 0,
+    };
+}
+export function recordToolSetMutation(mutation) {
+    logLatency({
+        type: "phase",
+        filePath: "<pi-lens>",
+        phase: "tool_set_mutation",
+        durationMs: 0,
+        metadata: { ...mutation },
+    });
+}

package/node_modules/pi-lens/dist/clients/tree-sitter-cache.js

@@ -31,8 +31,56 @@ export const TREE_CACHE_COUNTER_KEYS = [
     "ghostHistoryDrops",
 ];
 export function createTreeCacheCounters() {
+    // SAFETY: `Object.fromEntries` returns `Record<string, number>` — it cannot
+    // prove the key set. `TREE_CACHE_COUNTER_KEYS` is declared `as const
+    // satisfies readonly (keyof TreeCacheCounters)[]`, so the compiler already
+    // rejects a key that is not a counter; every counter is a `number` and
+    // every key gets 0, so the result has the full shape. The `satisfies`
+    // clause does NOT check the reverse direction: add a counter to
+    // `TreeCacheCounters` without adding its key here and this cast becomes a
+    // lie. `tests/clients/tree-sitter-cache.test.ts` closes that direction with
+    // a compile-time `[Exclude<keyof TreeCacheCounters, …>] extends [never]`
+    // assertion, so a missing key fails `tsc`, not just the suite.
     return Object.fromEntries(TREE_CACHE_COUNTER_KEYS.map((key) => [key, 0]));
 }
+/** Interactive-editing default: safe LRU footprint for per-edit locality. */
+export const TREE_CACHE_DEFAULT_MAX_SIZE = 50;
+/**
+ * Hard ceiling on how far a full-project scan may grow the tree cache
+ * (#1715). Entry count is not the resource that matters — WASM heap is
+ * (#417/#418, the leak this cache was fixed for once already) — so growing
+ * capacity to fit a scan's working set must still cap the heap's worst case,
+ * not just stop counting entries.
+ *
+ * Measured empirically on a fresh process (`heap-measure.mjs`, dropped from
+ * this PR — see the PR body): parsing 800 synthetic ~3.6KB TypeScript files
+ * with all 800 trees held resident (no eviction) grows `process.memoryUsage()
+ * .external` by ~254MB over the same run with only 1 tree resident at a
+ * time — about 330KB of non-V8 (WASM-backed) heap per resident tree on that
+ * sample. At the interactive default of 50 entries that is a ~16MB
+ * worst case; at this 500-entry ceiling it is a ~165MB worst case — bounded
+ * and stated, not unbounded growth.
+ */
+export const TREE_CACHE_SCAN_CAPACITY_CEILING = 500;
+/**
+ * Derive the capacity a full-project scan should grow the tree cache to
+ * (#1715): span the scan's file count so a second scan over the same files
+ * reuses every tree instead of re-parsing files the LRU evicted at the
+ * interactive default — bounded by `TREE_CACHE_SCAN_CAPACITY_CEILING` (or
+ * its `PI_LENS_TREE_SITTER_CACHE_SCAN_CAP` override) so the heap cost stated
+ * above stays a real ceiling. Never shrinks a capacity the cache already
+ * has — a later, smaller scan (or an unrelated caller) must not undo an
+ * earlier grow.
+ */
+export function deriveScanTreeCacheCapacity(fileCount, currentMaxSize) {
+    const envRaw = process.env.PI_LENS_TREE_SITTER_CACHE_SCAN_CAP;
+    const envValue = envRaw !== undefined ? Number.parseInt(envRaw, 10) : Number.NaN;
+    const ceiling = Number.isSafeInteger(envValue) && envValue > 0
+        ? envValue
+        : TREE_CACHE_SCAN_CAPACITY_CEILING;
+    const target = Math.min(Math.max(fileCount, TREE_CACHE_DEFAULT_MAX_SIZE), ceiling);
+    return Math.max(currentMaxSize, target);
+}
 export class TreeCache {
     cache = new Map();
     recentlyEvicted = new Map();
@@ -42,7 +90,7 @@ export class TreeCache {
     counters = createTreeCacheCounters();
     counterObserver;
     treeErrorObserver;
-    constructor(maxSize = 50, debug = false, evictionHistoryMax = 4096, counterObserver, treeErrorObserver) {
+    constructor(maxSize = TREE_CACHE_DEFAULT_MAX_SIZE, debug = false, evictionHistoryMax = 4096, counterObserver, treeErrorObserver) {
         this.maxSize = maxSize;
         this.evictionHistoryMax = Math.max(1, Math.floor(evictionHistoryMax));
         this.counterObserver = counterObserver;
@@ -59,6 +107,32 @@ export class TreeCache {
         this.counters[key] += amount;
         this.counterObserver?.(key, amount);
     }
+    /** Current capacity ceiling (entry count, not bytes — see class docstring). */
+    getMaxSize() {
+        return this.maxSize;
+    }
+    /**
+     * Resize the capacity ceiling (#1715). Growing only changes the bound —
+     * existing entries are untouched. Shrinking evicts the LRU tail down to
+     * the new size through the same `removeEntry` path eviction uses, so a
+     * shrink still frees every dropped tree's WASM heap (#417) instead of
+     * silently orphaning it. `n` is floored at 1: a cache that can hold zero
+     * entries can never record a hit.
+     */
+    setMaxSize(n) {
+        const next = Math.max(1, Math.floor(n));
+        this.maxSize = next;
+        while (this.cache.size > this.maxSize) {
+            const firstKey = this.cache.keys().next().value;
+            if (firstKey === undefined)
+                break;
+            const evicted = this.cache.get(firstKey);
+            if (evicted)
+                this.rememberEviction(firstKey, evicted);
+            this.recordCounter("evictions");
+            this.removeEntry(firstKey);
+        }
+    }
     /**
      * Free a tree-sitter Tree's WASM-heap allocation.
      *