@xpert-ai/chatkit-types 0.8.0 → 0.9.0

package/dist/index.d.ts

@@ -460,6 +460,14 @@ export declare type ChatKitMessageNavigationOptions = {
     enabled?: boolean;
 };
 
+/** Rendering policy only; never changes messages, execution or model context. */
+export declare type ChatKitMessagePresentationOptions = {
+    /** Defaults to the existing transcript presentation. */
+    mode?: 'transcript' | 'bubbles';
+    /** Collapse the process before the final answer. Only applies to transcript. */
+    collapseProcess?: boolean;
+};
+
 export declare type ChatKitOptions = {
     /**
      * ChatKit iframe URL for web component integrations.
@@ -513,10 +521,7 @@ export declare type ChatKitOptions = {
      */
     messageNavigation?: ChatKitMessageNavigationOptions;
     /** Message presentation only; never changes stored messages or model context. */
-    messagePresentation?: {
-        /** Collapse the process preceding each final assistant answer. Default: false. */
-        collapseProcess?: boolean;
-    };
+    messagePresentation?: ChatKitMessagePresentationOptions;
     /**
      * Optional Xpert Remote Views workbench.
      *
@@ -1005,6 +1010,11 @@ export declare type ChatKitThreadReference = {
 };
 
 export declare type ChatKitWorkbenchClientCommandRequest = {
+    /** User-clicked persisted resource; hosts resolve its canonical target from message history. */
+    resourceCard?: {
+        messageId: string;
+        id: string;
+    };
     commandKey: string;
     payload?: unknown;
     hostType: 'agent';
@@ -1034,9 +1044,8 @@ export declare type ChatKitWorkbenchOptions = {
      */
     enabled?: boolean;
     /**
-     * Show a vertical strip of available remote-view icons at the right edge of
-     * chat while the workbench is closed. Clicking an icon opens that view.
-     * Requires `workbench.enabled`. Disabled by default.
+     * @deprecated Views now open from the stacked-tabs button in the chat header.
+     * This option is retained for compatibility and no longer renders a view rail.
      */
     viewRail?: {
         enabled?: boolean;
@@ -1375,9 +1384,25 @@ declare type ControlSize = '3xs' | '2xs' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2
 
 declare type ControlVariant = 'solid' | 'soft' | 'outline' | 'ghost';
 
+/** Presentation of a committed business resource; distinct from versioned file Artifacts. */
+export declare interface ConversationResourceCard {
+    resource: {
+        namespace: string;
+        type: string;
+        id: string;
+        artifactId?: string;
+    };
+    title: string;
+    description?: string;
+    icon?: IconDefinition;
+    open: ResourceCardOpenTarget;
+}
+
 /** Exact line LCS with bounded CPU/memory. Unknown text never becomes zero changes. */
 export declare function countFileChangeLines(report: FileChangeReport): FileChangeLineStats;
 
+export declare function createResourceCardContent(card: ConversationResourceCard): TMessageContentResourceCard;
+
 declare type CustomApiConfig = {
     /**
      * The URL (relative or absolute) of the ChatKit API. The configured endpoint
@@ -1871,6 +1896,8 @@ export declare function isLangGraphInterruptPayload(value: unknown): value is La
 
 export declare function isLangGraphInterruptTask(value: unknown): value is LangGraphInterruptTask;
 
+export declare function isResourceCardContent(value: unknown): boolean;
+
 export declare function isToolCallInterrupt(value: unknown): value is ToolCallInterrupt;
 
 export declare function isToolCallInterruptPayload(value: unknown): value is ToolCallInterruptPayload;
@@ -2023,6 +2050,11 @@ export declare function parseFileActivityContent(value: unknown): TMessageConten
 
 export declare function parseFileChangeReport(value: unknown): FileChangeReport | null;
 
+/** JSON boundary: copy only supported fields, never executable commands or host URLs. */
+export declare function parseResourceCard(value: unknown): ConversationResourceCard | null;
+
+export declare function parseResourceCardContent(value: unknown): TMessageContentResourceCard | null;
+
 export declare const PET_ANIMATION_NAMES: readonly ["idle", "running-right", "running-left", "waving", "jumping", "failed", "waiting", "running", "review"];
 
 export declare type PetFrameAnimationDefinition = {
@@ -2207,6 +2239,21 @@ export declare function resolveLocalizedText(value: unknown, language?: string):
 
 export declare function resolvePetCharacter(character: ChatKitPetCharacter): ResolvedPetCharacter | null;
 
+export declare function resourceCardId(card: ConversationResourceCard): string;
+
+export declare type ResourceCardOpenTarget = {
+    viewKey: string;
+    selectionId?: string;
+    parameters?: Record<string, ResourceCardScalar | ResourceCardScalar[]>;
+} & ({
+    target: 'workbench.view';
+} | {
+    target: 'assistant.project';
+    projectId: string;
+});
+
+export declare type ResourceCardScalar = string | number | boolean | null;
+
 export declare type Row = {
     type: 'Row';
     key?: string;
@@ -2727,7 +2774,7 @@ export declare type TMessageContent = string | TMessageContentComplex[];
 /**
  * Enhance {@link MessageContentComplex} in Langchain.js
  */
-export declare type TMessageContentComplex = (TMessageContentText | TMessageContentReasoning | MessageContentImageUrl | TMessageContentComponent | TMessageContentFileActivity | TMessageContentMemory | (Record<string, any> & {
+export declare type TMessageContentComplex = (TMessageContentText | TMessageContentReasoning | MessageContentImageUrl | TMessageContentComponent | TMessageContentFileActivity | TMessageContentResourceCard | TMessageContentMemory | (Record<string, any> & {
     type?: 'text' | 'image_url' | string;
 }) | (Record<string, any> & {
     type?: never;
@@ -2790,6 +2837,15 @@ export declare type TMessageContentReasoning = {
     text: string;
 };
 
+export declare interface TMessageContentResourceCard {
+    type: 'resource_card';
+    id: string;
+    data: ConversationResourceCard;
+    /** Bound by the server, never supplied by an emitting plugin. */
+    messageId?: string;
+    executionId?: string;
+}
+
 export declare type TMessageContentText = {
     id?: string;
     xpertName?: string;
@@ -2900,7 +2956,7 @@ export declare type ToolOutputImageAttachment = {
 
 export declare type ToolOutputImageMimeType = 'image/png' | 'image/jpeg' | 'image/webp';
 
-export declare type ToolOutputImageSource = 'knowledge-document' | 'sandbox';
+export declare type ToolOutputImageSource = 'knowledge-document' | 'sandbox' | 'tool';
 
 /**
  * UI-only ToolMessage artifact. ToolMessage content remains the compact
@@ -2992,6 +3048,9 @@ export declare type TXpertChatTarget = {
 /** Receipts are immutable terminal facts; replay replaces by identity, never appends a second operation. */
 export declare function upsertFileActivityContent<T>(content: T[], receipt: TMessageContentFileActivity): (T | TMessageContentFileActivity)[];
 
+/** Identity is local to one reply. Repeat emissions replace the snapshot in place. */
+export declare function upsertResourceCardContent<T>(parts: T[], card: TMessageContentResourceCard): (T | TMessageContentResourceCard)[];
+
 export declare type UserMessageContent = unknown;
 
 export declare type WidgetComponent = TextComponent | Title | Caption | Badge | Markdown | Box | Row | Col | Divider | Icon | Image_2 | Button | Checkbox | Spacer | Select | DatePicker | Form | Input | Label | RadioGroup | Textarea | Transition;

package/dist/index.js

@@ -1,5 +1,120 @@
 import { CHAT_EVENT_TYPE_FOLLOW_UP_CONSUMED, ChatMessageEventTypeEnum, ChatMessageStepCategory, ChatMessageTypeEnum, STATE_VARIABLE_HUMAN } from "./constants.js";
 import "@langchain/core/messages/tool";
+function resourceCardId(card) {
+  return JSON.stringify([
+    card.resource.namespace,
+    card.resource.type,
+    card.resource.id
+  ]);
+}
+function nonempty(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+function scalar(value) {
+  return value === null || typeof value === "string" || typeof value === "boolean" || typeof value === "number" && Number.isFinite(value);
+}
+function parseResourceCard(value) {
+  if (!value || typeof value !== "object" || !("resource" in value) || !("title" in value) || !nonempty(value.title) || !("open" in value))
+    return null;
+  const resource = value.resource;
+  if (!resource || typeof resource !== "object" || !("namespace" in resource) || !nonempty(resource.namespace) || !("type" in resource) || !nonempty(resource.type) || !("id" in resource) || !nonempty(resource.id))
+    return null;
+  if ("artifactId" in resource && !nonempty(resource.artifactId)) return null;
+  const open = value.open;
+  if (!open || typeof open !== "object" || !("target" in open) || open.target !== "workbench.view" && open.target !== "assistant.project" || !("viewKey" in open) || !nonempty(open.viewKey))
+    return null;
+  if (Object.keys(open).some(
+    (key) => ![
+      "target",
+      "viewKey",
+      "selectionId",
+      "parameters",
+      "projectId"
+    ].includes(key)
+  ))
+    return null;
+  if ("selectionId" in open && !nonempty(open.selectionId)) return null;
+  const parameters = {};
+  if ("parameters" in open) {
+    if (!open.parameters || typeof open.parameters !== "object" || Array.isArray(open.parameters))
+      return null;
+    for (const [key, item] of Object.entries(open.parameters)) {
+      if (["__proto__", "constructor", "prototype"].includes(key)) return null;
+      if (scalar(item)) parameters[key] = item;
+      else if (Array.isArray(item) && item.every(scalar))
+        parameters[key] = item;
+      else return null;
+    }
+  }
+  const common = {
+    viewKey: open.viewKey,
+    ..."selectionId" in open && nonempty(open.selectionId) ? { selectionId: open.selectionId } : {},
+    ..."parameters" in open ? { parameters } : {}
+  };
+  let target;
+  if (open.target === "assistant.project") {
+    if (!("projectId" in open) || !nonempty(open.projectId)) return null;
+    target = {
+      ...common,
+      target: "assistant.project",
+      projectId: open.projectId
+    };
+  } else {
+    if ("projectId" in open) return null;
+    target = { ...common, target: "workbench.view" };
+  }
+  if ("description" in value && typeof value.description !== "string")
+    return null;
+  let icon;
+  if ("icon" in value) {
+    const candidate = value.icon;
+    if (!candidate || typeof candidate !== "object" || !("type" in candidate) || !("value" in candidate) || !nonempty(candidate.value))
+      return null;
+    if (candidate.type !== "svg" && candidate.type !== "emoji" && candidate.type !== "font")
+      return null;
+    icon = { type: candidate.type, value: candidate.value };
+  }
+  return {
+    resource: {
+      namespace: resource.namespace,
+      type: resource.type,
+      id: resource.id,
+      ..."artifactId" in resource && nonempty(resource.artifactId) ? { artifactId: resource.artifactId } : {}
+    },
+    title: value.title,
+    ..."description" in value ? { description: value.description } : {},
+    ...icon ? { icon } : {},
+    open: target
+  };
+}
+function createResourceCardContent(card) {
+  const data = parseResourceCard(card);
+  if (!data) throw new Error("Invalid resource card");
+  return { type: "resource_card", id: resourceCardId(data), data };
+}
+function isResourceCardContent(value) {
+  return !!value && typeof value === "object" && "type" in value && value.type === "resource_card";
+}
+function parseResourceCardContent(value) {
+  if (!value || typeof value !== "object" || !("type" in value) || value.type !== "resource_card" || !("data" in value))
+    return null;
+  const card = parseResourceCard(value.data);
+  if (!card) return null;
+  return {
+    ...createResourceCardContent(card),
+    ..."messageId" in value && nonempty(value.messageId) ? { messageId: value.messageId } : {},
+    ..."executionId" in value && nonempty(value.executionId) ? { executionId: value.executionId } : {}
+  };
+}
+function upsertResourceCardContent(parts, card) {
+  const index = parts.findIndex(
+    (part) => {
+      var _a;
+      return ((_a = parseResourceCardContent(part)) == null ? void 0 : _a.id) === card.id;
+    }
+  );
+  return index < 0 ? [...parts, card] : parts.map((part, i) => i === index ? card : part);
+}
 function isApprovalHostReference(value) {
   return !!value && typeof value === "object" && "kind" in value && typeof value.kind === "string" && value.kind.length > 0 && "id" in value && typeof value.id === "string" && value.id.length > 0 && "expiresAt" in value && typeof value.expiresAt === "number" && Number.isFinite(value.expiresAt);
 }
@@ -848,6 +963,7 @@ export {
   chatSkillUsageKey,
   clampPetPosition,
   countFileChangeLines,
+  createResourceCardContent,
   fileChangeRangeKey,
   getFileActivityContribution,
   getLegacyFileActivityContribution,
@@ -869,6 +985,7 @@ export {
   isLangGraphInterrupt,
   isLangGraphInterruptPayload,
   isLangGraphInterruptTask,
+  isResourceCardContent,
   isToolCallInterrupt,
   isToolCallInterruptPayload,
   isToolCallInterruptTask,
@@ -886,10 +1003,14 @@ export {
   normalizeThreadReference,
   parseFileActivityContent,
   parseFileChangeReport,
+  parseResourceCard,
+  parseResourceCardContent,
   petSpriteAtlas,
   projectMessageFileActivity,
   resolveLocalizedText,
   resolvePetCharacter,
-  upsertFileActivityContent
+  resourceCardId,
+  upsertFileActivityContent,
+  upsertResourceCardContent
 };
 //# sourceMappingURL=index.js.map