cortena-ui 1.8.0 → 1.10.0

package/CHANGELOG.md

@@ -3,6 +3,90 @@
 Notable changes per release. Versions before 1.6.0 are recorded in the git log
 and in `../../CONSUMING.md`; this file starts where the changelog does.
 
+## 1.10.0
+
+1.9.0 was never released: it was published by mistake and has been deprecated.
+
+### Added
+
+- **Screens inside the pop-up** (DESIGN-78). An extension's tool can answer
+  with its own screen — a `ui://` resource — and until now only cortenaweb
+  could show it; the pop-up inside the extension had no host. The host is now
+  in this package, on the `cortena-ui/agent-chat` entry:
+  - `McpAppFrame` — the sandboxed iframe (`allow-scripts allow-forms`, never
+    `allow-same-origin`), the `srcdoc` with the CSP written ahead of the app's
+    markup (`default-src 'none'`, no `unsafe-eval`, `form-action 'none'`), the
+    JSON-RPC bridge (`ui/initialize`, `ui/message`, `tools/call`,
+    `ui/update-model-context`, size and theme), the source and origin check
+    on every message, the height clamp (120–720 px), the `ui/message` bound
+    (`MCP_APP_MAX_MESSAGE_CHARS`, 4,000 chars; longer is refused with
+    `-32602`, since that text reaches the model) and the theme push. It holds
+    no credential: `callTool({ name, arguments, extensionId, lane })` is
+    supplied by the mounting app. A name that visibly belongs to another
+    extension (`mcp__notes__x`, `notes.note.delete`) is refused with `-32602`
+    before the relay is reached; a bare name (`task_get`, and equally
+    `broker_invoke`, `exec`, `read_file`) names no extension, so the frame
+    does not claim to confine it — it arrives as `lane: "bare"` beside
+    `extensionId`, for a relay that resolves it on that extension and nowhere
+    else. A resource another extension owns, a non-HTML type or a document
+    over
+    `MCP_APP_MAX_DOCUMENT_CHARS` (512,000; exported so a caller can make the
+    bound its own later, PLATFORM-82) is drawn as nothing and reported through
+    `onRefused`. Design tokens go in as `tokensCss` (inlined) or `tokensUrl`
+    (linked; its origin joins `style-src`/`font-src`); nothing is fetched
+    implicitly.
+  - `renderMcpAppToolCall({ extensionId, callTool, onMessage, … })` — a
+    `renderToolCall` for one extension. A screen is drawn only when the
+    *producing tool* can be named as this extension's — `mcp__<extensionId>__*`,
+    or `broker_invoke` whose `source` argument is this extension — **and** the
+    result carries that extension's embedded `ui://` resource (with
+    `structuredContent` from the result, or from
+    `_meta.cortena.structuredContent` on the block, as a reopened chat carries
+    it). A result is not a permission: an `exec` or a `read_file` whose output
+    happens to embed a `ui://` block keeps the ordinary card. `isEligible`
+    replaces the allowlist for a host whose tools are spelled another way.
+    Anything else returns `undefined` and the default card is drawn. Same type
+    as the seam in every mode.
+  - `AgentChatPopup` and owned-mode `AgentChat` take `renderToolCall` as
+    hosted mode does — the prop was on the shared base already; this release
+    pins it with a type-level test that the 1.7.0 mount shapes still compile.
+    See "Screens inside the pop-up" in `README.md`.
+- **The pop-up keeps every turn, and a screen can answer back** (DESIGN-80).
+  The pop-up used to hold the current turn only: `send` emptied the tool
+  cards, so an extension's screen was unmounted by the very turn it asked
+  for. It now behaves like the main chat.
+  - **A turn's tool record is its own.** Each turn keeps its steps, its cards
+    and its screens, and they are drawn in the transcript **under the answer
+    that turn produced** rather than in a strip at the foot that the next run
+    clears. A screen from three turns ago is still on the page and still
+    running. `AgentChatState` gains `turns?: AgentChatTurn[]` — optional, so a
+    host projecting its own store onto `UseAgentChatResult` compiles and
+    behaves exactly as before — with `TURN_LIMIT` (20) turns kept.
+  - **A reopened chat gets the record back, not just the prose.**
+    `parseHistory(records)` returns the messages *and* the per-turn tool
+    record behind them: the calls (`tool_use`, `toolCall`, `serverToolUse` —
+    matched with the case and the underscores taken out, as cortenacore
+    matches them), their results, and the embedded `ui://` resource with its
+    payload read from `_meta.cortena.structuredContent` where the pod
+    persisted it. The budget is cortenaweb's: 1,100,000 characters for one
+    result (`MAX_HISTORY_TOOL_RESULT_CHARS`) and 2,000,000 for a whole load
+    (`MAX_HISTORY_SNAPSHOT_RESULT_CHARS`), spent newest turn first; past it a
+    result becomes a note giving its size, with the call id, the tool's name
+    and whether it failed all kept. `parseHistoryMessages` is unchanged.
+  - **`AgentToolRenderContext` gains `send(text)`**, and
+    `AgentChatToolsSlotProps` gains the same field for a host that replaces
+    the region and builds the context itself. Optional on both, so a host
+    that builds the render context as an object literal of its own — as
+    cortenaweb's step accordion does — compiles unchanged. `renderMcpAppToolCall` wires
+    `onMessage` to it by default, so `onMessage` is now optional: a
+    `ui/message` from a screen goes out as the MCP App action envelope —
+    `{ toolCallId, appUri, serverName, name: "message", payload: { text } }` —
+    attributed to the screen, with no user bubble, bounded by
+    `MCP_APP_MAX_MESSAGE_CHARS` (4,000) and refused while a run is live.
+  - A host that supplies `components.Tools` still owns the whole tool region:
+    it is handed every turn's entries, and the transcript draws none.
+  - See "Screens inside the pop-up" in `README.md`.
+
 ## 1.8.0
 
 ### Added

