@fitchmultz/pi-mcp-adapter 7.1.1 → 8.0.0

package/dist/proxy-modes.js

@@ -6,13 +6,14 @@ import { combineAbortSignals, isAbortError } from "./runtime-owner.js";
 import { buildToolMetadata, catalogCoverage, findToolByName, formatSchema, toToolDescriptor } from "./tool-metadata.js";
 import { reconstructPromptMetadata } from "./metadata-cache.js";
 import { renderMcpResultContent } from "./tool-registrar.js";
-import { guardMcpOutput, guardedMcpDetails, retainMcpResult, resolveMcpOutputGuardOptions, formatMcpResultReference } from "./mcp-output-guard.js";
+import { guardMcpOutput, guardedMcpDetails, retainMcpResult, resolveMcpOutputGuardOptions, formatMcpResultReference, saveMcpOutputStream } from "./mcp-output-guard.js";
 import { maybeStartUiSession, summarizeUiSessionResult } from "./ui-session.js";
 import { formatAuthRequiredMessage, formatMcpStatus, resolveServerUrl, truncateAtWord } from "./utils.js";
 import { authenticate, completeAuthFromInput, startAuth, supportsOAuth } from "./mcp-auth-flow.js";
 import { isInterruptedToolCall, isToolTransportFailure, trackToolCallOutcome, SessionRecoveryAuthRequiredError, withSessionRecovery } from "./session-recovery.js";
 import { paginate, rankSuggestions, rankToolMatches } from "./search-ranking.js";
 import { ensureToolCallApproved, isToolCallApprovalRequired } from "./tool-approval.js";
+import { materializeUiMessages, uiMessages } from "./ui-message-history.js";
 const INSTRUCTIONS_PREVIEW_LENGTH = 300;
 function disabledResult(mode, serverName) {
     const message = `Server "${serverName}" is disabled. Run /mcp enable ${serverName} and /reload to enable it.`;
@@ -120,8 +121,80 @@ async function attemptAutoAuth(state, serverName, signal) {
         };
     }
 }
