@fitchmultz/pi-mcp-adapter 5.0.0 → 7.0.0

package/dist/lifecycle.d.ts

@@ -4,8 +4,6 @@ import { hasPendingAuth } from "./mcp-auth-flow.ts";
 export type ReconnectCallback = (serverName: string) => void;
 export type ReconnectFailureCallback = (serverName: string, error: unknown) => void;
 export declare class McpLifecycleManager {
-    private readonly manager;
-    private readonly hasPendingAuthForServer;
     private keepAliveServers;
     private allServers;
     private serverSettings;
@@ -23,6 +21,8 @@ export declare class McpLifecycleManager {
     pauseForCheckpoint(): () => void;
     private healthSignal;
     private removeHealthAbortListener;
+    private readonly manager;
+    private readonly hasPendingAuthForServer;
     constructor(manager: McpServerManager, hasPendingAuthForServer?: typeof hasPendingAuth);
     setReconnectCallback(callback: ReconnectCallback): void;
     setReconnectFailureCallback(callback: ReconnectFailureCallback): void;

package/dist/lifecycle.js

@@ -3,8 +3,6 @@ import { hasPendingAuth } from "./mcp-auth-flow.js";
 import { logger } from "./logger.js";
 import { formatTerminalError, sanitizeTerminalText } from "./utils.js";
 export class McpLifecycleManager {
-    manager;
-    hasPendingAuthForServer;
     keepAliveServers = new Map();
     allServers = new Map();
     serverSettings = new Map();
@@ -31,6 +29,8 @@ export class McpLifecycleManager {
     }
     healthSignal;
     removeHealthAbortListener;
+    manager;
+    hasPendingAuthForServer;
     constructor(manager, hasPendingAuthForServer = hasPendingAuth) {
         this.manager = manager;
         this.hasPendingAuthForServer = hasPendingAuthForServer;

package/dist/mcp-auth-flow.js

@@ -9,7 +9,7 @@ import { McpOAuthProvider, issuersMatch, loopbackRedirectsMatch, validateOAuthCl
 import { ensureCallbackServer, waitForCallback, cancelPendingCallback, stopCallbackServer, releaseCallbackServer, takeCallbackResult, } from "./mcp-callback-server.js";
 import { getAuthForUrl, clearAllCredentials, clearClientInfo, clearTokens, clearCodeVerifier, getOAuthState, clearOAuthState, getAuthBaseDir, } from "./mcp-auth.js";
 import { isServerDisabled, isNonInteractiveOAuth, validateServerProtocolConfig } from "./types.js";
-import { formatTerminalError, interpolateEnvRecord, interpolateEnvVars, normalizeRequestTimeoutMs } from "./utils.js";
+import { ADAPTER_VERSION, formatTerminalError, interpolateEnvRecord, interpolateEnvVars, normalizeRequestTimeoutMs } from "./utils.js";
 import { abortable, throwIfAborted } from "./abort.js";
 import { combineAbortSignals, isAbortError } from "./runtime-owner.js";
 function applyConfiguredScope(discovery, config) {
@@ -255,7 +255,7 @@ async function probeAuthDiscovery(serverUrl, definition, signal) {
     const timeout = normalizeRequestTimeoutMs(definition?.requestTimeoutMs) ?? 5000;
     const discoverySignal = combineAbortSignals(signal, AbortSignal.timeout(Math.ceil(timeout)));
     let discovery = {};
-    const client = new Client({ name: "pi-mcp-auth-discovery", version: "4.3.1" }, {
+    const client = new Client({ name: "pi-mcp-auth-discovery", version: ADAPTER_VERSION }, {
         versionNegotiation: { mode: definition?.protocolVersion ?? "auto" },
         ...(isNonInteractiveOAuth(definition?.oauth)
             ? { capabilities: { extensions: { [definition?.oauth && definition.oauth.crossAppAccess

package/dist/mcp-auth.d.ts

@@ -51,8 +51,8 @@ export interface AuthStorageOptions {
     baseDir?: string;
 }
 export declare class OAuthCredentialStoreError extends Error {
-    readonly operation: 'read' | 'write' | 'remove';
     readonly code = "OAUTH_CREDENTIAL_STORE_UNAVAILABLE";
+    readonly operation: 'read' | 'write' | 'remove';
     constructor(message: string, operation: 'read' | 'write' | 'remove', cause: unknown);
 }
 export type OAuthCredentialStatus = {

package/dist/mcp-auth.js

@@ -15,8 +15,8 @@ import { createRequire } from 'module';
 import { readFileSync, existsSync, rmSync } from 'fs';
 import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
-import { getAdapterPath, getAgentPath } from "./agent-dir.js";
-import { resolveConfiguredOAuthDir } from "./config.js";
+import { getAdapterPath, getAgentPath } from './agent-dir.js';
+import { resolveConfiguredOAuthDir } from './config.js';
 const require = createRequire(import.meta.url);
 const AUTH_SECRET_SERVICE = 'fitch-mcp-adapter.oauth';
 const LEGACY_AUTH_SECRET_SERVICE = 'pi-mcp-adapter.oauth';
@@ -30,8 +30,8 @@ const TEST_LINUX_KEYRING_RECOVERY_ENV = 'PI_MCP_ADAPTER_TEST_LINUX_KEYRING_RECOV
 const KEYRING_RECOVERY_TIMEOUT_MS = 10_000;
 const AUTH_CHUNK_MANIFEST_KEY = '__piMcpAdapterOAuthChunked';
 export class OAuthCredentialStoreError extends Error {
-    operation;
     code = 'OAUTH_CREDENTIAL_STORE_UNAVAILABLE';
+    operation;
     constructor(message, operation, cause) {
         super(isAndroidKeyringLoadFailure(cause)
             ? `${message}. Android/Termux: @napi-rs/keyring could not load a native binding. Persistent OAuth requires a supported platform with an OS credential store; no plaintext fallback is used.`

package/dist/mcp-code.d.ts

@@ -1,11 +1,17 @@
 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<{
     content: ContentBlock[];
     details: {
+        mode: string;
+        resultRefs?: string[];
+        error?: "aborted" | "call_capture_failed" | "script_error" | "timeout";
+        message?: string | undefined;
+        timeoutMs: number | null;
+        recovery?: {} | null;
         calls?: ({
             operation: "call";
             path: string;
@@ -41,11 +47,6 @@ declare function runMcpScriptOperation(state: McpExtensionState, code: string, t
             error: string;
             durationMs: number;
         })[];
-        recovery?: {} | null;
-        timeoutMs: number | null;
-        error?: "aborted" | "timeout" | "call_capture_failed" | "script_error";
-        message?: string | undefined;
-        mode: string;
     };
 }>;
 export {};

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 };
@@ -123,18 +122,21 @@ async function runMcpScriptOperation(state, code, timeoutMs = DEFAULT_MCP_SCRIPT
             ? Math.max(0, Date.now() - startedAt)
             : operation.durationMs,
     }));
-    let callsSnapshot;
-    const callTool = async (innerCallId, path, args) => {
+    const pendingOperations = new Set();
+    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)
@@ -147,37 +149,57 @@ async function runMcpScriptOperation(state, code, timeoutMs = DEFAULT_MCP_SCRIPT
                     : textFromContent(result.content);
             calls[index] = {
                 operation: "call", path, ok: false, error: errorCode, durationMs: Date.now() - startedAt, startedAt,
-                ...(errorCode === "ambiguous_outcome" ? { recovery: details.recovery } : {}),
+                ...(details.recovery !== undefined ? { recovery: details.recovery } : {}),
             };
             if (errorCode === "call_capture_failed")
                 throw new McpScriptCaptureError(details.recovery, message);
-            if (errorCode === "ambiguous_outcome")
+            if (details.recovery !== undefined)
                 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,
@@ -274,20 +301,40 @@ async function runMcpScriptOperation(state, code, timeoutMs = DEFAULT_MCP_SCRIPT
                     reject(new Error(message.message));
                     return;
                 }
-                void (async () => {
+                const operation = (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);
-                })().catch(reject);
+                })();
+                pendingOperations.add(operation);
+                void operation.catch(reject).finally(() => pendingOperations.delete(operation));
             });
             activeWorker.once("error", reject);
             activeWorker.once("exit", (code) => {
@@ -300,7 +347,6 @@ async function runMcpScriptOperation(state, code, timeoutMs = DEFAULT_MCP_SCRIPT
                 return;
             const timeoutError = new McpScriptTimeoutError(resolvedTimeoutMs);
             timer = setTimeout(() => {
-                callsSnapshot = snapshotCalls();
                 timeoutController.abort(timeoutError);
                 void activeWorker.terminate();
                 reject(timeoutError);
@@ -309,7 +355,6 @@ async function runMcpScriptOperation(state, code, timeoutMs = DEFAULT_MCP_SCRIPT
         const aborted = externalSignal
             ? new Promise((_resolve, reject) => {
                 const onAbort = () => {
-                    callsSnapshot = snapshotCalls();
                     void activeWorker.terminate();
                     reject(abortReasonError(externalSignal.reason));
                 };
@@ -342,20 +387,22 @@ async function runMcpScriptOperation(state, code, timeoutMs = DEFAULT_MCP_SCRIPT
     finally {
         clearTimeout(timer);
         removeAbortListener();
-        // "incomplete" means the call had not settled when the script finished
-        // (deadline, abort, or early return). Snapshot before aborting stragglers.
-        callsSnapshot ??= snapshotCalls();
+        worker?.removeAllListeners("message");
         // A script may finish without awaiting every call; abort leftovers so
         // parent-side dispatches do not outlive the script.
         timeoutController.abort(new Error("mcp_script finished"));
+        // Let cancelled dispatches report whether an outcome is known before taking the trace.
+        await Promise.allSettled(pendingOperations);
         await worker?.terminate();
     }
+    const callsSnapshot = snapshotCalls();
     // 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-oauth-provider.d.ts

@@ -49,11 +49,6 @@ export interface McpOAuthCallbacks {
  * Implements the OAuthClientProvider interface from the MCP SDK.
  */
 export declare class McpOAuthProvider implements OAuthClientProvider {
-    private serverName;
-    private serverUrl;
-    private config;
-    private callbacks;
-    private storageOptions;
     private readonly redirectUrlSnapshot;
     readonly clientMetadataUrl?: string;
     private readonly controller;
@@ -66,6 +61,11 @@ export declare class McpOAuthProvider implements OAuthClientProvider {
     private flowDiscoveryState;
     private flowIssuerMismatch;
     private flowState;
+    private serverName;
+    private serverUrl;
+    private config;
+    private callbacks;
+    private storageOptions;
     constructor(serverName: string, serverUrl: string, config: McpOAuthConfig, callbacks: McpOAuthCallbacks, storageOptions?: AuthStorageOptions, runtimeSignal?: AbortSignal, initialState?: string);
     private get isNonInteractive();
     private get discoveredIssuer();

package/dist/mcp-oauth-provider.js

@@ -152,11 +152,6 @@ function addAuthorizationParams(authorizationUrl, params) {
  * Implements the OAuthClientProvider interface from the MCP SDK.
  */
 export class McpOAuthProvider {
-    serverName;
-    serverUrl;
-    config;
-    callbacks;
-    storageOptions;
     redirectUrlSnapshot;
     clientMetadataUrl;
     controller = new AbortController();
@@ -169,6 +164,11 @@ export class McpOAuthProvider {
     flowDiscoveryState;
     flowIssuerMismatch = false;
     flowState;
+    serverName;
+    serverUrl;
+    config;
+    callbacks;
+    storageOptions;
     constructor(serverName, serverUrl, config, callbacks, storageOptions = {}, runtimeSignal, initialState) {
         this.serverName = serverName;
         this.serverUrl = serverUrl;

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: {
+        ref: string;
+        offset: number;
+        nextOffset: number | null;
+        totalCharacters: number;
+        path?: string;
+        error?: never;
+        message?: never;
+    };
+} | {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    details: {
+        error: string;
+        message: string;
+    };
+}>;