@fitchmultz/pi-mcp-adapter 7.1.1 → 8.0.1

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

package/dist/ui-message-history.js

@@ -0,0 +1,81 @@
+import { appendFileSync, createReadStream, mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { randomBytes } from "node:crypto";
+import { createInterface } from "node:readline";
+/** Private append-only history; failed writes stay owned in memory, never silently discarded. */
+export function createUiMessageHistory(outputDirectory) {
+    const messages = { prompts: [], intents: [], notifications: [], contexts: [] };
+    let failed = false;
+    return {
+        messages,
+        append(category, value) {
+            try {
+                if (failed)
+                    throw new Error(messages.historyError);
+                if (!messages.historyRef) {
+                    const root = outputDirectory === undefined ? tmpdir() : resolve(outputDirectory);
+                    if (outputDirectory !== undefined)
+                        mkdirSync(root, { recursive: true, mode: 0o700 });
+                    const dir = mkdtempSync(join(root, "pi-mcp-output-"));
+                    const ref = join(dir, `output-${randomBytes(4).toString("hex")}.txt`);
+                    writeFileSync(ref, "", { mode: 0o600 });
+                    messages.historyRef = ref;
+                    messages.historyBytes = 0;
+                    messages.historyCount = 0;
+                }
+                const line = JSON.stringify({ category, value }) + "\n";
+                // ponytail: synchronous append owns acceptance order; upgrade to an awaited serial writer if local disk latency becomes material.
+                appendFileSync(messages.historyRef, line, { flush: true });
+                messages.historyBytes += Buffer.byteLength(line);
+                messages.historyCount++;
+                return undefined;
+            }
+            catch (error) {
+                failed = true;
+                messages.historyError = error instanceof Error ? error.message : String(error);
+                if (category === "intents")
+                    messages.intents.push(value);
+                else
+                    messages[category].push(value);
+                return `UI history could not be saved; messages remain in memory for recovery: ${messages.historyError}. Unsaved messages will be lost on reload or process exit.`;
+            }
+        },
+    };
+}
+export async function* uiMessages(messages, category) {
+    if (messages.historyRef && messages.historyBytes) {
+        // A failed partial append is not an accepted event; the in-memory tail owns it instead.
+        const input = createReadStream(messages.historyRef, { encoding: "utf8", end: messages.historyBytes - 1 });
+        let bytes = 0, count = 0;
+        input.on("data", chunk => { bytes += Buffer.byteLength(chunk); });
+        const lines = createInterface({ input, crlfDelay: Infinity });
+        try {
+            for await (const line of lines) {
+                const record = JSON.parse(line);
+                count++;
+                if (record.category === category)
+                    yield record.value;
+            }
+            if (bytes !== messages.historyBytes || (messages.historyCount !== undefined && count !== messages.historyCount)) {
+                throw new Error("UI history is incomplete; accepted messages remain pending recovery");
+            }
+        }
+        finally {
+            lines.close();
+            input.destroy();
+        }
+    }
+    for (const value of messages[category])
+        yield value;
+}
+export async function materializeUiMessages(messages) {
+    const result = { prompts: [], intents: [], notifications: [], contexts: messages.contexts };
+    for await (const value of uiMessages(messages, "prompts"))
+        result.prompts.push(value);
+    for await (const value of uiMessages(messages, "intents"))
+        result.intents.push(value);
+    for await (const value of uiMessages(messages, "notifications"))
+        result.notifications.push(value);
+    return result;
+}

package/dist/ui-server.js

@@ -10,6 +10,7 @@ import { logger } from "./logger.js";
 import { SessionRecoveryAuthRequiredError, withSessionRecovery } from "./session-recovery.js";
 import { ensureToolCallApproved, isToolCallApprovalRequired } from "./tool-approval.js";
 import { extractUiToolVisibility, isUiToolCallableByApp } from "./ui-tool-visibility.js";
+import { createUiMessageHistory } from "./ui-message-history.js";
 import { createUiModelContextUpdate, extractUiPromptText, getVisualizationStreamEnvelope, isServerDisabled, isToolAllowed, resolveToolPrefix, } from "./types.js";
 const MAX_BODY_SIZE = 2 * 1024 * 1024;
 const ABANDONED_GRACE_MS = 60_000;
@@ -38,12 +39,8 @@ export async function startUiServer(options) {
     const eventLog = [];
     let streamSummary;
     // Track messages from UI for retrieval
-    const sessionMessages = {
-        prompts: [],
-        notifications: [],
-        intents: [],
-        contexts: [],
-    };
+    const history = createUiMessageHistory(options.state?.outputDirectory);
+    const sessionMessages = history.messages;
     const hostContext = {
         displayMode: currentDisplayMode,
         availableDisplayModes: ["inline", "fullscreen", "pip"],
@@ -281,6 +278,11 @@ export async function startUiServer(options) {
                 return;
             if (!validateTokenBody(body, sessionToken, res))
                 return;
+            // A partial upload is not accepted until its authenticated body is complete.
+            if (completed && (url.pathname === "/proxy/ui/message" || url.pathname === "/proxy/ui/context")) {
+                sendJson(res, 409, { ok: false, error: "UI session is complete; message was not accepted" });
+                return;
+            }
             const params = body.params ?? {};
             touchHeartbeat();
             if (url.pathname === "/proxy/tools/call") {
@@ -376,14 +378,15 @@ export async function startUiServer(options) {
                 const promptText = extractUiPromptText(msgParams);
                 // Track messages by type (order: prompt → intent → notify)
                 // Must match the order in index.ts onMessage handler
+                let warning;
                 if (promptText) {
-                    sessionMessages.prompts.push(promptText);
+                    warning = history.append("prompts", promptText);
                     log.debug("UI prompt received", { prompt: promptText.slice(0, 100) });
                 }
                 else if (msgParams.type === "intent" || msgParams.intent) {
                     const intentName = msgParams.intent ?? "";
                     if (intentName) {
-                        sessionMessages.intents.push({
+                        warning = history.append("intents", {
                             intent: intentName,
                             ...(msgParams.params !== undefined ? { params: msgParams.params } : {}),
                         });
@@ -393,12 +396,16 @@ export async function startUiServer(options) {
                 else if (msgParams.type === "notify" || msgParams.message) {
                     const notifyText = msgParams.message ?? "";
                     if (notifyText) {
-                        sessionMessages.notifications.push(notifyText);
+                        warning = history.append("notifications", notifyText);
                         log.debug("UI notification", { message: notifyText.slice(0, 100) });
                     }
                 }
                 await options.onMessage?.(msgParams);
-                sendJson(res, 200, { ok: true, result: {} });
+                if (warning) {
+                    log.warn(warning);
+                    options.state?.ui?.notify(warning, "warning");
+                }
+                sendJson(res, 200, { ok: true, result: {}, ...(warning ? { warning } : {}) });
                 return;
             }
             if (url.pathname === "/proxy/ui/context") {

package/dist/ui-session.js

@@ -297,7 +297,8 @@ export async function maybeStartUiSession(state, request) {
                 if (state.uiServer === handle) {
                     const messages = handle.getSessionMessages();
                     const stream = handle.getStreamSummary();
-                    const hasContent = messages.prompts.length > 0 ||
+                    const hasContent = !!messages.historyCount ||
+                        messages.prompts.length > 0 ||
                         messages.intents.length > 0 ||
                         messages.notifications.length > 0 ||
                         messages.contexts.length > 0 ||
@@ -316,7 +317,7 @@ export async function maybeStartUiSession(state, request) {
                         }
                         log.debug("Session completed", {
                             reason,
-                            prompts: messages.prompts.length,
+                            prompts: messages.historyCount ?? messages.prompts.length,
                             intents: messages.intents.length,
                             notifications: messages.notifications.length,
                             contexts: messages.contexts.length,