@fitchmultz/pi-mcp-adapter 7.1.1 → 8.0.0

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [8.0.0] - 2026-10-01
+
+### Changed
+
+- Require Pi 1.0.0 and qualify the exact official SDK/CLI cohort; live installations are not changed.
+- Typed MCP tools expose native schemas, complete namespace instructions, annotations, bounded structured output and result-level failures. Human content, private raw capture, output/readback artifacts, cancellation and no-replay ownership remain separate.
+- Restore the selection journal backward to the first valid snapshot, preserving legacy/incomplete recovery, pins, restrictions, lazy startup and enable-first permissions. Keep this journal for the official initial SDK-resume gap.
+- Save MCP App messages privately on disk. Small retrievals stay inline; large histories stream to existing paged output references. Failed persistence/delivery remains recoverable, with no new retention caps.
+- Reject App messages/context updates whose authenticated upload finishes after completion, and refuse incomplete history delivery before draining accepted sessions.
+- Report and document the owner-accepted failed-storage boundary: unsaved in-memory App history is lost on reload/process exit; no second recovery store is added. Normal private disk history and failed-delivery recovery remain protected.
+- Remove retired fork checkpoint/metadata APIs. Preserve actual transport/OAuth/sampling/elicitation/capture shutdown ownership and move their independent lifetime tests out of the retired checkpoint suite.
+
 ## [7.1.1] - 2026-10-01
 
 ### Changed

package/OAUTH.md

@@ -327,7 +327,7 @@ Persistent OAuth entries are stored in service `fitch-mcp-adapter.oauth`, with t
 
 The adapter fails closed when the OS credential store is unavailable. On headless Linux, configure an unlocked Secret Service-compatible keyring before using persistent OAuth; the adapter does not silently fall back to plaintext token files.
 
