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

package/dist/ai-artifact-card-group/ai-artifact-card-group.mjs

@@ -0,0 +1,137 @@
+import { unsafeCSS, LitElement, html, nothing } from "lit";
+import { property, queryAssignedElements, customElement } from "lit/decorators.js";
+import { AI_ARTIFACT_CARD_COLLAPSED_ATTRIBUTE } from "../ai-artifact-card/ai-artifact-card.mjs";
+import styles from "./ai-artifact-card-group.scss.mjs";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __typeError = (msg) => {
+  throw TypeError(msg);
+};
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp(target, key, result);
+  return result;
+};
+var __accessCheck = (obj, member, msg) => member.has(obj) || __typeError("Cannot " + msg);
+var __privateGet = (obj, member, getter) => (__accessCheck(obj, member, "read from private field"), getter ? getter.call(obj) : member.get(obj));
+var __privateAdd = (obj, member, value) => member.has(obj) ? __typeError("Cannot add the same private member more than once") : member instanceof WeakSet ? member.add(obj) : member.set(obj, value);
+var __privateMethod = (obj, member, method) => (__accessCheck(obj, member, "access private method"), method);
+var _AiArtifactCardGroupComponent_instances, visibleCards_get, collapsedCount_get, overflowCount_get, _chevronDownIcon, _chevronUpIcon, syncCardVisibility_fn, handleSlotChange_fn, handleToggle_fn, toggle_get;
+const AiArtifactCardGroupComponentTagName = "forge-ai-artifact-card-group";
+const DEFAULT_VISIBLE_COUNT = 3;
+let AiArtifactCardGroupComponent = class extends LitElement {
+  constructor() {
+    super(...arguments);
+    __privateAdd(this, _AiArtifactCardGroupComponent_instances);
+    this.visibleCount = DEFAULT_VISIBLE_COUNT;
+    this.expanded = false;
+    this.showMoreText = "{count} more";
+    this.showLessText = "Show less";
+    __privateAdd(this, _chevronDownIcon, html`
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 18 18" fill="none" aria-hidden="true">
+      <path
+        d="M4.5 6.75L9 11.25L13.5 6.75"
+        stroke="currentColor"
+        stroke-width="1.5"
+        stroke-linecap="round"
+        stroke-linejoin="round" />
+    </svg>
+  `);
+    __privateAdd(this, _chevronUpIcon, html`
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 18 18" fill="none" aria-hidden="true">
+      <path
+        d="M13.5 11.25L9 6.75L4.5 11.25"
+        stroke="currentColor"
+        stroke-width="1.5"
+        stroke-linecap="round"
+        stroke-linejoin="round" />
+    </svg>
+  `);
+  }
+  updated(changedProperties) {
+    super.updated(changedProperties);
+    __privateMethod(this, _AiArtifactCardGroupComponent_instances, syncCardVisibility_fn).call(this);
+  }
+  render() {
+    return html`
+      <div class="artifact-card-group">
+        <div class="list" role="list">
+          <slot @slotchange=${__privateMethod(this, _AiArtifactCardGroupComponent_instances, handleSlotChange_fn)}></slot>
+        </div>
+        ${__privateGet(this, _AiArtifactCardGroupComponent_instances, toggle_get)}
+      </div>
+    `;
+  }
+};
+_AiArtifactCardGroupComponent_instances = /* @__PURE__ */ new WeakSet();
+visibleCards_get = function() {
+  return this._cards.filter((card) => !card.hidden);
+};
+collapsedCount_get = function() {
+  if (!Number.isFinite(this.visibleCount)) {
+    return DEFAULT_VISIBLE_COUNT;
+  }
+  return Math.max(1, Math.floor(this.visibleCount));
+};
+overflowCount_get = function() {
+  return Math.max(0, __privateGet(this, _AiArtifactCardGroupComponent_instances, visibleCards_get).length - __privateGet(this, _AiArtifactCardGroupComponent_instances, collapsedCount_get));
+};
+_chevronDownIcon = /* @__PURE__ */ new WeakMap();
+_chevronUpIcon = /* @__PURE__ */ new WeakMap();
+syncCardVisibility_fn = function() {
+  __privateGet(this, _AiArtifactCardGroupComponent_instances, visibleCards_get).forEach((card, index) => {
+    card.toggleAttribute(AI_ARTIFACT_CARD_COLLAPSED_ATTRIBUTE, !this.expanded && index >= __privateGet(this, _AiArtifactCardGroupComponent_instances, collapsedCount_get));
+  });
+};
+handleSlotChange_fn = function() {
+  this.requestUpdate();
+};
+handleToggle_fn = function() {
+  this.expanded = !this.expanded;
+  this.dispatchEvent(
+    new CustomEvent("forge-ai-artifact-card-group-toggle", {
+      detail: { expanded: this.expanded },
+      bubbles: true,
+      composed: true
+    })
+  );
+};
+toggle_get = function() {
+  if (__privateGet(this, _AiArtifactCardGroupComponent_instances, overflowCount_get) === 0) {
+    return nothing;
+  }
+  const label = this.expanded ? this.showLessText : this.showMoreText.replace("{count}", String(__privateGet(this, _AiArtifactCardGroupComponent_instances, overflowCount_get)));
+  return html`
+      <button class="toggle" type="button" aria-expanded=${this.expanded} @click=${__privateMethod(this, _AiArtifactCardGroupComponent_instances, handleToggle_fn)}>
+        ${this.expanded ? __privateGet(this, _chevronUpIcon) : __privateGet(this, _chevronDownIcon)}
+        <span>${label}</span>
+        <span class="focus-indicator"></span>
+      </button>
+    `;
+};
+AiArtifactCardGroupComponent.styles = unsafeCSS(styles);
+__decorateClass([
+  property({ type: Number, attribute: "visible-count" })
+], AiArtifactCardGroupComponent.prototype, "visibleCount", 2);
+__decorateClass([
+  property({ type: Boolean, reflect: true })
+], AiArtifactCardGroupComponent.prototype, "expanded", 2);
+__decorateClass([
+  property({ attribute: "show-more-text" })
+], AiArtifactCardGroupComponent.prototype, "showMoreText", 2);
+__decorateClass([
+  property({ attribute: "show-less-text" })
+], AiArtifactCardGroupComponent.prototype, "showLessText", 2);
+__decorateClass([
+  queryAssignedElements({ selector: "forge-ai-artifact-card", flatten: true })
+], AiArtifactCardGroupComponent.prototype, "_cards", 2);
+AiArtifactCardGroupComponent = __decorateClass([
+  customElement(AiArtifactCardGroupComponentTagName)
+], AiArtifactCardGroupComponent);
+export {
+  AiArtifactCardGroupComponent,
+  AiArtifactCardGroupComponentTagName
+};