-export function executeUiMessages(state) {
-    const sessions = state.completedUiSessions;
+async function* uiSessionText(session) {
+    yield `\n## ${session.serverName} / ${session.toolName} (${session.completedAt.toLocaleTimeString()}, ${session.reason})`;
+    let heading = false;
+    for await (const prompt of uiMessages(session.messages, "prompts")) {
+        if (parseUiPromptHandoff(prompt))
+            continue;
+        if (!heading) {
+            yield "\n\n### Prompts:";
+            heading = true;
+        }
+        yield `\n- ${prompt}`;
+    }
+    heading = false;
+    for await (const value of uiMessages(session.messages, "intents")) {
+        const intent = value;
+        if (!heading) {
+            yield "\n\n### Intents:";
+            heading = true;
+        }
+        yield `\n- ${intent.intent}${intent.params ? ` (${JSON.stringify(intent.params)})` : ""}`;
+    }
+    for await (const prompt of uiMessages(session.messages, "prompts")) {
+        const handoff = parseUiPromptHandoff(prompt);
+        if (!handoff)
+            continue;
+        if (!heading) {
+            yield "\n\n### Intents:";
+            heading = true;
+        }
+        yield `\n- ${handoff.intent} (${JSON.stringify(handoff.params)})`;
+    }
+    if (session.messages.contexts.length) {
+        yield "\n\n### Context updates:";
+        for (const context of session.messages.contexts)
+            yield `\n- ${context.summary}${context.truncated ? " (truncated)" : ""}`;
+    }
+    heading = false;
+    for await (const notification of uiMessages(session.messages, "notifications")) {
+        if (!heading) {
+            yield "\n\n### Notifications:";
+            heading = true;
+        }
+        yield `\n- ${notification}`;
+    }
+}
+export async function executeUiMessages(state) {
+    const pending = [...state.completedUiSessions];
+    const options = resolveMcpOutputGuardOptions(state.config?.settings, state.outputDirectory);
+    // Bound both inline output and details. Large retrieval streams; it never flattens all events.
+    const size = pending.reduce((bytes, session) => bytes + (session.messages.historyBytes ?? 0) + Buffer.byteLength(JSON.stringify(session.messages)), 0);
+    const large = size > Math.min(options.maxBytes, options.detailsMaxBytes);
+    const warnings = pending.flatMap(session => session.messages.historyError ? [session.messages.historyError] : []);
+    const paged = async () => {
+        async function* output() {
+            yield `UI Session Messages (${pending.length} sessions):\n`;
+            for (const session of pending)
+                yield* uiSessionText(session);
+        }
+        const artifact = await saveMcpOutputStream(output(), state.outputDirectory);
+        if (!artifact.path)
+            return { content: [{ type: "text", text: `UI messages remain available; retrieval could not be saved: ${artifact.error}` }], isError: true, details: { error: "ui_history_delivery_failed", cleared: false } };
+        // Newly completed sessions during I/O are not part of this drain.
+        state.completedUiSessions = state.completedUiSessions.filter(session => !pending.includes(session));
+        return { content: [{ type: "text", text: `UI Session Messages (${pending.length} sessions). ${formatMcpResultReference(artifact.path)}${warnings.length ? `\nHistory persistence warning: ${warnings.join("; ")}` : ""}` }], details: { sessions: pending.length, resultRef: artifact.path, historyRefs: pending.flatMap(session => session.messages.historyRef ? [session.messages.historyRef] : []), cleared: true } };
+    };
+    if (large)
+        return paged();
+    let sessions;
+    try {
+        sessions = await Promise.all(pending.map(async (session) => ({ ...session, messages: await materializeUiMessages(session.messages) })));
+    }
+    catch (error) {
+        return { content: [{ type: "text", text: `UI messages remain available; history could not be read: ${String(error)}` }], isError: true, details: { error: "ui_history_delivery_failed", cleared: false } };
+    }
     if (sessions.length === 0) {
         return {
             content: [{ type: "text", text: "No UI session messages available." }],
@@ -183,9 +256,8 @@ export function executeUiMessages(state) {
         }
     }
     const count = sessions.length;
-    state.completedUiSessions = [];
-    return {
-        content: [{ type: "text", text: output.join("\n") }],
+    const inline = {
+        content: [{ type: "text", text: output.join("\n") + (warnings.length ? `\nHistory persistence warning: ${warnings.join("; ")}` : "") }],
         details: {
             sessions: count,
             prompts: allPrompts,
@@ -195,6 +267,11 @@ export function executeUiMessages(state) {
             cleared: true,
         },
     };
+    const text = inline.content.map(block => block.type === "text" ? block.text : "").join("\n");
+    if (Buffer.byteLength(JSON.stringify(inline.details)) > options.detailsMaxBytes || Buffer.byteLength(text) > options.maxBytes || text.split("\n").length > options.maxLines)
+        return paged();
+    state.completedUiSessions = state.completedUiSessions.filter(session => !pending.includes(session));
+    return inline;
 }
 export function executeStatus(state) {
     const servers = [];
@@ -699,7 +776,7 @@ export async function runToolCall(state, serverName, target, args, options) {
             beforeDispatchPending = false;
         }
         throwIfAborted(callerSignal);
-        // Host checkpoints and UI preparation do not consume the service deadline.
+        // Approval and UI preparation do not consume the service deadline.
         const ownedSignal = combineAbortSignals(callerSignal, AbortSignal.timeout(Math.ceil(configuredOptions?.timeout ?? DEFAULT_REQUEST_TIMEOUT_MSEC)));
         const requestOptions = { ...configuredOptions, signal: ownedSignal };
         const recovery = { manager: state.manager, config: state.config, signal: ownedSignal, onNeedsAuth: recoverAuthConnection };
@@ -735,7 +812,7 @@ export async function runToolCall(state, serverName, target, args, options) {
         if (options.raw) {
             const message = isError
                 ? (Array.isArray(record.content) ? record.content.filter(block => block.type === "text").map(block => block.text).join("\n") : "") || "Tool execution failed" : undefined;
-            return { content: [], details: { ...details, ...retained, ...(message ? { message } : {}) } };
+            return { content: [], ...(isError ? { isError: true } : {}), details: { ...details, ...retained, ...(message ? { message } : {}) } };
         }
         const content = renderMcpResultContent(record, retained.payloadFiles);
         const guarded = await guardMcpOutput(content.length ? content : [{ type: "text", text: target.resourceUri ? "(empty resource)" : "(empty result)" }], {
@@ -743,7 +820,7 @@ export async function runToolCall(state, serverName, target, args, options) {
             ...(isError ? { prefix: "Error: ", suffix: schemaSuffix(), emptyTextFallback: "Tool execution failed" }
                 : uiSummary ? { suffix: `\n\n${uiSummary.message}` } : {}),
         });
-        return { content: guarded.content, details: { ...details, ...guardedMcpDetails(guarded) } };
+        return { content: guarded.content, ...(isError ? { isError: true } : {}), details: { ...details, ...guardedMcpDetails(guarded) } };
     }
     catch (error) {
         // Direct/proxy host errors throw; scripts retain their failed-call envelope.
@@ -759,6 +836,7 @@ export async function runToolCall(state, serverName, target, args, options) {
                 ? await retainMcpResult(captureFailure.result, { ...outputGuardOptions, enabled: true, detailsMaxBytes: 1 }) : {};
             return {
                 content: [{ type: "text", text: message }, ...(retained.resultRef ? [{ type: "text", text: formatMcpResultReference(retained.resultRef) }] : [])],
+                isError: true,
                 details: { ...detailsBase, ...retained, error: isAbortError(error, callerSignal) ? "aborted" : "call_capture_failed", message, recovery: context },
             };
         }
@@ -767,6 +845,7 @@ export async function runToolCall(state, serverName, target, args, options) {
             uiSession?.sendToolCancelled(message);
             return {
                 content: [{ type: "text", text: message }],
+                isError: true,
                 details: { ...detailsBase, error: "ambiguous_outcome", message, recovery: { ...identity, action: "readback" } },
             };
         }
@@ -794,6 +873,7 @@ export async function runToolCall(state, serverName, target, args, options) {
         const guarded = await guardMcpOutput([{ type: "text", text: message }], { ...outputGuardOptions, prefix: "Failed to call tool: ", suffix: schemaSuffix() });
         return {
             content: guarded.content,
+            isError: true,
             details: {
                 ...detailsBase,
                 error: isAbortError(error, callerSignal) ? "aborted" : "call_failed",

package/dist/runtime-owner.d.ts

@@ -1,4 +1,3 @@
-import type { McpCheckpointEvent } from "./checkpoint.ts";
 import type { ExtensionUIContext } from "@earendil-works/pi-coding-agent";
 export interface McpRuntimeOwner {
     readonly signal: AbortSignal;
@@ -6,10 +5,7 @@ export interface McpRuntimeOwner {
     addCleanup(cleanup: () => void | Promise<void>): void;
     stop(reason?: string): Promise<void>;
     throwIfInactive(): void;
-    beforeActivity(): void;
-    holdCheckpoint(event: McpCheckpointEvent): () => void;
     runCallback<T>(kind: "beforeExecute" | "onToolCall", run: () => Promise<T>): Promise<T>;
-    getCheckpointBlocker(): string | undefined;
 }
 export declare function createMcpRuntimeOwner(): McpRuntimeOwner;
 export declare function combineAbortSignals(...signals: Array<AbortSignal | undefined>): AbortSignal | undefined;

package/dist/runtime-owner.js

@@ -3,12 +3,10 @@ export function createMcpRuntimeOwner() {
     const controller = new AbortController();
     const cleanups = [];
     let stopPromise;
-    let checkpoint;
-    const beforeActivity = () => checkpoint?.invalidate();
     // These two host hooks can outlive abortable() at their call sites. Count their underlying
     // promises through settlement, without cancelling, serializing, or replaying callback work.
     const callbacks = { beforeExecute: 0, onToolCall: 0 };
-    const getCheckpointBlocker = () => {
+    const pendingCallback = () => {
         if (callbacks.beforeExecute)
             return "MCP beforeExecute callback is pending";
         if (callbacks.onToolCall)
@@ -20,10 +18,7 @@ export function createMcpRuntimeOwner() {
     };
     return {
         signal: controller.signal,
-        beforeActivity,
-        getCheckpointBlocker,
         runCallback: async (kind, run) => {
-            beforeActivity();
             // Invocation/cancellation policy stays at the call site. In particular, an accepted
             // tool's outcome callback may still need to persist its result during shutdown.
             callbacks[kind]++;
@@ -34,13 +29,6 @@ export function createMcpRuntimeOwner() {
                 callbacks[kind]--;
             }
         },
-        holdCheckpoint: event => {
-            if (checkpoint)
-                throw new Error("MCP checkpoint is already held");
-            checkpoint = event;
-            return () => { if (checkpoint === event)
-                checkpoint = undefined; };
-        },
         isActive: () => !controller.signal.aborted,
         addCleanup: cleanup => {
             if (controller.signal.aborted) {
@@ -52,14 +40,13 @@ export function createMcpRuntimeOwner() {
         stop: (reason = "MCP extension runtime stopped") => {
             if (stopPromise)
                 return stopPromise;
-            beforeActivity();
             controller.abort(new Error(reason));
             const pendingCleanups = cleanups.splice(0).reverse().map(cleanup => Promise.resolve().then(cleanup));
             stopPromise = Promise.allSettled(pendingCleanups).then(results => {
                 const failures = results.flatMap(result => result.status === "rejected" ? [result.reason] : []);
-                const pendingCallback = getCheckpointBlocker();
-                if (pendingCallback)
-                    failures.push(new Error(pendingCallback));
+                const callback = pendingCallback();
+                if (callback)
+                    failures.push(new Error(callback));
                 if (failures.length > 0) {
                     const aggregate = new AggregateError(failures, "MCP runtime cleanup failed");
                     console.error(`MCP: runtime cleanup failed: ${formatTerminalError(aggregate)}`);
@@ -68,7 +55,7 @@ export function createMcpRuntimeOwner() {
             });
             return stopPromise;
         },
-        throwIfInactive: () => { beforeActivity(); controller.signal.throwIfAborted(); },
+        throwIfInactive: () => { controller.signal.throwIfAborted(); },
     };
 }
 export function combineAbortSignals(...signals) {

package/dist/server-manager.d.ts

@@ -1,4 +1,3 @@
-import type { McpCheckpointEvent } from "./checkpoint.ts";
 import { Client, type RequestOptions, type GetPromptResult, type ReadResourceResult, type UrlElicitationRequiredError } from "@modelcontextprotocol/client";
 import { type McpTool, type McpResource, type McpPrompt, type ServerDefinition, type ServerStreamResultPatchNotification, type Transport, type McpTraceSettings } from "./types.ts";
 import { type McpOAuthRuntime } from "./mcp-auth-flow.ts";
@@ -45,15 +44,9 @@ export declare class McpServerManager {
     private traceSettings;
     private traceWriter;
     private stopped;
-    private checkpoint;
-    private readonly beforeActivity;
-    holdCheckpoint(event: McpCheckpointEvent): () => void;
-    getCheckpointBlocker(): string | undefined;
-    flushForCheckpoint(): Promise<void>;
     private releaseClientWhenSettled;
-    /** Fence before SDK callbacks AND before trace observers; retain native transport identity.
-     * Preserve existing property setters (including tracing) rather than replacing their behavior. */
-    private fenceTransport;
+    /** Own native send/auth tails even after a public request has been cancelled. */
+    private ownTransportSends;
     /** Default cwd for stdio servers without an explicit config `cwd`. */
     private readonly defaultCwd;
     constructor(defaultCwd?: string);

package/dist/server-manager.js

@@ -41,8 +41,6 @@ async function drainClientOperations(client) {
 class ManagedClient extends Client {
     serverName = "";
     oauthProvider;
-    beforeActivity = () => { };
-    resourceSubscriptions = new Set();
     own(operation, kind) {
         let pending = clientOperations.get(this);
         if (!pending)
@@ -53,21 +51,17 @@ class ManagedClient extends Client {
         return operation;
     }
     ownNative(run) {
-        this.beforeActivity();
         return this.own(run(), "request/refresh");
     }
     ownSend(run) {
-        this.beforeActivity();
         // SDK-generated callback replies also perform HTTP/auth work, without calling callTool().
         return this.own(Promise.resolve().then(run), "request/refresh");
     }
     ownCallback(kind, run) {
-        this.beforeActivity();
         // Insert before dispatch. Cancellation/close of the SDK response does not settle this promise.
         return this.own(Promise.resolve().then(run), kind);
     }
     async track(start, signal) {
-        this.beforeActivity();
         const controller = this.oauthProvider ? new AbortController() : undefined;
         let removeAbortListener = () => { };
         const operation = this.oauthProvider
@@ -119,19 +113,11 @@ class ManagedClient extends Client {
     subscribeResource(...args) {
         return this.track(async (signal) => {
             throwIfAborted(signal);
-            // A cancelled/lost response does not prove the server rejected the subscription.
-            // Retain the attempted URI until an explicit unsubscribe succeeds or the connection is discarded.
-            if (this.getServerCapabilities()?.resources?.subscribe)
-                this.resourceSubscriptions.add(args[0].uri);
             return super.subscribeResource(args[0], { ...args[1], ...(signal ? { signal } : {}) });
         }, args[1]?.signal);
     }
     unsubscribeResource(...args) {
-        return this.track(async (signal) => {
-            const result = await super.unsubscribeResource(args[0], { ...args[1], ...(signal ? { signal } : {}) });
-            this.resourceSubscriptions.delete(args[0].uri);
-            return result;
-        }, args[1]?.signal);
+        return this.track(signal => super.unsubscribeResource(args[0], { ...args[1], ...(signal ? { signal } : {}) }), args[1]?.signal);
     }
 }
 function boundedStderrChunk(chunk) {
@@ -184,85 +170,15 @@ export class McpServerManager {
     traceSettings;
     traceWriter;
     stopped = false;
-    checkpoint;
-    beforeActivity = () => this.checkpoint?.invalidate();
-    holdCheckpoint(event) {
-        if (this.checkpoint)
-            throw new Error("MCP manager checkpoint is already held");
-        this.checkpoint = event;
-        return () => { if (this.checkpoint === event)
-            this.checkpoint = undefined; };
-    }
-    getCheckpointBlocker() {
-        if (this.stopped)
-            return "MCP manager is stopped";
-        if (this.connectPromises.size || this.reconnectPromises.size || this.closePromises.size || this.retiredConnections.size)
-            return "MCP connection/discovery/retirement is active";
-        if (this.acceptedUrlElicitations.size || this.uiStreamListeners.size)
-            return "MCP browser elicitation/UI stream is pending";
-        for (const client of this.ownedClients) {
-            // Only the SDK's exact auto-opened catalog handle reconstructs during connect().
-            // An explicit consumer listen(), even with the same filter, still owns private state.
-            const kinds = [...(clientOperations.get(client) ?? [])]
-                .filter(([operation, kind]) => kind !== "subscription" || operation !== client.autoOpenedSubscription?.closed)
-                .map(([, kind]) => kind);
-            const callback = kinds.find(kind => kind === "sampling callback" || kind === "elicitation callback");
-            if (callback)
-                return `MCP ${client.serverName}: ${callback} is active`;
-            if (kinds.includes("request/refresh"))
-                return `MCP ${client.serverName}: request/refresh is active`;
-            if (kinds.includes("subscription"))
-                return `MCP ${client.serverName}: subscription is active`;
-        }
-        for (const [name, connection] of this.connections) {
-            if (connection.inFlight)
-                return `MCP ${name}: request/refresh is active`;
-            if (connection.client instanceof ManagedClient && connection.client.resourceSubscriptions.size)
-                return `MCP ${name}: resource subscription is active or unresolved`;
-            if (!(connection.transport instanceof StreamableHTTPClientTransport))
-                return `MCP ${name}: only stateless Streamable HTTP is checkpoint-supported`;
-            if (connection.transport.sessionId !== undefined)
-                return `MCP ${name}: HTTP session state is not reconstructible`;
-            const capabilities = connection.client.getServerCapabilities();
-            if (capabilities?.tasks)
-                return `MCP ${name}: negotiated remote task state is not checkpoint-supported`;
-            const opaque = Object.keys(capabilities ?? {}).find(key => !["tools", "resources", "prompts", "logging", "completions"].includes(key)
-                && !(key === "experimental" && Object.keys(capabilities?.experimental ?? {}).length === 0));
-            if (opaque)
-                return `MCP ${name}: unsupported negotiated capability ${opaque}`;
-        }
-        return undefined;
-    }
-    // Diagnostics are best-effort, not session authority or a clean-exit prerequisite.
-    async flushForCheckpoint() { await this.traceWriter?.flush(); }
     releaseClientWhenSettled(client) {
         if (client instanceof ManagedClient)
             void drainClientOperations(client).then(() => this.ownedClients.delete(client));
     }
-    /** Fence before SDK callbacks AND before trace observers; retain native transport identity.
-     * Preserve existing property setters (including tracing) rather than replacing their behavior. */
-    fenceTransport(transport, client) {
-        for (const key of ["onmessage", "onerror", "onclose"]) {
-            const descriptor = Object.getOwnPropertyDescriptor(transport, key);
-            let value = transport[key];
-            Object.defineProperty(transport, key, {
-                configurable: true,
-                get: () => {
-                    const handler = descriptor?.get ? descriptor.get.call(transport) : value;
-                    return handler ? (...args) => { this.beforeActivity(); return handler(...args); } : undefined;
-                },
-                set: next => { if (descriptor?.set)
-                    descriptor.set.call(transport, next);
-                else
-                    value = next; },
-            });
-        }
-        if (typeof transport.send === "function") {
+    /** Own native send/auth tails even after a public request has been cancelled. */
+    ownTransportSends(transport, client) {
+        if (typeof transport.send === "function" && client instanceof ManagedClient) {
             const send = transport.send.bind(transport);
-            transport.send = (...args) => {
-                this.beforeActivity();
-                return client instanceof ManagedClient ? client.ownSend(() => send(...args)) : send(...args);
-            };
+            transport.send = (...args) => client.ownSend(() => send(...args));
         }
     }
     /** Default cwd for stdio servers without an explicit config `cwd`. */
@@ -316,7 +232,6 @@ export class McpServerManager {
         };
     }
     async connect(name, definition, signal) {
-        this.beforeActivity();
         if (isServerDisabled(definition))
             throw new Error(`MCP server "${name}" is disabled`);
         if (this.stopped)
@@ -425,7 +340,6 @@ export class McpServerManager {
     }
     /** Retire only the expected current client; accepted native work drains before close. */
     retire(name, connection) {
-        this.beforeActivity();
         if (this.connections.get(name) !== connection)
             return;
         connection.status = "closed";
@@ -644,7 +558,7 @@ export class McpServerManager {
     }
     async connectClientWithAbort(client, transport, requestOptions, signal) {
         throwIfAborted(signal);
-        this.fenceTransport(transport, client);
+        this.ownTransportSends(transport, client);
         let abortCleanup;
         const closeTransport = () => {
             abortCleanup = Promise.resolve().then(() => transport.close());
@@ -714,7 +628,6 @@ export class McpServerManager {
         });
         client.serverName = serverName;
         this.ownedClients.add(client);
-        client.beforeActivity = this.beforeActivity;
         if (this.samplingConfig) {
             registerSamplingHandler(client, { ...this.samplingConfig, serverName }, run => client.ownCallback("sampling callback", run));
         }
@@ -740,7 +653,6 @@ export class McpServerManager {
         return client;
     }
     handleToolsListChanged(serverName, client, error, tools) {
-        this.beforeActivity();
         if (error) {
             logger.debug(`MCP: tools/list_changed refresh failed for ${serverName}: ${error.message}`);
             return;
@@ -754,7 +666,6 @@ export class McpServerManager {
         this.metadataListChangedListener?.(serverName, "tools-list-changed");
     }
     handlePromptsListChanged(serverName, client, error, prompts) {
-        this.beforeActivity();
         if (error) {
             logger.debug(`MCP: prompts/list_changed refresh failed for ${serverName}: ${error.message}`);
             return;
@@ -769,7 +680,6 @@ export class McpServerManager {
         this.metadataListChangedListener?.(serverName, "prompts-list-changed");
     }
     handleResourcesListChanged(serverName, client, error, resources) {
-        this.beforeActivity();
         if (error) {
             logger.debug(`MCP: resources/list_changed refresh failed for ${serverName}: ${error.message}`);
             return;
@@ -920,7 +830,6 @@ export class McpServerManager {
                 const timer = setTimeout(() => {
                     if (transportClosed)
                         return;
-                    this.beforeActivity();
                     reconnect();
                 }, delay);
                 return () => clearTimeout(timer);
@@ -1037,7 +946,6 @@ export class McpServerManager {
         }
     }
     async close(name) {
-        this.beforeActivity();
         this.closeGenerations.set(name, (this.closeGenerations.get(name) ?? 0) + 1);
         this.connectAttempts.get(name)?.controller.abort(new Error(`MCP connection ${name} was closed`));
         const pendingClose = this.closePromises.get(name);
@@ -1116,7 +1024,7 @@ export class McpServerManager {
         this.elicitationConfig = undefined;
         await Promise.all([...this.ownedClients].map(client => drainClientOperations(client)));
         try {
-            await this.flushForCheckpoint();
+            await this.traceWriter?.flush();
         }
         catch (error) {
             failures.push(error);

package/dist/tool-loader.js

@@ -4,6 +4,8 @@ import { isServerCacheValid, reconstructToolMetadata } from "./metadata-cache.js
 import { createMcpDirectToolCallRenderer, renderMcpToolResult } from "./tool-result-renderer.js";
 import { isServerDisabled } from "./types.js";
 import { normalizeDirectToolInputSchema } from "./utils.js";
+import { nativeMcpOutputSchema } from "./tool-registrar.js";
+import { toolErrorOverride } from "./error-signal.js";
 const featureNames = { gateway: "mcp", script: "mcp_script" };
 const ENTRY = "mcp-tool-selection";
 const key = (value) => JSON.stringify([value.server, value.tool]);
@@ -27,7 +29,10 @@ export function createToolLoader(pi, getState, getInitPromise, beforeExecute) {
         pi.setActiveTools(unique);
     };
     function registerFeature(feature, definition) {
-        pi.registerTool(definition);
+        pi.registerTool({ defaultActive: false, ...definition, async execute(...args) {
+                const result = await definition.execute(...args);
+                return { ...result, ...toolErrorOverride(result.details) };
+            } });
         registeredFeatures.add(feature);
     }
     function capture() {
@@ -68,10 +73,25 @@ export function createToolLoader(pi, getState, getInitPromise, beforeExecute) {
         inactive = new Map();
         selectedFeatures = new Set();
         inactiveFeatures = new Set();
-        for (const entry of ctx.sessionManager.getBranch()) {
-            if (entry.type !== "custom" || entry.customType !== ENTRY || !entry.data || typeof entry.data !== "object")
+        const manager = ctx.sessionManager;
+        function* snapshots() {
+            let id = manager.getLeafId();
+            while (id) {
+                const entry = manager.getEntry(id);
+                if (!entry)
+                    break;
+                yield entry;
+                id = entry.parentId;
+            }
+        }
+        for (const entry of snapshots()) {
+            if (entry?.type !== "custom" || entry.customType !== ENTRY || !entry.data || typeof entry.data !== "object")
                 continue;
             const data = entry.data;
+            if (!Array.isArray(data.selected) || [data.inactive, data.features, data.inactiveFeatures].some(value => value !== undefined && !Array.isArray(value)))
+                continue;
+            if ([...data.selected, ...(data.inactive ?? [])].some(value => !value || typeof value.server !== "string" || typeof value.tool !== "string"))
+                continue;
             selectedFeatures = new Set(Array.isArray(data.features) ? data.features.filter(value => value === "gateway" || value === "script") : []);
             inactiveFeatures = new Set(Array.isArray(data.inactiveFeatures) ? data.inactiveFeatures.filter(value => value === "gateway" || value === "script") : []);
             for (const [field, target] of [[data.selected, selected], [data.inactive, inactive]]) {
@@ -81,6 +101,7 @@ export function createToolLoader(pi, getState, getInitPromise, beforeExecute) {
                         target.set(key(selection), selection);
                 }
             }
+            break;
         }
         restoring = true;
     }
@@ -114,11 +135,19 @@ export function createToolLoader(pi, getState, getInitPromise, beforeExecute) {
             if (reserved.has(name) || counts.get(name) > 1 || (existing.has(name) && !previousNames.has(name)))
                 continue;
             available.add(id);
-            const fingerprint = JSON.stringify({ spec, name });
+            const instructions = getState()?.serverInstructions.get(spec.serverName) ?? cache?.servers[spec.serverName]?.instructions;
+            const fingerprint = JSON.stringify({ spec, name, instructions });
             if (registered.get(id)?.fingerprint !== fingerprint) {
                 pi.registerTool({
                     name,
-                    namespace: { name: `mcp_${spec.serverName}` },
+                    namespace: { name: `mcp_${spec.serverName}`, ...(instructions !== undefined ? { instructions } : {}) },
+                    ...(spec.outputSchema ? { outputSchema: nativeMcpOutputSchema(spec.outputSchema) } : {}),
+                    ...(spec.annotations ? { annotations: {
+                            ...(typeof spec.annotations.readOnlyHint === "boolean" ? { readOnlyHint: spec.annotations.readOnlyHint } : {}),
+                            ...(typeof spec.annotations.destructiveHint === "boolean" ? { destructiveHint: spec.annotations.destructiveHint } : {}),
+                            ...(typeof spec.annotations.idempotentHint === "boolean" ? { idempotentHint: spec.annotations.idempotentHint } : {}),
+                            ...(typeof spec.annotations.openWorldHint === "boolean" ? { openWorldHint: spec.annotations.openWorldHint } : {}),
+                        } } : {}),
                     // Inactive direct tools are not callable through codemode or nested execution.
                     defaultActive: false,
                     ...(beforeExecute ? { executionMode: "sequential" } : {}),
@@ -153,7 +182,7 @@ export function createToolLoader(pi, getState, getInitPromise, beforeExecute) {
                 }
             }
         }
-        // Official 0.87 reactivates allowlisted definitions on registration. Apply our loadout last.
+        // Retain the journal: official 1.0 initial SDK resume has a native loadout restoration gap.
         const ownedNames = new Set([...previousNames, ...[...registered.values()].map(item => item.name)]);
         for (const feature of registeredFeatures)
             ownedNames.add(featureNames[feature]);

package/dist/tool-registrar.d.ts

@@ -1,5 +1,16 @@
 import type { McpContent, ContentBlock } from "./types.ts";
 import { type McpPayloadFile } from "./mcp-output-guard.ts";
+import { Type } from "typebox";
+import type { AgentToolResult } from "@earendil-works/pi-coding-agent";
+/** Overflow/not-run outcomes are receipts, never a fabricated server-schema result. */
+export declare function nativeMcpOutputSchema(schema: Record<string, unknown>): Type.TUnion<[Type.TUnsafe<unknown>, Type.TObject<{
+    mcpAdapter: Type.TObject<{
+        omitted: Type.TLiteral<true>;
+        resultRef: Type.TOptional<Type.TString>;
+        error: Type.TOptional<Type.TString>;
+    }>;
+}>]>;
+export declare function nativeMcpResult(result: AgentToolResult<Record<string, unknown>>, structured?: boolean): AgentToolResult<Record<string, unknown>>;
 /**
  * Transform MCP content types to Pi content blocks.
  */

package/dist/tool-registrar.js

@@ -1,5 +1,28 @@
 // MCP protocol content to model-visible content.
 import { formatMcpPayloadFile } from "./mcp-output-guard.js";
+import { Type } from "typebox";
+import { toolErrorOverride } from "./error-signal.js";
+/** Overflow/not-run outcomes are receipts, never a fabricated server-schema result. */
+export function nativeMcpOutputSchema(schema) {
+    return Type.Union([Type.Unsafe(schema), Type.Object({
+            mcpAdapter: Type.Object({
+                omitted: Type.Literal(true),
+                resultRef: Type.Optional(Type.String()),
+                error: Type.Optional(Type.String()),
+            }),
+        })]);
+}
+export function nativeMcpResult(result, structured = false) {
+    const { details } = result;
+    const raw = details.mcpResult;
+    return {
+        ...result,
+        ...toolErrorOverride(details),
+        ...(structured ? { structuredContent: !details.outputGuard && (!details.error || details.error === "tool_error") && raw?.structuredContent !== undefined
+                ? raw.structuredContent
+                : { mcpAdapter: { omitted: true, ...(typeof details.resultRef === "string" ? { resultRef: details.resultRef } : {}), ...(typeof details.error === "string" ? { error: details.error } : {}) } } } : {}),
+    };
+}
 /**
  * Transform MCP content types to Pi content blocks.
  */

package/dist/types.d.ts

@@ -136,6 +136,11 @@ export declare function parseUiPromptHandoff(prompt: string): UiPromptHandoff |
  * Collected during the session and available when it ends.
  */
 export interface UiSessionMessages {
+    /** Private JSONL history, readable with the normal paged result reader. */
+    historyRef?: string;
+    historyBytes?: number;
+    historyCount?: number;
+    historyError?: string;
     prompts: string[];
     notifications: string[];
     intents: Array<{

package/dist/ui-message-history.d.ts

@@ -0,0 +1,11 @@
+import type { UiSessionMessages } from "./types.ts";
+type Category = "prompts" | "intents" | "notifications";
+type Message = string | UiSessionMessages["intents"][number];
+/** Private append-only history; failed writes stay owned in memory, never silently discarded. */
+export declare function createUiMessageHistory(outputDirectory?: string): {
+    messages: UiSessionMessages;
+    append(category: Category, value: Message): string | undefined;
+};
+export declare function uiMessages(messages: UiSessionMessages, category: Category): AsyncGenerator<Message>;
+export declare function materializeUiMessages(messages: UiSessionMessages): Promise<UiSessionMessages>;
+export {};