-The optional native working-session checkpoint barrier acknowledges completed refresh persistence only after owned SDK operations finish, including background GET/reconnect provider work and cancellation tails. Active browser flows (including captured callbacks awaiting `auth-complete`) and authentication operations keep sleep readiness false; PKCE/callback memory is not serialized. The server-challenge cache alone is reconstructible through normal re-challenge; granted scopes and issuer bindings persist in the native credential store. Per-server cancellation stays prompt, but final shutdown joins actual provider promises rather than just the cancelled public request. Hosts must preserve and unlock the actual private OS credential store on replacement compute, not merely copy the legacy import directory. The Linux binding may select a kernel keyring when Secret Service is unavailable, so successful credential access alone does not prove durable storage. Verify the persistent unlocked Secret Service collection before launching a durable Linux workspace. See [native working-session checkpoints](README.md#native-working-session-checkpoints) for the supported HTTP boundary.
+Final runtime shutdown joins owned SDK operations, including background GET/reconnect provider work and cancellation tails. Per-server cancellation stays prompt; closing the runtime waits for actual provider promises, not just the cancelled public request. Granted scopes and issuer bindings remain in the native OS credential store. Active browser flows and callback memory are not serialized, and no operation is replayed to recover them. Hosts must preserve and unlock the actual private credential store on replacement compute; a Linux kernel keyring alone does not prove persistent Secret Service storage.
 
 On Linux, if credential access fails because Pi inherited a revoked session keyring, the adapter makes one best-effort retry through `keyctl session - node <packaged helper>`. This lets explicit re-authentication write fresh credentials from a new session keyring without restarting a long-lived tmux or server process. The recovery path requires `keyctl` and `node` on `PATH`; missing, locked, or otherwise unavailable credential stores still fail closed.
 

package/README.md

@@ -20,7 +20,7 @@ The MCP ecosystem has useful databases, browsers, and APIs. This adapter keeps t
 
 ## Pi release qualification
 
-The development baseline is official Pi **0.99.2**; host peers remain wildcard and the declared Pi/Node floors are unchanged. Current-host checks do not requalify older Pi versions. `npm run check:compat` verifies the installed SDK and CLI identity, builds and typechecks, runs Vitest and memory-only OAuth tests, then loads a packed consumer through the native SDK and CLI.
+The supported Pi baseline is official **1.0.0**; host peers remain wildcard. Older Pi releases are not supported. `npm run check:compat` verifies the installed SDK and CLI identity, builds and typechecks, runs Vitest and memory-only OAuth tests, then loads a packed consumer through the native SDK and CLI.
 
 GitHub CI runs that contract on Node 24 against both official Pi and the maintained fork through the shared Pi compatibility automation, including fresh Git and npm installations loaded by the real Pi CLI. A second job checks lockfile registry hosts, published type declarations, the built interactive visualizer, and MCP protocol conformance. These checks use local MCP fixtures and disposable agent directories, never live credentials or paid providers.
 
@@ -28,7 +28,7 @@ Keep the development TypeBox pin aligned with the official Pi baseline's depende
 
 ## Install
 
-Requires Pi 0.87.1 or later and Node.js 24 or later.
+Requires Pi 1.0.0 or later and Node.js 24 or later.
 
 ```bash
 pi install npm:@fitchmultz/pi-mcp-adapter
@@ -235,17 +235,11 @@ Supplying `beforeExecute` marks the adapter's tools `executionMode: "sequential"
 
 The two callbacks serve different boundaries: `beforeExecute` saves completed workspace writes; `onToolCall` captures the resolved operation and its raw outcome. The host owns `pi.appendEntry()` and the awaited checkpoint of that same native JSONL. Exclude `signal`, serialize thrown errors explicitly, redact sensitive checkpoint bytes, and honor the signal and session/attempt fence. `pi.appendEntry()` alone only persists locally; `pi.events.emit()` is not an awaited barrier. Custom entries do not enter model context automatically: the host must provide truthful recovered results or readback instructions when resuming. The adapter stores no separate transcript or receipts, does not replay scripts, and does not invent provider operation keys.
 
-### Native working-session checkpoints
+### Runtime shutdown and replacement
 
-On hosts that emit the optional awaited `session_checkpoint` event, the adapter can acknowledge an **idle, stateless Streamable HTTP** runtime with its **default sampling and elicitation capabilities intact**. Older Pi hosts continue normally and never invoke this hook. The host still owns native session capture, coherent filesystem capture, private credential retention, and commit-before-sleep.
+Pi 1.0 owns session replacement and emits `session_shutdown`. The adapter aborts outgoing activity before awaiting cleanup, closes owned connections, health watchers, OAuth callbacks and UI servers, and reports persistence/cleanup failures. Actual sampling/elicitation and native send/auth tails remain owned through settlement, even when a public request has already been cancelled. Unfinished callbacks prevent idle connection closure; final shutdown joins transport work. Pending `beforeExecute`/`onToolCall` promises prevent a clean-shutdown success claim. No detached work is declared finished merely because the agent settled.
 
-Sampling/elicitation handlers are owned through their actual UI/model/handler promises. A pending handler returns a named veto; after it finishes, an otherwise reconstructible runtime can qualify. Cancelling an SDK response or closing a transport does not discard an unfinished handler: connection cleanup drains those callbacks. Native sends that outlive per-server cancellation remain owned and veto readiness; final shutdown joins them. SDK-generated callback replies remain owned through HTTP/auth completion even after the handler returns. Unfinished callbacks also prevent automatic idle closure. Configured `beforeExecute`/`onToolCall` hooks likewise do not block idle checkpoints. Their underlying promises stay counted even if the caller's abortable wait has ended. Callbacks must return/await their work and persist any logical state they need on resume; arbitrary unreturned detached work and closure memory are not serialized.
-
-Ordinary logging, argument completion, empty experimental metadata, and the SDK's auto-opened catalog notification subscription are reconstructible: requests are owned and notification ingress is fenced. Explicit consumer resource/listen subscriptions, negotiated remote tasks, opaque protocol capabilities, HTTP session IDs, legacy SSE, stdio/Unix servers, pending initialization/requests/refresh/health checks, browser OAuth flows, UI sessions/messages, active scripts, and unpersisted session approvals return a named `sleepReady: false`. Session grants are not silently reset to obtain readiness. Advertising subscription support alone is not an active subscription. A resource-subscribe attempt with a cancelled/lost response remains unresolved until successful unsubscribe or connection disposal; it is not silently replayed. Completed URL elicitation clears only its accepted ID; other pending IDs still veto. Failed cleanup remains owned; an explicit later close may retry only if the native client still owns its transport. Unsupported work remains usable while compute stays running; the hook does not cancel accepted operations to manufacture readiness.
-
-Before any asynchronous flush, the adapter fences owned activity and pauses its existing health-check timer. New requests, background HTTP GET/reconnect/auth work, or incoming callbacks invalidate the host's hold **before** dispatch or mutation. Native provider promises and HTTP headers/body reads remain owned through settlement, including cancellation tails; final shutdown joins them while per-server cancellation stays prompt. An idle inbound SSE stream is not a perpetual active request. Completed refreshes use the existing native OS credential store; no token file or second auth store is introduced. Server OAuth challenges reconstruct through normal re-challenge, with granted scopes and issuer bindings in native credentials. Required metadata persistence errors reject capture; optional diagnostic tracing stays best-effort and never prevents recovery or clean exit. Release/cancellation resumes the same clients and timer, without replaying tools, reauthenticating, or running shutdown. Cold startup uses normal discovery and native credentials; only a new explicit tool invocation sends a new tool request.
-
-`session_shutdown` separately performs best-effort cleanup and propagates persistence/cleanup failures through the host's ordinary extension error contract. A host callback still running after cleanup also prevents clean-shutdown success. A clean-exit host must not infer success after a failed handler. No callback/process memory recovery is promised.
+The retired fork `session_checkpoint`/`acquireCheckpoint` APIs are no longer used. Host-supplied `beforeExecute` and raw `onToolCall` capture remain supported; the host still owns durable effect receipts and coherent workspace/session capture. No callback/process-memory recovery or automatic operation replay is promised.
 
 ### Runtime status snapshots
 
@@ -783,7 +777,11 @@ MCP servers can ship interactive UIs via [MCP Apps](https://github.com/modelcont
 mcp({ action: "ui-messages" })
 ```
 
-Returns accumulated messages from UI sessions. Each message includes `type`, `sessionId`, `serverName`, `toolName`, and `timestamp`. Prompt messages include `prompt`, intent messages include `intent` and `params`.
+Returns completed UI sessions (the last ten), grouped in the existing prompt → intent → context → notification order. Prompt handoffs are also normalized into intents. Prompts, intents and notifications are saved in private disk history as they arrive; context updates and SSE replay retain their existing bounds. Small retrievals keep the original inline content/details. Large retrievals return `resultRef` for the complete grouped output and `historyRefs` for original JSONL events; use `read-result` with `offset`/`limit` to page them without rerunning UI actions. Plain output pages are streamed without loading the entire artifact into memory.
+
+Retrieval drains only the sessions included in a usable inline/file receipt; read/write failure leaves them available for retry. History-write failure is explicitly reported, and unsaved events remain recoverable in the current instance's memory. **If normal storage fails and you then reload or exit, that unsaved tail is lost.** There is deliberately no session-journal rescue or alternate recovery file. Retrieve the pending messages before reloading or exiting when possible; do not treat the warning as a durable receipt. This rare failed-storage boundary does not change normal disk-history persistence or failed-delivery recovery. Files use private directory/file permissions and the existing output-directory lifetime: receipts remain readable after draining or UI closure, and are not deleted automatically. Remove artifacts only when you no longer need recovery. New sessions completed during retrieval are not cleared.
+
+Messages and context updates are accepted only while the UI is open. An upload finishing after completion is rejected before it can invoke callbacks or alter history. Retrieval verifies the accepted history prefix's byte and event counts; truncated history remains pending recovery instead of being delivered and cleared.
 
 **Browser controls:**
 
@@ -887,7 +885,7 @@ In interactive sessions, you can also authenticate from `/mcp` with `ctrl+a` or
 
 ### MCP output schemas
 
-Advertised tool `outputSchema` values support JSON Schema draft-07 and 2020-12. Unstamped schemas use the SDK's 2020-12 default. Returned `structuredContent` is validated against the advertised schema for both proxy and direct-tool calls. Any JSON structured value—including `null`, `false`, and `0`—is rendered as text, including alongside non-empty content or images. The raw result remains available for script reduction and saved-result readback.
+Advertised tool `outputSchema` values support JSON Schema draft-07 and 2020-12. Unstamped schemas use the SDK's 2020-12 default. Returned `structuredContent` is validated against the advertised schema for both proxy and direct-tool calls. Typed direct tools also expose that schema and bounded `structuredContent` to native Pi composition. Human text/images remain complementary. Oversized, absent, or not-run structured results return an `mcpAdapter` receipt (`omitted`, optional `resultRef`/`error`) instead of fabricating a server-schema value. Only the protocol's structured field is exposed: private details and `_meta` are not copied. Native content-only result-hook redaction drops structured output, as intended. Any JSON structured value—including `null`, `false`, and `0`—is rendered as text, including alongside non-empty content or images. The raw result remains available for script reduction and saved-result readback.
 
 ## How It Works
 

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,7 +10,6 @@ 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";
@@ -20,7 +19,6 @@ import { gatewayParameters, prepareGatewayArguments } from "./gateway-arguments.
 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");
@@ -269,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();
@@ -300,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;

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>;