package/dist/ai-artifact-card-group/ai-artifact-card-group.scss.mjs

@@ -0,0 +1,173 @@
+const styles = `/* prettier-ignore */
+@keyframes forge-focus-indicator-outward-grow {
+  from {
+    outline-width: 0;
+  }
+  to {
+    outline-width: var(--_focus-indicator-active-width);
+  }
+}
+@keyframes forge-focus-indicator-outward-shrink {
+  from {
+    outline-width: var(--_focus-indicator-active-width);
+  }
+}
+@keyframes forge-focus-indicator-inward-grow {
+  from {
+    border-width: 0;
+  }
+  to {
+    border-width: var(--_focus-indicator-active-width);
+  }
+}
+@keyframes forge-focus-indicator-inward-shrink {
+  from {
+    border-width: var(--_focus-indicator-active-width);
+  }
+}
+:host {
+  display: block;
+}
+
+.artifact-card-group {
+  overflow: hidden;
+  border: 1px solid var(--forge-theme-outline, #e0e0e0);
+  border-radius: var(--forge-ai-artifact-card-group-border-radius, 12px);
+  background: var(--forge-theme-surface, #ffffff);
+}
+
+/*
+ * Every row carries a top divider and the list is pulled up by one pixel so the first visible row's
+ * divider hides under the group border, whichever row that is once cards are hidden or collapsed.
+ */
+.list {
+  margin-top: -1px;
+}
+
+::slotted(*) {
+  border-top: 1px solid var(--forge-theme-outline, #e0e0e0);
+}
+
+/*
+ * Rows meeting the group's rounded corners get its inner radius for their focus rings. The bottom row only
+ * does when no toggle sits below it.
+ */
+.list ::slotted(:nth-child(1 of :not([hidden], [data-collapsed]))) {
+  --_forge-ai-artifact-card-group-start-radius: calc(var(--forge-ai-artifact-card-group-border-radius, 12px) - 1px);
+}
+
+.artifact-card-group:not(:has(.toggle)) ::slotted(:nth-last-child(1 of :not([hidden], [data-collapsed]))) {
+  --_forge-ai-artifact-card-group-end-radius: calc(var(--forge-ai-artifact-card-group-border-radius, 12px) - 1px);
+}
+
+.toggle {
+  -moz-osx-font-smoothing: grayscale;
+  -webkit-font-smoothing: antialiased;
+  font-family: var(--forge-typography-body1-font-family, var(--forge-typography-font-family, "Roboto", sans-serif));
+  font-size: var(--forge-typography-body1-font-size, calc(var(--forge-typography-font-size, 1rem) * var(--forge-typography-body-font-size-scale, 0.875)));
+  font-weight: var(--forge-typography-body1-font-weight, 400);
+  line-height: var(--forge-typography-body1-line-height, calc(var(--forge-typography-font-size, 1rem) * var(--forge-typography-body-line-height-scale, 1.125)));
+  letter-spacing: var(--forge-typography-body1-letter-spacing, 0.0357142857em);
+  text-transform: var(--forge-typography-body1-text-transform, inherit);
+  text-decoration: var(--forge-typography-body1-text-decoration, inherit);
+  position: relative;
+  display: flex;
+  align-items: center;
+  gap: var(--forge-spacing-xsmall, 8px);
+  width: 100%;
+  min-height: var(--forge-spacing-xxlarge, 48px);
+  padding: var(--forge-spacing-small, 12px);
+  border: none;
+  border-top: 1px solid var(--forge-theme-outline, #e0e0e0);
+  background: transparent;
+  color: var(--forge-theme-text-high, rgba(0, 0, 0, 0.87));
+  text-align: start;
+  cursor: pointer;
+  outline: none;
+  --_state-layer-display: var(--forge-state-layer-display, flex);
+  --_state-layer-color: var(--forge-state-layer-color, var(--forge-theme-on-surface, #000000));
+  --_state-layer-hover-color: var(--forge-state-layer-hover-color, var(--_state-layer-color));
+  --_state-layer-hover-opacity: var(--forge-state-layer-hover-opacity, 0.08);
+  --_state-layer-pressed-color: var(--forge-state-layer-pressed-color, var(--_state-layer-color));
+  --_state-layer-pressed-opacity: var(--forge-state-layer-pressed-opacity, 0.12);
+  --_state-layer-hover-duration: var(--forge-state-layer-hover-duration, 15ms);
+  --_state-layer-pressed-duration: var(--forge-state-layer-pressed-duration, 105ms);
+  --_state-layer-animation-duration: var(--forge-state-layer-animation-duration, 375ms);
+}
+.toggle::before {
+  opacity: 0;
+  position: absolute;
+  backface-visibility: hidden;
+  transform: translateZ(0);
+  background-color: var(--_state-layer-hover-color);
+  inset: 0;
+  transition: opacity var(--_state-layer-hover-duration) linear, background-color var(--_state-layer-hover-duration) linear;
+  --_state-layer-hover-duration: var(--forge-state-layer-hover-duration, 100ms);
+  content: "";
+  opacity: 0;
+  border-radius: inherit;
+}
+.toggle:hover::before {
+  background-color: var(--_state-layer-hover-color);
+  opacity: var(--_state-layer-hover-opacity);
+}
+.toggle:active::before {
+  opacity: var(--_state-layer-pressed-opacity);
+  transition-duration: var(--_state-layer-pressed-duration);
+  --_state-layer-pressed-opacity: var(--forge-state-layer-pressed-opacity, 0.18);
+}
+
+.toggle svg {
+  flex-shrink: 0;
+  width: 18px;
+  height: 18px;
+}
+
+.focus-indicator {
+  position: absolute;
+  display: none;
+}
+
+/* The toggle is always the bottom row, so its lower corners follow the group's inner radius */
+.toggle:focus-visible .focus-indicator {
+  --_focus-indicator-display: var(--forge-focus-indicator-display, flex);
+  --_focus-indicator-width: var(--forge-focus-indicator-width, var(--forge-border-medium, 2px));
+  --_focus-indicator-active-width: var(--forge-focus-indicator-active-width, 6px);
+  --_focus-indicator-color: var(--forge-focus-indicator-color, var(--forge-theme-primary, #3f51b5));
+  --_focus-indicator-shape: var(--forge-focus-indicator-shape, calc(var(--forge-shape-extra-small, 1px) * var(--forge-shape-factor, 1)));
+  --_focus-indicator-duration: var(--forge-focus-indicator-duration, var(--forge-animation-duration-long4, 600ms));
+  --_focus-indicator-easing: var(--forge-focus-indicator-easing, var(--forge-animation-easing-emphasized, cubic-bezier(0.2, 0, 0, 1)));
+  --_focus-indicator-shape-start-start: var(--forge-focus-indicator-shape-start-start, var(--_focus-indicator-shape));
+  --_focus-indicator-shape-start-end: var(--forge-focus-indicator-shape-start-end, var(--_focus-indicator-shape));
+  --_focus-indicator-shape-end-end: var(--forge-focus-indicator-shape-end-end, var(--_focus-indicator-shape));
+  --_focus-indicator-shape-end-start: var(--forge-focus-indicator-shape-end-start, var(--_focus-indicator-shape));
+  --_focus-indicator-outward-offset: var(--forge-focus-indicator-outward-offset, var(--forge-spacing-xxsmall, 4px));
+  --_focus-indicator-inward-offset: var(--forge-focus-indicator-inward-offset, 0px);
+  --_focus-indicator-offset-block: var(--forge-focus-indicator-offset-block, 0);
+  --_focus-indicator-offset-inline: var(--forge-focus-indicator-offset-inline, 0);
+  animation-delay: 0s, calc(var(--_focus-indicator-duration) * 0.25);
+  animation-duration: calc(var(--_focus-indicator-duration) * 0.25), calc(var(--_focus-indicator-duration) * 0.75);
+  animation-timing-function: var(--_focus-indicator-easing);
+  box-sizing: border-box;
+  color: var(--_focus-indicator-color);
+  display: none;
+  pointer-events: none;
+  position: absolute;
+  margin-block: var(--_focus-indicator-offset-block);
+  margin-inline: var(--_focus-indicator-offset-inline);
+  animation-name: forge-focus-indicator-inward-grow, forge-focus-indicator-inward-shrink;
+  border-end-end-radius: calc(var(--_focus-indicator-shape-end-end) - var(--_focus-indicator-inward-offset));
+  border-end-start-radius: calc(var(--_focus-indicator-shape-end-start) - var(--_focus-indicator-inward-offset));
+  border-start-end-radius: calc(var(--_focus-indicator-shape-start-end) - var(--_focus-indicator-inward-offset));
+  border-start-start-radius: calc(var(--_focus-indicator-shape-start-start) - var(--_focus-indicator-inward-offset));
+  border: var(--_focus-indicator-width) solid currentColor;
+  inset: var(--_focus-indicator-inward-offset);
+  display: block;
+  --forge-focus-indicator-shape-start-start: 0px;
+  --forge-focus-indicator-shape-start-end: 0px;
+  --forge-focus-indicator-shape-end-start: calc(var(--forge-ai-artifact-card-group-border-radius, 12px) - 1px);
+  --forge-focus-indicator-shape-end-end: calc(var(--forge-ai-artifact-card-group-border-radius, 12px) - 1px);
+}`;
+export {
+  styles as default
+};

