@tylertech/forge-ai 0.15.2 → 0.15.3-dev.0

package/dist/ai-chatbot/ai-chatbot-base.mjs

@@ -1,5 +1,7 @@
+import { provide } from "@lit/context";
 import { LitElement } from "lit";
 import { property } from "lit/decorators.js";
+import { mcpAppHostContext } from "../tools/ai-mcp-app/mcp-app-context.mjs";
 import { ChatbotCoreController } from "../core/chatbot-core-controller.mjs";
 import { fileAttachmentsToContextItems, generateId, formatChatTranscript, downloadFile, createChatExportFilename } from "./utils.mjs";
 var __defProp = Object.defineProperty;
@@ -11,6 +13,34 @@ var __decorateClass = (decorators, target, key, kind) => {
   if (result) __defProp(target, key, result);
   return result;
 };
+function mcpAppHostCapabilities(adapter) {
+  return {
+    openLinks: {},
+    logging: {},
+    message: { text: {} },
+    ...typeof adapter?.callMcpTool === "function" ? { serverTools: {} } : {},
+    ...typeof adapter?.updateMcpModelContext === "function" ? { updateModelContext: { text: {}, structuredContent: {} } } : {}
+  };
+}
+function mcpAppEnvironment() {
+  return {
+    availableDisplayModes: ["inline", "fullscreen", "pip"],
+    locale: navigator.language,
+    timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+    userAgent: navigator.userAgent,
+    platform: "web",
+    deviceCapabilities: {
+      touch: window.matchMedia("(pointer: coarse)").matches || navigator.maxTouchPoints > 0,
+      hover: window.matchMedia("(hover: hover)").matches
+    },
+    safeAreaInsets: { top: 0, right: 0, bottom: 0, left: 0 }
+  };
+}
+function mcpMessageText(content) {
+  return content.filter(
+    (block) => !!block && typeof block === "object" && block.type === "text" && typeof block.text === "string"
+  ).map((block) => block.text).join("\n\n");
+}
 class AiChatbotBase extends LitElement {
   constructor() {
     super(...arguments);
@@ -29,6 +59,74 @@ class AiChatbotBase extends LitElement {
     this.clearOption = "on";
     this.agents = [];
     this.contextItems = [];
+    this.#themeMediaQuery = window.matchMedia("(prefers-color-scheme: dark)");
+    this.#mcpAppViews = /* @__PURE__ */ new Map();
+    this._mcpAppHost = {
+      callTool: (params) => this._coreController?.adapter?.callMcpTool?.(params) ?? Promise.reject(new Error("tools/call is not supported by this host")),
+      readResource: (params) => this._coreController?.adapter?.readMcpResource?.(params) ?? Promise.reject(new Error("resources/read is not supported by this host")),
+      updateModelContext: (params) => this._coreController?.adapter?.updateMcpModelContext?.(params) ?? Promise.resolve(),
+      draftMessage: ({ content }) => this.#draftMcpAppMessage(content),
+      teardownView: ({ toolCallId }) => this._teardownMcpAppViews({ toolCallIds: [toolCallId] }),
+      registerView: (view) => {
+        this.#mcpAppViews.set(view.toolCallId, view);
+        return () => {
+          if (this.#mcpAppViews.get(view.toolCallId) === view) {
+            this.#mcpAppViews.delete(view.toolCallId);
+          }
+        };
+      },
+      hostContext: { theme: this.#effectiveTheme, ...mcpAppEnvironment() },
+      sandboxUrl: void 0,
+      hostCapabilities: mcpAppHostCapabilities(void 0)
+    };
+    this.#handleThemeChange = () => {
+      this.#refreshMcpAppHostContext();
+    };
+  }
+  #themeMediaQuery;
+  get #effectiveTheme() {
+    return this.mcpAppTheme ?? (this.#themeMediaQuery.matches ? "dark" : "light");
+  }
+  #mcpAppViews;
+  /**
+   * Places a widget's `ui/message` text in the prompt for the user to review and send. A
+   * widget never starts a model turn on its own. Refused when the message has no text.
+   */
+  async #draftMcpAppMessage(content) {
+    const text = mcpMessageText(content);
+    const prompt = this._promptRef.value;
+    if (!text.trim() || !prompt) {
+      return { isError: true };
+    }
+    prompt.value = text;
+    prompt.focus();
+    return {};
+  }
+  /**
+   * Sends `ui/resource-teardown` to mounted MCP-app widgets (all, or only `toolCallIds`) and
+   * releases them immediately, without waiting for acks. The adapter then drops any state it
+   * holds for them (e.g. a pending model context).
+   */
+  _teardownMcpAppViews({ toolCallIds } = {}) {
+    const views = [...this.#mcpAppViews.values()].filter((view) => toolCallIds?.includes(view.toolCallId) ?? true);
+    for (const view of views) {
+      this.#mcpAppViews.delete(view.toolCallId);
+      view.teardown();
+      this._coreController?.adapter?.disposeMcpAppView?.({ toolCallId: view.toolCallId });
+    }
+  }
+  /** Tears down widgets rendered at or after `index`, then removes those items. */
+  #removeMessageItemsFrom(index) {
+    this._teardownMcpAppViews({ toolCallIds: this._coreController.getToolCallIdsFrom(index) });
+    this._coreController.removeMessageItemsFrom(index);
+  }
+  #handleThemeChange;
+  /** A new host context object makes every widget re-read its Forge styles and notify its View. */
+  #refreshMcpAppHostContext() {
+    this._mcpAppHost = {
+      ...this._mcpAppHost,
+      hostContext: { ...this._mcpAppHost.hostContext, theme: this.#effectiveTheme }
+    };
   }
   get _isStreaming() {
     return this._coreController?.isStreaming ?? false;
@@ -66,12 +164,26 @@ class AiChatbotBase extends LitElement {
     if (this.adapter) {
       this._coreController.adapter = this.adapter;
     }
+    this.#themeMediaQuery.addEventListener("change", this.#handleThemeChange);
     this._onConnected();
   }
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    this.#themeMediaQuery.removeEventListener("change", this.#handleThemeChange);
+  }
   willUpdate(changedProperties) {
     if (changedProperties.has("adapter") && this._coreController) {
       this._coreController.adapter = this.adapter;
     }
+    if (changedProperties.has("adapter")) {
+      this._mcpAppHost = { ...this._mcpAppHost, hostCapabilities: mcpAppHostCapabilities(this.adapter) };
+    }
+    if (changedProperties.has("mcpAppSandboxUrl")) {
+      this._mcpAppHost = { ...this._mcpAppHost, sandboxUrl: this.mcpAppSandboxUrl };
+    }
+    if (changedProperties.has("mcpAppTheme")) {
+      this.#refreshMcpAppHostContext();
+    }
   }
   _onConnected() {
   }
@@ -239,7 +351,7 @@ class AiChatbotBase extends LitElement {
     }
     const responseIndex = messageIndex + 1;
     if (responseIndex < this._messageItems.length) {
-      this._coreController.removeMessageItemsFrom(responseIndex);
+      this.#removeMessageItemsFrom(responseIndex);
     }
     adapter.sendMessage(this.getMessages());
   }
