@metad/contracts 3.7.0 → 3.8.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metad/contracts",
-  "version": "3.7.0",
+  "version": "3.8.1",
   "license": "AGPL-3.0",
   "repository": {
     "type": "git",
@@ -13,5 +13,9 @@
     "docs": "yarn typedoc --out ./.docs"
   },
   "module": "./index.esm.js",
-  "main": "./index.cjs.js"
+  "main": "./index.cjs.js",
+  "dependencies": {
+    "@a2ui/lit": "^0.8.1",
+    "@xpert-ai/chatkit-types": "^0.0.12"
+  }
 }

package/src/agent/graph.d.ts

@@ -1,22 +1,27 @@
 import { BaseMessage } from '@langchain/core/messages';
 import { RunnableConfig } from '@langchain/core/runnables';
+import { TMessageContentComplex } from '@xpert-ai/chatkit-types';
 import { Subscriber } from 'rxjs';
 import { TWorkflowVarGroup } from '../ai/xpert-workflow.model';
-import { TMessageContentComplex } from '../ai/chat-message.model';
-import { I18nObject } from '../types';
-import { TXpertGraph, TXpertTeamNode } from '../ai/xpert.model';
+import { TXpertGraph } from '../ai/xpert.model';
+import { IXpertAgent } from '../ai/xpert-agent.model';
 /**
  * @deprecated can use getCurrentTaskInput instead?
  */
 export declare const CONTEXT_VARIABLE_CURRENTSTATE = "currentState";
 export declare const STATE_VARIABLE_SYS = "sys";
-export declare const STATE_VARIABLE_HUMAN = "human";
 export declare const GRAPH_NODE_SUMMARIZE_CONVERSATION = "summarize_conversation";
 export declare const GRAPH_NODE_TITLE_CONVERSATION = "title_conversation";
 export declare const STATE_VARIABLE_FILES = "files";
 export declare const STATE_VARIABLE_INPUT = "input";
 export declare const STATE_SYS_VOLUME = "volume";
+/**
+ * Workspace path in sandbox environment
+ */
 export declare const STATE_SYS_WORKSPACE_PATH = "workspace_path";