package/README.md

@@ -300,24 +300,101 @@ cortenacore.http.endpoints.agui.enabled          = true
 cortenacore.http.endpoints.controlPlane.enabled  = true
 ```
 
-### The MCP App frame
+### Screens inside the pop-up
 
-Rendering an extension's own screen means a sandboxed iframe, a `srcdoc` CSP, a
-JSON-RPC postMessage bridge and a `tools/invoke` proxy holding a credential —
-host concerns, not component ones. `renderToolCall` is the seam: it is handed
-each tool call and the `ui://` resource its result carries, and a node it
-returns replaces the default card.
+An extension's tool may answer with the extension's own screen — an embedded
+`ui://` resource whose body is HTML — and the pop-up draws it inside the
+conversation, sandboxed, with a postMessage bridge (DESIGN-78; the protocol as
+implemented is cortena's `docs/mcp-apps.md`). `renderToolCall` is the seam,
+in every mode, and `renderMcpAppToolCall` answers it for one extension:
 
 ```tsx
-<AgentChatPopup
-  extension={extension}
-  client={client}
-  renderToolCall={({ entry, mcpAppUri }) =>
-    mcpAppUri ? <McpAppFrame uri={mcpAppUri} result={entry.output} /> : undefined
-  }
-/>
+const renderToolCall = renderMcpAppToolCall({ extensionId: "tasks", callTool });
+<AgentChatPopup extension={extension} client={client} renderToolCall={renderToolCall} />
 ```
 
+That is the whole round trip. A tool answers with a screen, the screen is
+drawn under the answer it came with, a click inside it starts the next turn,
+and the screen is still there when the answer arrives (DESIGN-80).
+
+- **Only a tool that can be named as yours may draw a screen.** The default
+  allowlist is `mcp__<extensionId>__*`, and `broker_invoke` whose `source`
+  argument is your extension. A result is not a permission: an `exec` that
+  cat'd a fixture or a `read_file` over your test data answers with whatever
+  `ui://` block was in the file, and that stays an ordinary tool card. Pass
+  `isEligible(entry)` to replace the rule if your host's tools are spelled a
+  third way — you are replacing an allowlist, so you are deciding which tools
+  may put unreviewed HTML on the page.
+- `callTool(call)` is **yours**: the relay that reaches your extension — your
+  own MCP relay, or cortenaweb's `/tools/invoke` — and whatever credential it
+  takes stays with it. The frame never sees a token. It hands you
+  `{ name, arguments, extensionId, lane }`, and the lane is the point:
+
+  ```ts
+  type McpAppToolCaller = (call: {
+    name: string;
+    arguments: Record<string, unknown>;
+    extensionId: string;
+    lane: "mcp" | "broker" | "bare";
+  }) => Promise<unknown>;
+  ```
+
+  `lane: "mcp"` (`mcp__tasks__x`) and `lane: "broker"` (`tasks.task.get`)
+  carry the extension in the name, and a name that carries a *different* one
+  (`mcp__notes__x`, `notes.note.delete`) is refused with `-32602` before your
+  relay is reached. `lane: "bare"` (`task_get`) carries nothing: `exec`,
+  `read_file` and `broker_invoke` are bare names too. **Resolve a bare name on
+  `extensionId` and nowhere else** — never forward it as a tool name of your
+  own — and an app cannot reach past its extension whatever it asks for.
+- `onMessage(text)` is the app asking for something to be said, and **it is
+  wired for you**: with nothing passed, the text goes out through the seam's
+  own `send` as the next turn, attributed to the screen and not to the user —
+  nobody typed it, so no user bubble is drawn. What reaches the agent is the
+  MCP App action envelope (`{ toolCallId, appUri, serverName, name: "message",
+  payload: { text } }`), which is what lets an agent tell an event from your
+  board apart from one from another extension's card. It is bounded: the host
+  refuses text over 4,000 characters (`MCP_APP_MAX_MESSAGE_CHARS`) with
+  `-32602`, because this text reaches the model, and it is a no-op while a run
+  is already live — one run at a time, the same rule the composer follows.
+  Pass your own `onMessage` to do something else with it instead.
+  `onModelContext(ctx)` is its latest context for the next run.
+- A call from a tool outside the allowlist, or a result carrying another
+  extension's screen, a bare link, or no screen at all, returns `undefined`
+  and the default card is drawn.
+- Design tokens are not fetched implicitly. Pass `tokensCss` (the sheet,
+  inlined ahead of the app's markup) or `tokensUrl` (linked; its origin joins
+  `style-src` and `font-src`, never `connect-src`).
+
+What the frame owns and no caller can widen: `sandbox="allow-scripts
+allow-forms"` (never `allow-same-origin`, so the document runs in an opaque
+origin with no storage and no reach into the page), a CSP written into the
+`srcdoc` ahead of the app's markup (`default-src 'none'`, no `unsafe-eval`,
+`form-action 'none'`; `_meta.ui.csp` on the resource may open named `https`
+origins and nothing else), a message check that accepts only its own frame's
+window at an opaque origin, a height the app asks for clamped to 120–720 px,
+and a document bound of `MCP_APP_MAX_DOCUMENT_CHARS` (512,000) past which the
+resource is refused. A refusal draws nothing and reports through
+`onRefused(reason)`. `McpAppFrame` is exported for a host that finds the
+resource itself.
+
+**Where a screen lives.** Each turn keeps its own tool record — its steps, its
+cards and its screens — and the record is drawn in the transcript under the
+answer that turn produced, not in a strip at the foot that the next `send`
+empties. So a screen from three turns ago is still on the page, still running,
+and a turn sent from a screen does not unmount the screen that sent it. The
+record of a turn survives a reopen too: `chat.history` carries the calls and
+their results, so the cards, the worded steps and any screen come back with the
+prose (`parseHistory`). Twenty turns are kept (`TURN_LIMIT`), and a reopen
+spends at most 2 MB on tool results, newest turn first; past that a result
+becomes a note that says how big it was, with its call, its name and its
+outcome intact.
+
+`AgentToolRenderContext` therefore carries `send(text)` — the handle
+`renderMcpAppToolCall` wires `onMessage` to. A host that replaces the whole
+tool region with `components.Tools` gets the same handle on its slot props and
+passes it into `renderToolCall` itself; that host owns every card, so the
+transcript draws none, and its `entries` are every turn's, not just the newest.
+
 ### Hosting the surface
 
 `AgentChatPopup` owns its state. A host that already has state of its own —