@@ -256,7 +368,7 @@ class AiChatbotBase extends LitElement {
     this._coreController.updateMessageContent(messageId, content);
     const responseIndex = messageIndex + 1;
     if (responseIndex < this._messageItems.length) {
-      this._coreController.removeMessageItemsFrom(responseIndex);
+      this.#removeMessageItemsFrom(responseIndex);
     }
     adapter.sendMessage(this.getMessages());
   }
@@ -272,7 +384,7 @@ class AiChatbotBase extends LitElement {
     if (responseIndex === -1) {
       return;
     }
-    this._coreController.removeMessageItemsFrom(responseIndex);
+    this.#removeMessageItemsFrom(responseIndex);
     adapter.sendMessage(this.getMessages());
   }
   _handleFeedback(evt, type) {
@@ -348,6 +460,7 @@ class AiChatbotBase extends LitElement {
     if (event.defaultPrevented) {
       return false;
     }
+    this._teardownMcpAppViews();
     this._coreController.clearMessages();
     return true;
   }
@@ -365,6 +478,7 @@ class AiChatbotBase extends LitElement {
    * resetting thread IDs or closing panels.
    */
   startNewChat() {
+    this._teardownMcpAppViews();
     this._coreController.clearMessages();
   }
   getMessages() {
@@ -431,6 +545,14 @@ class AiChatbotBase extends LitElement {
   abort() {
     this._handleStop();
   }
+  /**
+   * Re-sends the Forge-derived `styles.variables` to every MCP-app widget. Call after
+   * changing Forge tokens without a light/dark switch (e.g. a brand change); for light/dark,
+   * set {@link mcpAppTheme} instead.
+   */
+  refreshMcpAppStyles() {
+    this.#refreshMcpAppHostContext();
+  }
   async scrollToBottom({ behavior } = {}) {
     await this._messageThreadRef.value?.updateComplete;
     await new Promise(requestAnimationFrame);
@@ -448,6 +570,7 @@ class AiChatbotBase extends LitElement {
     return this.agents.find((a) => a.id === this.selectedAgentId);
   }
   async setThreadState(threadState) {
+    this._teardownMcpAppViews();
     this.setMessages(threadState.messages);
     this.selectedAgentId = threadState.selectedAgentId;
     if (threadState.threadId && this._coreController.adapter) {
@@ -535,6 +658,16 @@ __decorateClass([
 __decorateClass([
   property({ attribute: false })
 ], AiChatbotBase.prototype, "contextItems");
+__decorateClass([
+  property({ attribute: "mcp-app-sandbox-url" })
+], AiChatbotBase.prototype, "mcpAppSandboxUrl");
+__decorateClass([
+  property({ attribute: "mcp-app-theme" })
+], AiChatbotBase.prototype, "mcpAppTheme");
+__decorateClass([
+  provide({ context: mcpAppHostContext }),
+  property({ attribute: false })
+], AiChatbotBase.prototype, "_mcpAppHost");
 export {
   AiChatbotBase
 };

package/dist/ai-chatbot/index.d.ts

@@ -3,8 +3,8 @@ export { AiChatbotComponent, AiChatbotComponentTagName } from './ai-chatbot.js';
 export type { ForgeAiChatbotMessageEventData, ForgeAiChatbotToolCallEventData, ForgeAiChatbotErrorEventData, ForgeAiChatbotResponseFeedbackEventData, ForgeAiChatbotAgentChangeEventData, ForgeAiChatbotFileSelectEventData, ForgeAiChatbotFileRemoveEventData } from './ai-chatbot.js';
 export { AiChatbotToolCallComponent, AiChatbotToolCallComponentTagName } from './ai-chatbot-tool-call.js';
 export type { Suggestion } from '../ai-suggestions/index.js';
-export { AgentAdapter, type MessageStartEvent, type MessageDeltaEvent, type MessageEndEvent, type ToolCallEvent, type ToolCallStartEvent, type ToolCallArgsEvent, type ToolCallEndEvent, type FileUploadEvent, type FileRemoveEvent, type AdapterState, type ErrorEvent, type CustomAgentEvent, type RawAgentEvent, type RunStartedAgentEvent, type StepStartedAgentEvent, type StepFinishedAgentEvent, type StateSnapshotAgentEvent, type StateDeltaAgentEvent, type ActivitySnapshotAgentEvent, type ActivityDeltaAgentEvent } from './agent-adapter.js';
-export type { Agent, ChatMessage, ClientMessageAction, ClientMessageInput, ClientMessageKind, ContextItem, ToolDefinition, ToolCall, ToolRenderer, IToolRenderer, HandlerContext, ToolStartContext, ToolDeltaContext, ToolEndContext, FileAttachment, UploadedFileMetadata, FileUploadCallbacks, FileUploadHandler, FileRemoveCallbacks, ThreadState, FeedbackType, ResponseFeedback, MessageItem, ForgeAiChatbotContextRemoveEventData, ForgeAiChatbotThreadSelectEventData, ForgeAiChatbotThreadSearchEventData, ForgeAiChatbotThreadLoadMoreEventData, ForgeAiChatbotThreadRenameEventData, ForgeAiChatbotThreadDeleteEventData } from './types.js';
+export { AgentAdapter, type MessageStartEvent, type MessageDeltaEvent, type MessageEndEvent, type ToolCallEvent, type ToolCallStartEvent, type ToolCallArgsEvent, type ToolCallEndEvent, type FileUploadEvent, type FileRemoveEvent, type AdapterState, type ErrorEvent, type CustomAgentEvent, type RawAgentEvent, type RunStartedAgentEvent, type StepStartedAgentEvent, type StepFinishedAgentEvent, type StateSnapshotAgentEvent, type StateDeltaAgentEvent, type ActivitySnapshotAgentEvent, type ActivityDeltaAgentEvent, type McpUiResourceEvent, type McpToolCallParams, type McpResourceReadParams, type McpAppResourceResolveParams, type McpModelContextUpdateParams, type ToolResultEvent } from './agent-adapter.js';
+export type { Agent, ChatMessage, ClientMessageAction, ClientMessageInput, ClientMessageKind, ContextItem, ToolDefinition, ToolCall, ToolCallStatus, ToolRenderer, IToolRenderer, HandlerContext, ToolStartContext, ToolDeltaContext, ToolEndContext, FileAttachment, UploadedFileMetadata, FileUploadCallbacks, FileUploadHandler, FileRemoveCallbacks, ThreadState, FeedbackType, ResponseFeedback, MessageItem, ForgeAiChatbotContextRemoveEventData, ForgeAiChatbotThreadSelectEventData, ForgeAiChatbotThreadSearchEventData, ForgeAiChatbotThreadLoadMoreEventData, ForgeAiChatbotThreadRenameEventData, ForgeAiChatbotThreadDeleteEventData, McpAppUiResource, McpAppResourceCsp, McpAppResourcePermissions, McpAppHostContext, McpAppHostStyles, McpAppHostCapabilities, McpAppContainerDimensions, McpAppContentModalities, McpAppToolInfo, McpAppSandboxCapabilities, McpAppDisplayMode, McpToolResult } from './types.js';
 export * from './ag-ui-adapter.js';
 export * from './http-agent-with-credentials.js';
 export * from './event-emitter.js';

package/dist/ai-chatbot/message-state-controller.d.ts

@@ -34,6 +34,10 @@ export declare class MessageStateController implements ReactiveController {
     appendTextDelta(messageId: string, delta: string): void;
     markTextComplete(messageId: string): void;
     addToolCallToResponse(toolCall: ToolCall): void;
+    /**
+     * Applies `updates` to a tool call wherever it is rendered: the in-progress response,
+     * an already finalized/restored response, or a top-level tool-call item.
+     */
     updateToolCallInResponse(toolCallId: string, updates: Partial<ToolCall>): void;
     completeToolCallInResponse(toolCallId: string, result: unknown, event?: ToolResultEvent): void;
     tryFinalizeResponse(): void;
@@ -52,10 +56,15 @@ export declare class MessageStateController implements ReactiveController {
     updateMessageContent(id: string, content: string): void;
     removeMessageItem(index: number): void;
     clearMessages(): void;
-    removeMessageItemsFrom(index: number): void;
+    /** Tool call ids rendered at or after `index`, inside assistant responses or as top-level items. */
+    getToolCallIdsFrom(index: number): string[];
+    /** Removes items from `index` onward and returns the ids of the tool calls they held. */
+    removeMessageItemsFrom(index: number): string[];
     /**
      * Reconstructs the message hierarchy for API compatibility.
      * Converts assistant responses back to ChatMessage format with tool calls.
+     * MCP-app `uiResource`s are stripped: they are re-resolved via the adapter on restore,
+     * never persisted or sent back to the agent.
      */
     getMessages(): ChatMessage[];
     setMessages(messages: ChatMessage[]): void;

package/dist/ai-chatbot/message-state-controller.mjs

@@ -1,4 +1,14 @@
 import { generateId } from "./utils.mjs";
+function withoutUiResource(toolCall) {
+  if (!toolCall.uiResource) {
+    return toolCall;
+  }
+  const { uiResource: _uiResource, ...rest } = toolCall;
+  return rest;
+}
+function responseItemWithoutUiResource(item) {
+  return item.type === "toolCall" ? { type: "toolCall", data: withoutUiResource(item.data) } : item;
+}
 class MessageStateController {
   constructor(_host, _config) {
     this._host = _host;
@@ -103,33 +113,61 @@ class MessageStateController {
     this.#updateResponseInItems();
     this.#notifyStateChange();
   }
+  /**
+   * Applies `updates` to a tool call wherever it is rendered: the in-progress response,
+   * an already finalized/restored response, or a top-level tool-call item.
+   */
   updateToolCallInResponse(toolCallId, updates) {
     const toolCall = this._toolCalls.get(toolCallId);
     if (!toolCall) {
       return;
     }
-    const isCompleting = updates.status === "complete" || updates.status === "error";
+    const isFinishing = updates.status === "complete" || updates.status === "error" || updates.status === "cancelled";
     const updated = {
       ...toolCall,
       ...updates,
-      ...isCompleting && !toolCall.endTimestamp ? { endTimestamp: Date.now() } : {}
+      ...isFinishing && !toolCall.endTimestamp ? { endTimestamp: Date.now() } : {}
     };
     this._toolCalls.set(toolCallId, updated);
-    if (this._activeResponse) {
-      for (const child of this._activeResponse.children) {
-        if (child.type === "toolCall" && child.data.id === toolCallId) {
-          child.data = updated;
-          break;
-        }
-      }
-    }
-    this.#updateResponseInItems();
+    this.#replaceToolCall(updated);
     this.#notifyStateChange();
   }
   completeToolCallInResponse(toolCallId, result, event) {
     this.updateToolCallInResponse(toolCallId, {
       result,
-      status: event?.isError === true ? "error" : "complete"
+      status: this.#resultStatus(event),
+      ...event ? {
+        structuredContent: event.structuredContent,
+        structuredContentOmitted: event.structuredContentOmitted,
+        mcpResult: event.mcpResult,
+        mcpResultOmitted: event.mcpResultOmitted
+      } : {}
+    });
+  }
+  #resultStatus(event) {
+    if (event?.cancelled) {
+      return "cancelled";
+    }
+    return event?.isError ? "error" : "complete";
+  }
+  #replaceToolCall(updated) {
+    const matches = (child) => child.type === "toolCall" && child.data.id === updated.id;
+    const replace = (children) => children.map((child) => matches(child) ? { type: "toolCall", data: updated } : child);
+    const activeResponse = this._activeResponse;
+    if (activeResponse?.children.some(matches)) {
+      activeResponse.children = replace(activeResponse.children);
+    }
+    this._messageItems = this._messageItems.map((item) => {
+      if (item.type === "toolCall" && item.data.id === updated.id) {
+        return { type: "toolCall", data: updated };
+      }
+      if (item.type !== "assistant" || !item.data.children.some(matches)) {
+        return item;
+      }
+      if (item.data.id === activeResponse?.id) {
+        return { type: "assistant", data: { ...activeResponse } };
+      }
+      return { type: "assistant", data: { ...item.data, children: replace(item.data.children) } };
     });
   }
   tryFinalizeResponse() {
@@ -242,14 +280,32 @@ class MessageStateController {
     this.#notifyStateChange();
     this._config.onThreadSettled?.();
   }
+  /** Tool call ids rendered at or after `index`, inside assistant responses or as top-level items. */
+  getToolCallIdsFrom(index) {
+    return this._messageItems.slice(index).flatMap((item) => {
+      if (item.type === "toolCall") {
+        return [item.data.id];
+      }
+      if (item.type === "assistant") {
+        return item.data.children.flatMap((child) => child.type === "toolCall" ? [child.data.id] : []);
+      }
+      return [];
+    });
+  }
+  /** Removes items from `index` onward and returns the ids of the tool calls they held. */
   removeMessageItemsFrom(index) {
+    const removedToolCallIds = this.getToolCallIdsFrom(index);
+    removedToolCallIds.forEach((id) => this._toolCalls.delete(id));
     this._messageItems = this._messageItems.slice(0, index);
     this._activeResponse = null;
     this.#notifyStateChange();
+    return removedToolCallIds;
   }
   /**
    * Reconstructs the message hierarchy for API compatibility.
    * Converts assistant responses back to ChatMessage format with tool calls.
+   * MCP-app `uiResource`s are stripped: they are re-resolved via the adapter on restore,
+   * never persisted or sent back to the agent.
    */
   getMessages() {
     const messages = [];
@@ -258,8 +314,9 @@ class MessageStateController {
         messages.push({ ...item.data, toolCalls: [] });
       } else if (item.type === "assistant") {
         const response = item.data;
-        const textContent = response.children.filter((c) => c.type === "text").map((c) => c.content).join("");
-        const toolCalls = response.children.filter((c) => c.type === "toolCall").map((c) => c.data);
+        const children = response.children.map(responseItemWithoutUiResource);
+        const textContent = children.filter((c) => c.type === "text").map((c) => c.content).join("");
+        const toolCalls = children.filter((c) => c.type === "toolCall").map((c) => c.data);
         const message = {
           id: response.id,
           role: "assistant",
@@ -268,13 +325,13 @@ class MessageStateController {
           status: response.status === "streaming" ? "streaming" : response.status === "error" ? "error" : "complete",
           toolCalls: toolCalls.length ? toolCalls : void 0,
           feedback: response.feedback,
-          children: response.children
+          children
         };
         messages.push(message);
       } else if (item.type === "toolCall") {
         const lastMsg = messages[messages.length - 1];
         if (lastMsg && lastMsg.role === "assistant") {
-          lastMsg.toolCalls = [...lastMsg.toolCalls || [], item.data];
+          lastMsg.toolCalls = [...lastMsg.toolCalls || [], withoutUiResource(item.data)];
         }
       }
     }
@@ -289,10 +346,11 @@ class MessageStateController {
         let children;
         if (msg.children?.length) {
           children = msg.children.map((child) => {
-            if (child.type === "toolCall") {
-              this._toolCalls.set(child.data.id, child.data);
+            const restored = responseItemWithoutUiResource(child);
+            if (restored.type === "toolCall") {
+              this._toolCalls.set(restored.data.id, restored.data);
             }
-            return child;
+            return restored;
           });
         } else {
           children = [];
@@ -300,7 +358,7 @@ class MessageStateController {
             children.push({ type: "text", messageId: msg.id, content: msg.content, status: "complete" });
           }
           if (msg.toolCalls) {
-            for (const toolCall of msg.toolCalls) {
+            for (const toolCall of msg.toolCalls.map(withoutUiResource)) {
               children.push({ type: "toolCall", data: toolCall });
               this._toolCalls.set(toolCall.id, toolCall);
             }

package/dist/ai-chatbot/types.d.ts

@@ -88,6 +88,15 @@ export interface ToolDefinition<THandlerArgs = Record<string, unknown>> {
     renderer?: ToolRenderer;
     /** If true, renderer shows immediately on tool call start (default: false). */
     renderOnStart?: boolean;
+    /**
+     * Opt-in marker declaring this tool is backed by an MCP-app UI resource. Presence
+     * signals the core controller to resolve + stamp a {@link McpAppUiResource} when the
+     * tool is called. `resourceUri` is informational; the resolved URI arrives on the
+     * `mcp-ui-resource` event.
+     */
+    mcpApp?: {
+        resourceUri?: string;
+    };
     /** Called when tool call starts (before args stream). */
     onStart?: (context: ToolStartContext) => void;
     /** Called during streaming with partial args. */
@@ -100,6 +109,176 @@ export interface ToolDefinition<THandlerArgs = Record<string, unknown>> {
      */
     handler?: (context: HandlerContext<THandlerArgs>) => Promise<string | Record<string, unknown> | void> | string | Record<string, unknown> | void;
 }
+/**
+ * Content-Security-Policy domain allow-lists for an MCP-app resource, mirroring the
+ * spec's `_meta.ui.csp` shape (2026-01-26). The sandbox proxy composes these into the
+ * enforced CSP; when omitted a restrictive default block applies.
+ *
+ * Local type — intentionally NOT aliased from `@modelcontextprotocol/ext-apps` so the
+ * type layer stays bridge-agnostic.
+ */
+export interface McpAppResourceCsp {
+    /** Domains the widget may `connect-src` to (fetch/XHR/WebSocket). */
+    connectDomains?: string[];
+    /** Domains the widget may load passive resources from (img/media/etc.). */
+    resourceDomains?: string[];
+    /** Domains allowed in `frame-src`; absent → `frame-src 'none'`. */
+    frameDomains?: string[];
+    /** Domains allowed in `base-uri`; absent → `base-uri 'self'`. */
+    baseUriDomains?: string[];
+}
+/**
+ * Iframe permission policy for an MCP-app resource, mirroring the spec's
+ * `_meta.ui.permissions` shape (2026-01-26): a key being present (with an empty object
+ * value) means the permission is requested. The sandbox maps requested keys onto the
+ * iframe `allow` attribute.
+ *
+ * Local type — not aliased from ext-apps.
+ */
+export interface McpAppResourcePermissions {
+    camera?: Record<string, never>;
+    microphone?: Record<string, never>;
+    geolocation?: Record<string, never>;
+    clipboardWrite?: Record<string, never>;
+}
+/**
+ * The resolved UI resource stamped onto a {@link ToolCall} once a `mcp-ui-resource`
+ * event arrives. Presence of this on a tool call is the single render discriminator for
+ * mounting `<forge-ai-mcp-app>`.
+ *
+ * Returned by `AgentAdapter.resolveMcpAppResource`, which fills `csp`/`permissions` from
+ * the template response's `_meta.ui` (pass `{}` when the template declares none). The
+ * widget refuses to render when either is missing.
+ *
+ * Local type — not aliased from ext-apps.
+ */
+export interface McpAppUiResource {
+    /** The complete standalone app HTML document, resolved server-side. */
+    html: string;
+    /** CSP domain allow-lists to enforce in the sandbox. Empty → restrictive default. */
+    csp: McpAppResourceCsp;
+    /** Iframe permission policy for the sandbox inner frame. */
+    permissions: McpAppResourcePermissions;
+    /** The concrete resolved `ui://` resource URI (never a template). */
+    resourceUri?: string;
+    /**
+     * Whether the widget prefers the host to draw a border/background around it.
+     * `true` → visible chrome, `false` → none, omitted → renderer default.
+     */
+    prefersBorder?: boolean;
+}
+/** Display modes an MCP-app widget can be presented in (spec 2026-01-26). */
+export type McpAppDisplayMode = 'inline' | 'fullscreen' | 'pip';
+/**
+ * The raw MCP `CallToolResult` (minus `structuredContent`) for an MCP-app tool call. The
+ * View's `ui/notifications/tool-result` is built from this plus
+ * {@link ToolCall.structuredContent} — never from the model-facing `result`.
+ */
+export interface McpToolResult {
+    content: unknown[];
+    isError?: boolean;
+    _meta?: Record<string, unknown>;
+}
+/**
+ * Size of the container holding a widget, in CSS pixels (spec `containerDimensions`): a
+ * fixed `height` or a `maxHeight` bound, and a fixed `width` or a `maxWidth` bound.
+ */
+export type McpAppContainerDimensions = ({
+    height: number;
+} | {
+    maxHeight?: number;
+}) & ({
+    width: number;
+} | {
+    maxWidth?: number;
+});
+/** The tool call that instantiated a widget (spec `toolInfo`). */
+export interface McpAppToolInfo {
+    id?: string | number;
+    tool: {
+        name: string;
+        inputSchema: {
+            type: 'object';
+            [key: string]: unknown;
+        };
+        [key: string]: unknown;
+    };
+}
+/**
+ * Theming sent to MCP-app widgets (spec `hostContext.styles`): spec CSS variables (e.g.
+ * `--color-background-primary`) resolved from Forge tokens. Font loading (`css.fonts`) is not sent.
+ */
+export interface McpAppHostStyles {
+    variables?: Record<string, string>;
+}
+/**
+ * Host context projected into an MCP-app widget.
+ *
+ * Local type — not aliased from ext-apps.
+ */
+export interface McpAppHostContext {
+    theme: 'light' | 'dark';
+    /** Spec CSS variables resolved from the widget's Forge tokens. */
+    styles?: McpAppHostStyles;
+    /** The tool call that instantiated the widget. */
+    toolInfo?: McpAppToolInfo;
+    /** Size of the container holding the widget. */
+    containerDimensions?: McpAppContainerDimensions;
+    /** The widget's current display mode. */
+    displayMode?: McpAppDisplayMode;
+    /** Display modes the host is able to present. */
+    availableDisplayModes?: McpAppDisplayMode[];
+    /** BCP 47 language tag. */
+    locale?: string;
+    /** IANA time zone. */
+    timeZone?: string;
+    userAgent?: string;
+    platform?: 'web' | 'desktop' | 'mobile';
+    deviceCapabilities?: {
+        touch?: boolean;
+        hover?: boolean;
+    };
+    safeAreaInsets?: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+}
+/** Content-block types a host accepts for `ui/message` / `ui/update-model-context`. */
+export interface McpAppContentModalities {
+    text?: Record<string, never>;
+    image?: Record<string, never>;
+    audio?: Record<string, never>;
+    resource?: Record<string, never>;
+    resourceLink?: Record<string, never>;
+    structuredContent?: Record<string, never>;
+}
+/** The sandbox policy the host enforces for a widget, echoed in its host capabilities. */
+export interface McpAppSandboxCapabilities {
+    csp?: McpAppResourceCsp;
+    permissions?: McpAppResourcePermissions;
+}
+/**
+ * Host capability advertisement returned to the widget in `McpUiInitializeResult`.
+ * Spec-compliant widgets gate `ui/open-link` / `tools/call` / `resources/read` on these,
+ * so they must be declared, not left implicit.
+ *
+ * Local type — not aliased from ext-apps.
+ */
+export interface McpAppHostCapabilities {
+    openLinks?: Record<string, never>;
+    serverTools?: {
+        listChanged?: boolean;
+    };
+    serverResources?: {
+        listChanged?: boolean;
+    };
+    logging?: Record<string, never>;
+    message?: McpAppContentModalities;
+    updateModelContext?: McpAppContentModalities;
+    sandbox?: McpAppSandboxCapabilities;
+}
 export interface ChatMessage {
     id: string;
     role: 'user' | 'assistant' | 'system' | 'tool';
@@ -144,11 +323,30 @@ export interface ToolCall<TArgs = Record<string, unknown>> {
     args: TArgs;
     argsBuffer?: string;
     result?: unknown;
-    status: 'pending' | 'parsing' | 'executing' | 'complete' | 'error';
+    status: ToolCallStatus;
     type: ToolType;
     startTimestamp?: number;
     endTimestamp?: number;
+    /**
+     * The resolved MCP-app UI resource. When present, this tool call renders as a
+     * sandboxed `<forge-ai-mcp-app>` widget instead of the standard tool-call UI. Its
+     * presence is the single render discriminator.
+     */
+    uiResource?: McpAppUiResource;
+    /** Companion structured payload for the widget, stripped from LLM context. */
+    structuredContent?: unknown;
+    /** `true` when `structuredContent` was dropped by the backend (size caps). */
+    structuredContentOmitted?: boolean;
+    /** Raw MCP result for an MCP-app tool call; the source of the View's `tool-result`. */
+    mcpResult?: McpToolResult;
+    /** `true` when `mcpResult` was dropped by the backend (size caps). */
+    mcpResultOmitted?: boolean;
 }
+/**
+ * Tool call lifecycle. `cancelled` means the call ended without a result (run aborted,
+ * stream ended/errored, or the adapter reported `cancelled: true`).
+ */
+export type ToolCallStatus = 'pending' | 'parsing' | 'executing' | 'complete' | 'error' | 'cancelled';
 export type ResponseItem = {
     type: 'text';
     messageId: string;

package/dist/ai-chatbot/utils.mjs

@@ -10,7 +10,7 @@ function shouldShowToolRenderer(toolCall, toolDefinition) {
   return !!toolDefinition.renderOnStart && (toolCall.status === "parsing" || toolCall.status === "executing");
 }
 function isToolCallSettled(toolCall, toolDefinition) {
-  return toolCall.status === "complete" || toolCall.status === "error" || shouldShowToolRenderer(toolCall, toolDefinition);
+  return toolCall.status === "complete" || toolCall.status === "error" || toolCall.status === "cancelled" || shouldShowToolRenderer(toolCall, toolDefinition);
 }
 function generateId() {
   return v4();
@@ -49,6 +49,8 @@ function formatToolCallForExport(toolCall) {
   if (toolCall.status === "error") {
     const errorMsg = typeof toolCall.result === "object" && toolCall.result !== null && "error" in toolCall.result ? toolCall.result.error : "Unknown error";
     lines.push(`    Error: ${errorMsg}`);
+  } else if (toolCall.status === "cancelled") {
+    lines.push("    Cancelled");
   } else if (toolCall.result !== void 0) {
     lines.push(`    Result: ${JSON.stringify(toolCall.result)}`);
   }