@fitchmultz/pi-mcp-adapter 5.0.0

package/dist/ui-session.d.ts

@@ -0,0 +1,39 @@
+import { type CallToolResult } from "@modelcontextprotocol/client";
+import type { McpExtensionState } from "./state.ts";
+import { type UiStreamMode } from "./types.ts";
+import type { SessionRecoveryDeps } from "./session-recovery.ts";
+export interface UiSessionRequest {
+    serverName: string;
+    toolName: string;
+    toolArgs: Record<string, unknown>;
+    uiResourceUri: string;
+    streamMode?: UiStreamMode;
+    signal?: AbortSignal;
+    onNeedsAuth?: SessionRecoveryDeps["onNeedsAuth"];
+}
+export type UiSessionViewer = "browser" | "glimpse" | "suppressed";
+export interface UiSessionRuntime {
+    serverName: string;
+    toolName: string;
+    reused: boolean;
+    streamId?: string;
+    streamToken?: string;
+    streamMode?: UiStreamMode;
+    requestMeta?: Record<string, unknown>;
+    url: string;
+    viewer: UiSessionViewer;
+    windowOpen: boolean;
+    isActive: () => boolean;
+    sendToolResult: (result: CallToolResult) => void;
+    sendResultPatch: (result: CallToolResult) => void;
+    sendToolCancelled: (reason: string) => void;
+    close: (reason?: string) => void;
+}
+export interface UiSessionResultSummary {
+    message: string;
+    uiOpen: boolean;
+    uiViewer?: UiSessionViewer;
+    uiUrl?: string;
+}
+export declare function summarizeUiSessionResult(uiSession: UiSessionRuntime | null): UiSessionResultSummary;
+export declare function maybeStartUiSession(state: McpExtensionState, request: UiSessionRequest): Promise<UiSessionRuntime | null>;

package/dist/ui-session.js

