@botiverse/porthole 0.0.1 → 0.1.0

package/src/protocol/mcp-apps.ts

@@ -0,0 +1,138 @@
+/**
+ * MCP Apps (`io.modelcontextprotocol/ui`, 2026-01-26): the method names Porthole speaks. The shell
+ * is an MCP Apps view of its host; content may also use the official App SDK directly, so the host
+ * side answers these whoever sends them. This module holds names and shapes only: the core's own
+ * adapter (the subset the shell speaks) and the `/mcp` adapter (full MCP Apps views) both use it.
+ */
+
+export const MCP_APPS_PROTOCOL_VERSION = "2026-01-26";
+
+export const MCP_APPS_METHODS = {
+  // View → host requests.
+  initialize: "ui/initialize",
+  message: "ui/message",
+  openLink: "ui/open-link",
+  downloadFile: "ui/download-file",
+  requestDisplayMode: "ui/request-display-mode",
+  updateModelContext: "ui/update-model-context",
+  callTool: "tools/call",
+  readResource: "resources/read",
+  // View → host notifications.
+  initialized: "ui/notifications/initialized",
+  sizeChanged: "ui/notifications/size-changed",
+  requestTeardown: "ui/notifications/request-teardown",
+  log: "notifications/message",
+  // Host → view notifications.
+  toolInput: "ui/notifications/tool-input",
+  toolInputPartial: "ui/notifications/tool-input-partial",
+  toolResult: "ui/notifications/tool-result",
+  toolCancelled: "ui/notifications/tool-cancelled",
+  hostContextChanged: "ui/notifications/host-context-changed",
+  // Host → view requests.
+  resourceTeardown: "ui/resource-teardown",
+  // Sandbox proxy (a second origin that relays between host and view).
+  sandboxProxyReady: "ui/notifications/sandbox-proxy-ready",
+  sandboxResourceReady: "ui/notifications/sandbox-resource-ready",
+} as const;
+
+export type McpAppsMethod = (typeof MCP_APPS_METHODS)[keyof typeof MCP_APPS_METHODS];
+
+/**
+ * What the shell's `tool-input(-partial)` carries: the content to draw. Porthole's own argument
+ * names, since the shell is the only view that reads them.
+ */
+export interface ShellToolInput {
+  readonly html: string;
+}
+
+/**
+ * The style variables MCP Apps defines (`McpUiStyleVariableKey`, 2026-01-26). The official App SDK
+ * refuses a host context whose `styles.variables` holds any other name ("Unrecognized key"), so a
+ * host sends exactly these there; Porthole's own names go under `PORTHOLE_STYLES` instead.
+ */
+export const MCP_APPS_STYLE_VARIABLES: readonly string[] = [
+  ...["background", "text", "border", "ring"].flatMap((kind) =>
+    (kind === "background"
+      ? [
+          "primary",
+          "secondary",
+          "tertiary",
+          "inverse",
+          "ghost",
+          "info",
+          "danger",
+          "success",
+          "warning",
+          "disabled",
+        ]
+      : kind === "text"
+        ? [
+            "primary",
+            "secondary",
+            "tertiary",
+            "inverse",
+            "ghost",
+            "info",
+            "danger",
+            "success",
+            "warning",
+            "disabled",
+          ]
+        : kind === "border"
+          ? [
+              "primary",
+              "secondary",
+              "tertiary",
+              "inverse",
+              "ghost",
+              "info",
+              "danger",
+              "success",
+              "warning",
+              "disabled",
+            ]
+          : ["primary", "secondary", "inverse", "info", "danger", "success", "warning"]
+    ).map((name) => `--color-${kind}-${name}`),
+  ),
+  "--font-sans",
+  "--font-mono",
+  ...["normal", "medium", "semibold", "bold"].map((weight) => `--font-weight-${weight}`),
+  ...["xs", "sm", "md", "lg"].map((size) => `--font-text-${size}-size`),
+  ...["xs", "sm", "md", "lg", "xl", "2xl", "3xl"].map((size) => `--font-heading-${size}-size`),
+  ...["xs", "sm", "md", "lg"].map((size) => `--font-text-${size}-line-height`),
+  ...["xs", "sm", "md", "lg", "xl", "2xl", "3xl"].map(
+    (size) => `--font-heading-${size}-line-height`,
+  ),
+  ...["xs", "sm", "md", "lg", "xl", "full"].map((size) => `--border-radius-${size}`),
+  "--border-width-regular",
+  ...["hairline", "sm", "md", "lg"].map((size) => `--shadow-${size}`),
+];
+
+/**
+ * The host context's own-prefixed field for the theme variables MCP Apps doesn't define (an
+ * accent, a chart palette): `{ variables }`. The shell applies them with the standard ones; a view
+ * that doesn't know the field ignores it (the host context is open to extra fields).
+ */
+export const PORTHOLE_STYLES = "porthole/styles";
+
+/** The logger name the shell's error reports (`notifications/message`, level `error`) carry. */
+export const SHELL_LOGGER = "porthole";
+
+/**
+ * The host context a view receives in `ui/initialize`'s result and in `host-context-changed`
+ * (the fields Porthole sets; the spec allows more, which views ignore).
+ */
+export interface HostContext {
+  readonly theme: "light" | "dark";
+  readonly styles: { readonly variables: Readonly<Record<string, string>> };
+  readonly displayMode: "inline" | "fullscreen" | "pip";
+  readonly availableDisplayModes: readonly ("inline" | "fullscreen" | "pip")[];
+  readonly containerDimensions?: { readonly maxWidth?: number; readonly maxHeight?: number };
+  readonly locale?: string;
+  readonly timeZone?: string;
+  readonly platform?: "web" | "desktop" | "mobile";
+  readonly deviceCapabilities?: { readonly touch?: boolean; readonly hover?: boolean };
+  /** Porthole's own theme variables, outside the spec's list (`PORTHOLE_STYLES`). */
+  readonly "porthole/styles"?: { readonly variables: Readonly<Record<string, string>> };
+  readonly [key: string]: unknown;
+}

