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

package/dist/types/tool.d.ts

@@ -0,0 +1,197 @@
+/**
+ * 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?: 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.
+ * 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 (hosts that can open it automatically; others 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>, 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.
+ * @template TArgs - Type of the tool call arguments
+ */
+export interface HandlerContext<TArgs = Record<string, unknown>> {
+    /** Tool call arguments */
+    args: TArgs;
+    /** Unique identifier for this tool call */
+    toolCallId: string;
+    /** Name of the tool being called */
+    toolName: string;
+    /** Optional abort signal for cancellation support */
+    signal?: AbortSignal;
+}
+/**
+ * Context provided to onStart callback when tool call begins.
+ */
+export interface ToolStartContext {
+    toolCallId: string;
+    toolName: string;
+}
+/**
+ * Context provided to onDelta callback during streaming.
+ * @template TArgs - Type of the tool call arguments
+ */
+export interface ToolDeltaContext<TArgs = Record<string, unknown>> {
+    argsBuffer: string;
+    partialArgs: Partial<TArgs>;
+    toolCallId: string;
+    toolName: string;
+}
+/**
+ * Context provided to onEnd callback when args are complete.
+ * @template TArgs - Type of the tool call arguments
+ */
+export interface ToolEndContext<TArgs = Record<string, unknown>> {
+    args: TArgs;
+    toolCallId: string;
+    toolName: string;
+}
+export type ToolType = 'client' | 'agent';
+/**
+ * Tool definition with optional type-safe handler.
+ * @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<TArgs = Record<string, unknown>, TResult = string | Record<string, unknown>> {
+    name: string;
+    displayName?: string;
+    description?: string;
+    parameters?: {
+        type: 'object';
+        properties?: Record<string, unknown>;
+        required?: string[];
+    };
+    /**
+     * 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;
+    /** 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;
+    /** Called during streaming with partial args. */
+    onDelta?(context: ToolDeltaContext<TArgs>): void;
+    /** Called when args are complete (before handler execution). */
+    onEnd?(context: ToolEndContext<TArgs>): void;
+    /**
+     * Optional handler function invoked when tool is called.
+     * Strings and objects are used directly as the tool result; `void` yields a generic success message.
+     */
+    handler?(context: HandlerContext<TArgs>): Promise<TResult | void> | TResult | void;
+}
+/**
+ * Type-erased tool definition for collections that mix tools with different argument types, e.g. a
+ * list of tools passed to an agent. Any `ToolDefinition<TArgs, TResult>` is assignable to it.
+ */
+export type AnyToolDefinition = ToolDefinition<object, any>;
+export interface ToolCall<TArgs = Record<string, unknown>, TResult = unknown> {
+    id: string;
+    messageId: string;
+    name: string;
+    args: TArgs;
+    argsBuffer?: string;
+    /** Handler return value once the call completes; an `{ error }` object if the handler threw. */
+    result?: TResult;
+    status: 'pending' | 'parsing' | 'executing' | 'complete' | 'error';
+    type: ToolType;
+    startTimestamp?: number;
+    endTimestamp?: number;
+}

package/dist/utils/csv-utils.mjs

