@fitchmultz/pi-mcp-adapter 5.0.0 → 6.0.0

package/dist/mcp-code.d.ts

@@ -1,6 +1,6 @@
 import type { ToolInfo } from "@earendil-works/pi-coding-agent";
 import type { McpExtensionState } from "./state.ts";
-import type { ContentBlock, McpOperationContext } from "./types.ts";
+import { type ContentBlock, type McpOperationContext } from "./types.ts";
 export declare const DEFAULT_MCP_SCRIPT_TIMEOUT_MS = 30000;
 export declare const runMcpScript: typeof runMcpScriptOperation;
 declare function runMcpScriptOperation(state: McpExtensionState, code: string, timeoutMs?: number | null, getPiTools?: () => ToolInfo[], signal?: AbortSignal, toolCallId?: string, beforeDispatch?: (signal: AbortSignal | undefined, operation: McpOperationContext) => Promise<void>): Promise<{
@@ -45,6 +45,7 @@ declare function runMcpScriptOperation(state: McpExtensionState, code: string, t
         timeoutMs: number | null;
         error?: "aborted" | "timeout" | "call_capture_failed" | "script_error";
         message?: string | undefined;
+        resultRefs?: string[];
         mode: string;
     };
 }>;

package/dist/mcp-code.js

@@ -1,11 +1,12 @@
 import { formatWithOptions } from "node:util";
 import { Worker } from "node:worker_threads";
-import { guardMcpOutput, guardedMcpDetails, resolveMcpOutputGuardOptions } from "./mcp-output-guard.js";
-import { executeCall } from "./proxy-modes.js";
+import { guardMcpOutput, guardedMcpDetails, resolveMcpOutputGuardOptions, readMcpResult, formatMcpResultReference, formatMcpPayloadFile } from "./mcp-output-guard.js";
+import { executeCall, executeConnect } from "./proxy-modes.js";
+import { executeResourceList, executeResourceRead } from "./resource-tools.js";
 import { combineAbortSignals } from "./runtime-owner.js";
 import { paginate, rankSuggestions, rankToolMatches } from "./search-ranking.js";
-import { findToolByName } from "./tool-metadata.js";
-import { renderTsShape } from "./ts-shape.js";
+import { catalogCoverage, toToolDescriptor } from "./tool-metadata.js";
+import { isServerDisabled } from "./types.js";
 export const DEFAULT_MCP_SCRIPT_TIMEOUT_MS = 30_000;
 class McpScriptTimeoutError extends Error {
     constructor(timeoutMs) {
@@ -73,11 +74,9 @@ function parseWorkerMessage(value) {
     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 };
@@ -124,17 +123,20 @@ async function runMcpScriptOperation(state, code, timeoutMs = DEFAULT_MCP_SCRIPT
             : operation.durationMs,
     }));
     let callsSnapshot;
