@fitchmultz/pi-mcp-adapter 5.0.0 → 6.0.0

package/init.ts

@@ -1,7 +1,6 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { McpExtensionState } from "./state.ts";
 import { isServerDisabled, type McpAdapterOptions, type McpConfig, type PromptMetadata, type ToolMetadata } from "./types.ts";
-import { existsSync } from "node:fs";
 import { cloneMcpConfig, isPathInsideProject, loadMcpConfig } from "./config.ts";
 import { ConsentManager } from "./consent-manager.ts";
 import { McpLifecycleManager } from "./lifecycle.ts";
@@ -214,18 +213,7 @@ export async function initializeMcp(
   const idleSetting = typeof config.settings?.idleTimeout === "number" ? config.settings.idleTimeout : 10;
   lifecycle.setGlobalIdleTimeout(idleSetting);
 
-  const cachePath = getMetadataCachePath();
-  const cacheFileExists = metadataCacheEnabled && existsSync(cachePath);
-  let cache = loadMetadataCache(metadataCacheEnabled);
-  let bootstrapAll = false;
-
-  if (!cacheFileExists) {
-    bootstrapAll = true;
-    saveMetadataCache({ version: 1, servers: {} }, metadataCacheEnabled);
-  } else if (!cache) {
-    cache = { version: 1, servers: {} };
-    saveMetadataCache(cache, metadataCacheEnabled);
-  }
+  const cache = loadMetadataCache(metadataCacheEnabled);
 
   const prefix = config.settings?.toolPrefix ?? "server";
 
@@ -258,12 +246,10 @@ export async function initializeMcp(
     }
   }
 
-  const startupServers = bootstrapAll
-    ? serverEntries
-    : serverEntries.filter(([, definition]) => {
-        const mode = definition.lifecycle ?? "lazy";
-        return mode === "keep-alive" || mode === "eager";
-      });
+  const startupServers = serverEntries.filter(([, definition]) => {
+    const mode = definition.lifecycle ?? "lazy";
+    return mode === "keep-alive" || mode === "eager";
+  });
 
   if (ui && startupServers.length > 0) {
     const status = formatMcpStatus(state.config, `connecting to ${startupServers.length} servers...`);
@@ -376,7 +362,7 @@ export async function initializeMcp(
       const bootstrapped = bootstrapResults.filter(r => r.ok).map(r => r.name);
       owner.throwIfInactive();
       if (bootstrapped.length > 0 && ui) {
-        ui.notify(`MCP: direct tools for ${bootstrapped.join(", ")} will be available after restart`, "info");
+        ui.notify(`MCP: tools discovered for ${bootstrapped.join(", ")}`, "info");
       }
     }
   }

package/mcp-code.ts

@@ -1,14 +1,14 @@
 import type { ToolInfo } from "@earendil-works/pi-coding-agent";
 import { formatWithOptions } from "node:util";
 import { Worker } from "node:worker_threads";
-import { guardMcpOutput, guardedMcpDetails, resolveMcpOutputGuardOptions } from "./mcp-output-guard.ts";
-import { executeCall } from "./proxy-modes.ts";
+import { guardMcpOutput, guardedMcpDetails, resolveMcpOutputGuardOptions, readMcpResult, formatMcpResultReference, formatMcpPayloadFile, type McpPayloadFile, type ReadMcpResultInput } from "./mcp-output-guard.ts";
+import { executeCall, executeConnect } from "./proxy-modes.ts";
+import { executeResourceList, executeResourceRead } from "./resource-tools.ts";
 import { combineAbortSignals } from "./runtime-owner.ts";
 import { paginate, rankSuggestions, rankToolMatches } from "./search-ranking.ts";
 import type { McpExtensionState } from "./state.ts";
