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

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

@@ -19,16 +19,107 @@ export interface ForgeAiSlashCommandMenuSelectEventData {
     command: SlashCommand;
     index: number;
 }
-export interface ToolRenderer {
+/**
+ * Function of a tool call whose parameter stays bivariant, so a `ToolDefinition<MyArgs>` can be stored in a
+ * `ToolDefinition[]` alongside untyped tools without casts.
+ */
+export type ToolCallMapper<TReturn, TArgs = Record<string, unknown>, TResult = unknown> = {
+    bivarianceHack(toolCall: ToolCall<TArgs, TResult>): TReturn;
+}['bivarianceHack'];
+/** A static value, or one derived from the tool call. */
+export type ToolCallValue<TValue, TArgs = Record<string, unknown>, TResult = unknown> = TValue | ToolCallMapper<TValue, TArgs, TResult>;
+/** Host-provided context passed to a tool renderer's `render` function. */
+export interface ToolRenderContext {
+    presentation: ToolPresentation;
+    /** Controls captured when `render` runs; element renderers receive a reactive `canvas` property instead. */
+    canvas: ToolCanvas;
+}
+/**
+ * Bivariant like `ToolCallMapper`. `context` is optional so existing `render(toolCall)` implementations and
+ * callers keep compiling; hosts always pass it.
+ */
+export type ToolRenderFunction<TArgs = Record<string, unknown>, TResult = unknown> = {
+    bivarianceHack(toolCall: ToolCall<TArgs, TResult>, context?: ToolRenderContext): HTMLElement | DocumentFragment;
+}['bivarianceHack'];
+export interface ToolRenderer<TArgs = any, TResult = any> {
     elementTag?: string;
-    render?: (toolCall: ToolCall) => HTMLElement | DocumentFragment;
+    render?: ToolRenderFunction<TArgs, TResult>;
+}
+/**
+ * Where a tool renderer instance is displayed. Set by the host on the elements it creates.
+ * - `inline`: in the message thread with no canvas available
+ * - `inline-expandable`: in the message thread; a canvas is available and the renderer may request it
+ * - `canvas`: inside the canvas panel
+ */
+export type ToolPresentation = 'inline' | 'inline-expandable' | 'canvas';
+/** Artifact card icon: an `<svg>` element, or SVG markup reduced to static shape elements and attributes. */
+export type ToolCanvasIcon = SVGElement | string;
+/** Artifact card labels for each state; shown as the tooltip and read by assistive technology. */
+export interface ToolCanvasActionLabel {
+    /** Label while the artifact is not in the canvas, e.g. "Open report". */
+    open: string;
+    /** Label while the artifact is in the canvas, e.g. "Collapse report". */
+    collapse: string;
+}
+/**
+ * Opts a tool into the canvas panel of hosts that provide one (e.g. `forge-ai-chatbot-launcher`).
+ * Hosts without a canvas ignore this and render the tool inline as usual. Every mapper receives the
+ * `ToolCall`, so values can come from the agent's `args` or the handler's `result`.
+ */
+export interface ToolCanvasConfig<TArgs = Record<string, unknown>, TResult = unknown> {
+    /**
+     * When the canvas opens. `auto`: as soon as the tool call renders (launcher only; other hosts treat it as
+     * `on-request`). `on-request` (default): only when the renderer or artifact card asks for it.
+     */
+    open?: 'auto' | 'on-request';
+    /**
+     * What the thread shows for the tool call. `renderer`: the inline renderer. `card`: an artifact card that
+     * opens the canvas. `card-while-open`: the renderer, swapped for the card while this call is in the canvas.
+     * Defaults to `card` when `open` is `auto`, otherwise `renderer`.
+     */
+    inline?: ToolCanvasInline;
+    /** Renderer used inside the canvas. Defaults to the tool's `renderer`. */
+    renderer?: ToolRenderer<TArgs, TResult>;
+    /** Canvas and artifact card title. Defaults to `displayName`, then `name`. */
+    title?: ToolCallValue<string, TArgs, TResult>;
+    /** Artifact card subtitle, e.g. a row count. */
+    subtitle?: ToolCallValue<string, TArgs, TResult>;
+    /** Artifact card icon. Defaults to a generic artifact glyph. */
+    icon?: ToolCallValue<ToolCanvasIcon, TArgs, TResult>;
+    /** Artifact card action labels. Defaults to "Open in canvas" / "Collapse canvas". */
+    actionLabel?: ToolCallValue<ToolCanvasActionLabel, TArgs, TResult>;
+}
+export type ToolCanvasInline = 'renderer' | 'card' | 'card-while-open';
+/**
+ * Canvas controls the host injects into a tool renderer as `canvas`. A new object is assigned whenever
+ * `available` or `isOpen` changes, so declaring `canvas` as a reactive property re-renders the renderer.
+ * Hosts without a canvas inject one with `available: false` whose methods return `false`.
+ */
+export interface ToolCanvas {
+    /** Whether the host can show this tool call in a canvas. */
+    readonly available: boolean;
+    /** Whether this tool call is the one currently shown in the canvas. */
+    readonly isOpen: boolean;
+    /** Shows this tool call in the canvas. Returns false when unavailable or the host declined. */
+    open(options?: {
+        title?: string;
+    }): boolean;
+    /** Closes the canvas if it is showing this tool call. Returns false when it was not or the host declined. */
+    close(): boolean;
+    /** Closes the canvas when this tool call is open, otherwise opens it. */
+    toggle(): boolean;
 }
 /**
  * Interface that tool renderer components should implement for type-safe tool call handling.
  * @template TArgs - Type of the tool call arguments
+ * @template TResult - Type returned by the tool's handler
  */
-export interface IToolRenderer<TArgs = Record<string, unknown>> {
-    toolCall: ToolCall<TArgs>;
+export interface IToolRenderer<TArgs = Record<string, unknown>, TResult = unknown> {
+    toolCall: ToolCall<TArgs, TResult>;
+    /** Assigned by the host to tell the renderer where it is displayed. */
+    presentation?: ToolPresentation;
+    /** Assigned by the host to let the renderer open and close the canvas. */
+    canvas?: ToolCanvas;
 }
 /**
  * Context provided to tool handlers when they are invoked.
@@ -73,9 +164,10 @@ export interface ToolEndContext<TArgs = Record<string, unknown>> {
 export type ToolType = 'client' | 'agent';
 /**
  * Tool definition with optional type-safe handler.
- * @template TArgs - Type of the tool call arguments for type-safe handler context
+ * @template TArgs - Type of the tool call arguments, typed through the handler, renderer, and canvas mappers
+ * @template TResult - Type returned by `handler`, available as `toolCall.result`
  */
-export interface ToolDefinition<THandlerArgs = Record<string, unknown>> {
+export interface ToolDefinition<TArgs = Record<string, unknown>, TResult = string | Record<string, unknown>> {
     name: string;
     displayName?: string;
     description?: string;
@@ -84,7 +176,11 @@ export interface ToolDefinition<THandlerArgs = Record<string, unknown>> {
         properties?: Record<string, unknown>;
         required?: string[];
     };
-    /** Optional renderer for displaying tool call results within the chat UI. */
+    /**
+     * Optional renderer for displaying tool call results within the chat UI. Deliberately untyped (`any`
+     * arguments) so renderers written before `ToolDefinition` had a `TResult`, including `render` callbacks
+     * annotated with plain `ToolCall`, keep compiling on any `ToolDefinition<TArgs>`.
+     */
     renderer?: ToolRenderer;
     /** If true, renderer shows immediately on tool call start (default: false). */
     renderOnStart?: boolean;
@@ -97,17 +193,19 @@ export interface ToolDefinition<THandlerArgs = Record<string, unknown>> {
     mcpApp?: {
         resourceUri?: string;
     };
+    /** Canvas behavior for hosts that provide a canvas panel. Requires `renderer`. */
+    canvas?: ToolCanvasConfig<TArgs, TResult>;
     /** Called when tool call starts (before args stream). */
-    onStart?: (context: ToolStartContext) => void;
+    onStart?(context: ToolStartContext): void;
     /** Called during streaming with partial args. */
-    onDelta?: (context: ToolDeltaContext<THandlerArgs>) => void;
+    onDelta?(context: ToolDeltaContext<TArgs>): void;
     /** Called when args are complete (before handler execution). */
-    onEnd?: (context: ToolEndContext<THandlerArgs>) => void;
+    onEnd?(context: ToolEndContext<TArgs>): void;
     /**
      * Optional handler function invoked when tool is called.
-     * Can return a string, object, or void. Strings and objects are used directly as tool results.
+     * Strings and objects are used directly as the tool result; `void` yields a generic success message.
      */
-    handler?: (context: HandlerContext<THandlerArgs>) => Promise<string | Record<string, unknown> | void> | string | Record<string, unknown> | void;
+    handler?(context: HandlerContext<TArgs>): Promise<TResult | void> | TResult | void;
 }
 /**
  * Content-Security-Policy domain allow-lists for an MCP-app resource, mirroring the
@@ -167,6 +265,8 @@ export interface McpAppUiResource {
      */
     prefersBorder?: boolean;
 }
+/** Resolve state of an announced MCP-app UI resource that has not been stamped yet. */
+export type McpAppUiResourceStatus = 'loading' | 'error';
 /** Display modes an MCP-app widget can be presented in (spec 2026-01-26). */
 export type McpAppDisplayMode = 'inline' | 'fullscreen' | 'pip';
 /**
@@ -279,6 +379,11 @@ export interface McpAppHostCapabilities {
     updateModelContext?: McpAppContentModalities;
     sandbox?: McpAppSandboxCapabilities;
 }
+/**
+ * Type-erased tool definition for collections that mix tools with different argument types, e.g. the
+ * `tools` passed to an adapter. Any `ToolDefinition<TArgs, TResult>` is assignable to it.
+ */
+export type AnyToolDefinition = ToolDefinition<object, any>;
 export interface ChatMessage {
     id: string;
     role: 'user' | 'assistant' | 'system' | 'tool';
@@ -316,23 +421,30 @@ export interface ClientMessageInput {
     header?: string;
     actions?: ClientMessageAction[];
 }
-export interface ToolCall<TArgs = Record<string, unknown>> {
+export interface ToolCall<TArgs = Record<string, unknown>, TResult = unknown> {
     id: string;
     messageId: string;
     name: string;
     args: TArgs;
     argsBuffer?: string;
-    result?: unknown;
+    /** Handler return value once the call completes; an `{ error }` object if the handler threw. */
+    result?: TResult;
     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.
+     * sandboxed `<forge-ai-mcp-app>` widget instead of the standard tool-call UI.
      */
     uiResource?: McpAppUiResource;
+    /**
+     * Set while an announced MCP-app UI resource has not resolved: `loading` while it is
+     * being fetched, `error` when the fetch failed. The tool call renders as a
+     * `<forge-ai-mcp-app>` placeholder (or error) in its final position meanwhile.
+     * Cleared once `uiResource` is stamped, or when the adapter resolves no resource.
+     */
+    uiResourceStatus?: McpAppUiResourceStatus;
     /** Companion structured payload for the widget, stripped from LLM context. */
     structuredContent?: unknown;
     /** `true` when `structuredContent` was dropped by the backend (size caps). */

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

@@ -1,16 +1,21 @@
-import { ChatMessage, ContextItem, FileAttachment, ToolCall, ToolDefinition } from './types.js';
+import { ChatMessage, ContextItem, FileAttachment, ToolCall, AnyToolDefinition } from './types.js';
 export { renderMarkdown, renderInlineMarkdown, type RenderMarkdownOptions } from '../utils/markdown.js';
 /**
  * Whether a tool call's renderer should currently be shown: once the call is complete,
  * or immediately (while still parsing/executing) if the tool opted into `renderOnStart`.
  */
-export declare function shouldShowToolRenderer(toolCall: ToolCall, toolDefinition?: ToolDefinition): boolean;
+export declare function shouldShowToolRenderer(toolCall: ToolCall, toolDefinition?: AnyToolDefinition): boolean;
 /**
  * Whether a tool call should be treated as settled for activity indicators (thinking
  * indicator, tool-call summary spinner): either genuinely finished, or already showing
  * its own renderer to the user, which makes a redundant "running" spinner misleading.
  */
-export declare function isToolCallSettled(toolCall: ToolCall, toolDefinition?: ToolDefinition): boolean;
+export declare function isToolCallSettled(toolCall: ToolCall, toolDefinition?: AnyToolDefinition): boolean;
+/**
+ * Whether a tool call renders as a `<forge-ai-mcp-app>` widget: its UI resource is resolved,
+ * or announced and still loading (or failed to load).
+ */
+export declare function rendersAsMcpAppWidget(toolCall: ToolCall): boolean;
 /**
  * Generates a unique ID using UUID v4
  */

package/dist/ai-chatbot/utils.mjs

@@ -12,6 +12,9 @@ function shouldShowToolRenderer(toolCall, toolDefinition) {
 function isToolCallSettled(toolCall, toolDefinition) {
   return toolCall.status === "complete" || toolCall.status === "error" || toolCall.status === "cancelled" || shouldShowToolRenderer(toolCall, toolDefinition);
 }
+function rendersAsMcpAppWidget(toolCall) {
+  return !!toolCall.uiResource || !!toolCall.uiResourceStatus;
+}
 function generateId() {
   return v4();
 }
@@ -106,5 +109,6 @@ export {
   isToolCallSettled,
   renderInlineMarkdown,
   renderMarkdown,
+  rendersAsMcpAppWidget,
   shouldShowToolRenderer
 };

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

@@ -1,9 +1,10 @@
-import { TemplateResult, CSSResult } from 'lit';
+import { PropertyValues, TemplateResult, CSSResult } from 'lit';
 import { AiMessageThreadComponent } from '../ai-message-thread';
 import { AiPromptComponent, ForgeAiPromptSendEventData } from '../ai-prompt';
 import { ForgeAiSuggestionsEventData } from '../ai-suggestions';
-import { AiChatbotBase } from '../ai-chatbot/ai-chatbot-base.js';
+import { AiChatbotBase, FeatureToggle } from '../ai-chatbot/ai-chatbot-base.js';
 import { ChatMessage, ThreadState } from '../ai-chatbot/types.js';
+import { CanvasOpenEventData, OpenCanvasOptions } from '../core/canvas-controller.js';
 import { Thread } from '../ai-threads/ai-threads';
 import { Ref } from 'lit/directives/ref.js';
 export type LauncherViewState = 'welcome' | 'conversation' | 'history';
@@ -32,6 +33,12 @@ export interface ForgeAiChatbotLauncherThreadLoadMoreEventData {
     query: string;
     appendResults: (results: Thread[]) => void;
 }
+export type { OpenCanvasOptions };
+export type ForgeAiChatbotLauncherCanvasOpenEventData = CanvasOpenEventData;
+export interface ForgeAiChatbotLauncherCanvasResizeEventData {
+    /** Width of the conversation column in pixels; the canvas takes the remaining width. */
+    chatWidth: number;
+}
 declare global {
     interface HTMLElementTagNameMap {
         'forge-ai-chatbot-launcher': AiChatbotLauncherComponent;
@@ -47,6 +54,9 @@ declare global {
         'forge-ai-chatbot-launcher-thread-load-more': CustomEvent<ForgeAiChatbotLauncherThreadLoadMoreEventData>;
         'forge-ai-chatbot-launcher-new-chat': CustomEvent<void>;
         'forge-ai-chatbot-launcher-thread-retry': CustomEvent<void>;
+        'forge-ai-chatbot-launcher-canvas-open': CustomEvent<ForgeAiChatbotLauncherCanvasOpenEventData>;
+        'forge-ai-chatbot-launcher-canvas-close': CustomEvent<void>;
+        'forge-ai-chatbot-launcher-canvas-resize': CustomEvent<ForgeAiChatbotLauncherCanvasResizeEventData>;
     }
 }
 export declare const AiChatbotLauncherComponentTagName: keyof HTMLElementTagNameMap;
@@ -60,10 +70,16 @@ export declare const AiChatbotLauncherComponentTagName: keyof HTMLElementTagName
  * that animates into a full conversation interface when the user sends their first message.
  * In conversation mode, a header is displayed with options for clear, export, and agent selection.
  *
+ * In conversation mode an artifact canvas can open beside the thread via `openCanvas()`, a tool definition's
+ * `canvas` config, or a renderer's `forge-ai-canvas-open-request`. The conversation narrows to a sidebar-style
+ * column and the canvas takes the remaining width. The canvas closes whenever the conversation view is left.
+ *
  * @slot icon - Slot for custom icon (used in both welcome view and conversation header)
  * @slot heading - Slot for custom heading content (welcome view only)
  * @slot description - Slot for custom description/welcome message below the title (welcome view only)
  * @slot header-actions - Slot for custom header action buttons in conversation mode (rendered before built-in header actions)
+ * @slot canvas - Content shown in the canvas when `openCanvas()` is called without `content`
+ * @slot canvas-actions - Action buttons rendered in the canvas header before the close button
  *
  * @property {string} titleText - The title text to display in the welcome view and header (default: 'AI Assistant')
  * @property {string} descriptionText - The description text displayed below the title in the welcome view.
@@ -81,6 +97,9 @@ export declare const AiChatbotLauncherComponentTagName: keyof HTMLElementTagName
  * @property {boolean} threadsLoading - Whether chats are currently loading, used to show a spinner on the history button and disable it
  * @property {string | undefined} threadsError - Message describing a failed chat history load. When set, the history popover/view shows the message with a retry button instead of the empty state, and the history button shows an error badge so the failure is visible with the popover closed. If chats are already loaded the list stays visible and the message renders as a compact single line with a retry - at the bottom of the list when a page was in flight, otherwise above it. Clear it once a load succeeds.
  * @property {string | null} selectedThreadId - The id of the currently selected thread, highlighted in the history popover/view. Updated internally when a thread is selected or a new chat starts.
+ * @property {string} canvasTitle - Default title for the canvas header, used when the open request does not supply one
+ * @property {FeatureToggle} canvasResizable - Controls the drag handle between the conversation and the canvas. `'on'` (default) lets users resize with a pointer or the arrow keys; `'off'` hides it, so the conversation stays at `chatWidth`.
+ * @property {number} chatWidth - Width in pixels of the conversation column while the canvas is open (default: 420). Updated as the user resizes, clamped to at least 360px and to leave the canvas at least 320px when there is room. Resized widths are persisted per tab in sessionStorage and shared across tabs via localStorage; on load the session value is preferred, then the local value, then the default.
  *
  * @cssproperty --forge-ai-chatbot-launcher-icon-color - The fill color for the AI icon.
  *
@@ -102,6 +121,9 @@ export declare const AiChatbotLauncherComponentTagName: keyof HTMLElementTagName
  * @event {CustomEvent<ForgeAiChatbotLauncherThreadLoadMoreEventData>} forge-ai-chatbot-launcher-thread-load-more - Fired when scrolling near the bottom of the history list for pagination. Call appendResults() with the next page (empty array signals no more results)
  * @event {CustomEvent<void>} forge-ai-chatbot-launcher-new-chat - Fired when "New chat" is clicked from the full history view. Cancelable - prevents startNewChat() from being called
  * @event {CustomEvent<void>} forge-ai-chatbot-launcher-thread-retry - Fired when the retry button in the history error state is clicked. Re-request the chats and clear threadsError once the load succeeds
+ * @event {CustomEvent<ForgeAiChatbotLauncherCanvasOpenEventData>} forge-ai-chatbot-launcher-canvas-open - Fired before the canvas opens or replaces its content. Cancelable - prevents the canvas from opening
+ * @event {CustomEvent<ForgeAiChatbotLauncherCanvasResizeEventData>} forge-ai-chatbot-launcher-canvas-resize - Fired when a resize is committed via pointer release or keyboard step. Detail has the new `chatWidth`
+ * @event {CustomEvent<void>} forge-ai-chatbot-launcher-canvas-close - Fired when the canvas closes. Cancelable only for user or `closeCanvas()` initiated closes; closes caused by leaving the conversation view cannot be prevented
  */
 export declare class AiChatbotLauncherComponent extends AiChatbotBase {
     #private;
@@ -117,7 +139,11 @@ export declare class AiChatbotLauncherComponent extends AiChatbotBase {
     threadsLoading: boolean;
     threadsError?: string;
     selectedThreadId: string | null;
+    canvasTitle?: string;
+    canvasResizable: FeatureToggle;
+    chatWidth: number;
     private _viewState;
+    private _isResizing;
     private _skipAnimation;
     private _editingThreadId;
     private _historyPopoverOpen;
@@ -125,6 +151,8 @@ export declare class AiChatbotLauncherComponent extends AiChatbotBase {
     protected _promptRef: Ref<AiPromptComponent>;
     constructor();
     protected _onConnected(): void;
+    willUpdate(changedProperties: PropertyValues<this>): void;
+    updated(changedProperties: PropertyValues<this>): void;
     startConversation(): void;
     /**
      * Returns to the welcome view without touching conversation state. Unlike `startNewChat()`, this
@@ -147,6 +175,16 @@ export declare class AiChatbotLauncherComponent extends AiChatbotBase {
         skipAnimation?: boolean;
     }): Promise<void>;
     get viewState(): LauncherViewState;
+    get canvasOpen(): boolean;
+    /**
+     * Opens the canvas beside the conversation, or swaps its content if already open. Only available in the
+     * conversation view; returns false elsewhere or when the open event is prevented.
+     */
+    openCanvas(options?: OpenCanvasOptions): boolean;
+    /**
+     * Closes the canvas. Returns false if it was not open or the close event was prevented.
+     */
+    closeCanvas(): boolean;
     focus(): void;
     render(): TemplateResult;
 }