package/src/protocol/shell-adapter.ts

@@ -0,0 +1,261 @@
+import type { CapabilityName } from "../config/capabilities.ts";
+import type { CallOutcome } from "../bridge/types.ts";
+import type { AdapterSession, ProtocolAdapter, ShellConnection } from "./adapter.ts";
+import {
+  JSON_RPC_ERRORS,
+  parseJsonRpc,
+  type JsonRpcId,
+  type JsonRpcRequest,
+  type JsonRpcResponse,
+} from "./jsonrpc.ts";
+import { MCP_APPS_METHODS as M, MCP_APPS_PROTOCOL_VERSION, type HostContext } from "./mcp-apps.ts";
+
+/**
+ * The core's adapter: the host side of the MCP Apps subset the shell speaks, which content using
+ * the official App SDK speaks too. Every message is checked before use; every power goes through
+ * the bridge. Content goes as `tool-input-partial` while it is written and `tool-input` once,
+ * after the view has initialized.
+ */
+
+const LOG_ERRORS = new Set(["error", "critical", "alert", "emergency"]);
+
+/** Requests that are capability calls, and how their params become the capability's args. */
+const REQUESTS: Readonly<
+  Record<string, { capability: CapabilityName; args: (params: Record<string, unknown>) => unknown }>
+> = {
+  [M.message]: {
+    capability: "sendPrompt",
+    args: (params) => ({
+      text: Array.isArray(params.content)
+        ? params.content
+            .map((part: unknown) => {
+              const block = part as { type?: unknown; text?: unknown } | null;
+              return block !== null &&
+                typeof block === "object" &&
+                block.type === "text" &&
+                typeof block.text === "string"
+                ? block.text
+                : "";
+            })
+            .join("")
+        : undefined,
+    }),
+  },
+  [M.openLink]: { capability: "openLink", args: (params) => ({ url: params.url }) },
+  [M.downloadFile]: {
+    capability: "downloadFile",
+    args: (params) => ({ contents: params.contents }),
+  },
+  [M.callTool]: {
+    capability: "callTool",
+    args: (params) => ({ name: params.name, arguments: params.arguments }),
+  },
+  [M.readResource]: { capability: "readData", args: (params) => ({ uri: params.uri }) },
+  [M.updateModelContext]: {
+    capability: "setModelContext",
+    args: (params) => ({ content: params.content, structuredContent: params.structuredContent }),
+  },
+};
+
+/** What a capability's outcome looks like to the view. */
+function answer(
+  capability: CapabilityName,
+  outcome: CallOutcome<unknown>,
+): { result: unknown } | { error: { code: number; message: string } } {
+  const flagged =
+    capability === "sendPrompt" || capability === "openLink" || capability === "downloadFile";
+  if (!outcome.ok) {
+    return flagged
+      ? { result: { isError: true } }
+      : { error: { code: -32000, message: `Refused (${outcome.refusal})` } };
+  }
+  if (flagged) {
+    return { result: outcome.value === true ? {} : { isError: true } };
+  }
+  return { result: outcome.value ?? {} };
+}
+
+/** What the host offers, from the declared capabilities (MCP Apps `hostCapabilities`). */
+export function hostCapabilities(
+  declared: (name: CapabilityName) => boolean,
+): Record<string, object> {
+  const offered: Record<string, object> = {};
+  if (declared("openLink")) {
+    offered.openLinks = {};
+  }
+  if (declared("sendPrompt")) {
+    offered.message = { text: {} };
+  }
+  if (declared("downloadFile")) {
+    offered.downloadFile = {};
+  }
+  if (declared("callTool")) {
+    offered.serverTools = {};
+  }
+  if (declared("readData")) {
+    offered.serverResources = {};
+  }
+  if (declared("setModelContext")) {
+    offered.updateModelContext = { text: {} };
+  }
+  if (declared("reportError")) {
+    offered.logging = {};
+  }
+  return offered;
+}
+
+export const shellAdapter: ProtocolAdapter<ShellConnection> = {
+  name: "porthole-shell",
+  connect(session: AdapterSession): ShellConnection {
+    const { transport, bridge } = session;
+    let initialized = false;
+    let closed = false;
+    let drafted: string | null = null;
+    let content: { html: string; partial: boolean } | null = null;
+    let sentWhole = false;
+    let nextId = 1;
+    const pending = new Map<JsonRpcId, (response: JsonRpcResponse) => void>();
+
+    const respond = (
+      id: JsonRpcId,
+      body: { result: unknown } | { error: { code: number; message: string } },
+    ) => transport.send({ jsonrpc: "2.0", id, ...body });
+    const notify = (method: string, params: Record<string, unknown>) =>
+      transport.send({ jsonrpc: "2.0", method, params });
+
+    const flush = () => {
+      if (!initialized || closed || content === null || sentWhole) {
+        return;
+      }
+      if (content.partial) {
+        if (drafted !== content.html) {
+          drafted = content.html;
+          notify(M.toolInputPartial, { arguments: { html: content.html } });
+        }
+        return;
+      }
+      sentWhole = true;
+      notify(M.toolInput, { arguments: { html: content.html } });
+    };
+
+    const onRequest = async (request: JsonRpcRequest) => {
+      const params = request.params ?? {};
+      if (request.method === M.initialize) {
+        respond(request.id, {
+          result: {
+            protocolVersion: MCP_APPS_PROTOCOL_VERSION,
+            hostInfo: session.hostInfo,
+            hostCapabilities: hostCapabilities((name) => bridge.declared(name)),
+            hostContext: session.hostContext(),
+          },
+        });
+        return;
+      }
+      if (request.method === "ping") {
+        respond(request.id, { result: {} });
+        return;
+      }
+      if (request.method === M.requestDisplayMode) {
+        respond(request.id, { result: { mode: "inline" } });
+        return;
+      }
+      const mapped = REQUESTS[request.method];
+      if (mapped === undefined) {
+        respond(request.id, {
+          error: {
+            code: JSON_RPC_ERRORS.methodNotFound,
+            message: `${request.method} isn't offered here`,
+          },
+        });
+        return;
+      }
+      const outcome = await bridge.call(mapped.capability, mapped.args(params));
+      if (!closed) {
+        respond(request.id, answer(mapped.capability, outcome));
+      }
+    };
+
+    const onNotification = (method: string, params: Record<string, unknown>) => {
+      switch (method) {
+        case M.initialized:
+          if (!initialized) {
+            initialized = true;
+            session.emit({ type: "initialized" });
+            flush();
+          }
+          return;
+        case M.sizeChanged:
+          void bridge.call("resize", { height: params.height, width: params.width });
+          return;
+        case M.log:
+          if (LOG_ERRORS.has(String(params.level))) {
+            const data = params.data;
+            void bridge.call("reportError", {
+              message:
+                typeof data === "string" ? data : JSON.stringify(data ?? null).slice(0, 2_000),
+            });
+          }
+          return;
+        case M.requestTeardown:
+          session.emit({ type: "teardown-requested" });
+          return;
+        default:
+          return;
+      }
+    };
+
+    const stop = transport.listen((raw) => {
+      const message = parseJsonRpc(raw);
+      if (message === null || closed) {
+        return;
+      }
+      if ("method" in message) {
+        if ("id" in message) {
+          void onRequest(message);
+        } else {
+          onNotification(message.method, message.params ?? {});
+        }
+        return;
+      }
+      pending.get(message.id)?.(message);
+      pending.delete(message.id);
+    });
+
+    return {
+      setContent(html: string, options?: { readonly partial?: boolean }) {
+        if (sentWhole) {
+          return;
+        }
+        content = { html, partial: options?.partial === true };
+        flush();
+      },
+      hostContextChanged(context: HostContext) {
+        if (initialized && !closed) {
+          notify(M.hostContextChanged, { ...context });
+        }
+      },
+      teardown() {
+        if (!initialized || closed) {
+          return Promise.resolve();
+        }
+        const id = `teardown-${nextId++}`;
+        return new Promise<void>((resolve) => {
+          const timer = setTimeout(() => {
+            pending.delete(id);
+            resolve();
+          }, 500);
+          pending.set(id, () => {
+            clearTimeout(timer);
+            resolve();
+          });
+          transport.send({ jsonrpc: "2.0", id, method: M.resourceTeardown, params: {} });
+        });
+      },
+      close() {
+        closed = true;
+        stop();
+        pending.clear();
+      },
+    };
+  },
+};