-    const callTool = async (innerCallId, path, args) => {
+    const resultRefs = new Set();
+    const payloadNotices = new Set();
+    const recordCall = async (path, dispatch) => {
         // 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;
-        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 ?? []))
+            payloadNotices.add(formatMcpPayloadFile(file));
         if (details.error !== undefined) {
             const errorCode = String(details.error);
             const suggestions = Array.isArray(details.suggestions)
@@ -155,29 +157,49 @@ async function runMcpScriptOperation(state, code, timeoutMs = DEFAULT_MCP_SCRIPT
                 output.push({ type: "text", text: message });
             return {
                 ok: false,
+                ...(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,
-            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) => {
+    const callIdentity = (innerCallId) => ({ ...(toolCallId !== undefined ? { toolCallId } : {}), innerCallId });
+    const callTool = (innerCallId, path, args, server) => recordCall(path, () => executeCall(state, path, args, server, getPiTools, callSignal, callIdentity(innerCallId), beforeDispatch, { raw: true }));
+    const discoverServer = async (server) => {
+        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) => {
         const startedAt = Date.now();
         const query = typeof input?.query === "string" ? input.query : "";
         let error;
         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,
@@ -197,26 +219,31 @@ async function runMcpScriptOperation(state, code, timeoutMs = DEFAULT_MCP_SCRIPT
                 : { operation: "search", query, ok: false, error: error instanceof Error ? error.message : String(error), durationMs: Date.now() - startedAt, startedAt });
         }
     };
-    const describeTool = (input) => {
+    const describeTool = async (input) => {
         const startedAt = Date.now();
         const path = typeof input?.path === "string" ? input.path : "";
         let error;
         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 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) : [];
+            const suggestions = path ? rankSuggestions(state, path, 5, selectedServer) : [];
             error = "tool_not_found";
             return {
                 path,
@@ -277,13 +304,31 @@ async function runMcpScriptOperation(state, code, timeoutMs = DEFAULT_MCP_SCRIPT
                 void (async () => {
                     let envelope;
                     if (message.type === "call") {
-                        envelope = await callTool(message.id, message.path, message.args);
+                        envelope = await callTool(message.id, message.path, message.args, message.server);
                     }
                     else if (message.type === "search") {
-                        envelope = searchTools(message.input);
+                        envelope = await searchTools(message.input);
+                    }
+                    else if (message.type === "describe") {
+                        envelope = await describeTool(message.input);
+                    }
+                    else if (message.type === "readResult") {
+                        envelope = await readMcpResult(message.input, resolveMcpOutputGuardOptions(state.config.settings, state.outputDirectory));
                     }
                     else {
-                        envelope = describeTool(message.input);
+                        const input = message.input;
+                        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;
+                            envelope = await recordCall(`${server}:${uri}`, () => executeResourceRead(state, server, uri, callSignal, callIdentity(message.id), beforeDispatch, true));
+                        }
                     }
                     const response = { type: "result", id: message.id, envelope };
                     activeWorker.postMessage(response);
@@ -351,11 +396,12 @@ async function runMcpScriptOperation(state, code, timeoutMs = DEFAULT_MCP_SCRIPT
         await worker?.terminate();
     }
     // 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)" }], resolveMcpOutputGuardOptions(state.config.settings, state.outputDirectory));
+    const guarded = await guardMcpOutput([...(output.length > 0 ? output : [{ type: "text", text: "(no output)" }]), ...[...payloadNotices].map(text => ({ type: "text", text })), ...[...resultRefs].map(ref => ({ type: "text", 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/dist/mcp-output-guard.d.ts

@@ -38,16 +38,29 @@ 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 declare function resolveMcpOutputGuardOptions(settings?: McpSettings, outputDirectory?: string): Pick<McpOutputGuardOptions, "enabled" | "maxBytes" | "maxLines" | "detailsMaxBytes" | "outputDirectory">;
 /** Spread helper for tool-result details: includes mcpResult/outputGuard only when present. */
 export declare function guardedMcpDetails(guarded: GuardedMcpOutput): Record<string, unknown>;
@@ -57,3 +70,45 @@ export declare function guardedMcpDetails(guarded: GuardedMcpOutput): Record<str
  * they are delivered to the provider as native image content, not text context.
  */
 export declare function guardMcpOutput(content: ContentBlock[], options?: McpOutputGuardOptions): Promise<GuardedMcpOutput>;
+/**
+ * Bound details.mcpResult: keep the raw result when its JSON fits within
+ * detailsMaxBytes; otherwise replace it with a compact summary and spill the
+ * raw JSON to a temp file.
+ */
+export declare function retainMcpResult(result: unknown, options?: McpOutputGuardOptions, rawResult?: boolean): Promise<RetainedMcpResult>;
+export declare function formatMcpPayloadFile(file: McpPayloadFile): string;
+export declare function formatMcpResultReference(ref: string): 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 declare function readMcpResult(input: ReadMcpResultInput, options?: McpOutputGuardOptions): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    details: {
+        path?: string;
+        ref: string;
+        offset: number;
+        nextOffset: number | null;
+        totalCharacters: number;
+        error?: never;
+        message?: never;
+    };
+} | {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    details: {
+        error: string;
+        message: string;
+    };
+}>;

package/dist/mcp-output-guard.js

@@ -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";
 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;
@@ -24,6 +24,9 @@ export function guardedMcpDetails(guarded) {
     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 } : {}),
     };
 }
 /**
@@ -34,18 +37,17 @@ export function guardedMcpDetails(guarded) {
 export async function guardMcpOutput(content, options = {}) {
     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 ?? "";
     const normalizedContent = withEmptyTextFallback(content.length > 0
         ? sanitizeContent(content)
         : [{ type: "text", text: options.emptyTextFallback ?? "(empty result)" }], 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) => reference ? [...blocks, { type: "text", 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
         .filter((block) => block.type === "text")
@@ -53,15 +55,17 @@ export async function guardMcpOutput(content, options = {}) {
         .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 = addAffixes(normalizedContent, prefix, suffix);
     let outputGuard;
-    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", text: finalText }, ...imageBlocks];
         outputGuard = {
             truncated: true,
@@ -74,13 +78,10 @@ export async function guardMcpOutput(content, options = {}) {
             ...(writeError !== undefined ? { writeError } : {}),
         };
     }
-    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,
     };
 }
 function sanitizeContent(content) {
@@ -187,15 +188,45 @@ function formatTruncationNotice(stats, fullOutputPath, writeError) {
  * detailsMaxBytes; otherwise replace it with a compact summary and spill the
  * raw JSON to a temp file.
  */
-async function boundMcpResult(result, detailsMaxBytes, outputDirectory) {
+export async function retainMcpResult(result, options = {}, rawResult = false) {
     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) => {
+        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, ...(typeof resource?.uri === "string" ? { uri: resource.uri } : {}), ...(typeof mimeType === "string" ? { mimeType } : {}), ...await saveArtifact("payload", Buffer.from(data, "base64"), options.outputDirectory) };
+    }))).filter((file) => 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 } : {}),
+    };
 }
-async function summarizeMcpResult(result, raw, rawBytes, outputDirectory) {
-    const { path: fullResultPath, error: resultWriteError } = await saveArtifact("mcp-result", raw, outputDirectory);
+export function formatMcpPayloadFile(file) {
+    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}`}]`;
+}
+export function formatMcpResultReference(ref) {
+    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, rawBytes, artifact) {
+    const { path: fullResultPath, error: resultWriteError } = artifact;
     const record = asRecord(result);
     const content = Array.isArray(record?.content) ? record.content : [];
     const summary = {
@@ -281,7 +312,7 @@ async function saveArtifact(kind, text, 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 };
     }
@@ -289,6 +320,80 @@ async function saveArtifact(kind, text, outputDirectory) {
         return { error: error instanceof Error ? error.message : String(error) };
     }
 }
+export async function readMcpResult(input, options = {}) {
+    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 = 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[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) => {
+                    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[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) => `[MCP result page: ${offset}–${end} of ${rendered.length} characters. Continue with offset: ${end}.]`;
+        const pageEnd = (byteCap, lineCap) => {
+            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", text: rendered.slice(offset, end) }, ...(nextOffset !== null ? [{ type: "text", 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", text: message }], details: { error: "result_read_failed", message } };
+    }
+}
 function asRecord(value) {
     return typeof value === "object" && value !== null ? value : undefined;
 }

package/dist/mcp-panel.d.ts

@@ -1,6 +1,6 @@
 import { type PanelKeybindings } from "./panel-keys.ts";
 import type { McpConfig, McpPanelCallbacks, McpPanelResult, ServerProvenance } from "./types.ts";
-import type { MetadataCache } from "./metadata-cache.ts";
+import { type MetadataCache } from "./metadata-cache.ts";
 declare class McpPanel {
     private callbacks;
     private done;