package/dist/ai-artifact-card-group/index.d.ts

@@ -0,0 +1 @@
+export * from './ai-artifact-card-group';

package/dist/ai-artifact-card-group/index.mjs

@@ -0,0 +1,5 @@
+import { AiArtifactCardGroupComponent, AiArtifactCardGroupComponentTagName } from "./ai-artifact-card-group.mjs";
+export {
+  AiArtifactCardGroupComponent,
+  AiArtifactCardGroupComponentTagName
+};

package/dist/ai-assistant-response/ai-assistant-response.mjs

@@ -2,11 +2,13 @@ import { unsafeCSS, LitElement, html, nothing } from "lit";
 import { property, customElement } from "lit/decorators.js";
 import { unsafeHTML } from "lit/directives/unsafe-html.js";
 import { ifDefined } from "lit/directives/if-defined.js";
+import { keyed } from "lit/directives/keyed.js";
 import { MarkdownStreamController } from "../ai-chatbot/markdown-stream-controller.mjs";
 import "../ai-response-message-toolbar/ai-response-message-toolbar.mjs";
 import "../ai-chatbot/ai-chatbot-tool-call.mjs";
 import "../ai-tool-call-indicator/ai-tool-call-indicator.mjs";
 import "../ai-thinking-indicator/ai-thinking-indicator.mjs";