package/dist/agent-chat/mcp-app/bridge.d.ts

@@ -0,0 +1,194 @@
+"use client";
+//#region src/agent-chat/mcp-app/bridge.d.ts
+/**
+ * The host side of the MCP Apps postMessage bridge.
+ *
+ * Implements the host role of the MCP Apps specification dated 2026-01-26 —
+ * the one `@modelcontextprotocol/ext-apps` 1.7.5 publishes — with the method
+ * names and handshake verbatim, so an app built with the SDK's `App` class
+ * connects with no Cortena-specific code. Ported from cortenaweb's host
+ * (DESIGN-36); the spec strings are copied rather than imported so this
+ * package does not take `@modelcontextprotocol/sdk` and a zod copy into the
+ * browser bundle for one JSON-RPC dialogue, and the tests pin every one.
+ *
+ * ## Who the host will listen to
+ *
+ * Three checks, in order, before a frame's message is looked at at all:
+ *
+ * 1. `event.source === iframe.contentWindow` — the one thing a frame cannot
+ *    forge. Any other frame on the page fails here.
+ * 2. `event.origin === "null"` — an app runs without `allow-same-origin`, so
+ *    its origin is opaque and serialises as the string `"null"`. A message
+ *    from a real origin did not come from a sandboxed app, whatever its
+ *    `source` claims.
+ * 3. The body must be a JSON-RPC 2.0 envelope naming a method the host serves.
+ *
+ * Replies go out with `targetOrigin: "*"`, which is correct rather than lazy:
+ * an opaque origin cannot be named, so `"*"` is the only value that reaches
+ * it, and nothing sent is a secret — the tool result the app's own extension
+ * produced, and the theme.
+ */
+/** `LATEST_PROTOCOL_VERSION` in the MCP Apps spec. */
+export declare const MCP_APP_PROTOCOL_VERSION = "2026-01-26";
+/** Every method name the spec defines, as the host sees them. */
+export declare const MCP_APP_METHOD: {
+  readonly INITIALIZE: "ui/initialize";
+  readonly OPEN_LINK: "ui/open-link";
+  readonly MESSAGE: "ui/message";
+  readonly UPDATE_MODEL_CONTEXT: "ui/update-model-context";
+  readonly REQUEST_DISPLAY_MODE: "ui/request-display-mode";
+  readonly CALL_TOOL: "tools/call";
+  readonly PING: "ping";
+  readonly INITIALIZED: "ui/notifications/initialized";
+  readonly SIZE_CHANGED: "ui/notifications/size-changed";
+  readonly TOOL_INPUT: "ui/notifications/tool-input";
+  readonly TOOL_RESULT: "ui/notifications/tool-result";
+  readonly HOST_CONTEXT_CHANGED: "ui/notifications/host-context-changed";
+};
+/** JSON-RPC error codes the host returns. */
+export declare const MCP_APP_ERROR: {
+  readonly METHOD_NOT_FOUND: -32601;
+  readonly INVALID_PARAMS: -32602;
+  readonly INTERNAL: -32603;
+};
+/**
+ * The longest `ui/message` the host will carry.
+ *
+ * `ui/message` becomes a turn in the conversation, so the text an app sends
+ * is text that goes to the model — and an app is HTML nobody reviewed. An
+ * unbounded field is a way to spend a context window, and a paste of a
+ * hundred kilobytes is not a sentence a screen wanted said. Long enough for
+ * any real request; short enough that it cannot be the payload.
+ */
+export declare const MCP_APP_MAX_MESSAGE_CHARS = 4000;
+export interface McpAppHostContext {
+  theme?: "light" | "dark";
+  styles?: {
+    variables?: Record<string, string | undefined>;
+  };
+  displayMode?: "inline";
+  availableDisplayModes?: Array<"inline">;
+  containerDimensions?: {
+    maxWidth?: number;
+    maxHeight?: number;
+  };
+  locale?: string;
+  timeZone?: string;
+  userAgent?: string;
+  platform?: "web";
+  /** Cortena extension: where the app can fetch the design tokens, when the host serves them. */
+  cortena?: {
+    tokensCssUrl?: string;
+  };
+  [key: string]: unknown;
+}
+/**
+ * How a scoped `tools/call` reaches the app's own extension. Supplied by the
+ * mounting app; the frame never sees a token.
+ *
+ * The call arrives as one envelope rather than a name and arguments, because
+ * a name on its own cannot be confined. Two of the three spellings an app may
+ * use carry the extension (`mcp__tasks__x`, `tasks.task.get`) and are refused
+ * before they reach here when the extension is not this one; the third is
+ * **bare** (`task_get`), and a bare name names nothing — `broker_invoke`,
+ * `exec` and `read_file` are bare names too. So `extensionId` and `lane`
+ * travel with it: a relay handed `lane: "bare"` must resolve `name` on
+ * `extensionId` and nowhere else, and a relay that scopes on `extensionId`
+ * cannot be tricked into forwarding an app's bare name as a tool of its own.
+ */
+export type McpAppToolCaller = (call: {
+  name: string;
+  arguments: Record<string, unknown>;
+  extensionId: string;
+  lane: "mcp" | "broker" | "bare";
+}) => Promise<unknown>;
+export interface McpAppBridgeOptions {
+  /** The frame the app runs in. Its `contentWindow` is the only valid source. */
+  iframe: HTMLIFrameElement;
+  /** The extension the app belongs to; every `tools/call` is confined to it. */
+  extensionId: string;
+  /** `_meta.ui` the resource declared, echoed in `hostCapabilities.sandbox`. */
+  sandbox?: {
+    permissions?: unknown;
+    csp?: unknown;
+  };
+  /** Arguments the agent passed. Sent as `ui/notifications/tool-input`. */
+  toolArguments?: Record<string, unknown>;
+  /** The whole tool result. Sent as `ui/notifications/tool-result`. */
+  toolResult?: unknown;
+  hostContext: McpAppHostContext;
+  /** Present only when the app's own extension can be reached. */
+  callTool?: McpAppToolCaller;
+  /** `ui/message`: the text the app wants said in the conversation. */
+  onMessage?: (text: string) => void;
+  /** The app asked for a height. */
+  onSizeChanged?: (size: {
+    width?: number;
+    height?: number;
+  }) => void;
+  /** The handshake completed. */
+  onInitialized?: () => void;
+  /** `ui/open-link`. Defaults to a `noopener` `window.open`. */
+  onOpenLink?: (url: string) => boolean;
+  /** The app's latest `ui/update-model-context`. */
+  onModelContext?: (context: {
+    content?: unknown[];
+    structuredContent?: unknown;
+  }) => void;
+  /** For tests. Defaults to `window`. */
+  listenTarget?: Pick<Window, "addEventListener" | "removeEventListener">;
+}
+export declare class McpAppHostBridge {
+  private readonly options;
+  private readonly listenTarget;
+  private hostContext;
+  private toolResult;
+  private initialized;
+  private closed;
+  private readonly onMessage;
+  constructor(options: McpAppBridgeOptions);
+  start(): void;
+  close(): void;
+  /** Did the app complete `ui/initialize` + `ui/notifications/initialized`? */
+  get isInitialized(): boolean;
+  /**
+   * Capabilities the host advertises. `serverTools` only when there is a
+   * caller: an app that sees it absent knows not to try, which is the spec's
+   * own way of saying "not here" and better than letting it call and fail.
+   */
+  private capabilities;
+  /**
+   * A replaced tool result for a screen already running.
+   *
+   * The same call re-run answers with the same document, so the frame is not
+   * remounted and the app never repeats its handshake — which is where the
+   * payload is otherwise sent. Without this the screen would keep drawing the
+   * first answer's data for the rest of the conversation.
+   */
+  setToolResult(result: unknown): void;
+  /** Push a changed theme (or anything else) to a running app. */
+  setHostContext(patch: McpAppHostContext): void;
+  private post;
+  private notify;
+  private respond;
+  private fail;
+  /** The right window, and an origin that proves it is sandboxed. */
+  private isFromApp;
+  private handleMessage;
+  private dispatch;
+  /**
+   * `tools/call` from the app: scoped, not proxied. The app may call tools on
+   * *its own* extension and nothing else — see `scopeMcpAppToolCall` for the
+   * rule and why. A name that visibly belongs to another extension is refused
+   * here, before the relay is reached; a bare name reaches the relay wrapped
+   * in `extensionId` and `lane: "bare"`, so the relay resolves it on this
+   * extension rather than taking it for a tool of its own. Whatever the relay
+   * answers goes back as the result, and a throw becomes a tool result the
+   * app can show.
+   */
+  private handleCallTool;
+  /** The tool's arguments and result, once the app says it is listening. */
+  private sendToolPayload;
+}
+//#endregion
+//# sourceMappingURL=bridge.d.ts.map