@fitchmultz/pi-mcp-adapter 7.1.0 → 8.0.0

package/dist/direct-tools.js

@@ -3,6 +3,7 @@ import { parseDirectToolSelectors } from "./metadata-cache.js";
 export { getMissingConfiguredDirectToolServers } from "./metadata-cache.js";
 import { executeCall } from "./proxy-modes.js";
 import { isServerDisabled } from "./types.js";
+import { nativeMcpResult } from "./tool-registrar.js";
 export function directToolSelection(config, serverName, envOverride) {
     if (envOverride) {
         const selection = parseDirectToolSelectors(envOverride);
@@ -33,20 +34,20 @@ export function createDirectToolExecutor(getState, getInitPromise, spec, beforeE
             catch (error) {
                 throwIfAborted(signal);
                 const message = error instanceof Error ? error.message : String(error);
-                return {
+                return nativeMcpResult({
                     content: [{ type: "text", text: `MCP initialization failed: ${message}` }],
                     details: { error: "init_failed", message },
-                };
+                }, !!spec.outputSchema);
             }
         }
         if (!state) {
-            return {
+            return nativeMcpResult({
                 content: [{ type: "text", text: "MCP not initialized" }],
                 details: { error: "not_initialized" },
-            };
+            }, !!spec.outputSchema);
         }
         const result = await executeCall(state, spec.originalName, params, spec.serverName, undefined, signal, { toolCallId }, beforeExecute ? (callSignal, operation) => beforeExecute(toolCallId, { ...ctx, signal: callSignal }, operation) : undefined, { exactOriginalName: true, ...(spec.resourceUri ? { resourceUri: spec.resourceUri } : {}) });
         const { mode: _mode, ...details } = result.details;
-        return { ...result, details };
+        return nativeMcpResult({ ...result, details }, !!spec.outputSchema);
     };
 }

package/dist/error-signal.d.ts