-import { findToolByName } from "./tool-metadata.ts";
-import { renderTsShape } from "./ts-shape.ts";
-import type { ContentBlock, McpOperationContext } from "./types.ts";
+import { catalogCoverage, toToolDescriptor } from "./tool-metadata.ts";
+import { isServerDisabled, type ContentBlock, type McpOperationContext } from "./types.ts";
 
 export const DEFAULT_MCP_SCRIPT_TIMEOUT_MS = 30_000;
 
@@ -20,12 +20,12 @@ class McpScriptTimeoutError extends Error {
 }
 
 type SearchInput = { query?: unknown; server?: unknown; limit?: unknown; offset?: unknown };
-type DescribeInput = { path?: unknown };
+type DescribeInput = { path?: unknown; server?: unknown };
 type WorkerMessage =
   | { type: "emit"; block: unknown }
-  | { type: "call"; id: number; path: string; args?: unknown }
+  | { type: "call"; id: number; path: string; args?: unknown; server?: string }
   | { type: "search"; id: number; input?: unknown }
-  | { type: "describe"; id: number; input?: unknown }
+  | { type: "describe" | "resources" | "readResource" | "readResult"; id: number; input?: unknown }
   | { type: "done"; returnBlock?: unknown }
   | { type: "error"; message: string };
 