+import "../tools/ai-mcp-app/ai-mcp-app.mjs";
 import styles from "./ai-assistant-response.scss.mjs";
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -26,7 +28,7 @@ var __privateGet = (obj, member, getter) => (__accessCheck(obj, member, "read fr
 var __privateAdd = (obj, member, value) => member.has(obj) ? __typeError("Cannot add the same private member more than once") : member instanceof WeakSet ? member.add(obj) : member.set(obj, value);
 var __privateSet = (obj, member, value, setter) => (__accessCheck(obj, member, "write to private field"), member.set(obj, value), value);
 var __privateMethod = (obj, member, method) => (__accessCheck(obj, member, "access private method"), method);
-var _internals, _markdownController, _AiAssistantResponseComponent_instances, hasVisibleContent_get, updateEmptyState_fn, renderTextChunk_fn, renderToolCall_fn, children_get, handleToolbarAction_fn, handleToolbarFeedback_fn, toolbar_get, thinkingIndicator_get;
+var _internals, _markdownController, _AiAssistantResponseComponent_instances, hasVisibleContent_get, updateEmptyState_fn, renderTextChunk_fn, isMcpAppToolCall_fn, renderToolCall_fn, children_get, handleToolbarAction_fn, handleToolbarFeedback_fn, toolbar_get, thinkingIndicator_get;
 const AiAssistantResponseComponentTagName = "forge-ai-assistant-response";
 let AiAssistantResponseComponent = class extends LitElement {
   constructor() {
@@ -81,7 +83,21 @@ renderTextChunk_fn = function(child) {
   const renderedHtml = __privateGet(this, _markdownController).getCachedHtml(child.messageId, content);
   return html`<div class="text-chunk">${unsafeHTML(renderedHtml)}</div>`;
 };
+isMcpAppToolCall_fn = function(toolCall) {
+  return !!toolCall.uiResource || this.tools?.get(toolCall.name)?.mcpApp !== void 0;
+};
 renderToolCall_fn = function(toolCall) {
+  if (toolCall.uiResource) {
+    return keyed(
+      toolCall.id,
+      html`<forge-ai-mcp-app
+          .toolCall=${toolCall}
+          .toolDefinition=${this.tools?.get(toolCall.name)}></forge-ai-mcp-app>`
+    );
+  }
+  if (__privateMethod(this, _AiAssistantResponseComponent_instances, isMcpAppToolCall_fn).call(this, toolCall)) {
+    return nothing;
+  }
   const toolDefinition = this.tools?.get(toolCall.name);
   if (!toolDefinition?.renderer) {
     return nothing;
@@ -113,6 +129,9 @@ children_get = function() {
     if (child.type === "text") {
       flushIndicator();
       results.push(__privateMethod(this, _AiAssistantResponseComponent_instances, renderTextChunk_fn).call(this, child));
+    } else if (__privateMethod(this, _AiAssistantResponseComponent_instances, isMcpAppToolCall_fn).call(this, child.data)) {
+      flushIndicator();
+      results.push(__privateMethod(this, _AiAssistantResponseComponent_instances, renderToolCall_fn).call(this, child.data));
     } else {
       toolBuffer.push(child.data);
     }
@@ -178,7 +197,11 @@ thinkingIndicator_get = function() {
     if (child.type !== "toolCall") {
       return false;
     }
-    return child.data.status === "parsing" || child.data.status === "executing" || child.data.status === "pending";
+    const isUnsettled = child.data.status === "parsing" || child.data.status === "executing" || child.data.status === "pending";
+    if (__privateMethod(this, _AiAssistantResponseComponent_instances, isMcpAppToolCall_fn).call(this, child.data)) {
+      return !!child.data.uiResource && isUnsettled;
+    }
+    return isUnsettled;
   });
   if (hasActiveToolCall) {
     return nothing;

package/dist/ai-chatbot/ag-ui-adapter.mjs

@@ -61,7 +61,7 @@ class AgUiAdapter extends AgentAdapter {
     const transformedMessages = this.#transformMessages(messages);
     const context = Object.keys(this.#context).length ? this.#transformContext(this.#context) : void 0;
     this.#agent.setMessages(transformedMessages);
-    const tools = this.#transformTools(this._tools);
+    const tools = this.#transformTools(this.getModelFacingTools());
     this.#agent.runAgent({ tools, context });
   }
   sendToolResult(toolCallId, result, messages) {

package/dist/ai-chatbot/agent-adapter.d.ts

@@ -1,4 +1,4 @@
-import { ChatMessage, FileUploadCallbacks, ToolDefinition } from './types.js';
+import { ChatMessage, FileUploadCallbacks, McpAppUiResource, McpToolResult, ToolDefinition } from './types.js';
 import { EventEmitter, Subscription } from './event-emitter.js';
 export interface MessageStartEvent {
     messageId: string;
@@ -44,11 +44,70 @@ export interface ToolCallEndEvent {
 }
 export interface ToolResultEvent {
     toolCallId: string;
+    /** Model-facing result. Never delivered to an MCP-app View. */
     result: unknown;
     message: ChatMessage;
+    /** Companion structured payload delivered to an MCP-app widget, stripped from LLM context. */
+    structuredContent?: unknown;
+    /** `true` when the backend dropped `structuredContent` (size caps). */
+    structuredContentOmitted?: boolean;
+    /** Raw MCP result for an MCP-app tool call; the View's `tool-result` is built from it. */
+    mcpResult?: McpToolResult;
+    /** `true` when the backend dropped `mcpResult` (size caps). */
+    mcpResultOmitted?: boolean;
     isError?: boolean;
+    /** `true` when the tool call was cancelled rather than failed; takes precedence over `isError`. */
+    cancelled?: boolean;
     rawEvent?: unknown;
 }
+/**
+ * Emitted when the backend signals that a tool call is backed by an MCP-app UI
+ * resource. Carries only the widget binding — the HTML and the `csp`/`permissions`
+ * policy come from {@link AgentAdapter.resolveMcpAppResource}. The core controller
+ * resolves the resource and stamps a {@link McpAppUiResource} onto the tool call.
+ *
+ * May be emitted before or after the matching `tool-call` chunk, and also after
+ * `setMessages`/`setThreadState` to remount widgets restored from history.
+ */
+export interface McpUiResourceEvent {
+    toolCallId: string;
+    toolName?: string;
+    /** The concrete resolved `ui://` URI (interpolation done server-side). */
+    resourceUri: string;
+    serverId?: string;
+    mimeType?: string;
+    rawEvent?: unknown;
+}
+/** Parameters for {@link AgentAdapter.resolveMcpAppResource}. */
+export interface McpAppResourceResolveParams {
+    /** The concrete resolved `ui://` URI from the `mcp-ui-resource` event. */
+    resourceUri: string;
+    /** The widget's tool call id; template reads are bound to it. */
+    toolCallId: string;
+}
+/**
+ * Parameters an MCP-app widget passes when forwarding a `tools/call` to the server.
+ * The library never owns a `Client`; these delegate to the adapter.
+ */
+export interface McpToolCallParams {
+    name: string;
+    arguments?: Record<string, unknown>;
+    /** The calling widget's tool call id; the backend derives the MCP server from it. */
+    toolCallId: string;
+}
+/** Parameters for an MCP-app widget-initiated `resources/read`. */
+export interface McpResourceReadParams {
+    uri: string;
+    /** The calling widget's tool call id. */
+    toolCallId: string;
+}
+/** Payload of a widget's `ui/update-model-context`, forwarded to the adapter. */
+export interface McpModelContextUpdateParams {
+    /** The widget's tool call id. */
+    toolCallId: string;
+    content?: unknown[];
+    structuredContent?: unknown;
+}
 export interface AdapterState {
     isConnected: boolean;
     isConnecting: boolean;
@@ -121,6 +180,7 @@ export declare abstract class AgentAdapter {
         toolCallArgs: EventEmitter<ToolCallArgsEvent>;
         toolCallEnd: EventEmitter<ToolCallEndEvent>;
         toolResult: EventEmitter<ToolResultEvent>;
+        mcpUiResource: EventEmitter<McpUiResourceEvent>;
         fileUpload: EventEmitter<FileUploadEvent>;
         fileRemove: EventEmitter<FileRemoveEvent>;
         error: EventEmitter<ErrorEvent>;
@@ -143,8 +203,46 @@ export declare abstract class AgentAdapter {
     abstract get threadId(): string;
     abstract set threadId(value: string);
     clearMemory?(): Promise<void>;
+    /**
+     * Resolve the MCP-app UI resource for an already-resolved `resourceUri`, bound to the
+     * widget's `toolCallId`. The adapter fetches the template for that concrete URI and
+     * fills `csp`/`permissions` from the template response's `_meta.ui` (`{}` when absent).
+     * It MUST NOT re-derive the URI (templated-URI interpolation is server-side only).
+     */
+    resolveMcpAppResource?(params: McpAppResourceResolveParams): Promise<McpAppUiResource | undefined>;
+    /**
+     * Forward a widget-initiated `tools/call` to the MCP server. Resolve with the View's
+     * `CallToolResult` (tool-level errors resolve with `isError: true`); reject for
+     * transport/HTTP errors (e.g. a 403 for a tool without `"app"` visibility) — the
+     * rejection is returned to the View as a JSON-RPC error.
+     */
+    callMcpTool?(params: McpToolCallParams): Promise<unknown>;
+    /**
+     * Forward a widget-initiated `resources/read` to the MCP server. When not implemented
+     * the View's request is rejected with a JSON-RPC error.
+     */
+    readMcpResource?(params: McpResourceReadParams): Promise<unknown>;
+    /**
+     * Called when a widget sends `ui/update-model-context`. Each call replaces the previous
+     * context for that `toolCallId`; adapters should debounce and may hold the latest value
+     * until the run ends.
+     */
+    updateMcpModelContext?(params: McpModelContextUpdateParams): Promise<void>;
+    /**
+     * Called after a widget is torn down (its turn left the visible thread, or the thread was
+     * cleared/replaced). Drop any state held for that `toolCallId`, e.g. a pending model context.
+     */
+    disposeMcpAppView?(params: {
+        toolCallId: string;
+    }): void;
     setTools(tools: ToolDefinition[]): void;
     getTools(): ToolDefinition[];
+    /**
+     * Tools to forward to the backend agent, excluding MCP-app tools (`ToolDefinition.mcpApp`).
+     * MCP-app tools are a host-internal mechanism for streaming a UI resource into an existing
+     * tool call — the model never calls them directly, so they must never reach the agent.
+     */
+    getModelFacingTools(): ToolDefinition[];
     getState(): AdapterState;
     get isConnected(): boolean;
     get isConnecting(): boolean;
@@ -160,6 +258,7 @@ export declare abstract class AgentAdapter {
     onToolCallArgs(callback: (event: ToolCallArgsEvent) => void): Subscription;
     onToolCallEnd(callback: (event: ToolCallEndEvent) => void): Subscription;
     onToolCallResult(callback: (event: ToolResultEvent) => void): Subscription;
+    onMcpUiResource(callback: (event: McpUiResourceEvent) => void): Subscription;
     onFileUpload(callback: (event: FileUploadEvent) => void): Subscription;
     onFileRemove(callback: (event: FileRemoveEvent) => void): Subscription;
     onError(callback: (event: ErrorEvent) => void): Subscription;
@@ -184,6 +283,14 @@ export declare abstract class AgentAdapter {
     protected _emitToolCallArgs(event: ToolCallArgsEvent, rawEvent?: unknown): void;
     protected _emitToolCallEnd(event: ToolCallEndEvent, rawEvent?: unknown): void;
     protected _emitToolResult(event: ToolResultEvent, rawEvent?: unknown): void;
+    /**
+     * Announce that a tool call renders as an MCP-app widget. Also the way to remount
+     * widgets restored from history: call it per widget after `setMessages`/`setThreadState`
+     * — the resource is resolved and stamped onto the restored (already finalized) tool
+     * call. If the tool call isn't in state yet, the resource is held and applied when it
+     * arrives.
+     */
+    protected _emitMcpUiResource(event: McpUiResourceEvent, rawEvent?: unknown): void;
     emitFileUpload(file: File, callbacks: FileUploadCallbacks): void;
     emitFileRemove(fileId: string, callbacks: {
         onSuccess: () => void;

package/dist/ai-chatbot/agent-adapter.mjs

@@ -15,6 +15,7 @@ class AgentAdapter {
       toolCallArgs: new EventEmitter(),
       toolCallEnd: new EventEmitter(),
       toolResult: new EventEmitter(),
+      mcpUiResource: new EventEmitter(),
       fileUpload: new EventEmitter(),
       fileRemove: new EventEmitter(),
       error: new EventEmitter(),
@@ -36,6 +37,14 @@ class AgentAdapter {
   getTools() {
     return [...this._tools];
   }
+  /**
+   * Tools to forward to the backend agent, excluding MCP-app tools (`ToolDefinition.mcpApp`).
+   * MCP-app tools are a host-internal mechanism for streaming a UI resource into an existing
+   * tool call — the model never calls them directly, so they must never reach the agent.
+   */
+  getModelFacingTools() {
+    return this._tools.filter((tool) => tool.mcpApp === void 0);
+  }
   getState() {
     return { ...this._state };
   }
@@ -81,6 +90,9 @@ class AgentAdapter {
   onToolCallResult(callback) {
     return this._events.toolResult.subscribe(callback);
   }
+  onMcpUiResource(callback) {
+    return this._events.mcpUiResource.subscribe(callback);
+  }
   onFileUpload(callback) {
     return this._events.fileUpload.subscribe(callback);
   }
@@ -153,6 +165,16 @@ class AgentAdapter {
   _emitToolResult(event, rawEvent) {
     this._events.toolResult.emit({ ...event, rawEvent });
   }
+  /**
+   * Announce that a tool call renders as an MCP-app widget. Also the way to remount
+   * widgets restored from history: call it per widget after `setMessages`/`setThreadState`
+   * — the resource is resolved and stamped onto the restored (already finalized) tool
+   * call. If the tool call isn't in state yet, the resource is held and applied when it
+   * arrives.
+   */
+  _emitMcpUiResource(event, rawEvent) {
+    this._events.mcpUiResource.emit({ ...event, rawEvent });
+  }
   emitFileUpload(file, callbacks) {
     this._events.fileUpload.emit({ file, ...callbacks });
   }

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

@@ -13,6 +13,7 @@ import { ChatbotCoreController } from '../core/chatbot-core-controller.js';
 import { Agent, ChatMessage, ClientMessageInput, ContextItem, HeadingLevel, MessageItem, SlashCommand, ThreadState, ToolDefinition } from './types.js';
 export type FeatureToggle = 'on' | 'off';
 export declare abstract class AiChatbotBase extends LitElement {
+    #private;
     protected abstract _messageThreadRef: Ref<AiMessageThreadComponent>;
     protected abstract _promptRef: Ref<AiPromptComponent>;
     adapter?: AgentAdapter;
@@ -34,6 +35,24 @@ export declare abstract class AiChatbotBase extends LitElement {
     agents: Agent[];
     selectedAgentId?: string;
     contextItems: ContextItem[];
+    mcpAppSandboxUrl?: string;
+    /**
+     * Theme fed into an MCP-app widget's `hostContext.theme`. The chatbot's own appearance
+     * comes from Forge tokens and is unaffected. Set this whenever the app switches between
+     * light and dark: it is the signal that re-sends `theme` and the Forge-derived
+     * `styles.variables` to widgets, since token changes alone can't be detected. Absent →
+     * follows `prefers-color-scheme`.
+     */
+    mcpAppTheme?: 'light' | 'dark';
+    private _mcpAppHost;
+    /**
+     * 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).
+     */
+    protected _teardownMcpAppViews({ toolCallIds }?: {
+        toolCallIds?: string[];
+    }): void;
     protected _coreController: ChatbotCoreController;
     protected get _isStreaming(): boolean;
     protected get _isUploading(): boolean;
@@ -42,6 +61,7 @@ export declare abstract class AiChatbotBase extends LitElement {
     protected get _hasMessages(): boolean;
     protected get _allContextItems(): ContextItem[];
     connectedCallback(): void;
+    disconnectedCallback(): void;
     willUpdate(changedProperties: PropertyValues<this>): void;
     protected _onConnected(): void;
     protected get _slashCommands(): SlashCommand[];
@@ -136,6 +156,12 @@ export declare abstract class AiChatbotBase extends LitElement {
     removeClientMessage(id: string): void;
     sendMessage(content: string, files?: File[]): Promise<void>;
     abort(): void;
+    /**
+     * 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(): void;
     scrollToBottom({ behavior }?: {
         behavior?: ScrollBehavior;
     }): Promise<void>;