@metad/contracts 3.8.0 → 3.8.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metad/contracts",
-  "version": "3.8.0",
+  "version": "3.8.3",
   "license": "AGPL-3.0",
   "repository": {
     "type": "git",

package/src/agent/token.d.ts

@@ -3,6 +3,23 @@ export type TTokenUsage = {
     completionTokens: number;
     totalTokens: number;
 };
+export type TThreadContextUsageMetrics = {
+    contextTokens: number;
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    embedTokens: number;
+    totalPrice: number;
+    currency: string | null;
+};
+export type TThreadContextUsageEvent = {
+    type: 'thread_context_usage';
+    threadId: string;
+    runId: string | null;
+    agentKey: string;
+    updatedAt: string;
+    usage: TThreadContextUsageMetrics;
+};
 export interface IModelUsage {
     totalTokens: number;
     totalPrice: number;

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

@@ -2,7 +2,7 @@ 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 { IXpertAgentExecution, 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';
@@ -41,6 +41,7 @@ export interface IChatMessage extends IBasePerTenantAndOrganizationEntityModel,
     conversation?: IChatConversation;
     conversationId?: string | null;
     executionId?: string;
+    execution?: IXpertAgentExecution;
 }
 /**
  * @deprecated
@@ -52,7 +53,7 @@ export type ChatMessageStatusEnum = XpertAgentExecutionStatusEnum | 'thinking' |
  * BaseMessage or AIMessage in Langchain.js
  */
 export interface CopilotBaseMessage {
-    id: string;
+    id?: string;
     createdAt?: Date;
     role: CopilotMessageType;
     /**

package/src/ai/index.d.ts

@@ -42,3 +42,4 @@ 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/xpert-tool-mcp.model.d.ts

@@ -1,7 +1,8 @@
 export declare enum MCPServerType {
     SSE = "sse",
     STDIO = "stdio",
-    CODE = "code"
+    CODE = "code",
+    HTTP = "http"
 }
 /**
  * Configuration for stdio transport connection
@@ -23,6 +24,19 @@ export interface SSEConnection {
     headers?: Record<string, string>;
     useNodeEventSource?: boolean;
 }
+/**
+ * Configuration for Streamable HTTP transport connection
+ */
+export interface HttpConnection {
+    transport: "http";
+    url: string;
+    headers?: Record<string, string>;
+    /**
+     * Whether to automatically fallback to SSE if Streamable HTTP is not available.
+     * Defaults to true.
+     */
+    automaticSSEFallback?: boolean;
+}
 export type TMCPServerReconnect = {
     /**
      * Whether to automatically restart the process if it exits
@@ -51,6 +65,11 @@ export type TMCPServer = {
     url?: string;
     headers?: Record<string, string>;
     useNodeEventSource?: boolean;
+    /**
+     * Whether to automatically fallback to SSE if Streamable HTTP is not available.
+     * Defaults to true. Only applicable for HTTP transport.
+     */
+    automaticSSEFallback?: boolean;
     /**
      * Default timeout in milliseconds for tool execution. Must be greater than 0.
      * If not specified, tools will use their own configured timeout values.

package/src/analytics/screenshot.model.d.ts

@@ -1,5 +1,4 @@
 import { IBasePerTenantAndOrganizationEntityModel } from '../base-entity.model';
-import { FileStorageProviderEnum } from '../file-provider';
 export interface IScreenshot extends IBasePerTenantAndOrganizationEntityModel {
     file: string;
     url?: string;
@@ -11,7 +10,7 @@ export interface IScreenshot extends IBasePerTenantAndOrganizationEntityModel {
     thumbUrl?: string;
     recordedAt?: Date;
     size?: number;
-    storageProvider?: FileStorageProviderEnum;
+    storageProvider?: string;
 }
 export interface IUpdateScreenshotInput extends ICreateScreenshotInput {
     id: string;

package/src/file-asset.model.d.ts

@@ -0,0 +1,77 @@
+import { IStorageFile } from './storage-file.model';
+export type FileAssetStatus = 'success' | 'partial_success' | 'failed';
+export type FileAssetDestinationKind = 'storage' | 'volume' | 'sandbox';
+export type FileAssetSourceKind = 'multipart' | 'storage_file' | 'local_file';
+export type FileUploadVolumeCatalog = 'projects' | 'users' | 'knowledges' | 'skills';
+export type FileUploadSandboxMode = 'mounted_workspace' | 'backend_upload';
+export interface IFileAssetSource {
+    kind: FileAssetSourceKind;
+    name?: string;
+    originalName?: string;
+    mimeType?: string;
+    size?: number;
+    storageFileId?: string;
+    filePath?: string;
+    metadata?: Record<string, any>;
+}
+export interface IFileAssetDestination {
+    kind: FileAssetDestinationKind;
+    status: 'success' | 'failed';
+    path?: string;
+    url?: string;
+    referenceId?: string;
+    metadata?: Record<string, any>;
+    error?: string;
+}
+export interface IFileAsset {
+    name?: string;
+    originalName?: string;
+    mimeType?: string;
+    size?: number;
+    status: FileAssetStatus;
+    metadata?: Record<string, any>;
+    source?: IFileAssetSource;
+    destinations: IFileAssetDestination[];
+}
+export interface IUploadFileStorageTarget {
+    kind: 'storage';
+    strategy?: string;
+    provider?: string;
+    providerOptions?: Record<string, any>;
+    directory?: string;
+    fileName?: string;
+    prefix?: string;
+    metadata?: Record<string, any>;
+}
+export interface IUploadFileVolumeTarget {
+    kind: 'volume';
+    strategy?: string;
+    catalog: FileUploadVolumeCatalog;
+    projectId?: string;
+    knowledgeId?: string;
+    userId?: string;
+    tenantId?: string;
+    folder?: string;
+    fileName?: string;
+    metadata?: Record<string, any>;
+}
+export interface IUploadFileSandboxTarget {
+    kind: 'sandbox';
+    strategy?: string;
+    mode: FileUploadSandboxMode;
+    workspacePath?: string;
+    workspaceUrl?: string;
+    workspaceId?: string;
+    sandboxUrl?: string;
+    folder?: string;
+    fileName?: string;
+    metadata?: Record<string, any>;
+}
+export type IUploadFileTarget = IUploadFileStorageTarget | IUploadFileVolumeTarget | IUploadFileSandboxTarget;
+export type TStorageFileAssetDestination = IFileAssetDestination & {
+    kind: 'storage';
+    referenceId?: IStorageFile['id'];
+    metadata?: Record<string, any> & {
+        storageFile?: IStorageFile;
+    };
+};

package/src/file-provider.d.ts

@@ -1,6 +1,6 @@
 export interface FileStorageOption {
     dest: string | CallableFunction;
-    provider?: FileStorageProviderEnum;
+    provider?: string;
     prefix?: string;
     filename?: string | CallableFunction;
 }
@@ -9,10 +9,7 @@ export interface FileSystem {
     baseUrl?: string;
 }
 export declare enum FileStorageProviderEnum {
-    LOCAL = "LOCAL",
-    S3 = "S3",
-    WASABI = "WASABI",
-    OSS = "OSS"
+    LOCAL = "LOCAL"
 }
 export interface UploadedFile {
     fieldname: string;
@@ -30,4 +27,5 @@ export interface S3FileStorageProviderConfig {
     aws_secret_access_key?: string;
     aws_default_region?: string;
     aws_bucket?: string;
+    aws_endpoint?: string;
 }

package/src/index.d.ts

@@ -9,6 +9,7 @@ export * from './employee.model';
 export * from './entity-with-members.model';
 export * from './feature.model';
 export * from './file-provider';
+export * from './file-asset.model';
 export * from './http-status.enum';
 export * from './import-export.model';
 export * from './language.model';

package/src/plugin.d.ts

@@ -1,9 +1,24 @@
 import { IBasePerTenantAndOrganizationEntityModel } from './base-entity.model';
+import { JsonSchemaObjectType } from './ai/types';
 import { IconDefinition } from './types';
 export type PluginName = string;
+export declare const PLUGIN_LEVEL: {
+    readonly SYSTEM: "system";
+    readonly ORGANIZATION: "organization";
+};
+/**
+ * Classifies plugin scope and governance.
+ * - `system`: built-in/platform-managed plugin that users cannot install/uninstall from org APIs.
+ * - `organization`: tenant/org-managed plugin that can be installed and removed per organization.
+ */
+export type PluginLevel = (typeof PLUGIN_LEVEL)[keyof typeof PLUGIN_LEVEL];
 export interface PluginMeta {
     name: PluginName;
     version: string;
+    /**
+     * Declares the plugin's operational level used for visibility and install/uninstall guardrails.
+     */
+    level?: PluginLevel;
     icon?: IconDefinition;
     category: 'set' | 'doc-source' | 'agent' | 'tools' | 'model' | 'vlm' | 'vector-store' | 'integration' | 'datasource' | 'database' | 'middleware';
     displayName: string;
@@ -16,6 +31,21 @@ export interface IPlugin extends IBasePerTenantAndOrganizationEntityModel {
     pluginName: string;
     packageName: string;
     version?: string;
-    source?: "marketplace" | "local" | "git" | "url" | "npm" | "code";
+    source?: 'marketplace' | 'local' | 'git' | 'url' | 'npm' | 'code' | 'env';
+    level?: PluginLevel;
     config: Record<string, any>;
 }
+export interface IPluginDescriptor {
+    organizationId?: string;
+    name: PluginName;
+    meta: PluginMeta;
+    isGlobal: boolean;
+    level: PluginLevel;
+    canConfigure?: boolean;
+    configSchema?: JsonSchemaObjectType;
+}
+export interface IPluginConfiguration<TConfig extends Record<string, any> = Record<string, any>> {
+    pluginName: PluginName;
+    config: TConfig;
+    configSchema?: JsonSchemaObjectType;
+}

package/src/storage-file.model.d.ts

@@ -1,5 +1,4 @@
 import { IBasePerTenantAndOrganizationEntityModel } from './base-entity.model';
-import { FileStorageProviderEnum } from './file-provider';
 import { _TFile } from './types';
 export type TFile = _TFile & {
     fileType?: string;
@@ -20,7 +19,7 @@ export interface IStorageFile extends IBasePerTenantAndOrganizationEntityModel {
     size?: number;
     mimetype?: string;
     recordedAt?: Date;
-    storageProvider?: FileStorageProviderEnum;
+    storageProvider?: string;
 }
 export interface ICreateStorageFileInput extends IBasePerTenantAndOrganizationEntityModel {
     activityTimestamp: string;

package/src/tenant.model.d.ts

@@ -1,6 +1,6 @@
 import { IImportRecord } from './import-export.model';
 import { IFeatureOrganization } from './feature.model';
-import { FileStorageProviderEnum, S3FileStorageProviderConfig } from './file-provider';
+import { S3FileStorageProviderConfig } from './file-provider';
 import { IOrganization, IOrganizationCreateInput } from './organization.model';
 import { IRolePermission } from './role-permission.model';
 import { IUserCreateInput } from './user.model';
@@ -28,7 +28,7 @@ export interface ISetting {
     value: string;
 }
 export interface ITenantSetting extends S3FileStorageProviderConfig {
-    fileStorageProvider?: FileStorageProviderEnum;
+    fileStorageProvider?: string;
     tenant_title?: string;
     tenant_title_en?: string;
     tenant_enable_feishu?: boolean;