@fitchmultz/pi-mcp-adapter 8.0.1 → 8.0.3

package/dist/mcp-output-guard.js

@@ -1,8 +1,9 @@
 import { randomBytes } from "node:crypto";
 import { mkdir, mkdtemp, open, readFile, realpath, writeFile } from "node:fs/promises";
-import { createReadStream } from "node:fs";
+import { readPlainResult } from "./plain-result-reader.js";
 import { tmpdir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
+import { byteLength, sanitizeContent, textStats, truncatedOutput } from "./mcp-output-preview.js";
 export const DEFAULT_MCP_OUTPUT_MAX_BYTES = 50 * 1024;
 export const DEFAULT_MCP_OUTPUT_MAX_LINES = 2000;
 export const DEFAULT_MCP_DETAILS_MAX_BYTES = 16 * 1024;
@@ -61,23 +62,8 @@ export async function guardMcpOutput(content, options = {}) {
     let guardedContent = addAffixes(normalizedContent, prefix, suffix);
     let outputGuard;
     if (totalStats.bytes > maxBytes || totalStats.lines > maxLines) {
-        const { path: fullOutputPath, error: writeError } = await saveArtifact("output", composedOutput, options.outputDirectory);
-        const notice = formatTruncationNotice(stats, fullOutputPath, writeError);
-        const previewBudget = reserveBudget(maxBytes, maxLines, notice + referenceSuffix);
-        const preview = truncateHead(composedOutput, previewBudget.maxBytes, previewBudget.maxLines);
-        const finalText = `${preview.content}\n\n${notice}`;
-        const finalStats = textStats(finalText + referenceSuffix);
-        guardedContent = [{ type: "text", text: finalText }, ...imageBlocks];
-        outputGuard = {
-            truncated: true,
-            originalBytes: stats.bytes,
-            returnedBytes: finalStats.bytes,
-            originalLines: stats.lines,
-            returnedLines: finalStats.lines,
-            ...(imageBlocks.length > 0 ? { imageBlocksPassedThrough: imageBlocks.length } : {}),
-            ...(fullOutputPath !== undefined ? { fullOutputPath } : {}),
-            ...(writeError !== undefined ? { writeError } : {}),
-        };
+        const artifact = await saveArtifact("output", composedOutput, options.outputDirectory);
+        ({ content: guardedContent, outputGuard } = truncatedOutput(composedOutput, stats, artifact, imageBlocks, maxBytes, maxLines, referenceSuffix));
     }
     return {
         content: withReference(guardedContent),
@@ -85,16 +71,6 @@ export async function guardMcpOutput(content, options = {}) {
         ...retained,
     };
 }
-function sanitizeContent(content) {
-    return content.map((block) => {
-        if (block.type !== "image")
-            return block;
-        const mimeType = typeof block.mimeType === "string" && block.mimeType.trim()
-            ? block.mimeType.trim().slice(0, 100)
-            : "image/png";
-        return { ...block, mimeType };
-    });
-}
 function withEmptyTextFallback(content, fallback) {
     if (!fallback)
         return content;
@@ -138,52 +114,6 @@ function addAffixes(content, prefix, suffix) {
     }
     return next;
 }
-function reserveBudget(maxBytes, maxLines, notice) {
-    const noticeStats = textStats(`\n\n${notice}`);
-    return {
-        maxBytes: Math.max(0, maxBytes - noticeStats.bytes),
-        maxLines: Math.max(0, maxLines - noticeStats.lines),
-    };
-}
-function truncateHead(text, maxBytes, maxLines) {
-    const lines = text.split("\n");
-    const output = [];
-    let bytes = 0;
-    for (const line of lines) {
-        if (output.length >= maxLines)
-            break;
-        const separatorBytes = output.length > 0 ? 1 : 0;
-        const lineBytes = byteLength(line);
-        if (bytes + separatorBytes + lineBytes > maxBytes) {
-            const remaining = maxBytes - bytes - separatorBytes;
-            if (remaining > 0) {
-                output.push(truncateStringToBytes(line, remaining));
-            }
-            break;
-        }
-        output.push(line);
-        bytes += separatorBytes + lineBytes;
-    }
-    const content = output.join("\n");
-    const stats = textStats(content);
-    return { content, bytes: stats.bytes, lines: stats.lines };
-}
-function truncateStringToBytes(value, maxBytes) {
-    if (byteLength(value) <= maxBytes)
-        return value;
-    const buffer = Buffer.from(value, "utf8");
-    let end = Number.isFinite(maxBytes) ? Math.max(0, Math.floor(maxBytes)) : 0;
-    while (end > 0 && (buffer.readUInt8(end) & 0xc0) === 0x80)
-        end--;
-    return buffer.subarray(0, end).toString("utf8");
-}
-function formatTruncationNotice(stats, fullOutputPath, writeError) {
-    const base = `[MCP text output truncated: original ${stats.lines.toLocaleString()} lines / ${formatSize(stats.bytes)}.`;
-    if (fullOutputPath) {
-        return `${base} Full text saved to: ${fullOutputPath} — use read with offset/limit or grep to inspect.]`;
-    }
-    return `${base} Full output could not be saved: ${writeError ?? "unknown error"}]`;
-}
 /**
  * Bound details.mcpResult: keep the raw result when its JSON fits within
  * detailsMaxBytes; otherwise replace it with a compact summary and spill the
@@ -359,27 +289,7 @@ export async function readMcpResult(input, options = {}) {
                 throw new Error("offset must be a non-negative integer and limit a positive integer");
             const maxBytes = Math.max(1, (options.maxBytes ?? DEFAULT_MCP_OUTPUT_MAX_BYTES) - 256);
             const maxLines = Math.max(1, (options.maxLines ?? DEFAULT_MCP_OUTPUT_MAX_LINES) - 1);
-            let total = 0, bytes = 0, lines = 1;
-            let page = "";
-            let finished = false;
-            for await (const chunk of createReadStream(ref, { encoding: "utf8" })) {
-                for (const char of chunk) {
-                    if (total < offset && total + char.length > offset)
-                        throw new Error("offset must not split a Unicode surrogate pair");
-                    if (total >= offset && !finished) {
-                        const nextBytes = bytes + byteLength(char);
-                        const nextLines = lines + (char === "\n" ? 1 : 0);
-                        if (page && (nextBytes > maxBytes || nextLines > maxLines || page.length + char.length > limit))
-                            finished = true;
-                        else {
-                            page += char;
-                            bytes = nextBytes;
-                            lines = nextLines;
-                        }
-                    }
-                    total += char.length;
-                }
-            }
+            const { page, total } = await readPlainResult(ref, offset, limit, maxBytes, maxLines);
             const end = offset + page.length;
             const nextOffset = end < total ? end : null;
             return { content: [{ type: "text", text: page }, ...(nextOffset !== null ? [{ type: "text", text: `[MCP result page: ${offset}–${end} of ${total} characters. Continue with offset: ${end}.]` }] : [])], details: { ref, offset, nextOffset, totalCharacters: total } };
@@ -460,12 +370,6 @@ function safeStringify(value) {
         return String(value);
     }
 }
-function textStats(text) {
-    return { bytes: byteLength(text), lines: text.length === 0 ? 0 : text.split("\n").length };
-}
-function byteLength(text) {
-    return Buffer.byteLength(text, "utf8");
-}
 function positiveInt(value) {
     if (typeof value !== "number" || !Number.isFinite(value))
         return undefined;
@@ -482,10 +386,3 @@ function envKillSwitch(name) {
         return true;
     return undefined;
 }
-function formatSize(bytes) {
-    if (bytes < 1024)
-        return `${bytes} B`;
-    if (bytes < 1024 * 1024)
-        return `${(bytes / 1024).toFixed(1)} KiB`;
-    return `${(bytes / (1024 * 1024)).toFixed(1)} MiB`;
-}

package/dist/mcp-output-preview.d.ts

@@ -0,0 +1,29 @@
+import type { GuardedMcpOutput, McpOutputGuardDetails, McpOutputGuardOptions } from "./mcp-output-guard.ts";
+import type { ContentBlock } from "./types.ts";
+/**
+ * Guard output that arrives one block at a time without retaining all of it. Blocks stay in
+ * memory while they fit the model-visible limits. After that, the joined text is appended to
+ * one private output artifact and only the preview head and image blocks are kept. Writes are
+ * synchronous, so a producer may be released as soon as push() returns.
+ */
+export declare function createMcpOutputSpool(options: Pick<McpOutputGuardOptions, "enabled" | "outputDirectory"> & Required<Pick<McpOutputGuardOptions, "maxBytes" | "maxLines">>): {
+    readonly empty: boolean;
+    push(block: ContentBlock): void;
+    finish(): GuardedMcpOutput;
+};
+export declare function truncatedOutput(text: string, stats: {
+    bytes: number;
+    lines: number;
+}, { path: fullOutputPath, error: writeError }: {
+    path?: string;
+    error?: string;
+}, imageBlocks: ContentBlock[], maxBytes: number, maxLines: number, referenceSuffix?: string): {
+    content: ContentBlock[];
+    outputGuard: McpOutputGuardDetails;
+};
+export declare function sanitizeContent(content: ContentBlock[]): ContentBlock[];
+export declare function textStats(text: string): {
+    bytes: number;
+    lines: number;
+};
+export declare function byteLength(text: string): number;

package/dist/mcp-output-preview.js

@@ -0,0 +1,220 @@
+import { randomBytes } from "node:crypto";
+import { closeSync, mkdirSync, mkdtempSync, openSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+// mcp-code.ts is imported on first use. A Pi process that loaded an older mcp-output-guard.ts
+// before an update links the updated mcp-code.ts against it, so the spool cannot live there.
+const SPOOL_WRITE_CHUNK = 1024 * 1024;
+/**
+ * Guard output that arrives one block at a time without retaining all of it. Blocks stay in
+ * memory while they fit the model-visible limits. After that, the joined text is appended to
+ * one private output artifact and only the preview head and image blocks are kept. Writes are
+ * synchronous, so a producer may be released as soon as push() returns.
+ */
+export function createMcpOutputSpool(options) {
+    const { maxBytes, maxLines } = options;
+    let retained = [];
+    const images = [];
+    let pushed = 0, textBlocks = 0, bytes = 0, newlines = 0, written = 0;
+    let head = "", headBytes = 0;
+    let artifact = {};
+    let fd;
+    let pending = [], pendingLength = 0;
+    const lines = () => bytes === 0 ? 0 : newlines + 1;
+    const fail = (error) => {
+        artifact = { error: error instanceof Error ? error.message : String(error) };
+        if (fd !== undefined)
+            try {
+                closeSync(fd);
+            }
+            catch { /* the write error is the reported failure */ }
+        fd = undefined;
+    };
+    const flush = () => {
+        if (fd !== undefined && pending.length > 0) {
+            try {
+                writeFileSync(fd, pending.length === 1 ? pending[0] : pending.join(""));
+            }
+            catch (error) {
+                fail(error);
+            }
+        }
+        pending = [];
+        pendingLength = 0;
+    };
+    const append = (piece) => {
+        if (headBytes <= maxBytes) {
+            // Each UTF-16 unit is at least one UTF-8 byte, so the head exceeds every preview budget.
+            let end = Math.min(piece.length, maxBytes + 1 - headBytes);
+            const last = piece.charCodeAt(end - 1);
+            if (end < piece.length && last >= 0xd800 && last <= 0xdbff)
+                end++;
+            const part = piece.slice(0, end);
+            head += part;
+            headBytes += byteLength(part);
+        }
+        if (fd === undefined)
+            return;
+        if (pendingLength + piece.length > SPOOL_WRITE_CHUNK)
+            flush();
+        pending.push(piece);
+        pendingLength += piece.length;
+    };
+    const appendText = (text) => {
+        if (written++ > 0)
+            append("\n");
+        append(text);
+    };
+    const spill = (blocks) => {
+        try {
+            const parent = options.outputDirectory === undefined ? tmpdir() : resolve(options.outputDirectory);
+            if (options.outputDirectory !== undefined)
+                mkdirSync(parent, { recursive: true, mode: 0o700 });
+            const path = join(mkdtempSync(join(parent, "pi-mcp-output-")), `output-${randomBytes(4).toString("hex")}.txt`);
+            fd = openSync(path, "wx", 0o600);
+            artifact = { path };
+        }
+        catch (error) {
+            fail(error);
+        }
+        for (const block of blocks) {
+            if (block.type === "image")
+                images.push(block);
+            else
+                appendText(block.text);
+        }
+    };
+    return {
+        get empty() { return pushed === 0; },
+        push(block) {
+            pushed++;
+            if (block.type === "image") {
+                (retained ?? images).push(...sanitizeContent([block]));
+                return;
+            }
+            const separator = textBlocks++ > 0 ? 1 : 0;
+            bytes += separator + byteLength(block.text);
+            newlines += separator + countNewlines(block.text);
+            if (!retained)
+                appendText(block.text);
+            else {
+                retained.push(block);
+                if (options.enabled !== false && (bytes > maxBytes || lines() > maxLines)) {
+                    const blocks = retained;
+                    retained = undefined;
+                    spill(blocks);
+                }
+            }
+        },
+        finish() {
+            if (retained)
+                return { content: retained };
+            flush();
+            if (fd !== undefined) {
+                try {
+                    closeSync(fd);
+                }
+                catch (error) {
+                    artifact = { error: error instanceof Error ? error.message : String(error) };
+                }
+                fd = undefined;
+            }
+            return truncatedOutput(head, { bytes, lines: lines() }, artifact, images, maxBytes, maxLines);
+        },
+    };
+}
+export function truncatedOutput(text, stats, { path: fullOutputPath, error: writeError }, imageBlocks, maxBytes, maxLines, referenceSuffix = "") {
+    const notice = formatTruncationNotice(stats, fullOutputPath, writeError);
+    const previewBudget = reserveBudget(maxBytes, maxLines, notice + referenceSuffix);
+    const preview = truncateHead(text, previewBudget.maxBytes, previewBudget.maxLines);
+    const finalText = `${preview.content}\n\n${notice}`;
+    const finalStats = textStats(finalText + referenceSuffix);
+    return {
+        content: [{ type: "text", text: finalText }, ...imageBlocks],
+        outputGuard: {
+            truncated: true,
+            originalBytes: stats.bytes,
+            returnedBytes: finalStats.bytes,
+            originalLines: stats.lines,
+            returnedLines: finalStats.lines,
+            ...(imageBlocks.length > 0 ? { imageBlocksPassedThrough: imageBlocks.length } : {}),
+            ...(fullOutputPath !== undefined ? { fullOutputPath } : {}),
+            ...(writeError !== undefined ? { writeError } : {}),
+        },
+    };
+}
+function countNewlines(text) {
+    let count = 0;
+    for (let index = text.indexOf("\n"); index !== -1; index = text.indexOf("\n", index + 1))
+        count++;
+    return count;
+}
+export function sanitizeContent(content) {
+    return content.map((block) => {
+        if (block.type !== "image")
+            return block;
+        const mimeType = typeof block.mimeType === "string" && block.mimeType.trim()
+            ? block.mimeType.trim().slice(0, 100)
+            : "image/png";
+        return { ...block, mimeType };
+    });
+}
+function reserveBudget(maxBytes, maxLines, notice) {
+    const noticeStats = textStats(`\n\n${notice}`);
+    return {
+        maxBytes: Math.max(0, maxBytes - noticeStats.bytes),
+        maxLines: Math.max(0, maxLines - noticeStats.lines),
+    };
+}
+function truncateHead(text, maxBytes, maxLines) {
+    const lines = text.split("\n");
+    const output = [];
+    let bytes = 0;
+    for (const line of lines) {
+        if (output.length >= maxLines)
+            break;
+        const separatorBytes = output.length > 0 ? 1 : 0;
+        const lineBytes = byteLength(line);
+        if (bytes + separatorBytes + lineBytes > maxBytes) {
+            const remaining = maxBytes - bytes - separatorBytes;
+            if (remaining > 0) {
+                output.push(truncateStringToBytes(line, remaining));
+            }
+            break;
+        }
+        output.push(line);
+        bytes += separatorBytes + lineBytes;
+    }
+    const content = output.join("\n");
+    const stats = textStats(content);
+    return { content, bytes: stats.bytes, lines: stats.lines };
+}
+function truncateStringToBytes(value, maxBytes) {
+    if (byteLength(value) <= maxBytes)
+        return value;
+    const buffer = Buffer.from(value, "utf8");
+    let end = Number.isFinite(maxBytes) ? Math.max(0, Math.floor(maxBytes)) : 0;
+    while (end > 0 && (buffer.readUInt8(end) & 0xc0) === 0x80)
+        end--;
+    return buffer.subarray(0, end).toString("utf8");
+}
+function formatTruncationNotice(stats, fullOutputPath, writeError) {
+    const base = `[MCP text output truncated: original ${stats.lines.toLocaleString()} lines / ${formatSize(stats.bytes)}.`;
+    if (fullOutputPath) {
+        return `${base} Full text saved to: ${fullOutputPath} — use read with offset/limit or grep to inspect.]`;
+    }
+    return `${base} Full output could not be saved: ${writeError ?? "unknown error"}]`;
+}
+export function textStats(text) {
+    return { bytes: byteLength(text), lines: text.length === 0 ? 0 : text.split("\n").length };
+}
+export function byteLength(text) {
+    return Buffer.byteLength(text, "utf8");
+}
+function formatSize(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KiB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MiB`;
+}

package/dist/mcp-panel.js

@@ -1,5 +1,4 @@
 import { matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
-import { copyToClipboard } from "@earendil-works/pi-coding-agent";
 import { createPanelKeys } from "./panel-keys.js";
 import { sanitizeTerminalText, stripOscSequences } from "./utils.js";
 import { reconstructToolMetadata } from "./metadata-cache.js";
@@ -380,7 +379,7 @@ class McpPanel {
                 return;
             const serverName = sanitizeDisplayText(server.name);
             const failureMessage = sanitizeDisplayText(server.failureMessage);
-            copyToClipboard(failureMessage).then(() => {
+            import("@earendil-works/pi-coding-agent").then(({ copyToClipboard }) => copyToClipboard(failureMessage)).then(() => {
                 this.authNotice = `Copied error for ${serverName} to clipboard`;
                 this.tui.requestRender();
             }).catch((error) => {

package/dist/mcp-script-worker.mjs

@@ -4,6 +4,7 @@ import vm from "node:vm";
 
 const TOOLS_ENUMERATION_ERROR = "tools is not enumerable — use tools.search({ query })";
 const RESERVED_TOOL_PROPS = new Set(["then", "catch", "finally", "toJSON", "toString", "valueOf"]);
+const { code, outputFlow, outputWindow } = workerData;
 
 // Keep this formatting logic in sync with mcp-code.ts; the standalone worker cannot import the TypeScript host module.
 function needsInspectableFormatting(value, stack = new WeakSet()) {
@@ -98,7 +99,18 @@ const tools = new Proxy(Object.create(null), {
 });
 
 const emit = (value) => {
-  parentPort.postMessage({ type: "emit", block: toContentBlock(value) });
+  const block = toContentBlock(value);
+  // A running Pi keeps the adapter it loaded but starts this file from disk, so an older host passes no window.
+  if (!outputFlow) {
+    parentPort.postMessage({ type: "emit", block });
+    return;
+  }
+  // Charge each queued message too, so many tiny emits cannot outrun the host.
+  const size = (block.type === "text" ? block.text.length : block.data.length) + 256;
+  Atomics.add(outputFlow, 0, size);
+  parentPort.postMessage({ type: "emit", block, size });
+  // Block this worker, not the host, until the host consumes queued output.
+  for (let queued; (queued = Atomics.load(outputFlow, 0)) > outputWindow;) Atomics.wait(outputFlow, 0, queued);
 };
 
 const capturedConsole = Object.freeze({
@@ -118,7 +130,7 @@ try {
     codeGeneration: { strings: false, wasm: false },
     name: "mcp_script",
   });
-  const script = new vm.Script(`(async () => {\n${workerData.code}\n})()`, { filename: "mcp_script.js" });
+  const script = new vm.Script(`(async () => {\n${code}\n})()`, { filename: "mcp_script.js" });
   const returnValue = await Promise.resolve(script.runInContext(context));
   parentPort.postMessage(returnValue === undefined
     ? { type: "done" }

package/dist/metadata-cache.d.ts

@@ -3,7 +3,7 @@ import { type ToolPrefix } from "./types.ts";
 export type { CachedPrompt, CachedResource, CachedTool, MetadataCache, ServerCacheEntry } from "./types.ts";
 export declare function getMetadataCachePath(): string;
 export declare function loadMetadataCache(enabled?: boolean): MetadataCache | null;
-export declare function saveMetadataCache(cache: MetadataCache, enabled?: boolean): void;
+export declare function saveMetadataCache(cache: MetadataCache, enabled?: boolean, selectedServers?: Iterable<string>): void;
 export declare function computeServerHash(definition: ServerEntry): string;
 export declare function isServerCacheValid(entry: ServerCacheEntry, definition: ServerEntry, maxAgeMs?: number): boolean;
 export declare function parseDirectToolSelectors(selectors: string[]): {

package/dist/metadata-cache.js

@@ -1,5 +1,5 @@
 // metadata-cache.ts - Persistent MCP metadata cache
-import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync, statSync } from "node:fs";
 import { dirname } from "node:path";
 import { getAdapterPath } from "./agent-dir.js";
 import { createHash } from "node:crypto";
@@ -9,6 +9,20 @@ import { interpolateEnvRecord, resolveBearerToken, resolveConfigPath, resolveSer
 // Version 2 stores raw descriptors; version 1 readers cannot enforce raw UI visibility.
 const CACHE_VERSION = 2;
 const CACHE_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+let snapshot;
+const toolProjections = new WeakMap();
+function cacheRevision(path) {
+    const stat = statSync(path, { bigint: true });
+    return `${stat.dev}:${stat.ino}:${stat.size}:${stat.mtimeNs}:${stat.ctimeNs}`;
+}
+function freezeMetadata(value) {
+    if (value && typeof value === "object" && !Object.isFrozen(value)) {
+        for (const child of Object.values(value))
+            freezeMetadata(child);
+        Object.freeze(value);
+    }
+    return value;
+}
 export function getMetadataCachePath() {
     return getAdapterPath("mcp-cache.json");
 }
@@ -16,23 +30,25 @@ export function loadMetadataCache(enabled = true) {
     if (!enabled)
         return null;
     const cachePath = getMetadataCachePath();
-    if (!existsSync(cachePath))
-        return null;
     try {
+        const revision = cacheRevision(cachePath);
+        if (snapshot?.path === cachePath && snapshot.revision === revision)
+            return snapshot.cache;
         const raw = JSON.parse(readFileSync(cachePath, "utf-8"));
-        if (!raw || typeof raw !== "object")
-            return null;
-        if (raw.version !== 1 && raw.version !== CACHE_VERSION)
-            return null;
-        if (!raw.servers || typeof raw.servers !== "object")
-            return null;
-        return raw;
+        const cache = raw && typeof raw === "object" && !Array.isArray(raw)
+            && (raw.version === 1 || raw.version === CACHE_VERSION)
+            && raw.servers && typeof raw.servers === "object" && !Array.isArray(raw.servers)
+            ? freezeMetadata(raw) : null;
+        // A concurrent rename must not associate the old bytes with the new file's revision.
+        snapshot = cacheRevision(cachePath) === revision ? { path: cachePath, revision, cache } : undefined;
+        return cache;
     }
     catch {
+        snapshot = undefined;
         return null;
     }
 }
-export function saveMetadataCache(cache, enabled = true) {
+export function saveMetadataCache(cache, enabled = true, selectedServers = []) {
     if (!enabled)
         return;
     const cachePath = getMetadataCachePath();
@@ -52,6 +68,14 @@ export function saveMetadataCache(cache, enabled = true) {
     }
     merged.version = CACHE_VERSION;
     merged.servers = { ...merged.servers, ...cache.servers };
+    const protectedServers = new Set([...selectedServers, ...Object.keys(cache.servers)]);
+    const now = Date.now();
+    for (const [name, entry] of Object.entries(merged.servers)) {
+        if (!protectedServers.has(name) && isCacheEntry(entry)
+            && (entry.cachedAt > now || now - entry.cachedAt > CACHE_MAX_AGE_MS)) {
+            delete merged.servers[name];
+        }
+    }
     const tmpPath = `${cachePath}.${process.pid}.tmp`;
     writeFileSync(tmpPath, JSON.stringify(merged, null, 2), "utf-8");
     renameSync(tmpPath, cachePath);
@@ -86,14 +110,24 @@ export function isServerCacheValid(entry, definition, maxAgeMs = CACHE_MAX_AGE_M
     catch {
         return false;
     }
-    if (!entry || entry.configHash !== configHash)
+    if (!isCacheEntry(entry) || entry.configHash !== configHash)
         return false;
-    if (!entry.cachedAt || typeof entry.cachedAt !== "number")
+    if (entry.cachedAt > Date.now())
         return false;
     if (maxAgeMs > 0 && Date.now() - entry.cachedAt > maxAgeMs)
         return false;
     return true;
 }
+function isCacheEntry(entry) {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry))
+        return false;
+    const value = entry;
+    return typeof value.configHash === "string"
+        && typeof value.cachedAt === "number" && Number.isFinite(value.cachedAt) && value.cachedAt > 0
+        && Array.isArray(value.tools) && Array.isArray(value.resources)
+        && (value.prompts === undefined || Array.isArray(value.prompts))
+        && (value.instructions === undefined || typeof value.instructions === "string");
+}
 export function parseDirectToolSelectors(selectors) {
     const servers = new Set();
     const tools = new Map();
@@ -138,7 +172,15 @@ export function getMissingConfiguredDirectToolServers(config, cache, envOverride
     return missing;
 }
 export function reconstructToolMetadata(serverName, entry, prefix, definition) {
-    return buildToolMetadata((entry.tools ?? []).filter(tool => tool?.name).map(restoreCachedTool), entry.resources ?? [], definition, serverName, prefix).metadata;
+    const key = JSON.stringify([serverName, prefix, definition.exposeResources, definition.includeTools,
+        definition.excludeTools, definition.toolPrefix, definition.disabled]);
+    const previous = toolProjections.get(entry);
+    if (Object.isFrozen(entry) && previous?.key === key)
+        return previous.metadata;
+    const metadata = buildToolMetadata((entry.tools ?? []).filter(tool => tool?.name).map(restoreCachedTool), entry.resources ?? [], definition, serverName, prefix).metadata;
+    if (Object.isFrozen(entry))
+        toolProjections.set(entry, { key, metadata: freezeMetadata(metadata) });
+    return metadata;
 }
 function restoreCachedTool(tool) {
     const { uiResourceUri, uiVisibility, uiStreamMode, ...descriptor } = tool;

package/dist/plain-result-reader.d.ts

@@ -0,0 +1,7 @@
+/** Only the native, synchronous history writer can certify an append. External changes invalidate. */
+export declare function appendPlainOutput(ref: string, text: string): void;
+/** Sparse byte/UTF16 checkpoints, never retained file contents. Changed/uncacheable files scan afresh. */
+export declare function readPlainResult(ref: string, offset: number, limit: number, maxBytes: number, maxLines: number): Promise<{
+    page: string;
+    total: number;
+}>;