@@ -0,0 +1,463 @@
+import { execFile } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import net from "node:net";
+import { UrlElicitationRequiredError } from "@modelcontextprotocol/client";
+import { createUiModelContextUpdate, extractUiPromptText, UI_STREAM_HOST_CONTEXT_KEY, UI_STREAM_REQUEST_META_KEY, UI_STREAM_STRUCTURED_CONTENT_KEY, } from "./types.js";
+import { logger } from "./logger.js";
+import { startUiServer } from "./ui-server.js";
+import { isGlimpseAvailable, openGlimpseWindow } from "./glimpse-ui.js";
+import { combineAbortSignals, isAbortError } from "./runtime-owner.js";
+import { throwIfAborted } from "./abort.js";
+let activeGlimpseWindow = null;
+export function summarizeUiSessionResult(uiSession) {
+    if (!uiSession) {
+        return {
+            message: "Interactive UI was unavailable; returning the tool result inline.",
+            uiOpen: false,
+        };
+    }
+    if (!uiSession.windowOpen) {
+        const action = uiSession.reused ? "Updated the suppressed MCP UI session." : "MCP UI window was suppressed.";
+        return {
+            message: `${action} Open manually: ${uiSession.url}`,
+            uiOpen: false,
+            uiViewer: uiSession.viewer,
+            uiUrl: uiSession.url,
+        };
+    }
+    return {
+        message: uiSession.reused
+            ? "Updated the open UI."
+            : "Interactive UI is open. I'll respond to your prompts and intents as you interact with it.",
+        uiOpen: true,
+        uiViewer: uiSession.viewer,
+        uiUrl: uiSession.url,
+    };
+}
+const MAX_COMPLETED_SESSIONS = 10;
+function withStreamEnvelope(result, streamId, sequence) {
+    if (!streamId) {
+        return result;
+    }
+    const structuredContent = result.structuredContent && typeof result.structuredContent === "object" && !Array.isArray(result.structuredContent)
+        ? { ...result.structuredContent }
+        : {};
+    const rawEnvelope = structuredContent[UI_STREAM_STRUCTURED_CONTENT_KEY];
+    const envelope = rawEnvelope && typeof rawEnvelope === "object" && !Array.isArray(rawEnvelope)
+        ? { ...rawEnvelope }
+        : {
+            frameType: "final",
+            phase: "settled",
+            status: result.isError ? "error" : "ok",
+        };
+    structuredContent[UI_STREAM_STRUCTURED_CONTENT_KEY] = {
+        ...envelope,
+        streamId,
+        sequence,
+    };
+    return {
+        ...result,
+        structuredContent,
+    };
+}
+async function openInBrowser(state, url, signal) {
+    throwIfAborted(signal);
+    try {
+        await state.openBrowser(url);
+        throwIfAborted(signal);
+        return null;
+    }
+    catch (error) {
+        if (isAbortError(error, signal))
+            throw error;
+        const message = error instanceof Error ? error.message : String(error);
+        if (state.owner?.isActive() === false)
+            return null;
+        state.ui?.notify(`MCP UI browser open failed: ${message}`, "warning");
+        return message;
+    }
+}
+function isRemoteSession() {
+    return Boolean(process.env.SSH_CONNECTION || process.env.SSH_TTY);
+}
+function hasActiveRemoteLogin() {
+    return new Promise((resolve) => {
+        execFile("who", { encoding: "utf8", timeout: 2000 }, (error, out) => {
+            if (error) {
+                resolve(false);
+                return;
+            }
+            resolve(/\(.+\)\s*$/m.test(out));
+        });
+    });
+}
+function probeMoshiGateway() {
+    return new Promise((resolve) => {
+        const socket = net.connect({ host: "127.0.0.1", port: 24543 });
+        const done = (ok) => {
+            socket.destroy();
+            resolve(ok);
+        };
+        socket.setTimeout(300);
+        socket.once("connect", () => done(true));
+        socket.once("timeout", () => done(false));
+        socket.once("error", () => done(false));
+    });
+}
+function remoteAccessHint(opts) {
+    const lines = [
+        opts.openError !== null
+            ? "Couldn't open MCP UI here. Open it from your own device:"
+            : opts.openedOnHost
+                ? "MCP UI opened on this host. If you're controlling this session remotely, open it from your own device:"
+                : "This looks like a remote session - if no MCP UI appeared, open it from your own device:",
+        `  ${opts.url}`,
+    ];
+    if (opts.openError !== null) {
+        lines.push(`Browser launch failed: ${opts.openError}`);
+    }
+    if (opts.moshi) {
+        lines.push("Moshi: tap the preview button in the terminal title bar and pick this MCP UI server.");
+    }
+    lines.push(`SSH: run \`ssh -L ${opts.port}:127.0.0.1:${opts.port} <this-host>\` on your local machine, then open the URL above.`, "mosh can't forward ports - run that ssh command in a separate terminal.");
+    return lines.join("\n");
+}
+export async function maybeStartUiSession(state, request) {
+    const log = logger.child({
+        component: "UiSession",
+        server: request.serverName,
+        tool: request.toolName,
+    });
+    const runtimeSignal = combineAbortSignals(state.owner?.signal, request.signal) ?? new AbortController().signal;
+    try {
+        throwIfAborted(runtimeSignal);
+        if (state.uiServer &&
+            state.uiServer.serverName === request.serverName &&
+            state.uiServer.toolName === request.toolName) {
+            const existingHandle = state.uiServer;
+            const streamMode = request.streamMode;
+            const streamId = streamMode ? randomUUID() : undefined;
+            const streamToken = streamMode ? randomUUID() : undefined;
+            let active = true;
+            let nextStreamSequence = 0;
+            const cleanupStreamListener = () => {
+                if (streamToken) {
+                    state.manager.removeUiStreamListener(streamToken);
+                }
+            };
+            existingHandle.sendToolInput(request.toolArgs);
+            if (streamToken) {
+                state.manager.registerUiStreamListener(streamToken, (serverName, notification) => {
+                    if (!active || state.uiServer !== existingHandle)
+                        return;
+                    if (serverName !== request.serverName)
+                        return;
+                    nextStreamSequence += 1;
+                    existingHandle.sendResultPatch(withStreamEnvelope(notification.result, streamId, nextStreamSequence));
+                });
+            }
+            return {
+                serverName: request.serverName,
+                toolName: request.toolName,
+                reused: true,
+                ...(streamId !== undefined ? { streamId } : {}),
+                ...(streamToken !== undefined ? { streamToken } : {}),
+                ...(streamMode !== undefined ? { streamMode } : {}),
+                ...(streamToken ? { requestMeta: { [UI_STREAM_REQUEST_META_KEY]: streamToken } } : {}),
+                url: existingHandle.url,
+                viewer: existingHandle.viewer ?? "browser",
+                windowOpen: existingHandle.windowOpen ?? true,
+                isActive: () => active && state.uiServer === existingHandle,
+                sendToolResult: (result) => {
+                    if (!active || state.uiServer !== existingHandle)
+                        return;
+                    nextStreamSequence += 1;
+                    existingHandle.sendToolResult(withStreamEnvelope(result, streamId, nextStreamSequence));
+                },
+                sendResultPatch: (result) => {
+                    if (!active || state.uiServer !== existingHandle)
+                        return;
+                    nextStreamSequence += 1;
+                    existingHandle.sendResultPatch(withStreamEnvelope(result, streamId, nextStreamSequence));
+                },
+                sendToolCancelled: (reason) => {
+                    if (!active || state.uiServer !== existingHandle)
+                        return;
+                    nextStreamSequence += 1;
+                    existingHandle.sendToolResult(withStreamEnvelope({
+                        isError: true,
+                        content: [{ type: "text", text: reason }],
+                    }, streamId, nextStreamSequence));
+                },
+                close: () => {
+                    active = false;
+                    cleanupStreamListener();
+                },
+            };
+        }
+        const resource = await state.uiResourceHandler.readUiResource(request.serverName, request.uiResourceUri, {
+            config: state.config,
+            signal: runtimeSignal,
+            onNeedsAuth: request.onNeedsAuth,
+        });
+        throwIfAborted(runtimeSignal);
+        if (state.uiServer) {
+            state.uiServer.close("replaced");
+            state.uiServer = null;
+        }
+        if (activeGlimpseWindow) {
+            activeGlimpseWindow.close();
+            activeGlimpseWindow = null;
+        }
+        const streamMode = request.streamMode;
+        const streamId = streamMode ? randomUUID() : undefined;
+        const streamToken = streamMode ? randomUUID() : undefined;
+        const hostContext = streamMode && streamId
+            ? {
+                [UI_STREAM_HOST_CONTEXT_KEY]: {
+                    mode: streamMode,
+                    streamId,
+                    intermediateResultPatches: streamMode === "stream-first",
+                    partialInput: false,
+                },
+            }
+            : undefined;
+        let active = true;
+        let nextStreamSequence = 0;
+        let handle;
+        const cleanupStreamListener = () => {
+            if (streamToken) {
+                state.manager.removeUiStreamListener(streamToken);
+            }
+        };
+        handle = await startUiServer({
+            serverName: request.serverName,
+            toolName: request.toolName,
+            toolArgs: streamMode === "stream-first" ? {} : request.toolArgs,
+            resource,
+            manager: state.manager,
+            config: state.config,
+            state,
+            ...(request.onNeedsAuth ? { onNeedsAuth: request.onNeedsAuth } : {}),
+            consentManager: state.consentManager,
+            ...(hostContext !== undefined ? { hostContext } : {}),
+            onMessage: (params) => {
+                const prompt = extractUiPromptText(params);
+                if (prompt) {
+                    if (state.sendMessage) {
+                        state.sendMessage({
+                            customType: "mcp-ui-prompt",
+                            content: [{ type: "text", text: `User sent prompt from ${request.serverName} UI: "${prompt}"` }],
+                            display: `💬 UI Prompt: ${prompt}`,
+                            details: { server: request.serverName, tool: request.toolName, prompt },
+                        }, { triggerTurn: true });
+                        log.debug("Triggered agent turn for UI prompt", { prompt: prompt.slice(0, 50) });
+                    }
+                }
+                else if (params.type === "intent" || params.intent) {
+                    const intent = params.intent ?? "";
+                    const intentParams = params.params;
+                    if (intent && state.sendMessage) {
+                        const paramsStr = intentParams ? ` ${JSON.stringify(intentParams)}` : "";
+                        state.sendMessage({
+                            customType: "mcp-ui-intent",
+                            content: [{ type: "text", text: `User triggered intent from ${request.serverName} UI: ${intent}${paramsStr}` }],
+                            display: `🎯 UI Intent: ${intent}`,
+                            details: { server: request.serverName, tool: request.toolName, intent, params: intentParams },
+                        }, { triggerTurn: true });
+                        log.debug("Triggered agent turn for UI intent", { intent });
+                    }
+                }
+                else if (params.type === "notify" || params.message) {
+                    const text = params.message ?? "";
+                    if (text && state.ui) {
+                        state.ui.notify(`[${request.serverName}] ${text}`, "info");
+                    }
+                }
+            },
+            onContextUpdate: (params) => {
+                const update = createUiModelContextUpdate(params);
+                log.debug("Model context update from UI", {
+                    hasContent: !!params.content,
+                    hasStructured: !!params.structuredContent,
+                    hasUpdate: !!update,
+                });
+                if (update && state.sendMessage) {
+                    state.sendMessage({
+                        customType: "mcp-ui-context",
+                        content: [{ type: "text", text: `User submitted model context from ${request.serverName} UI:\n${update.summary}` }],
+                        display: "UI Context submitted",
+                        details: { server: request.serverName, tool: request.toolName, context: update },
+                    }, { triggerTurn: true });
+                }
+            },
+            onComplete: (reason) => {
+                active = false;
+                cleanupStreamListener();
+                if (state.uiServer === handle) {
+                    const messages = handle.getSessionMessages();
+                    const stream = handle.getStreamSummary();
+                    const hasContent = messages.prompts.length > 0 ||
+                        messages.intents.length > 0 ||
+                        messages.notifications.length > 0 ||
+                        messages.contexts.length > 0 ||
+                        !!stream;
+                    if (hasContent) {
+                        state.completedUiSessions.push({
+                            serverName: handle.serverName,
+                            toolName: handle.toolName,
+                            completedAt: new Date(),
+                            reason,
+                            messages,
+                            ...(stream !== undefined ? { stream } : {}),
+                        });
+                        while (state.completedUiSessions.length > MAX_COMPLETED_SESSIONS) {
+                            state.completedUiSessions.shift();
+                        }
+                        log.debug("Session completed", {
+                            reason,
+                            prompts: messages.prompts.length,
+                            intents: messages.intents.length,
+                            notifications: messages.notifications.length,
+                            contexts: messages.contexts.length,
+                            streamFrames: stream?.frames ?? 0,
+                        });
+                    }
+                    state.uiServer = null;
+                    if (activeGlimpseWindow) {
+                        activeGlimpseWindow.close();
+                        activeGlimpseWindow = null;
+                    }
+                }
+            },
+        });
+        if (state.owner?.isActive() === false || runtimeSignal.aborted) {
+            handle.close("runtime_owner_stopped");
+            throwIfAborted(runtimeSignal);
+            throw new Error("MCP UI session became stale before registration");
+        }
+        if (streamToken) {
+            state.manager.registerUiStreamListener(streamToken, (serverName, notification) => {
+                if (!active || state.uiServer !== handle)
+                    return;
+                if (serverName !== request.serverName)
+                    return;
+                nextStreamSequence += 1;
+                handle.sendResultPatch(withStreamEnvelope(notification.result, streamId, nextStreamSequence));
+            });
+        }
+        state.uiServer = handle;
+        const viewerPref = process.env.MCP_UI_VIEWER?.toLowerCase();
+        const uiSuppressed = viewerPref === "none" || viewerPref === "off" || viewerPref === "disabled";
+        let viewer = "browser";
+        let windowOpen = true;
+        const remoteByEnv = isRemoteSession();
+        if (uiSuppressed) {
+            viewer = "suppressed";
+            windowOpen = false;
+            state.ui?.notify(`MCP UI window suppressed (MCP_UI_VIEWER=${viewerPref}). Open manually: ${handle.url}`, "info");
+            log.info("Suppressing MCP UI window (MCP_UI_VIEWER=" + viewerPref + ")", { url: handle.url });
+        }
+        else {
+            const remoteLikely = remoteByEnv || await hasActiveRemoteLogin();
+            const emitRemoteHint = async (openError, openedOnHost = false) => {
+                state.ui?.notify(remoteAccessHint({
+                    url: handle.url,
+                    port: handle.port,
+                    moshi: await probeMoshiGateway(),
+                    openError,
+                    openedOnHost,
+                }), openError === null ? "info" : "warning");
+            };
+            const glimpseDetected = !remoteByEnv && isGlimpseAvailable();
+            const useGlimpse = !remoteByEnv && (viewerPref === "glimpse" ||
+                (viewerPref !== "browser" && glimpseDetected));
+            if (useGlimpse) {
+                try {
+                    const glimpseHtml = `<!DOCTYPE html><html><head><meta charset="utf-8"><style>body{margin:0;padding:0;width:100vw;height:100vh;overflow:hidden}iframe{width:100%;height:100%;border:none}</style></head><body><iframe src="${handle.url}"></iframe></body></html>`;
+                    const glimpseWindow = await openGlimpseWindow(glimpseHtml, {
+                        title: `MCP · ${request.serverName} · ${request.toolName}`,
+                        width: 1000,
+                        height: 800,
+                        onClosed: () => {
+                            if (active)
+                                handle.close("glimpse-closed");
+                        },
+                    });
+                    if (state.owner?.isActive() === false || runtimeSignal.aborted) {
+                        glimpseWindow.close();
+                        throwIfAborted(runtimeSignal);
+                        throw new Error("MCP Glimpse window became stale before registration");
+                    }
+                    activeGlimpseWindow = glimpseWindow;
+                    viewer = "glimpse";
+                    if (remoteLikely) {
+                        await emitRemoteHint(null, true);
+                    }
+                }
+                catch (error) {
+                    log.debug("Glimpse unavailable, using browser", {
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                    const openError = await openInBrowser(state, handle.url, runtimeSignal);
+                    if (openError !== null || remoteLikely) {
+                        await emitRemoteHint(openError);
+                    }
+                    viewer = "browser";
+                }
+            }
+            else {
+                const openError = await openInBrowser(state, handle.url, runtimeSignal);
+                if (openError !== null || remoteLikely) {
+                    await emitRemoteHint(openError);
+                }
+            }
+        }
+        throwIfAborted(runtimeSignal);
+        handle.viewer = viewer;
+        handle.windowOpen = windowOpen;
+        return {
+            serverName: request.serverName,
+            toolName: request.toolName,
+            reused: false,
+            ...(streamId !== undefined ? { streamId } : {}),
+            ...(streamToken !== undefined ? { streamToken } : {}),
+            ...(streamMode !== undefined ? { streamMode } : {}),
+            ...(streamToken ? { requestMeta: { [UI_STREAM_REQUEST_META_KEY]: streamToken } } : {}),
+            url: handle.url,
+            viewer,
+            windowOpen,
+            isActive: () => active && state.uiServer === handle,
+            sendToolResult: (result) => {
+                if (!active || state.uiServer !== handle)
+                    return;
+                nextStreamSequence += 1;
+                handle.sendToolResult(withStreamEnvelope(result, streamId, nextStreamSequence));
+            },
+            sendResultPatch: (result) => {
+                if (!active || state.uiServer !== handle)
+                    return;
+                nextStreamSequence += 1;
+                handle.sendResultPatch(withStreamEnvelope(result, streamId, nextStreamSequence));
+            },
+            sendToolCancelled: (reason) => {
+                if (!active || state.uiServer !== handle)
+                    return;
+                handle.sendToolCancelled(reason);
+            },
+            close: (reason) => {
+                active = false;
+                cleanupStreamListener();
+                handle.close(reason);
+            },
+        };
+    }
+    catch (error) {
+        if (error instanceof UrlElicitationRequiredError || isAbortError(error, runtimeSignal))
+            throw error;
+        const message = error instanceof Error ? error.message : String(error);
+        log.error("Failed to start UI session", error instanceof Error ? error : undefined);
+        state.ui?.notify(`MCP UI unavailable for ${request.toolName} (${request.serverName}): ${message}`, "warning");
+        return null;
+    }
+}

package/dist/ui-stream-types.d.ts

@@ -0,0 +1,104 @@
+import { z } from "zod";
+export declare const UI_STREAM_HOST_CONTEXT_KEY = "pi-mcp-adapter/stream";
+export declare const UI_STREAM_REQUEST_META_KEY = "pi-mcp-adapter/stream-token";
+export declare const UI_STREAM_RESULT_PATCH_METHOD = "notifications/pi-mcp-adapter/ui-result-patch";
+export declare const SERVER_STREAM_RESULT_PATCH_METHOD = "notifications/pi-mcp-adapter/result-patch";
+export declare const UI_STREAM_STRUCTURED_CONTENT_KEY = "pi-mcp-adapter/stream";
+export declare const uiStreamModeSchema: z.ZodEnum<{
+    eager: "eager";
+    "stream-first": "stream-first";
+}>;
+export type UiStreamMode = z.infer<typeof uiStreamModeSchema>;
+export declare const visualizationStreamPhaseSchema: z.ZodEnum<{
+    shell: "shell";
+    narrative: "narrative";
+    structure: "structure";
+    detail: "detail";
+    settled: "settled";
+}>;
+export type VisualizationStreamPhase = z.infer<typeof visualizationStreamPhaseSchema>;
+export declare const visualizationStreamFrameTypeSchema: z.ZodEnum<{
+    patch: "patch";
+    checkpoint: "checkpoint";
+    final: "final";
+}>;
+export type VisualizationStreamFrameType = z.infer<typeof visualizationStreamFrameTypeSchema>;
+export declare const visualizationStreamStatusSchema: z.ZodEnum<{
+    error: "error";
+    ok: "ok";
+}>;
+export type VisualizationStreamStatus = z.infer<typeof visualizationStreamStatusSchema>;
+export declare const uiStreamHostContextSchema: z.ZodObject<{
+    mode: z.ZodEnum<{
+        eager: "eager";
+        "stream-first": "stream-first";
+    }>;
+    streamId: z.ZodString;
+    intermediateResultPatches: z.ZodBoolean;
+    partialInput: z.ZodBoolean;
+}, z.core.$strip>;
+export type UiStreamHostContext = z.infer<typeof uiStreamHostContextSchema>;
+export declare const visualizationStreamEnvelopeSchema: z.ZodObject<{
+    streamId: z.ZodString;
+    sequence: z.ZodNumber;
+    frameType: z.ZodEnum<{
+        patch: "patch";
+        checkpoint: "checkpoint";
+        final: "final";
+    }>;
+    phase: z.ZodEnum<{
+        shell: "shell";
+        narrative: "narrative";
+        structure: "structure";
+        detail: "detail";
+        settled: "settled";
+    }>;
+    status: z.ZodEnum<{
+        error: "error";
+        ok: "ok";
+    }>;
+    message: z.ZodOptional<z.ZodString>;
+    spec: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    checkpoint: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export type VisualizationStreamEnvelope = z.infer<typeof visualizationStreamEnvelopeSchema>;
+export declare const uiStreamCallToolResultSchema: z.ZodObject<{
+    content: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+    structuredContent: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    isError: z.ZodOptional<z.ZodBoolean>;
+    _meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$loose>;
+export type UiStreamCallToolResult = z.infer<typeof uiStreamCallToolResultSchema>;
+export declare const uiStreamResultPatchNotificationSchema: z.ZodObject<{
+    method: z.ZodLiteral<"notifications/pi-mcp-adapter/ui-result-patch">;
+    params: z.ZodObject<{
+        content: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+        structuredContent: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        isError: z.ZodOptional<z.ZodBoolean>;
+        _meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$loose>;
+}, z.core.$strip>;
+export type UiStreamResultPatchNotification = z.infer<typeof uiStreamResultPatchNotificationSchema>;
+export declare const serverStreamResultPatchNotificationSchema: z.ZodObject<{
+    method: z.ZodLiteral<"notifications/pi-mcp-adapter/result-patch">;
+    params: z.ZodObject<{
+        streamToken: z.ZodString;
+        result: z.ZodObject<{
+            content: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+            structuredContent: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            isError: z.ZodOptional<z.ZodBoolean>;
+            _meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, z.core.$loose>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type ServerStreamResultPatchNotification = z.infer<typeof serverStreamResultPatchNotificationSchema>;
+export interface UiStreamSummary {
+    streamId: string;
+    mode: UiStreamMode;
+    frames: number;
+    phases: VisualizationStreamPhase[];
+    finalStatus?: VisualizationStreamStatus;
+    lastMessage?: string;
+}
+export declare function getUiStreamHostContext(hostContext: Record<string, unknown> | undefined): UiStreamHostContext | undefined;
+export declare function getVisualizationStreamEnvelope(structuredContent: unknown): VisualizationStreamEnvelope | undefined;

package/dist/ui-stream-types.js

@@ -0,0 +1,58 @@
+import { z } from "zod";
+export const UI_STREAM_HOST_CONTEXT_KEY = "pi-mcp-adapter/stream";
+export const UI_STREAM_REQUEST_META_KEY = "pi-mcp-adapter/stream-token";
+export const UI_STREAM_RESULT_PATCH_METHOD = "notifications/pi-mcp-adapter/ui-result-patch";
+export const SERVER_STREAM_RESULT_PATCH_METHOD = "notifications/pi-mcp-adapter/result-patch";
+export const UI_STREAM_STRUCTURED_CONTENT_KEY = "pi-mcp-adapter/stream";
+export const uiStreamModeSchema = z.enum(["eager", "stream-first"]);
+export const visualizationStreamPhaseSchema = z.enum(["shell", "narrative", "structure", "detail", "settled"]);
+export const visualizationStreamFrameTypeSchema = z.enum(["patch", "checkpoint", "final"]);
+export const visualizationStreamStatusSchema = z.enum(["ok", "error"]);
+const looseRecordSchema = z.record(z.string(), z.unknown());
+const looseArraySchema = z.array(z.unknown());
+export const uiStreamHostContextSchema = z.object({
+    mode: uiStreamModeSchema,
+    streamId: z.string().min(1),
+    intermediateResultPatches: z.boolean(),
+    partialInput: z.boolean(),
+});
+export const visualizationStreamEnvelopeSchema = z.object({
+    streamId: z.string().min(1),
+    sequence: z.number().int().nonnegative(),
+    frameType: visualizationStreamFrameTypeSchema,
+    phase: visualizationStreamPhaseSchema,
+    status: visualizationStreamStatusSchema,
+    message: z.string().optional(),
+    spec: looseRecordSchema.optional(),
+    checkpoint: looseRecordSchema.optional(),
+});
+export const uiStreamCallToolResultSchema = z.object({
+    content: looseArraySchema.optional(),
+    structuredContent: looseRecordSchema.optional(),
+    isError: z.boolean().optional(),
+    _meta: looseRecordSchema.optional(),
+}).passthrough();
+export const uiStreamResultPatchNotificationSchema = z.object({
+    method: z.literal(UI_STREAM_RESULT_PATCH_METHOD),
+    params: uiStreamCallToolResultSchema,
+});
+export const serverStreamResultPatchNotificationSchema = z.object({
+    method: z.literal(SERVER_STREAM_RESULT_PATCH_METHOD),
+    params: z.object({
+        streamToken: z.string().min(1),
+        result: uiStreamCallToolResultSchema,
+    }),
+});
+export function getUiStreamHostContext(hostContext) {
+    const candidate = hostContext?.[UI_STREAM_HOST_CONTEXT_KEY];
+    const parsed = uiStreamHostContextSchema.safeParse(candidate);
+    return parsed.success ? parsed.data : undefined;
+}
+export function getVisualizationStreamEnvelope(structuredContent) {
+    if (!structuredContent || typeof structuredContent !== "object" || Array.isArray(structuredContent)) {
+        return undefined;
+    }
+    const candidate = structuredContent[UI_STREAM_STRUCTURED_CONTENT_KEY];
+    const parsed = visualizationStreamEnvelopeSchema.safeParse(candidate);
+    return parsed.success ? parsed.data : undefined;
+}

package/dist/ui-tool-visibility.d.ts

@@ -0,0 +1,4 @@
+export type UiToolVisibility = "model" | "app";
+export declare function extractUiToolVisibility(meta: Record<string, unknown> | undefined): UiToolVisibility[] | undefined;
+export declare function isUiToolVisibleToModel(visibility: readonly UiToolVisibility[] | undefined): boolean;
+export declare function isUiToolCallableByApp(visibility: readonly UiToolVisibility[] | undefined): boolean;