@@ -1,11 +1,9 @@
 /**
- * Decide the `isError` override for a finished tool result in the `tool_result` hook.
+ * Classify returned MCP execution failures for Pi's native result-level isError.
  *
  * A failed MCP tool call is *returned* (not thrown), tagged `details.error: "tool_error"` (the server
- * returned an error result) or `"call_failed"` (the call itself threw and was caught). pi never reads a
- * result-level `isError`, so without this such a call is recorded as a success. Returning
- * `{ isError: true }` (and nothing else) flips the flag; pi's field-by-field merge keeps the original
- * `content` and `details` intact.
+ * returned an error result) or `"call_failed"` (the call itself threw and was caught).
+ * Spread this onto the returned result without replacing human or structured content.
  *
  * Limited to those two codes: the adapter's other `details.error` values (`auth_required`, connection
  * states, search/validation feedback, ...) are not failed tool calls, so they get no override.

package/dist/error-signal.js

@@ -1,11 +1,9 @@
 /**
- * Decide the `isError` override for a finished tool result in the `tool_result` hook.
+ * Classify returned MCP execution failures for Pi's native result-level isError.
  *
  * A failed MCP tool call is *returned* (not thrown), tagged `details.error: "tool_error"` (the server
- * returned an error result) or `"call_failed"` (the call itself threw and was caught). pi never reads a
- * result-level `isError`, so without this such a call is recorded as a success. Returning
- * `{ isError: true }` (and nothing else) flips the flag; pi's field-by-field merge keeps the original
- * `content` and `details` intact.
+ * returned an error result) or `"call_failed"` (the call itself threw and was caught).
+ * Spread this onto the returned result without replacing human or structured content.
  *
  * Limited to those two codes: the adapter's other `details.error` values (`auth_required`, connection
  * states, search/validation feedback, ...) are not failed tool calls, so they get no override.

package/dist/index.js

@@ -10,17 +10,15 @@ import { executeAuthComplete, executeAuthStart, executeCall, executeConnect, exe
 import { formatTerminalError } from "./utils.js";
 import { createOAuthRuntime, shutdownOAuth } from "./mcp-auth-flow.js";
 import { renderMcpProxyToolCall, renderMcpToolResult } from "./tool-result-renderer.js";
-import { toolErrorOverride } from "./error-signal.js";
 import { createMcpRuntimeOwner, createOwnedUi, isAbortError } from "./runtime-owner.js";
 import { publishMcpStatusShutdown } from "./mcp-status.js";
 import { DEFAULT_MCP_SCRIPT_TIMEOUT_MS, runMcpScript } from "./mcp-code.js";
 import { MAX_PAGE_SIZE, paginate, rankToolMatches } from "./search-ranking.js";
-import { createToolLoader, supportsNativeAsync } from "./tool-loader.js";
+import { createToolLoader } from "./tool-loader.js";
 import { gatewayParameters, prepareGatewayArguments } from "./gateway-arguments.js";
 import { executeResourceList, executeResourceRead } from "./resource-tools.js";
 import { guardMcpOutput, guardedMcpDetails, readMcpResult, resolveMcpOutputGuardOptions } from "./mcp-output-guard.js";
 import { abortable, throwIfAborted } from "./abort.js";
-import { onSessionCheckpoint, prepareMcpCheckpoint } from "./checkpoint.js";
 export { MCP_STATUS_EVENT, MCP_STATUS_SNAPSHOT_VERSION, } from "./types.js";
 const INIT_WAIT_TIMEOUT_MS = 30_000;
 const INIT_WAIT_TIMED_OUT = Symbol("init-wait-timed-out");
@@ -95,7 +93,6 @@ function installMcpAdapter(pi, options) {
     const envDirectToolOverride = envRaw?.split(",").map(s => s.trim()).filter(Boolean);
     const toolLoader = createToolLoader(pi, () => state, () => initPromise, beforeExecute);
     let runtimeCwd;
-    let nativeAsyncSupported = false;
     let proxyToolRegistered = false;
     let proxyToolDescription = null;
     let directToolsFrozen = false;
@@ -112,7 +109,7 @@ function installMcpAdapter(pi, options) {
     function syncToolSurface(ctx) {
         const config = state?.config ?? currentConfig;
         const cache = loadMetadataCache(state?.metadataCacheEnabled ?? false);
-        toolLoader.sync(config, cache, envRaw === "__none__" ? null : envDirectToolOverride, nativeAsyncSupported, specs => syncGateways(config, cache, specs));
+        toolLoader.sync(config, cache, envRaw === "__none__" ? null : envDirectToolOverride, specs => syncGateways(config, cache, specs));
     }
     const registeredPromptCommands = new Set();
     function registerPromptCommands(specs) {
@@ -202,7 +199,6 @@ function installMcpAdapter(pi, options) {
     }
     async function startSession(ctx) {
         runtimeCwd = ctx.cwd;
-        nativeAsyncSupported = supportsNativeAsync(ctx);
         directToolsFrozen = false;
         const generation = ++lifecycleGeneration;
         const previousState = state;
@@ -249,7 +245,7 @@ function installMcpAdapter(pi, options) {
         toolLoader.restore(ctx);
         registerPromptCommands(resolveCachedPrompts(runtimeConfig, metadataCacheEnabled));
         const runtimeCache = loadMetadataCache(metadataCacheEnabled);
-        toolLoader.sync(runtimeConfig, runtimeCache, envRaw === "__none__" ? null : envDirectToolOverride, nativeAsyncSupported, specs => syncGateways(runtimeConfig, runtimeCache, specs));
+        toolLoader.sync(runtimeConfig, runtimeCache, envRaw === "__none__" ? null : envDirectToolOverride, specs => syncGateways(runtimeConfig, runtimeCache, specs));
         const initialization = startInitialization(ctx, owner, oauthRuntime, runtimeConfig, generation);
         if (envRaw !== undefined && envRaw !== "__none__") {
             const missingEnvDirectTools = getMissingConfiguredDirectToolServers(runtimeConfig, runtimeCache, envDirectToolOverride);
@@ -264,7 +260,6 @@ function installMcpAdapter(pi, options) {
         syncToolSurface(ctx);
     });
     pi.on("model_select", (_event, ctx) => {
-        nativeAsyncSupported = supportsNativeAsync(ctx);
         if (state)
             syncToolSurface(ctx);
     });
@@ -272,13 +267,6 @@ function installMcpAdapter(pi, options) {
         if (ctx.cwd !== runtimeCwd)
             await startSession(ctx);
     });
-    onSessionCheckpoint(pi, async (event) => {
-        if (initPromise)
-            return { sleepReady: false, reason: "MCP initialization is active" };
-        if (!state || !currentOwner?.isActive())
-            return { sleepReady: false, reason: "MCP runtime is not initialized" };
-        return prepareMcpCheckpoint(state, event);
-    });
     pi.on("session_shutdown", async () => {
         // Cached tool selections exist before background server initialization finishes.
         toolLoader.persist();
@@ -303,8 +291,6 @@ function installMcpAdapter(pi, options) {
         if (failures.length)
             throw new AggregateError(failures, "MCP session shutdown persistence/cleanup failed");
     });
-    // Re-flag returned MCP tool failures so pi registers them as errors (see toolErrorOverride).
-    pi.on("tool_result", (event) => toolErrorOverride(event.details));
     function createCommandContext(ctx) {
         const owner = currentOwner;
         const hasUI = ctx.hasUI;
@@ -519,7 +505,7 @@ function installMcpAdapter(pi, options) {
         owner?.throwIfInactive();
         return state ?? { content: [{ type: "text", text: "MCP not initialized" }], details: { error: "not_initialized" } };
     }
-    const unavailableFeatures = (enable = [], tools) => enable.filter(feature => !tools.some(tool => tool.name === (feature === "gateway" ? "mcp" : "mcp_script") && !tool.namespace));
+    const unavailableFeatures = (enable = [], tools) => enable.filter(feature => !tools.some(tool => tool.name === (feature === "gateway" ? "mcp" : "mcp_script")));
     async function searchAndLoad(params, signal, ctx) {
         throwIfAborted(signal);
         if (params.query === undefined && !params.enable?.length)
@@ -544,7 +530,7 @@ function installMcpAdapter(pi, options) {
         const page = paginate(matches, params.offset ?? 0, params.limit ?? 5);
         const tools = toolLoader.activate(page.items, params.enable);
         const unavailable = unavailableFeatures(params.enable, tools);
-        const typedCount = tools.filter(tool => tool.namespace || (tool.name !== "mcp" && tool.name !== "mcp_script")).length;
+        const typedCount = tools.filter(tool => tool.name !== "mcp" && tool.name !== "mcp_script").length;
         const result = executeSearch(ready, params.query, params.server, typedCount < page.items.length, params.limit ?? 5, params.offset, "mcp_search");
         const guarded = await guardMcpOutput([
             ...result.content,
@@ -574,10 +560,7 @@ function installMcpAdapter(pi, options) {
             return searchAndLoad(params, signal, ctx);
         },
     };
-    if (toolLoader.native)
-        pi.registerToolSearch(searchDefinition);
-    else
-        pi.registerTool(searchDefinition);
+    pi.registerTool(searchDefinition);
     let scriptToolRegistered = false;
     function registerScriptTool() {
         if (scriptToolRegistered)

package/dist/init.js

@@ -43,7 +43,6 @@ export function recordFailure(state, serverName, message) {
             getFailureExpiryTimers(state).delete(serverName);
             return;
         }
-        state.owner.beforeActivity();
         if (state.failureTracker.get(serverName) === failedAt) {
             state.failureTracker.delete(serverName);
             state.failureMessages?.delete(serverName);

package/dist/lifecycle.d.ts

@@ -15,10 +15,6 @@ export declare class McpLifecycleManager {
     private activeHealthCheck;
     private shutdownPromise;
     private stopped;
-    private checkpointPauses;
-    hasActiveHealthCheck(): boolean;
-    /** Skip ticks, without cancelling accepted work or permanently closing the manager. */
-    pauseForCheckpoint(): () => void;
     private healthSignal;
     private removeHealthAbortListener;
     private readonly manager;