package/src/react/dialog.tsx

@@ -0,0 +1,158 @@
+import { useEffect, useId, useRef, useState, type ReactElement } from "react";
+import type { ConfirmRequest } from "../bridge/types.ts";
+
+/**
+ * The default confirmation dialog (P019): drawn by the host's page, outside every frame, as a
+ * modal (the top layer covers the frames, so content can't draw over it or click it). It shows
+ * the call's whole effect (the prompt's full text, the link's full URL), the display's title as
+ * the host named it, Cancel focused, and ignores presses on its accept button for a moment after
+ * it opens (a click meant for the content mustn't land on it). Escape cancels. A host replaces it
+ * by passing its own `confirm`; it styles it through the `porthole-confirm` class and data
+ * attributes.
+ */
+
+/** How long the accept button ignores presses after the dialog opens. */
+export const ARM_DELAY_MS = 500;
+
+export interface ConfirmDialogProps {
+  /** The call to confirm, or null when nothing is asked. */
+  readonly request: ConfirmRequest | null;
+  readonly onAnswer: (accepted: boolean) => void;
+  readonly className?: string;
+}
+
+interface Words {
+  readonly heading: string;
+  readonly accept: string;
+  /** What the person is shown in full. */
+  readonly detail: string;
+  /** A line under it (the link's host). */
+  readonly note?: string;
+}
+
+const json = (value: unknown): string => JSON.stringify(value, null, 2) ?? "";
+
+function words(request: ConfirmRequest): Words {
+  switch (request.capability) {
+    case "sendPrompt":
+      return { heading: "Send this message?", accept: "Send", detail: request.args.text };
+    case "openLink": {
+      let host = "";
+      try {
+        host = new URL(request.args.url).host;
+      } catch {
+        host = "";
+      }
+      return {
+        heading: "Open this link?",
+        accept: "Open link",
+        detail: request.args.url,
+        ...(host === "" ? {} : { note: `It opens ${host}.` }),
+      };
+    }
+    case "downloadFile":
+      return {
+        heading: "Download this file?",
+        accept: "Download",
+        detail: json(request.args.contents),
+      };
+    case "callTool":
+      return {
+        heading: "Run this tool?",
+        accept: "Run",
+        detail: `${request.args.name}\n${json(request.args.arguments)}`,
+      };
+    case "setModelContext":
+      return { heading: "Share this with the agent?", accept: "Share", detail: json(request.args) };
+    case "readData":
+      return { heading: "Let it read this?", accept: "Allow", detail: request.args.uri };
+    default:
+      return { heading: "Allow this?", accept: "Allow", detail: json(request.args) };
+  }
+}
+
+const STYLE = `.porthole-confirm{color-scheme:light dark;color:CanvasText;background:Canvas;border:1px solid color-mix(in srgb,CanvasText 18%,transparent);border-radius:12px;padding:20px;width:min(440px,calc(100vw - 32px));font:inherit;box-shadow:0 12px 40px rgb(0 0 0 / .28)}
+.porthole-confirm::backdrop{background:rgb(0 0 0 / .4)}
+.porthole-confirm h2{font-size:1.05em;margin:0 0 4px}
+.porthole-confirm [data-porthole-source],.porthole-confirm [data-porthole-note]{opacity:.72;font-size:.9em;margin:0 0 12px}
+.porthole-confirm [data-porthole-detail]{white-space:pre-wrap;overflow-wrap:anywhere;max-height:40vh;overflow:auto;padding:10px 12px;border-radius:8px;background:color-mix(in srgb,CanvasText 7%,transparent);margin:0 0 12px;font:inherit}
+.porthole-confirm menu{display:flex;justify-content:flex-end;gap:8px;margin:16px 0 0;padding:0}
+.porthole-confirm button{font:inherit;min-height:36px;padding:0 14px;border-radius:8px;border:1px solid color-mix(in srgb,CanvasText 25%,transparent);background:transparent;color:inherit;cursor:pointer}
+.porthole-confirm button[data-porthole-accept]{background:Highlight;background:AccentColor;color:HighlightText;color:AccentColorText;border-color:transparent}`;
+
+export function ConfirmDialog({ request, onAnswer, className }: ConfirmDialogProps): ReactElement {
+  const dialog = useRef<HTMLDialogElement>(null);
+  const cancel = useRef<HTMLButtonElement>(null);
+  // The request the accept button is armed for: a new one starts unarmed.
+  const [armedFor, setArmedFor] = useState<ConfirmRequest | null>(null);
+  const armed = request !== null && armedFor === request;
+  const heading = useId();
+
+  useEffect(() => {
+    const element = dialog.current;
+    if (element === null) {
+      return;
+    }
+    if (request === null) {
+      if (element.open) {
+        element.close();
+      }
+      return;
+    }
+    if (!element.open) {
+      element.showModal();
+    }
+    cancel.current?.focus();
+    const timer = setTimeout(() => setArmedFor(request), ARM_DELAY_MS);
+    return () => clearTimeout(timer);
+  }, [request]);
+
+  const said = request === null ? null : words(request);
+  return (
+    <dialog
+      ref={dialog}
+      className={className === undefined ? "porthole-confirm" : `porthole-confirm ${className}`}
+      aria-labelledby={heading}
+      data-porthole-confirm={request?.capability ?? ""}
+      onCancel={(event) => {
+        event.preventDefault();
+        if (request !== null) {
+          onAnswer(false);
+        }
+      }}
+    >
+      <style>{STYLE}</style>
+      {said === null || request === null ? null : (
+        <>
+          <h2 id={heading}>{said.heading}</h2>
+          <p data-porthole-source="">{`From “${request.display.title}”`}</p>
+          <div data-porthole-detail="">{said.detail}</div>
+          {said.note === undefined ? null : <p data-porthole-note="">{said.note}</p>}
+          <menu>
+            <button
+              type="button"
+              ref={cancel}
+              autoFocus
+              data-porthole-cancel=""
+              onClick={() => onAnswer(false)}
+            >
+              Cancel
+            </button>
+            <button
+              type="button"
+              data-porthole-accept=""
+              data-armed={String(armed)}
+              onClick={() => {
+                if (armed) {
+                  onAnswer(true);
+                }
+              }}
+            >
+              {said.accept}
+            </button>
+          </menu>
+        </>
+      )}
+    </dialog>
+  );
+}