+/**
+ * URL for workspace files in sandbox environment
+ */
 export declare const STATE_SYS_WORKSPACE_URL = "workspace_url";
 export declare const STATE_VARIABLE_TITLE_CHANNEL: string;
 export type TMessageChannel = {
@@ -25,6 +30,11 @@ export type TMessageChannel = {
     summary?: string;
     error?: string | null;
 };
+export type TSandboxConfigurable = {
+    provider?: string;
+    workingDirectory?: string;
+    backend?: unknown;
+};
 export type TAgentRunnableConfigurable = {
     /**
      * Thread id
@@ -50,64 +60,29 @@ export type TAgentRunnableConfigurable = {
      * Execution id of agent workflow node
      */
     executionId: string;
+    /**
+     * Sandbox backend context
+     */
+    sandbox?: TSandboxConfigurable;
     signal?: AbortSignal;
 };
+/**
+ * @deprecated use import { type ToolCall } from '@langchain/core/messages/tool';
+ */
 export type TToolCall = {
     id?: string;
     name: string;
     type?: 'tool_call';
     args: Record<string, any>;
 };
+export declare function channelName(name: string): string;
+export declare function messageContentText(content: string | TMessageContentComplex): any;
 /**
+ * Get workspace folder for sandbox from runnable configurable
  *
- * Example:
- *
- * ```typescript
- *  const result = interrupt<TInterruptMessage<{ name: string }>, { projectId: string }>({
- *		category: 'BI',
- *		type: 'switch_project',
- *		title: {
- *			en_US: 'Switch project',
- *			zh_Hans: '切换项目'
- *		},
- *		message: {
- *			en_US: 'Please select a project or create a new one',
- *			zh_Hans: '请选择或创建一个新的项目'
- *		},
- *		data: { name: '' }
- *	})
- * ```
+ * @param configurable
+ * @returns
  */
-export type TInterruptMessage<T = unknown> = {
-    /**
-     * Major categories of interrupt components
-     */
-    category: 'BI';
-    /**
-     * The specific type of interactive component
-     */
-    type: string;
-    /**
-     * Title of the interrupt component
-     */
-    title: string | I18nObject;
-    /**
-     * Message content of the interrupt component
-     */
-    message: string | I18nObject;
-    /**
-     * Additional data
-     */
-    data?: T;
-};
-export type TInterruptCommand = {
-    resume?: any;
-    update?: any;
-    toolCalls?: TToolCall[];
-    agentKey?: string;
-};
-export declare function channelName(name: string): string;
-export declare function messageContentText(content: string | TMessageContentComplex): any;
 export declare function getWorkspaceFromRunnable(configurable: TAgentRunnableConfigurable): {
     type?: 'project' | 'conversation';
     id?: string;
@@ -148,4 +123,45 @@ export declare function getAgentVarGroup(key: string, graph: TXpertGraph): TWork
  * @param agentKey
  */
 export declare function getSwarmPartners(graph: TXpertGraph, agentKey: string, partners: string[], leaderKey?: string): string[];
-export declare function getWorkflowTriggers(graph: TXpertGraph, from: string): TXpertTeamNode[];
+export declare function getWorkflowTriggers(graph: TXpertGraph, from: string): ((import("../ai/xpert.model").TXpertTeamNodeBase & {
+    type: "agent";
+} & {
+    entity: IXpertAgent;
+}) | (import("../ai/xpert.model").TXpertTeamNodeBase & {
+    type: "knowledge";
+} & {
+    entity: import("..").IKnowledgebase;
+}) | (import("../ai/xpert.model").TXpertTeamNodeBase & {
+    type: "toolset";
+} & {
+    entity: import("..").IXpertToolset;
+}) | (import("../ai/xpert.model").TXpertTeamNodeBase & {
+    type: "xpert";
+} & {
+    entity: import("../ai/xpert.model").IXpert;
+    nodes?: ((import("../ai/xpert.model").TXpertTeamNodeBase & {
+        type: "agent";
+    } & {
+        entity: IXpertAgent;
+    }) | (import("../ai/xpert.model").TXpertTeamNodeBase & {
+        type: "knowledge";
+    } & {
+        entity: import("..").IKnowledgebase;
+    }) | (import("../ai/xpert.model").TXpertTeamNodeBase & {
+        type: "toolset";
+    } & {
+        entity: import("..").IXpertToolset;
+    }) | (import("../ai/xpert.model").TXpertTeamNodeBase & {
+        type: "xpert";
+    } & any) | (import("../ai/xpert.model").TXpertTeamNodeBase & {
+        type: "workflow";
+    } & {
+        entity: import("../ai/xpert-workflow.model").IWorkflowNode;
+    }))[];
+    connections?: import("../ai/xpert.model").TXpertTeamConnection[];
+    expanded?: boolean;
+}) | (import("../ai/xpert.model").TXpertTeamNodeBase & {
+    type: "workflow";
+} & {
+    entity: import("../ai/xpert-workflow.model").IWorkflowNode;
+}))[];

package/src/agent/index.d.ts

@@ -3,3 +3,4 @@ export * from './token';
 export * from './graph';
 export * from './utils';
 export * from './variables';
+export * from './interrupt';

package/src/agent/interrupt.d.ts

@@ -0,0 +1,51 @@
+import { I18nObject } from '../types';
+export type TInterrupt<T = unknown> = {
+    id?: string;
+    value?: T;
+    when?: 'during';
+    resumable?: boolean;
+    ns?: string[];
+};
+/**
+ *
+ * Example:
+ *
+ * ```typescript
+ *  const result = interrupt<TInterruptMessage<{ name: string }>, { projectId: string }>({
+ *		category: 'BI',
+ *		type: 'switch_project',
+ *		title: {
+ *			en_US: 'Switch project',
+ *			zh_Hans: '切换项目'
+ *		},
+ *		message: {
+ *			en_US: 'Please select a project or create a new one',
+ *			zh_Hans: '请选择或创建一个新的项目'
+ *		},
+ *		data: { name: '' }
+ *	})
+ * ```
+ */
+export type TInterruptMessage<T = unknown> = {
+    /**
+     * Major categories of interrupt components
+     */
+    category: 'BI';
+    /**
+     * The specific type of interactive component
+     */
+    type: string;
+    /**
+     * Title of the interrupt component
+     */
+    title: string | I18nObject;
+    /**
+     * Message content of the interrupt component
+     */
+    message: string | I18nObject;
+    /**
+     * Additional data
+     */
+    data?: T;
+};
+export declare function isInterruptMessage(obj: unknown): obj is TInterruptMessage;

package/src/ai/ai-model.model.d.ts

@@ -1,4 +1,4 @@
-import { AiModelTypeEnum } from '../agent/';
+import { AiModelTypeEnum } from '../agent/index';
 import { IBasePerTenantAndOrganizationEntityModel } from '../base-entity.model';
 import { I18nObject } from '../types';
 import { ICopilot } from './copilot.model';

package/src/ai/chat-message.model.d.ts

@@ -1,62 +1,24 @@
-import { MessageContentImageUrl, MessageType } from '@langchain/core/messages';
+import { MessageType } from '@langchain/core/messages';
 import { IBasePerTenantAndOrganizationEntityModel } from '../base-entity.model';
 import { IChatConversation } from './chat.model';
 import { LongTermMemoryTypeEnum } from './xpert.model';
 import { XpertAgentExecutionStatusEnum } from './xpert-agent-execution.model';
 import { JSONValue } from '../core.model';
 import { IStorageFile } from '../storage-file.model';
+import { TChatMessageStep, TMessageContent, TMessageContentReasoning } from '@xpert-ai/chatkit-types';
 export type TSummaryJob = Record<LongTermMemoryTypeEnum, {
     jobId: number | string;
     status: string;
     progress?: number;
     memoryKey?: string;
 }>;
-/**
- * Message step type: determines the type of canvas
- */
-/**
- * Category of step message: determines the display components of computer use
- */
-export declare enum ChatMessageStepCategory {
-    /**
-     * List of items: urls, files, etc.
-     */
-    List = "list",
-    /**
-     * Websearch results
-     */
-    WebSearch = "web_search",
-    /**
-     * Files list
-     */
-    Files = "files",
-    /**
-     * View a file
-     */
-    File = "file",
-    /**
-     * Program Execution
-     */
-    Program = "program",
-    /**
-     * Iframe
-     */
-    Iframe = "iframe",
-    Memory = "memory",
-    Tasks = "tasks",
-    /**
-     * Knowledges (knowledge base retriever results)
-     */
-    Knowledges = "knowledges"
-}
-/**
- * Step message type, in canvas and ai message.
- */
-export type TChatMessageStep<T = any> = TMessageComponent<TMessageComponentStep<T>>;
 /**
  * Chat message entity type
  */
 export interface IChatMessage extends IBasePerTenantAndOrganizationEntityModel, Omit<Omit<CopilotBaseMessage, 'createdAt'>, 'id'> {
+    parent?: IChatMessage | null;
+    children?: IChatMessage[];
+    parentId?: string | null;
     /**
      * Files
      */
@@ -90,7 +52,7 @@ export type ChatMessageStatusEnum = XpertAgentExecutionStatusEnum | 'thinking' |
  * BaseMessage or AIMessage in Langchain.js
  */
 export interface CopilotBaseMessage {
-    id: string;
+    id?: string;
     createdAt?: Date;
     role: CopilotMessageType;
     /**
@@ -124,98 +86,6 @@ export type CopilotChatMessage = CopilotBaseMessage & {
 export interface CopilotMessageGroup extends CopilotBaseMessage {
     messages?: CopilotChatMessage[];
 }
-/**
- * Similar to {@link MessageContentText} | {@link MessageContentImageUrl}, which together form {@link MessageContentComplex}
- */
-export type TMessageContentComponent<T extends object = object> = {
-    id: string;
-    type: 'component';
-    data: TMessageComponent<T>;
-    xpertName?: string;
-    agentKey?: string;
-};
-/**
- * Defines the data type of the sub-message of `component` type in the message `content` {@link MessageContentComplex}
- */
-export type TMessageComponent<T extends object = object> = T & {
-    id?: string;
-    category: 'Dashboard' | 'Computer' | 'Tool';
-    type?: string;
-    created_date?: Date | string;
-};
-export type TMessageContentText = {
-    id?: string;
-    xpertName?: string;
-    agentKey?: string;
-    type: "text";
-    text: string;
-};
-export type TMessageContentMemory = {
-    id?: string;
-    agentKey?: string;
-    type: "memory";
-    data: any[];
-};
-export type TMessageContentReasoning = {
-    id?: string;
-    xpertName?: string;
-    agentKey?: string;
-    type: "reasoning";
-    text: string;
-};
-/**
- * Enhance {@link MessageContentComplex} in Langchain.js
- */
-export type TMessageContentComplex = (TMessageContentText | TMessageContentReasoning | MessageContentImageUrl | TMessageContentComponent | TMessageContentMemory | (Record<string, any> & {
-    type?: "text" | "image_url" | string;
-}) | (Record<string, any> & {
-    type?: never;
-})) & {
-    id?: string;
-    xpertName?: string;
-    agentKey?: string;
-    created_date?: Date | string;
-};
-/**
- * Enhance {@link MessageContent} in Langchain.js
- */
-export type TMessageContent = string | TMessageContentComplex[];
-export type TMessageComponentIframe = {
-    type: 'iframe';
-    title: string;
-    url?: string;
-    data?: {
-        url?: string;
-    };
-};
-export type TMessageComponentStep<T = JSONValue> = {
-    type: ChatMessageStepCategory;
-    toolset: string;
-    toolset_id: string;
-    tool?: string;
-    title: string;
-    message: string;
-    status: 'success' | 'fail' | 'running';
-    created_date: Date | string;
-    end_date: Date | string;
-    error?: string;
-    data?: T;
-    input?: any;
-    output?: string;
-    artifact?: any;
-};
-/**
- * Data type for chat event message
- */
-export type TChatEventMessage = {
-    type?: string;
-    title?: string;
-    message?: string;
-    status?: 'success' | 'fail' | 'running';
-    created_date?: Date | string;
-    end_date?: Date | string;
-    error?: string;
-};
 /**
  * @deprecated use content in message
  */

package/src/ai/chat.model.d.ts

@@ -7,7 +7,8 @@ import { IXpertAgent } from './xpert-agent.model';
 import { IXpertProject } from './xpert-project.model';
 import { IStorageFile } from '../storage-file.model';
 import { IXpertTask } from './xpert-task.model';
-import { TInterruptMessage, TToolCall } from '../agent';
+import { TToolCall } from '../agent';
+import { TInterrupt } from '../agent/interrupt';
 export type TChatConversationOptions = {
     parameters?: {
         input?: string;
@@ -29,12 +30,7 @@ export type TSensitiveOperation = {
     messageId?: string;
     tasks?: {
         name: string;
-        interrupts: {
-            value?: TInterruptMessage;
-            when?: "during";
-            resumable?: boolean;
-            ns?: string[];
-        }[];
+        interrupts: TInterrupt[];
         type?: TToolCallType;
         info?: {
             name: string;

package/src/ai/copilot-model.model.d.ts

@@ -22,5 +22,9 @@ export type TCopilotModel = {
     options?: TCopilotModelOptions;
 };
 export type TCopilotModelOptions = {
+    /**
+     * Max input context size of selected model
+     */
+    context_size?: number;
     [key: string]: any;
 };

package/src/ai/copilot-user.model.d.ts

@@ -3,6 +3,7 @@ import { IOrganization } from '../organization.model';
 import { IUser } from '../user.model';
 import { AiProvider } from './ai.model';
 import { ICopilot, TCopilotTokenUsage } from './copilot.model';
+export declare const USAGE_HOUR_FORMAT = "yyyy-MM-dd HH";
 /**
  *
  */
@@ -13,6 +14,12 @@ export interface ICopilotUser extends IBasePerTenantAndOrganizationEntityModel,
     copilot?: ICopilot;
     userId?: string;
     user?: IUser;
+    xpertId?: string;
+    /**
+     * Usage hour in format 'yyyy-MM-dd HH' {@link USAGE_HOUR_FORMAT}
+     */
+    usageHour: string;
+    threadId: string;
     provider?: AiProvider | string;
     model?: string;
     tokenTotalUsed?: number;

package/src/ai/index.d.ts

@@ -1,3 +1,4 @@
+export * from '@xpert-ai/chatkit-types';
 export * from './ai-model.model';
 export * from './ai.model';
 export * from './chat.model';
@@ -40,3 +41,5 @@ export * from './knowledge-retrieval-log.model';
 export * from './knowledge-doc-chunk.model';
 export * from './skill.model';
 export * from './middleware.model';
+export * from './sandbox';
+export * from './message-content.utils';

package/src/ai/message-content.utils.d.ts

@@ -0,0 +1,52 @@
+import { TMessageContent, TMessageContentComplex } from '@xpert-ai/chatkit-types';
+import { CopilotChatMessage } from './chat-message.model';
+export type TMessageJoinHint = 'none' | 'space' | 'line' | 'paragraph';
+export type TMessageAppendContext = {
+    source?: string;
+    streamId?: string;
+    joinHint?: TMessageJoinHint;
+};
+export type TAppendMessageContentOptions = TMessageAppendContext & {
+    previous?: TMessageAppendContext | null;
+};
+export type TResolveMessageAppendContextOptions = {
+    previous?: TMessageAppendContext | null;
+    incoming: string | TMessageContentComplex;
+    fallbackSource?: string;
+    fallbackStreamId?: string;
+};
+export type TResolvedMessageAppendContext = {
+    appendContext: TMessageAppendContext;
+    messageContext: TMessageAppendContext;
+};
+export type TMessageAppendContextTracker = {
+    resolve: (options: Omit<TResolveMessageAppendContextOptions, 'previous'>) => TResolvedMessageAppendContext;
+    reset: () => void;
+    current: () => TMessageAppendContext | null;
+};
+export declare function inferMessageAppendContext(content: string | TMessageContentComplex, fallbackSource?: string): TMessageAppendContext;
+export declare function resolveMessageAppendContext(options: TResolveMessageAppendContextOptions): TResolvedMessageAppendContext;
+/**
+ * Stateful helper for streaming append.
+ *
+ * It keeps the previous append context and resolves the current one, so callers
+ * can avoid passing `previous` manually for every chunk and still get stable
+ * join behavior (for example, same source + same stream -> `joinHint: 'none'`).
+ *
+ * Call `reset()` at turn/session boundaries to prevent cross-turn contamination.
+ */
+export declare function createMessageAppendContextTracker(initial?: TMessageAppendContext | null): TMessageAppendContextTracker;
+/**
+ * Append one incoming chunk into a chat message in place.
+ *
+ * Behavior:
+ * - Keeps `aiMessage` object reference stable (caller may hold this object).
+ * - Updates message properties with new references (`content`/`reasoning` arrays)
+ *   so UI change detection that relies on reference changes can react reliably.
+ * - Applies context-aware merge rules for text/reasoning/component chunks.
+ * - `previous` must be supplied by caller when same-stream join inference is needed.
+ */
+export declare function appendMessageContent(aiMessage: CopilotChatMessage, incoming: string | TMessageContentComplex, context?: TAppendMessageContentOptions): void;
+export declare function appendMessagePlainText(accumulator: string, incoming: string | TMessageContentComplex, context?: TMessageAppendContext): string;
+export declare function stringifyMessageContent(content: TMessageContent | TMessageContentComplex): string;
+export declare function filterMessageText(content: TMessageContent | TMessageContentComplex): string;

package/src/ai/middleware.model.d.ts

@@ -6,7 +6,12 @@ export interface IWFNMiddleware extends IWorkflowNode {
     type: WorkflowNodeTypeEnum.MIDDLEWARE;
     provider: string;
     options?: Record<string, any>;
+    tools?: Record<string, TMiddlewareToolConfig | boolean>;
 }
+export type TMiddlewareToolConfig = {
+    enabled?: boolean;
+};
+export declare function isMiddlewareToolEnabled(config?: TMiddlewareToolConfig | boolean): boolean;
 export declare function genXpertMiddlewareKey(): string;
 export type TAgentMiddlewareMeta = {
     name: string;

package/src/ai/sandbox.d.ts

@@ -0,0 +1,6 @@
+import { I18nObject, IconDefinition } from "../types";
+export type TSandboxProviderMeta = {
+    name: I18nObject;
+    description?: I18nObject;
+    icon: IconDefinition;
+};

package/src/ai/types.d.ts

@@ -59,6 +59,12 @@ type JsonSchema7Meta = {
          * Additional inputs for the Custom UI component
          */
         inputs?: Record<string, unknown>;
+        /**
+         * Whether this component supports selecting LangGraph state variables
+         */
+        variable?: boolean;
+        enumLabels?: Record<string, I18nObject | string>;
+        styles?: Record<string, string>;
     };
 };
 export type JsonSchemaObjectType = {

package/src/ai/xpert-agent.model.d.ts

@@ -1,3 +1,4 @@
+import { STATE_VARIABLE_HUMAN, TChatRequestHuman, TInterruptCommand } from '@xpert-ai/chatkit-types';
 import { IBasePerTenantAndOrganizationEntityModel } from '../base-entity.model';
 import { ICopilotModel, TCopilotModel } from './copilot-model.model';
 import { IKnowledgebase, TKBRecallParams } from './knowledgebase.model';
@@ -6,7 +7,6 @@ import { IXpertToolset } from './xpert-toolset.model';
 import { IXpert, TXpertParameter } from './xpert.model';
 import { TVariableAssigner } from './xpert-workflow.model';
 import { TErrorHandling } from './types';
-import { TInterruptCommand } from '../agent';
 export type TXpertAgent = {
     key: string;
     name?: string;
@@ -140,19 +140,13 @@ export type TXpertAgentOptions = {
      */
     structuredOutputMethod?: "functionCalling" | "jsonMode" | "jsonSchema" | string;
     /**
-     * Vision config of agent
+     * @deprecated use attachment
      */
-    vision?: {
-        enabled?: boolean;
-        /**
-         * Variable name that store the list of files to be understood
-         */
-        variable?: string;
-        /**
-         * Image resolution for vision tasks
-         */
-        resolution?: 'high' | 'low';
-    };
+    vision?: TXpertAgentVision;
+    /**
+     * Attachment config of agent
+     */
+    attachment?: TXpertAgentAttachment;
     /**
      * Config of middlewares for agent
      */
@@ -160,6 +154,23 @@ export type TXpertAgentOptions = {
         order: string[];
     };
 };
+export type TXpertAgentVision = {
+    enabled?: boolean;
+    /**
+     * Variable name that store the list of files to be understood
+     */
+    variable?: string;
+    /**
+     * Image resolution for vision tasks
+     */
+    resolution?: 'high' | 'low';
+};
+export type TXpertAgentAttachment = TXpertAgentVision & {
+    /**
+     * Max number of files to be processed
+     */
+    maxNum?: number;
+};
 export type TAgentPromptTemplate = {
     id: string;
     role: 'ai' | 'human';
@@ -179,10 +190,17 @@ export type TAgentOutputVariable = TXpertParameter & {
  * @deprecated use TChatRequest
  */
 export type TChatAgentParams = {
-    input: {
+    /**
+     * @deprecated use state instead
+     */
+    input?: {
         input?: string;
         [key: string]: unknown;
     };
+    state: {
+        [STATE_VARIABLE_HUMAN]: TChatRequestHuman;
+        [key: string]: any;
+    };
     agentKey: string;
     xpertId: string;
     executionId?: string;