@@ -1,65 +1,45 @@
+//#region src/lib/utils/csv-utils.ts
 function escapeCSVCell(value) {
-  if (value === null || value === void 0) {
-    return "";
-  }
-  const stringValue = String(value);
-  if (!stringValue) {
-    return "";
-  }
-  const dangerousFormulaPattern = /^(@)?(\+|-|=)?(DDE|HYPERLINK|IMPORTXML|IMPORTHTML|IMPORTDATA|IMPORTFEED|IMPORTRANGE)/i;
-  const needsFormulaEscape = /^[=+\-@|\t\r\n]/.test(stringValue) || dangerousFormulaPattern.test(stringValue);
-  const escapedValue = needsFormulaEscape ? `'${stringValue}` : stringValue;
-  if (/[",\n\r]/.test(escapedValue)) {
-    return `"${escapedValue.replace(/"/g, '""')}"`;
-  }
-  return escapedValue;
+	if (value === null || value === void 0) return "";
+	const stringValue = String(value);
+	if (!stringValue) return "";
+	const escapedValue = /^[=+\-@|\t\r\n]/.test(stringValue) || /^(@)?(\+|-|=)?(DDE|HYPERLINK|IMPORTXML|IMPORTHTML|IMPORTDATA|IMPORTFEED|IMPORTRANGE)/i.test(stringValue) ? `'${stringValue}` : stringValue;
+	if (/[",\n\r]/.test(escapedValue)) return `"${escapedValue.replace(/"/g, "\"\"")}"`;
+	return escapedValue;
 }
 function buildCSVContent(headers, rows) {
-  const csvRows = [
-    headers.map((h) => escapeCSVCell(h)).join(","),
-    ...rows.map((row) => row.map((cell) => escapeCSVCell(cell)).join(","))
-  ];
-  return csvRows.join("\r\n");
+	return [headers.map((h) => escapeCSVCell(h)).join(","), ...rows.map((row) => row.map((cell) => escapeCSVCell(cell)).join(","))].join("\r\n");
 }
 function sanitizeFilename(filename, fallback = "download") {
-  const trimmed = filename.trim();
-  if (!trimmed) {
-    return `${fallback}.csv`;
-  }
-  let normalized = "";
-  let lastWasDash = false;
-  for (const char of trimmed) {
-    const isAlphaNum = /[a-zA-Z0-9._-]/.test(char);
-    const nextChar = isAlphaNum ? char : "-";
-    if (nextChar === "-") {
-      if (!normalized || lastWasDash) {
-        continue;
-      }
-      normalized += nextChar;
-      lastWasDash = true;
-      continue;
-    }
-    normalized += nextChar;
-    lastWasDash = false;
-  }
-  normalized = normalized.replace(/^[.-]+|[.-]+$/g, "");
-  return `${normalized || fallback}.csv`;
+	const trimmed = filename.trim();
+	if (!trimmed) return `${fallback}.csv`;
+	let normalized = "";
+	let lastWasDash = false;
+	for (const char of trimmed) {
+		const nextChar = /[a-zA-Z0-9._-]/.test(char) ? char : "-";
+		if (nextChar === "-") {
+			if (!normalized || lastWasDash) continue;
+			normalized += nextChar;
+			lastWasDash = true;
+			continue;
+		}
+		normalized += nextChar;
+		lastWasDash = false;
+	}
+	normalized = normalized.replace(/^[.-]+|[.-]+$/g, "");
+	return `${normalized || fallback}.csv`;
 }
 function downloadCSV(content, filename) {
-  const blob = new Blob([content], { type: "text/csv;charset=utf-8" });
-  const url = URL.createObjectURL(blob);
-  const link = document.createElement("a");
-  link.href = url;
-  link.download = filename;
-  link.style.display = "none";
-  document.body.appendChild(link);
-  link.click();
-  link.remove();
-  URL.revokeObjectURL(url);
+	const blob = new Blob([content], { type: "text/csv;charset=utf-8" });
+	const url = URL.createObjectURL(blob);
+	const link = document.createElement("a");
+	link.href = url;
+	link.download = filename;
+	link.style.display = "none";
+	document.body.appendChild(link);
+	link.click();
+	link.remove();
+	URL.revokeObjectURL(url);
 }
-export {
-  buildCSVContent,
-  downloadCSV,
-  escapeCSVCell,
-  sanitizeFilename
-};
+//#endregion
+export { buildCSVContent, downloadCSV, escapeCSVCell, sanitizeFilename };

package/dist/utils/delete-thread-controller.d.ts

@@ -1,5 +1,5 @@
 import { ReactiveController, ReactiveControllerHost, nothing, TemplateResult } from 'lit';
-import { Thread } from '../ai-threads';
+import { Thread } from '../types/index.js';
 export interface DeleteThreadControllerCallbacks {
     onConfirm: (thread: Thread) => void;
 }

package/dist/utils/delete-thread-controller.mjs

@@ -1,80 +1,57 @@
-import { nothing, html } from "lit";
+import { html, nothing } from "lit";
 import { createRef, ref } from "lit/directives/ref.js";
-class DeleteThreadController {
-  #host;
-  #callbacks;
-  #confirmingThread = null;
-  #modalRef = createRef();
-  constructor(host, callbacks) {
-    this.#host = host;
-    this.#callbacks = callbacks;
-    host.addController(this);
-  }
-  hostConnected() {
-  }
-  hostDisconnected() {
-  }
-  async show(thread) {
-    this.#confirmingThread = thread;
-    this.#host.requestUpdate();
-    await this.#host.updateComplete;
-    this.#modalRef.value?.show();
-  }
-  close() {
-    this.#modalRef.value?.close();
-    this.#confirmingThread = null;
-    this.#host.requestUpdate();
-  }
-  #handleConfirm = () => {
-    if (!this.#confirmingThread) {
-      return;
-    }
-    this.#callbacks.onConfirm(this.#confirmingThread);
-    this.close();
-  };
-  #handleDeny = () => {
-    this.close();
-  };
-  #handleModalClose = (evt) => {
-    evt.stopPropagation();
-    this.#confirmingThread = null;
-    this.#host.requestUpdate();
-  };
-  get template() {
-    if (!this.#confirmingThread) {
-      return nothing;
-    }
-    return html`
-      <forge-ai-modal
-        ${ref(this.#modalRef)}
-        .open=${true}
-        size-strategy="fixed"
-        @forge-ai-modal-close=${this.#handleModalClose}>
+//#region src/lib/utils/delete-thread-controller.ts
+var DeleteThreadController = class {
+	#host;
+	#callbacks;
+	#confirmingThread = null;
+	#modalRef = createRef();
+	constructor(host, callbacks) {
+		this.#host = host;
+		this.#callbacks = callbacks;
+		host.addController(this);
+	}
+	hostConnected() {}
+	hostDisconnected() {}
+	async show(thread) {
+		this.#confirmingThread = thread;
+		this.#host.requestUpdate();
+		await this.#host.updateComplete;
+		this.#modalRef.value?.show();
+	}
+	close() {
+		this.#modalRef.value?.close();
+		this.#confirmingThread = null;
+		this.#host.requestUpdate();
+	}
+	#handleConfirm = () => {
+		if (!this.#confirmingThread) return;
+		this.#callbacks.onConfirm(this.#confirmingThread);
+		this.close();
+	};
+	#handleDeny = () => {
+		this.close();
+	};
+	#handleModalClose = (evt) => {
+		evt.stopPropagation();
+		this.#confirmingThread = null;
+		this.#host.requestUpdate();
+	};
+	get template() {
+		if (!this.#confirmingThread) return nothing;
+		return html`
+      <forge-ai-modal ${ref(this.#modalRef)} .open=${true} size-strategy="fixed" @forge-ai-modal-close=${this.#handleModalClose}>
         <div class="delete-confirmation" role="alertdialog" aria-labelledby="delete-confirm-title">
           <h2 id="delete-confirm-title" class="delete-confirmation__title">Delete chat</h2>
-          <div class="delete-confirmation__text">
-            Are you sure you want to delete "${this.#confirmingThread.title}"? This action cannot be undone.
-          </div>
+          <div class="delete-confirmation__text">Are you sure you want to delete "${this.#confirmingThread.title}"? This action cannot be undone.</div>
           <div class="delete-confirmation__actions">
-            <button
-              class="forge-button forge-button--outlined"
-              @click=${this.#handleDeny}
-              autofocus
-              aria-label="Cancel deletion">
-              Cancel
-            </button>
-            <button
-              class="forge-button forge-button--filled"
-              @click=${this.#handleConfirm}
-              aria-label="Confirm deletion">
-              Delete
-            </button>
+            <button class="forge-button forge-button--outlined" @click=${this.#handleDeny} autofocus aria-label="Cancel deletion">Cancel</button>
+            <button class="forge-button forge-button--filled" @click=${this.#handleConfirm} aria-label="Confirm deletion">Delete</button>
           </div>
         </div>
       </forge-ai-modal>
     `;
-  }
-}
-export {
-  DeleteThreadController
+	}
 };
+//#endregion
+export { DeleteThreadController };

package/dist/utils/dom.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Generate a unique identifier with an optional prefix.
+ * @param prefix - Optional prefix for the ID.
+ * @returns A unique identifier string.
+ */
+export declare function generateUniqueId(prefix?: string): string;
+/**
+ * Adds or removes a state from an element's custom state set.
+ *
+ * @param internals - The element's internals object.
+ * @param state - The name of the custom state to toggle.
+ * @param value - Whether to add or remove the state.
+ */
+export declare function toggleState(internals: ElementInternals, state: string, value: boolean): void;

package/dist/utils/dom.mjs

@@ -0,0 +1,30 @@
+//#region src/lib/utils/dom.ts
+/**
+* Generate a unique identifier with an optional prefix.
+* @param prefix - Optional prefix for the ID.
+* @returns A unique identifier string.
+*/
+function generateUniqueId(prefix = "id") {
+	return `${prefix}-${Math.random().toString(36).substr(2, 9)}`;
+}
+/**
+* Adds or removes a state from an element's custom state set.
+*
+* @param internals - The element's internals object.
+* @param state - The name of the custom state to toggle.
+* @param value - Whether to add or remove the state.
+*/
+function toggleState(internals, state, value) {
+	if (value) try {
+		internals.states.add(state);
+	} catch {
+		internals.states.add(`--${state}`);
+	}
+	else try {
+		internals.states.delete(state);
+	} catch {
+		internals.states.delete(`--${state}`);
+	}
+}
+//#endregion
+export { generateUniqueId, toggleState };

package/dist/utils/format.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Formats a date as a short relative time label: "Just now" under a minute, "Xm ago"/"Xh ago"
+ * under 24 hours, "Yesterday" between 24-48 hours elapsed, otherwise a short date (with year if
+ * not the current year).
+ *
+ * @param dateString - An ISO date string to format.
+ * @returns The formatted relative time label.
+ */
+export declare function formatRelativeTime(dateString: string): string;

package/dist/utils/format.mjs

@@ -0,0 +1,27 @@
+//#region src/lib/utils/format.ts
+/**
+* Formats a date as a short relative time label: "Just now" under a minute, "Xm ago"/"Xh ago"
+* under 24 hours, "Yesterday" between 24-48 hours elapsed, otherwise a short date (with year if
+* not the current year).
+*
+* @param dateString - An ISO date string to format.
+* @returns The formatted relative time label.
+*/
+function formatRelativeTime(dateString) {
+	const date = new Date(dateString);
+	const diffMs = Date.now() - date.getTime();
+	const diffMinutes = Math.floor(diffMs / 6e4);
+	const diffHours = Math.floor(diffMs / 36e5);
+	const diffDays = Math.floor(diffMs / 864e5);
+	if (diffMinutes < 1) return "Just now";
+	if (diffHours < 24) return diffHours >= 1 ? `${diffHours}h ago` : `${diffMinutes}m ago`;
+	if (diffDays < 2) return "Yesterday";
+	const sameYear = date.getFullYear() === (/* @__PURE__ */ new Date()).getFullYear();
+	return new Intl.DateTimeFormat("en-US", {
+		month: "short",
+		day: "numeric",
+		...sameYear ? {} : { year: "numeric" }
+	}).format(date);
+}
+//#endregion
+export { formatRelativeTime };

package/dist/utils/index.d.ts

@@ -1,6 +1,9 @@
-export { DeleteThreadController } from './delete-thread-controller';
-export { InfiniteScrollController } from './infinite-scroll-controller';
-export { KeyboardNavigationController } from './keyboard-navigation-controller';
-export { renderMarkdown, renderInlineMarkdown, type RenderMarkdownOptions } from './markdown';
-export { buildCSVContent, downloadCSV, escapeCSVCell, sanitizeFilename } from './csv-utils';
-export { readStoredNumber, writeStoredNumber, removeStoredValue, type StorageKind, type StorageOptions, type WriteStorageOptions } from './storage-utils';
+export { generateUniqueId, toggleState } from './dom.js';
+export { formatRelativeTime } from './format.js';
+export { DeleteThreadController } from './delete-thread-controller.js';
+export { InfiniteScrollController } from './infinite-scroll-controller.js';
+export { KeyboardNavigationController } from './keyboard-navigation-controller.js';
+export { MarkdownStreamController } from './markdown-stream-controller.js';
+export { renderMarkdown, renderInlineMarkdown, type RenderMarkdownOptions, type RenderInlineMarkdownOptions } from './markdown.js';
+export { buildCSVContent, downloadCSV, escapeCSVCell, sanitizeFilename } from './csv-utils.js';
+export { readStoredNumber, writeStoredNumber, removeStoredValue, type StorageKind, type StorageOptions, type WriteStorageOptions } from './storage-utils.js';

package/dist/utils/index.mjs

@@ -1,20 +1,10 @@
+import { renderInlineMarkdown, renderMarkdown } from "./markdown.mjs";
+import { MarkdownStreamController } from "./markdown-stream-controller.mjs";
+import { generateUniqueId, toggleState } from "./dom.mjs";
 import { DeleteThreadController } from "./delete-thread-controller.mjs";
 import { InfiniteScrollController } from "./infinite-scroll-controller.mjs";
 import { KeyboardNavigationController } from "./keyboard-navigation-controller.mjs";
-import { renderInlineMarkdown, renderMarkdown } from "./markdown.mjs";
-import { buildCSVContent, downloadCSV, escapeCSVCell, sanitizeFilename } from "./csv-utils.mjs";
 import { readStoredNumber, removeStoredValue, writeStoredNumber } from "./storage-utils.mjs";
-export {
-  DeleteThreadController,
-  InfiniteScrollController,
-  KeyboardNavigationController,
-  buildCSVContent,
-  downloadCSV,
-  escapeCSVCell,
-  readStoredNumber,
-  removeStoredValue,
-  renderInlineMarkdown,
-  renderMarkdown,
-  sanitizeFilename,
-  writeStoredNumber
-};
+import { formatRelativeTime } from "./format.mjs";
+import { buildCSVContent, downloadCSV, escapeCSVCell, sanitizeFilename } from "./csv-utils.mjs";
+export { DeleteThreadController, InfiniteScrollController, KeyboardNavigationController, MarkdownStreamController, buildCSVContent, downloadCSV, escapeCSVCell, formatRelativeTime, generateUniqueId, readStoredNumber, removeStoredValue, renderInlineMarkdown, renderMarkdown, sanitizeFilename, toggleState, writeStoredNumber };