package/dist/lifecycle.js

@@ -14,19 +14,6 @@ export class McpLifecycleManager {
     activeHealthCheck;
     shutdownPromise;
     stopped = false;
-    checkpointPauses = 0;
-    hasActiveHealthCheck() { return this.activeHealthCheck !== undefined; }
-    /** Skip ticks, without cancelling accepted work or permanently closing the manager. */
-    pauseForCheckpoint() {
-        this.checkpointPauses++;
-        let released = false;
-        return () => {
-            if (!released) {
-                released = true;
-                this.checkpointPauses--;
-            }
-        };
-    }
     healthSignal;
     removeHealthAbortListener;
     manager;
@@ -81,7 +68,7 @@ export class McpLifecycleManager {
         signal?.addEventListener("abort", stop, { once: true });
         this.removeHealthAbortListener = () => signal?.removeEventListener("abort", stop);
         this.healthCheckInterval = setInterval(() => {
-            if (this.stopped || signal?.aborted || this.activeHealthCheck || this.checkpointPauses > 0)
+            if (this.stopped || signal?.aborted || this.activeHealthCheck)
                 return;
             const check = this.checkConnections(signal)
                 .catch(error => {

package/dist/mcp-auth-flow.d.ts

@@ -9,7 +9,6 @@ import { type AuthStorageOptions } from "./mcp-auth.ts";
 import { type ServerEntry } from "./types.ts";
 /** Auth status for a server */
 export type AuthStatus = "authenticated" | "expired" | "not_authenticated";
-import type { McpCheckpointEvent } from "./checkpoint.ts";
 export interface McpOAuthRuntime {
     readonly signal: AbortSignal;
 }
@@ -20,8 +19,6 @@ export interface AuthenticateOptions {
     runtime?: McpOAuthRuntime;
 }
 export declare function createOAuthRuntime(signal?: AbortSignal): McpOAuthRuntime;
-export declare function holdOAuthCheckpoint(runtime: McpOAuthRuntime, event: McpCheckpointEvent): () => void;
-export declare function getOAuthCheckpointBlocker(runtime: McpOAuthRuntime): string | undefined;
 type OAuthRequest = {
     serverName: string;
     serverUrl: string;
@@ -46,8 +43,7 @@ export declare function extractOAuthConfig(definition: ServerEntry): McpOAuthCon
  * Start OAuth authentication flow for a server.
  * Returns the authorization URL when browser authorization is required.
  */
-export declare const startAuth: typeof startAuthOperation;
-declare function startAuthOperation(serverName: string, serverUrl: string, definition?: ServerEntry, options?: AuthenticateOptions): Promise<{
+export declare function startAuth(serverName: string, serverUrl: string, definition?: ServerEntry, options?: AuthenticateOptions): Promise<{
     authorizationUrl: string;
 }>;
 /** Authorization code plus the optional RFC 9207 `iss` callback parameter. */
@@ -74,8 +70,7 @@ export declare function completeAuthFromInput(serverName: string, input?: string
 /**
  * Complete OAuth authentication with an explicit code or a captured callback.
  */
-export declare const completeAuth: typeof completeAuthOperation;
-declare function completeAuthOperation(serverName: string, authorizationCode?: string | AuthorizationResponseInput, options?: AuthenticateOptions): Promise<AuthStatus>;
+export declare function completeAuth(serverName: string, authorizationCode?: string | AuthorizationResponseInput, options?: AuthenticateOptions): Promise<AuthStatus>;
 /**
  * Perform the complete OAuth authentication flow for a server.
  *
@@ -90,8 +85,7 @@ export declare function authenticate(serverName: string, serverUrl: string, defi
  *
  * @param serverName - The name of the MCP server
  */
-export declare const removeAuth: typeof removeAuthOperation;
-declare function removeAuthOperation(serverName: string, options?: AuthenticateOptions): Promise<void>;
+export declare function removeAuth(serverName: string, options?: AuthenticateOptions): Promise<void>;
 /**
  * Check if OAuth is supported for a server configuration.
  * OAuth is supported for HTTP servers unless explicitly disabled.

package/dist/mcp-auth-flow.js

@@ -42,7 +42,6 @@ export function createOAuthRuntime(signal) {
     runtimeStates.set(runtime, {
         controller,
         generation: 0,
-        activeOperations: 0,
         pendingAuths: new Map(),
         pendingAuthStates: new Map(),
         pendingAuthCleanupTimers: new Map(),
@@ -71,36 +70,6 @@ function getRuntimeState(runtime) {
         throw new Error("Unknown OAuth runtime");
     return state;
 }
-export function holdOAuthCheckpoint(runtime, event) {
-    const state = getRuntimeState(runtime);
-    if (state.checkpoint)
-        throw new Error("MCP OAuth checkpoint is already held");
-    state.checkpoint = event;
-    return () => { if (state.checkpoint === event)
-        state.checkpoint = undefined; };
-}
-export function getOAuthCheckpointBlocker(runtime) {
-    const state = getRuntimeState(runtime);
-    if (state.activeOperations || state.pendingAuthentications.size)
-        return "MCP OAuth operation is active";
-    if (state.pendingAuths.size || state.pendingAuthStates.size || state.pendingAuthCleanupTimers.size)
-        return "MCP browser OAuth callback/flow is pending";
-    // requests caches server challenges/discovery, not a pending user callback.
-    // Cold connect re-challenges; granted scopes and issuer bindings live in the
-    // native credential store. Actual interactive/auth operations veto above.
-    return undefined;
-}
-async function withOAuthOperation(runtime, run) {
-    const state = getRuntimeState(runtime);
-    state.checkpoint?.invalidate();
-    state.activeOperations++;
-    try {
-        return await run();
-    }
-    finally {
-        state.activeOperations--;
-    }
-}
 function getPendingAuthKey(serverName, options) {
     return JSON.stringify([serverName, getAuthBaseDir(options)]);
 }
@@ -118,7 +87,6 @@ export function getOAuthRequest(serverName, serverUrl, storageBase, runtime = le
 export function recordOAuthChallenge(serverName, serverUrl, storageBase, error, runtime = legacyRuntime) {
     if (runtime.signal.aborted || !isOAuthChallenge(error))
         return;
-    getRuntimeState(runtime).checkpoint?.invalidate();
     const previous = getOAuthRequest(serverName, serverUrl, storageBase, runtime);
     const request = { ...previous, serverName, serverUrl };
     if (error instanceof InsufficientScopeError) {
@@ -315,8 +283,7 @@ function parseOAuthRedirectUri(redirectUri) {
  * Start OAuth authentication flow for a server.
  * Returns the authorization URL when browser authorization is required.
  */
-export const startAuth = async (...args) => withOAuthOperation(getRuntime(args[3]), () => startAuthOperation(...args));
-async function startAuthOperation(serverName, serverUrl, definition, options = {}) {
+export async function startAuth(serverName, serverUrl, definition, options = {}) {
     if (isServerDisabled(definition))
         throw new Error(`MCP server "${serverName}" is disabled`);
     const runtime = getRuntime(options);
@@ -479,10 +446,7 @@ async function setPendingAuth(runtime, serverName, pendingAuth, oauthState, sign
     cleanupTimer.unref?.();
     state.pendingAuthCleanupTimers.set(key, cleanupTimer);
 }
-function clearPendingAuth(...args) {
-    return withOAuthOperation(args[0], () => clearPendingAuthOperation(...args));
-}
-async function clearPendingAuthOperation(runtime, serverName, oauthState, fallbackStorageOptions = {}) {
+async function clearPendingAuth(runtime, serverName, oauthState, fallbackStorageOptions = {}) {
     const state = getRuntimeState(runtime);
     const key = getPendingAuthKey(serverName, fallbackStorageOptions);
     const pendingAuth = state.pendingAuths.get(key);
@@ -576,8 +540,7 @@ export async function completeAuthFromInput(serverName, input, options = {}) {
 /**
  * Complete OAuth authentication with an explicit code or a captured callback.
  */
-export const completeAuth = async (...args) => withOAuthOperation(getRuntime(args[2]), () => completeAuthOperation(...args));
-async function completeAuthOperation(serverName, authorizationCode, options = {}) {
+export async function completeAuth(serverName, authorizationCode, options = {}) {
     const runtime = getRuntime(options);
     const runtimeState = getRuntimeState(runtime);
     const fallbackAuthStorageOptions = options.authStorageOptions ?? {};
@@ -743,8 +706,7 @@ export async function authenticate(serverName, serverUrl, definition, options =
  *
  * @param serverName - The name of the MCP server
  */
-export const removeAuth = async (...args) => withOAuthOperation(getRuntime(args[1]), () => removeAuthOperation(...args));
-async function removeAuthOperation(serverName, options = {}) {
+export async function removeAuth(serverName, options = {}) {
     const runtime = getRuntime(options);
     const signal = combineAbortSignals(runtime.signal, options.signal);
     throwIfAborted(signal);
@@ -811,7 +773,6 @@ export async function shutdownOAuth(runtime = legacyRuntime) {
     const state = getRuntimeState(runtime);
     if (state.controller.signal.aborted)
         return;
-    state.checkpoint?.invalidate();
     state.generation += 1;
     state.controller.abort(new Error("OAuth runtime stopped"));
     for (const callbackState of Array.from(state.pendingAuthStates.values()))

package/dist/mcp-code.js

@@ -98,7 +98,6 @@ class McpScriptCaptureError extends Error {
 }
 export const runMcpScript = async (...args) => {
     const state = args[0];
-    state.owner?.beforeActivity();
     state.activeScripts = (state.activeScripts ?? 0) + 1;
     try {
         return await runMcpScriptOperation(...args);

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

@@ -78,6 +78,11 @@ export declare function guardMcpOutput(content: ContentBlock[], options?: McpOut
 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;
+/** Stream histories through the same private output-artifact and paged-reader boundary. */
+export declare function saveMcpOutputStream(chunks: AsyncIterable<string>, outputDirectory?: string): Promise<{
+    path?: string;
+    error?: string;
+}>;
 export interface ReadMcpResultInput {
     ref: string;
     /** RFC 6901 JSON Pointer. Omit to read the entire retained result. */

package/dist/mcp-output-guard.js

@@ -1,5 +1,6 @@
 import { randomBytes } from "node:crypto";
-import { mkdir, mkdtemp, readFile, realpath, writeFile } from "node:fs/promises";
+import { mkdir, mkdtemp, open, readFile, realpath, writeFile } from "node:fs/promises";
+import { createReadStream } from "node:fs";
 import { tmpdir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
 export const DEFAULT_MCP_OUTPUT_MAX_BYTES = 50 * 1024;
@@ -320,6 +321,26 @@ async function saveArtifact(kind, text, outputDirectory) {
         return { error: error instanceof Error ? error.message : String(error) };
     }
 }
+/** Stream histories through the same private output-artifact and paged-reader boundary. */
+export async function saveMcpOutputStream(chunks, outputDirectory) {
+    const artifact = await saveArtifact("output", "", outputDirectory);
+    if (!artifact.path)
+        return artifact;
+    try {
+        const file = await open(artifact.path, "a");
+        try {
+            for await (const chunk of chunks)
+                await file.writeFile(chunk);
+        }
+        finally {
+            await file.close();
+        }
+        return artifact;
+    }
+    catch (error) {
+        return { error: error instanceof Error ? error.message : String(error) };
+    }
+}
 export async function readMcpResult(input, options = {}) {
     try {
         if (!input || typeof input.ref !== "string")
@@ -330,6 +351,39 @@ export async function readMcpResult(input, options = {}) {
         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");
+        // Plain output pages without flattening a complete UI history into memory.
+        if (basename(ref).startsWith("output-") && input.path === undefined && input.fields === undefined) {
+            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");
+            const maxBytes = Math.max(1, (options.maxBytes ?? DEFAULT_MCP_OUTPUT_MAX_BYTES) - 256);
+            const maxLines = Math.max(1, (options.maxLines ?? DEFAULT_MCP_OUTPUT_MAX_LINES) - 1);
+            let total = 0, bytes = 0, lines = 1;
+            let page = "";
+            let finished = false;
+            for await (const chunk of createReadStream(ref, { encoding: "utf8" })) {
+                for (const char of chunk) {
+                    if (total < offset && total + char.length > offset)
+                        throw new Error("offset must not split a Unicode surrogate pair");
+                    if (total >= offset && !finished) {
+                        const nextBytes = bytes + byteLength(char);
+                        const nextLines = lines + (char === "\n" ? 1 : 0);
+                        if (page && (nextBytes > maxBytes || nextLines > maxLines || page.length + char.length > limit))
+                            finished = true;
+                        else {
+                            page += char;
+                            bytes = nextBytes;
+                            lines = nextLines;
+                        }
+                    }
+                    total += char.length;
+                }
+            }
+            const end = offset + page.length;
+            const nextOffset = end < total ? end : null;
+            return { content: [{ type: "text", text: page }, ...(nextOffset !== null ? [{ type: "text", text: `[MCP result page: ${offset}–${end} of ${total} characters. Continue with offset: ${end}.]` }] : [])], details: { ref, offset, nextOffset, totalCharacters: total } };
+        }
         let rendered = await readFile(ref, "utf8");
         if (input.path !== undefined || input.fields !== undefined || basename(ref).startsWith("mcp-result-")) {
             let value = JSON.parse(rendered);

package/dist/proxy-modes.d.ts

@@ -4,7 +4,7 @@ import type { ServerConnection } from "./server-manager.ts";
 import type { ToolMetadata, McpOperationContext, McpToolCallIdentity } from "./types.ts";
 import { type SessionRecoveryDeps } from "./session-recovery.ts";
 type ProxyToolResult = AgentToolResult<Record<string, unknown>>;
-export declare function executeUiMessages(state: McpExtensionState): ProxyToolResult;
+export declare function executeUiMessages(state: McpExtensionState): Promise<ProxyToolResult>;
 export declare function executeStatus(state: McpExtensionState): ProxyToolResult;
 export declare function executeAuthStart(state: McpExtensionState, serverName: string, signal?: AbortSignal): Promise<ProxyToolResult>;
 export declare function executeAuthComplete(state: McpExtensionState, serverName: string, input?: string, signal?: AbortSignal): Promise<ProxyToolResult>;