@@ -86,11 +86,9 @@ function parseWorkerMessage(value: unknown): WorkerMessage | null {
   const message = value as Record<string, unknown>;
   if (message.type === "emit" && "block" in message) return { type: "emit", block: message.block };
   if (message.type === "call" && typeof message.id === "number" && typeof message.path === "string") {
-    return "args" in message
-      ? { type: "call", id: message.id, path: message.path, args: message.args }
-      : { type: "call", id: message.id, path: message.path };
+    return { type: "call", id: message.id, path: message.path, ...(message.args !== undefined ? { args: message.args } : {}), ...(typeof message.server === "string" ? { server: message.server } : {}) };
   }
-  if ((message.type === "search" || message.type === "describe") && typeof message.id === "number") {
+  if ((message.type === "search" || message.type === "describe" || message.type === "resources" || message.type === "readResource" || message.type === "readResult") && typeof message.id === "number") {
     return "input" in message
       ? { type: message.type, id: message.id, input: message.input }
       : { type: message.type, id: message.id };
@@ -151,17 +149,17 @@ async function runMcpScriptOperation(
       : operation.durationMs,
   }));
   let callsSnapshot: ScriptOperation[] | undefined;
-  const callTool = async (innerCallId: number, path: string, args?: Record<string, unknown>) => {
+  const resultRefs = new Set<string>();
+  const payloadNotices = new Set<string>();
+  const recordCall = async (path: string, dispatch: () => ReturnType<typeof executeCall>) => {
     // Record before dispatch so calls still in flight at timeout/abort appear in the trace.
     const startedAt = Date.now();
     const index = calls.push({ operation: "call", path, ok: false, error: "incomplete", durationMs: 0, startedAt }) - 1;
-    let rawResult: unknown;
-    let hasRawResult = false;
-    const result = await executeCall(state, path, args, undefined, getPiTools, callSignal, (raw) => {
-      rawResult = raw;
-      hasRawResult = true;
-    }, { ...(toolCallId !== undefined ? { toolCallId } : {}), innerCallId }, beforeDispatch);
+    const result = await dispatch();
     const details = result.details;
+    if (typeof details.resultRef === "string") resultRefs.add(details.resultRef);
+    if (typeof details.resultWriteError === "string") payloadNotices.add(`[MCP result could not be saved: ${details.resultWriteError}]`);
+    for (const file of (details.payloadFiles ?? []) as McpPayloadFile[]) payloadNotices.add(formatMcpPayloadFile(file));
     if (details.error !== undefined) {
       const errorCode = String(details.error);
       const suggestions = Array.isArray(details.suggestions)
@@ -180,30 +178,45 @@ async function runMcpScriptOperation(
       if (errorCode === "ambiguous_outcome") output.push({ type: "text", text: message });
       return {
         ok: false as const,
+        ...(details.mcpResult !== undefined ? { data: details.mcpResult } : {}),
+        ...(details.resultRef ? { resultRef: details.resultRef } : {}),
         error: { code: errorCode, message, ...(details.recovery ? { recovery: details.recovery } : {}) },
       };
     }
     calls[index] = { operation: "call", path, ok: true, durationMs: Date.now() - startedAt, startedAt };
     return {
       ok: true as const,
-      data: hasRawResult ? rawResult : details.mcpResult !== undefined ? details.mcpResult : textFromContent(result.content),
+      data: details.mcpResult !== undefined ? details.mcpResult : textFromContent(result.content),
+      ...(details.resultRef ? { resultRef: details.resultRef } : {}),
     };
   };
 
-  const searchTools = (input?: SearchInput) => {
+  const callIdentity = (innerCallId: number) => ({ ...(toolCallId !== undefined ? { toolCallId } : {}), innerCallId });
+  const callTool = (innerCallId: number, path: string, args?: Record<string, unknown>, server?: string) => recordCall(path,
+    () => executeCall(state, path, args, server, getPiTools, callSignal, callIdentity(innerCallId), beforeDispatch, { raw: true }));
+
+  const discoverServer = async (server?: string) => {
+    if (!server) return undefined;
+    if (isServerDisabled(state.config.mcpServers[server])) return { code: "server_disabled", message: `Server "${server}" is disabled.` };
+    if (state.config.mcpServers[server] && state.toolMetadata.has(server)) return undefined;
+    const result = await executeConnect(state, server, callSignal);
+    return result.details.error ? { code: result.details.error, message: textFromContent(result.content) } : undefined;
+  };
+  const searchTools = async (input?: SearchInput) => {
     const startedAt = Date.now();
     const query = typeof input?.query === "string" ? input.query : "";
     let error: unknown;
     try {
-      if (query.trim() === "") {
-        return { items: [], total: 0, hasMore: false, nextOffset: null };
-      }
       const server = typeof input?.server === "string" ? input.server : undefined;
+      const discoveryError = await discoverServer(server);
+      const coverage = catalogCoverage(state, server);
+      if (discoveryError) { error = discoveryError.code; return { error: discoveryError, coverage }; }
+      if (query.trim() === "") return { items: [], total: 0, hasMore: false, nextOffset: null, coverage };
       const limit = typeof input?.limit === "number" ? input.limit : 12;
       const offset = typeof input?.offset === "number" ? input.offset : 0;
-      const page = paginate(rankToolMatches(state, query, server), offset, limit);
+      const page = paginate(rankToolMatches(state, query, server).filter(match => !match.tool.resourceUri), offset, limit);
       return {
-        ...page,
+        ...page, coverage,
         items: page.items.map(({ server: matchServer, tool, score }) => ({
           path: tool.name,
           name: tool.originalName,
@@ -222,25 +235,23 @@ async function runMcpScriptOperation(
     }
   };
 
-  const describeTool = (input?: DescribeInput) => {
+  const describeTool = async (input?: DescribeInput) => {
     const startedAt = Date.now();
     const path = typeof input?.path === "string" ? input.path : "";
     let error: unknown;
     try {
-      for (const [server, metadata] of state.toolMetadata) {
-        const tool = findToolByName(metadata, path);
-        if (!tool) continue;
-        const inputTypeScript = tool.inputSchema ? renderTsShape(tool.inputSchema) : null;
-        return {
-          path: tool.name,
-          name: tool.originalName,
-          server,
-          ...(tool.description ? { description: tool.description } : {}),
-          ...(inputTypeScript ? { inputTypeScript } : tool.inputSchema !== undefined ? { inputSchema: tool.inputSchema } : {}),
-          ...(tool.annotations !== undefined ? { annotations: tool.annotations } : {}),
-        };
-      }
-      const suggestions = path ? rankSuggestions(state, path, 5) : [];
+      const selectedServer = typeof input?.server === "string" ? input.server : undefined;
+      const discoveryError = await discoverServer(selectedServer);
+      if (discoveryError) { error = discoveryError.code; return { path, error: discoveryError }; }
+      const matches = [...state.toolMetadata].flatMap(([server, metadata]) => {
+        if ((selectedServer && server !== selectedServer) || !state.config.mcpServers[server] || isServerDisabled(state.config.mcpServers[server])) return [];
+        const tools = metadata.filter(tool => !tool.resourceUri);
+        const originals = selectedServer ? tools.filter(tool => tool.originalName === path) : [];
+        return (originals.length ? originals : tools.filter(tool => tool.name === path)).map(tool => toToolDescriptor(server, tool));
+      });
+      if (matches.length === 1) return matches[0];
+      if (matches.length > 1) { error = "ambiguous_tool"; return { path, error: { code: "ambiguous_tool", message: "Specify server and exact tool name." } }; }
+      const suggestions = path ? rankSuggestions(state, path, 5, selectedServer) : [];
       error = "tool_not_found";
       return {
         path,
@@ -301,11 +312,25 @@ async function runMcpScriptOperation(
         void (async () => {
           let envelope: unknown;
           if (message.type === "call") {
-            envelope = await callTool(message.id, message.path, message.args as Record<string, unknown> | undefined);
+            envelope = await callTool(message.id, message.path, message.args as Record<string, unknown> | undefined, message.server);
           } else if (message.type === "search") {
-            envelope = searchTools(message.input as SearchInput | undefined);
+            envelope = await searchTools(message.input as SearchInput | undefined);
+          } else if (message.type === "describe") {
+            envelope = await describeTool(message.input as DescribeInput | undefined);
+          } else if (message.type === "readResult") {
+            envelope = await readMcpResult(message.input as ReadMcpResultInput, resolveMcpOutputGuardOptions(state.config.settings, state.outputDirectory));
           } else {
-            envelope = describeTool(message.input as DescribeInput | undefined);
+            const input = message.input as { server?: unknown; uri?: unknown; limit?: unknown; offset?: unknown } | undefined;
+            if (typeof input?.server !== "string" || !input.server || (message.type === "readResource" && (typeof input.uri !== "string" || !input.uri))) {
+              envelope = { error: { code: "invalid_arguments", message: "Specify server and, for reads, resource uri." } };
+            } else if (message.type === "resources") {
+              const result = await executeResourceList(state, input.server, typeof input.limit === "number" ? input.limit : 12, typeof input.offset === "number" ? input.offset : 0, callSignal);
+              envelope = result.details.error ? { error: { code: result.details.error, message: textFromContent(result.content) } } : result.details;
+            } else {
+              const server = input.server;
+              const uri = input.uri as string;
+              envelope = await recordCall(`${server}:${uri}`, () => executeResourceRead(state, server, uri, callSignal, callIdentity(message.id), beforeDispatch, true));
+            }
           }
           const response: WorkerResultMessage = { type: "result", id: message.id, envelope };
           activeWorker.postMessage(response);
@@ -369,13 +394,14 @@ async function runMcpScriptOperation(
 
   // Snapshot before the asynchronous output guard; the terminated worker can no longer emit.
   const guarded = await guardMcpOutput(
-    output.length > 0 ? [...output] : [{ type: "text", text: "(no output)" }],
+    [...(output.length > 0 ? output : [{ type: "text" as const, text: "(no output)" }]), ...[...payloadNotices].map(text => ({ type: "text" as const, text })), ...[...resultRefs].map(ref => ({ type: "text" as const, text: formatMcpResultReference(ref) }))],
     resolveMcpOutputGuardOptions(state.config.settings, state.outputDirectory),
   );
   return {
     content: guarded.content,
     details: {
       mode: "script",
+      ...(resultRefs.size ? { resultRefs: [...resultRefs] } : {}),
       ...(errorCode ? { error: errorCode, message: errorMessage } : {}),
       timeoutMs: resolvedTimeoutMs,
       ...(recovery !== undefined ? { recovery } : {}),

package/mcp-output-guard.ts

@@ -1,7 +1,7 @@
 import { randomBytes } from "node:crypto";
-import { mkdir, mkdtemp, writeFile } from "node:fs/promises";
+import { mkdir, mkdtemp, readFile, realpath, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { join, resolve } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
 import type { ContentBlock, McpSettings } from "./types.ts";
 
 export const DEFAULT_MCP_OUTPUT_MAX_BYTES = 50 * 1024;
@@ -52,17 +52,31 @@ export interface McpOutputGuardOptions {
   /**
    * Raw MCP result to expose as details.mcpResult. Kept raw when its JSON
    * fits detailsMaxBytes (or when the guard is disabled); otherwise replaced
-   * with a compact summary and spilled to a temp file. Omit for call sites
-   * whose details never carried the raw result (e.g. resource reads).
+   * with a compact summary and spilled to a file. Payloads that are not fully
+   * visible as plain text also get a model-visible reference for local readback.
    */
   rawMcpResult?: unknown;
+  retainedMcpResult?: RetainedMcpResult;
 }
 
 export interface GuardedMcpOutput {
   content: ContentBlock[];
   outputGuard?: McpOutputGuardDetails;
   mcpResult?: unknown;
+  resultRef?: string;
+  resultWriteError?: string;
+  payloadFiles?: McpPayloadFile[];
+}
+
+export interface McpPayloadFile {
+  index: number;
+  kind: "audio" | "resource";
+  uri?: string;
+  mimeType?: string;
+  path?: string;
+  error?: string;
 }
+export type RetainedMcpResult = Pick<GuardedMcpOutput, "mcpResult" | "resultRef" | "resultWriteError" | "payloadFiles">;
 
 export function resolveMcpOutputGuardOptions(settings?: McpSettings, outputDirectory?: string): Pick<McpOutputGuardOptions, "enabled" | "maxBytes" | "maxLines" | "detailsMaxBytes" | "outputDirectory"> {
   const configured = settings?.outputGuard;
@@ -81,6 +95,9 @@ export function guardedMcpDetails(guarded: GuardedMcpOutput): Record<string, unk
   return {
     ...(guarded.mcpResult !== undefined ? { mcpResult: guarded.mcpResult } : {}),
     ...(guarded.outputGuard ? { outputGuard: guarded.outputGuard } : {}),
+    ...(guarded.resultRef ? { resultRef: guarded.resultRef } : {}),
+    ...(guarded.resultWriteError ? { resultWriteError: guarded.resultWriteError } : {}),
+    ...(guarded.payloadFiles?.length ? { payloadFiles: guarded.payloadFiles } : {}),
   };
 }
 
@@ -95,7 +112,6 @@ export async function guardMcpOutput(
 ): Promise<GuardedMcpOutput> {
   const maxBytes = options.maxBytes ?? DEFAULT_MCP_OUTPUT_MAX_BYTES;
   const maxLines = options.maxLines ?? DEFAULT_MCP_OUTPUT_MAX_LINES;
-  const detailsMaxBytes = options.detailsMaxBytes ?? DEFAULT_MCP_DETAILS_MAX_BYTES;
   const prefix = options.prefix ?? "";
   const suffix = options.suffix ?? "";
 
@@ -106,12 +122,11 @@ export async function guardMcpOutput(
     options.emptyTextFallback,
   );
 
-  if (options.enabled === false) {
-    return {
-      content: addAffixes(normalizedContent, prefix, suffix),
-      ...(options.rawMcpResult !== undefined ? { mcpResult: options.rawMcpResult } : {}),
-    };
-  }
+  const retained = options.retainedMcpResult ?? (options.rawMcpResult === undefined ? {} : await retainMcpResult(options.rawMcpResult, options));
+  const reference = retained.resultRef ? formatMcpResultReference(retained.resultRef)
+    : retained.resultWriteError ? `[MCP result could not be saved: ${retained.resultWriteError}]` : undefined;
+  const withReference = (blocks: ContentBlock[]) => reference ? [...blocks, { type: "text" as const, text: reference }] : blocks;
+  if (options.enabled === false) return { content: withReference(addAffixes(normalizedContent, prefix, suffix)), ...retained };
 
   const imageBlocks = normalizedContent.filter((block) => block.type === "image");
   const textOutput = normalizedContent
@@ -120,17 +135,19 @@ export async function guardMcpOutput(
     .join("\n");
   const composedOutput = `${prefix}${textOutput}${suffix}`;
   const stats = textStats(composedOutput);
+  const referenceSuffix = reference ? `\n${reference}` : "";
+  const totalStats = textStats(composedOutput ? composedOutput + referenceSuffix : reference ?? "");
 
   let guardedContent: ContentBlock[] = addAffixes(normalizedContent, prefix, suffix);
   let outputGuard: McpOutputGuardDetails | undefined;
 
-  if (stats.bytes > maxBytes || stats.lines > maxLines) {
+  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);
+    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);
+    const finalStats = textStats(finalText + referenceSuffix);
 
     guardedContent = [{ type: "text" as const, text: finalText }, ...imageBlocks];
     outputGuard = {
@@ -145,14 +162,10 @@ export async function guardMcpOutput(
     };
   }
 
-  const mcpResult = options.rawMcpResult === undefined
-    ? undefined
-    : await boundMcpResult(options.rawMcpResult, detailsMaxBytes, options.outputDirectory);
-
   return {
-    content: guardedContent,
+    content: withReference(guardedContent),
     ...(outputGuard ? { outputGuard } : {}),
-    ...(mcpResult !== undefined ? { mcpResult } : {}),
+    ...retained,
   };
 }
 
@@ -267,16 +280,46 @@ function formatTruncationNotice(
  * detailsMaxBytes; otherwise replace it with a compact summary and spill the
  * raw JSON to a temp file.
  */
-async function boundMcpResult(result: unknown, detailsMaxBytes: number, outputDirectory?: string): Promise<unknown> {
+export async function retainMcpResult(result: unknown, options: McpOutputGuardOptions = {}, rawResult = false): Promise<RetainedMcpResult> {
   const raw = safeStringify(result);
   const rawBytes = byteLength(raw);
-  if (rawBytes <= detailsMaxBytes) return result;
-  return summarizeMcpResult(result, raw, rawBytes, outputDirectory);
+  const record = asRecord(result);
+  const content = Array.isArray(record?.content) ? record.content
+    : Array.isArray(record?.contents) ? record.contents.map(resource => ({ type: "resource", resource })) : [];
+  const payloadFiles = (await Promise.all(content.map(async (block, index): Promise<McpPayloadFile | undefined> => {
+    const item = asRecord(block);
+    const resource = asRecord(item?.resource);
+    const data = item?.type === "audio" ? item.data : item?.type === "resource" ? resource?.blob : undefined;
+    if (typeof data !== "string") return undefined;
+    const mimeType = item?.mimeType ?? resource?.mimeType;
+    return { index, kind: item!.type as "audio" | "resource", ...(typeof resource?.uri === "string" ? { uri: resource.uri } : {}), ...(typeof mimeType === "string" ? { mimeType } : {}), ...await saveArtifact("payload", Buffer.from(data, "base64"), options.outputDirectory) };
+  }))).filter((file): file is McpPayloadFile => file !== undefined);
+  const oversized = options.enabled !== false && rawBytes > (options.detailsMaxBytes ?? DEFAULT_MCP_DETAILS_MAX_BYTES);
+  const shouldSave = oversized || !record || Object.keys(record).some(key => key !== "content" && key !== "isError")
+    || content.some(block => {
+      const item = asRecord(block);
+      return item?.type !== "text" || Object.keys(item).some(key => key !== "type" && key !== "text");
+    });
+  if (!shouldSave) return { mcpResult: result };
+  const artifact = await saveArtifact("mcp-result", raw, options.outputDirectory);
+  return {
+    mcpResult: oversized && !rawResult ? summarizeMcpResult(result, rawBytes, artifact) : result,
+    ...(artifact.path ? { resultRef: artifact.path } : {}),
+    ...(artifact.error ? { resultWriteError: artifact.error } : {}),
+    ...(payloadFiles.length ? { payloadFiles } : {}),
+  };
+}
+
+export function formatMcpPayloadFile(file: McpPayloadFile): string {
+  return `[MCP ${file.kind === "audio" ? "audio" : "binary resource"}${file.uri ? ` (${file.uri})` : ""}: ${file.mimeType ?? "unknown MIME type"}; not rendered. ${file.path ? `Saved file: ${file.path}` : `Could not save: ${file.error}`}]`;
 }
 
-async function summarizeMcpResult(result: unknown, raw: string, rawBytes: number, outputDirectory?: string): Promise<McpResultSummary> {
-  const { path: fullResultPath, error: resultWriteError } = await saveArtifact("mcp-result", raw, outputDirectory);
+export function formatMcpResultReference(ref: string): string {
+  return `[MCP result saved: ${JSON.stringify(ref)}. Inspect without repeating the call using mcp action "read-result" or tools.readResult with this ref. Optionally select a JSON Pointer with path.]`;
+}
 
+function summarizeMcpResult(result: unknown, rawBytes: number, artifact: { path?: string; error?: string }): McpResultSummary {
+  const { path: fullResultPath, error: resultWriteError } = artifact;
   const record = asRecord(result);
   const content = Array.isArray(record?.content) ? record.content : [];
   const summary: McpResultSummary = {
@@ -357,12 +400,12 @@ function truncateKey(key: string): string {
   return key.length <= KEY_MAX_CHARS ? key : `${key.slice(0, KEY_MAX_CHARS - 1)}…`;
 }
 
-async function saveArtifact(kind: string, text: string, outputDirectory?: string): Promise<{ path?: string; error?: string }> {
+async function saveArtifact(kind: string, text: string | Uint8Array, outputDirectory?: string): Promise<{ path?: string; error?: string }> {
   try {
     const parent = outputDirectory === undefined ? tmpdir() : resolve(outputDirectory);
     if (outputDirectory !== undefined) await mkdir(parent, { recursive: true, mode: 0o700 });
     const dir = await mkdtemp(join(parent, "pi-mcp-output-"));
-    const path = join(dir, `${kind}-${randomBytes(4).toString("hex")}.txt`);
+    const path = join(dir, `${kind}-${randomBytes(4).toString("hex")}.${typeof text === "string" ? "txt" : "bin"}`);
     await writeFile(path, text, { encoding: "utf8", mode: 0o600 });
     return { path };
   } catch (error) {
@@ -370,6 +413,81 @@ async function saveArtifact(kind: string, text: string, outputDirectory?: string
   }
 }
 
+export interface ReadMcpResultInput {
+  ref: string;
+  /** RFC 6901 JSON Pointer. Omit to read the entire retained result. */
+  path?: string;
+  fields?: string[];
+  /** Zero-based character offset in the selected, pretty-printed value. */
+  offset?: number;
+  /** Maximum characters, additionally bounded by the configured output limits. */
+  limit?: number;
+}
+
+export async function readMcpResult(input: ReadMcpResultInput, options: McpOutputGuardOptions = {}) {
+  try {
+    if (!input || typeof input.ref !== "string") throw new Error("ref must be a retained MCP result path");
+    // Script-only hosts deliberately have no general filesystem capability.
+    const root = await realpath(options.outputDirectory === undefined ? tmpdir() : resolve(options.outputDirectory));
+    const ref = await realpath(resolve(input.ref));
+    if (dirname(dirname(ref)) !== root || !/^pi-mcp-output-/.test(basename(dirname(ref)))
+      || !/^(mcp-result|output)-[a-f0-9]+\.txt$/.test(basename(ref))) throw new Error("ref is not an MCP output artifact in this host's output directory");
+    let rendered = await readFile(ref, "utf8");
+    if (input.path !== undefined || input.fields !== undefined || basename(ref).startsWith("mcp-result-")) {
+      let value: unknown = JSON.parse(rendered);
+      if (input.path !== undefined && input.path !== "") {
+        if (typeof input.path !== "string" || !input.path.startsWith("/") || /~(?:[^01]|$)/.test(input.path)) throw new Error("path must be an RFC 6901 JSON Pointer");
+        for (const token of input.path.slice(1).split("/")) {
+          const key = token.replace(/~1/g, "/").replace(/~0/g, "~");
+          if (value === null || typeof value !== "object" || (Array.isArray(value) && !/^(0|[1-9]\d*)$/.test(key)) || !Object.hasOwn(value, key)) throw new Error(`JSON Pointer does not exist: ${input.path}`);
+          value = (value as Record<string, unknown>)[key];
+        }
+      }
+      if (input.fields !== undefined) {
+        if (!Array.isArray(input.fields) || input.fields.some(field => typeof field !== "string")) throw new Error("fields must be an array of keys");
+        const select = (item: unknown) => {
+          if (!item || typeof item !== "object" || Array.isArray(item)) throw new Error("fields requires an object or array of objects");
+          return Object.fromEntries(input.fields!.filter(key => Object.hasOwn(item, key)).map(key => [key, (item as Record<string, unknown>)[key]]));
+        };
+        value = Array.isArray(value) ? value.map(select) : select(value);
+      }
+      rendered = JSON.stringify(value, null, 2);
+    }
+    const offset = input.offset ?? 0;
+    const limit = input.limit ?? 12_000;
+    if (!Number.isSafeInteger(offset) || offset < 0 || !Number.isSafeInteger(limit) || limit < 1) throw new Error("offset must be a non-negative integer and limit a positive integer");
+    if (offset > 0 && rendered.codePointAt(offset - 1)! > 0xffff) throw new Error("offset must not split a Unicode surrogate pair");
+    const maxBytes = options.maxBytes ?? DEFAULT_MCP_OUTPUT_MAX_BYTES;
+    const maxLines = options.maxLines ?? DEFAULT_MCP_OUTPUT_MAX_LINES;
+    const notice = (end: number) => `[MCP result page: ${offset}–${end} of ${rendered.length} characters. Continue with offset: ${end}.]`;
+    const pageEnd = (byteCap: number, lineCap: number) => {
+      let end = offset;
+      let bytes = 0;
+      let lines = 1;
+      while (end < rendered.length && end - offset < limit) {
+        const width = rendered.codePointAt(end)! > 0xffff ? 2 : 1;
+        const char = rendered.slice(end, end + width);
+        bytes += byteLength(char);
+        if (char === "\n") lines++;
+        // Tiny caps still return one complete character plus recovery guidance.
+        if (end > offset && (bytes > byteCap || lines > lineCap || end + width - offset > limit)) break;
+        end += width;
+      }
+      return end;
+    };
+    let end = pageEnd(maxBytes, maxLines);
+    if (end < rendered.length) {
+      // The final offset cannot need more digits than the total length. Include the block separator.
+      end = pageEnd(maxBytes - byteLength(notice(rendered.length)) - 1, maxLines - 1);
+    }
+    const nextOffset = end < rendered.length ? end : null;
+    return { content: [{ type: "text" as const, text: rendered.slice(offset, end) }, ...(nextOffset !== null ? [{ type: "text" as const, text: notice(end) }] : [])], details: { ref, offset, nextOffset, totalCharacters: rendered.length, ...(input.path !== undefined ? { path: input.path } : {}) } };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { content: [{ type: "text" as const, text: message }], details: { error: "result_read_failed", message } };
+  }
+}
+
 function asRecord(value: unknown): Recordish | undefined {
   return typeof value === "object" && value !== null ? value as Recordish : undefined;
 }