@xpert-ai/contracts 3.9.0-beta.3 → 3.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xpert-ai/contracts",
-  "version": "3.9.0-beta.3",
+  "version": "3.9.0",
   "license": "AGPL-3.0",
   "repository": {
     "type": "git",

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

@@ -30,6 +30,13 @@ export interface IAssistantBindingSkillPreference {
     workspaceId: string;
     disabledSkillIds: string[];
 }
+export type AssistantBindingToolPreferenceSourceType = 'toolset' | 'middleware';
+export type AssistantBindingToolPreferenceSourceMetadata = {
+    toolsetId?: string | null;
+    toolsetName: string;
+} | {
+    provider: string;
+};
 export interface IAssistantBindingConversationPreferences {
     version: 2;
     defaultThreadId?: string | null;
@@ -37,11 +44,24 @@ export interface IAssistantBindingConversationPreferences {
     defaultFollowUpBehavior?: 'queue' | 'steer';
 }
 export interface IAssistantBindingToolPreferences {
-    version: 1;
+    version: number;
     toolsets?: Record<string, IAssistantBindingToolsetPreference>;
     middlewares?: Record<string, IAssistantBindingMiddlewarePreference>;
     skills?: Record<string, IAssistantBindingSkillPreference>;
 }
+export declare function normalizeAssistantBindingToolPreferences(value?: IAssistantBindingToolPreferences | null): IAssistantBindingToolPreferences | null;
+export declare function isAssistantBindingToolPreferencesEmpty(preferences?: IAssistantBindingToolPreferences | null): boolean;
+export declare function getAssistantBindingDisabledTools(preferences: IAssistantBindingToolPreferences | null | undefined, sourceType: AssistantBindingToolPreferenceSourceType, nodeKey: string | null | undefined): string[];
+export declare function getAssistantBindingDisabledSkillIds(preferences: IAssistantBindingToolPreferences | null | undefined, workspaceId: string | null | undefined): string[];
+export declare function isAssistantBindingToolEnabled(preferences: IAssistantBindingToolPreferences | null | undefined, sourceType: AssistantBindingToolPreferenceSourceType, nodeKey: string | null | undefined, toolName: string): boolean;
+export declare function isAssistantBindingSkillEnabled(preferences: IAssistantBindingToolPreferences | null | undefined, workspaceId: string | null | undefined, skillId: string): boolean;
+export declare function filterAssistantBindingDisabledTools<T extends {
+    name: string;
+}>(tools: T[], preferences: IAssistantBindingToolPreferences | null | undefined, sourceType: AssistantBindingToolPreferenceSourceType, nodeKey: string | null | undefined): T[];
+export declare function filterAssistantBindingDisabledSkillIds(skillIds: string[], preferences: IAssistantBindingToolPreferences | null | undefined, workspaceId: string | null | undefined): string[];
+export declare function updateAssistantBindingToolPreferences(preferences: IAssistantBindingToolPreferences | null | undefined, sourceType: AssistantBindingToolPreferenceSourceType, nodeKey: string | null | undefined, metadata: AssistantBindingToolPreferenceSourceMetadata, toolName: string, enabled: boolean): IAssistantBindingToolPreferences | null;
+export declare function updateAssistantBindingSkillPreferences(preferences: IAssistantBindingToolPreferences | null | undefined, workspaceId: string | null | undefined, skillId: string, enabled: boolean): IAssistantBindingToolPreferences | null;
+export declare function ensureAssistantBindingSkillWorkspacePreference(preferences: IAssistantBindingToolPreferences | null | undefined, workspaceId: string): IAssistantBindingToolPreferences;
 export interface IAssistantBinding extends IBasePerTenantAndOrganizationEntityModel {
     code: AssistantCode;
     scope: AssistantBindingScope;

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

@@ -8,7 +8,7 @@ export type TConversationTitleSummaryEvent = TChatEventMessage & {
 };
 export type TFollowUpConsumedEvent = TChatEventMessage & {
     type: typeof CHAT_EVENT_TYPE_FOLLOW_UP_CONSUMED;
-    mode: 'steer';
+    mode: 'queue' | 'steer';
     messageIds: string[];
     clientMessageIds?: string[];
     executionId?: string | null;

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

@@ -12,6 +12,25 @@ export type TSummaryJob = Record<LongTermMemoryTypeEnum, {
     progress?: number;
     memoryKey?: string;
 }>;
+export type TChatReferenceBase = {
+    id?: string;
+    label?: string;
+    text: string;
+};
+export type TChatCodeReference = TChatReferenceBase & {
+    type: 'code';
+    path: string;
+    startLine: number;
+    endLine: number;
+    language?: string;
+    taskId?: string;
+};
+export type TChatQuoteReference = TChatReferenceBase & {
+    type: 'quote';
+    messageId?: string;
+    source?: string;
+};
+export type TChatReference = TChatCodeReference | TChatQuoteReference;
 /**
  * Chat message entity type
  */
@@ -23,6 +42,10 @@ export interface IChatMessage extends IBasePerTenantAndOrganizationEntityModel,
      * Files
      */
     attachments?: IStorageFile[];
+    /**
+     * Structured references associated with the human input
+     */
+    references?: TChatReference[];
     /**
      * Job of summary
      */

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

@@ -0,0 +1,13 @@
+export declare const CONTEXT_COMPRESSION_COMPONENT_TYPE = "context-compression";
+export type TContextCompressionComponentStatus = 'running' | 'success' | 'fail';
+export type TContextCompressionComponentData = {
+    category: 'Tool';
+    type: typeof CONTEXT_COMPRESSION_COMPONENT_TYPE;
+    status: TContextCompressionComponentStatus;
+    title?: string;
+    message?: string;
+    error?: string;
+    created_date?: string | Date | null;
+    end_date?: string | Date | null;
+};
+export declare function isContextCompressionComponentData(value: unknown): value is TContextCompressionComponentData;

package/src/ai/index.d.ts

@@ -58,6 +58,7 @@ export * from './knowledge-doc.model';
 export * from './knowledge-doc-page.model';
 export * from './role-permissions';
 export * from './xpert-agent-execution.model';
+export * from './sandbox-terminal.model';
 export * from './xpert-agent.model';
 export * from './xpert-chat.model';
 export * from './xpert-tool.model';
@@ -80,5 +81,6 @@ export * from './knowledge-retrieval-log.model';
 export * from './knowledge-doc-chunk.model';
 export * from './skill.model';
 export * from './middleware.model';
+export * from './context-compression.model';
 export * from './sandbox';
 export * from './message-content.utils';

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

@@ -2,6 +2,8 @@ import { IWorkflowNode, WorkflowNodeTypeEnum } from "./xpert-workflow.model";
 import { I18nObject, IconDefinition } from "../types";
 import { TXpertFeatureKey, TXpertGraph, TXpertTeamNode } from "./xpert.model";
 import { JsonSchemaObjectType } from "./types";
+export declare const LEGACY_SANDBOX_COMPRESSION_MIDDLEWARE_NAME = "SandboxCompressionMiddleware";
+export declare const CONTEXT_COMPRESSION_MIDDLEWARE_NAME = "ContextCompressionMiddleware";
 export interface IWFNMiddleware extends IWorkflowNode {
     type: WorkflowNodeTypeEnum.MIDDLEWARE;
     provider: string;
@@ -13,6 +15,9 @@ export type TMiddlewareToolConfig = {
 };
 export declare function isMiddlewareToolEnabled(config?: TMiddlewareToolConfig | boolean): boolean;
 export declare function genXpertMiddlewareKey(): string;
+export declare function normalizeMiddlewareProvider(provider?: string | null): string;
+export declare function normalizeMiddlewareNode<T extends TXpertTeamNode>(node: T): T;
+export declare function normalizeMiddlewareNodes<T extends TXpertTeamNode>(nodes?: T[] | null): T[];
 export type TAgentMiddlewareMeta = {
     name: string;
     label: I18nObject;

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

@@ -0,0 +1,108 @@
+export declare const SANDBOX_TERMINAL_NAMESPACE: "sandbox-terminal";
+export declare enum SandboxTerminalClientEvent {
+    Open = "open",
+    Input = "input",
+    Resize = "resize",
+    Close = "close"
+}
+export declare enum SandboxTerminalServerEvent {
+    Opened = "opened",
+    Output = "output",
+    Exit = "exit",
+    Error = "error",
+    Closed = "closed"
+}
+export declare enum SandboxTerminalClosedReason {
+    ClientClosed = "client_closed",
+    Error = "error",
+    OpenFailed = "open_failed",
+    ProcessExited = "process_exited",
+    SocketDisconnected = "socket_disconnected",
+    UnsupportedProvider = "unsupported_provider"
+}
+export declare enum SandboxTerminalErrorCode {
+    CloseFailed = "close_failed",
+    ConversationNotFound = "conversation_not_found",
+    ConversationRequired = "conversation_required",
+    InputFailed = "input_failed",
+    OpenFailed = "open_failed",
+    ProviderUnavailable = "provider_unavailable",
+    ResizeFailed = "resize_failed",
+    SandboxDisabled = "sandbox_disabled",
+    SessionNotFound = "session_not_found",
+    UnsupportedProvider = "unsupported_provider"
+}
+export type SandboxTerminalDimensions = {
+    cols: number;
+    rows: number;
+};
+export type SandboxTerminalOpenRequest = SandboxTerminalDimensions & {
+    conversationId: string;
+    projectId?: string | null;
+    requestId: string;
+};
+export type SandboxTerminalInputRequest = {
+    data: string;
+    sessionId: string;
+};
+export type SandboxTerminalResizeRequest = SandboxTerminalDimensions & {
+    sessionId: string;
+};
+export type SandboxTerminalCloseRequest = {
+    sessionId: string;
+};
+export type SandboxTerminalOpenedEvent = {
+    provider: string;
+    requestId: string;
+    sessionId: string;
+    workingDirectory: string;
+};
+export type SandboxTerminalOutputEvent = {
+    data: string;
+    sessionId: string;
+};
+export type SandboxTerminalExitEvent = {
+    exitCode: number | null;
+    sessionId: string;
+    signal?: number | null;
+};
+export type SandboxTerminalErrorEvent = {
+    code: SandboxTerminalErrorCode;
+    message: string;
+    requestId?: string;
+    sessionId?: string;
+};
+export type SandboxTerminalClosedEvent = {
+    reason: SandboxTerminalClosedReason;
+    requestId?: string;
+    sessionId?: string;
+};
+export type SandboxTerminalClientMessage = {
+    event: SandboxTerminalClientEvent.Open;
+    data: SandboxTerminalOpenRequest;
+} | {
+    event: SandboxTerminalClientEvent.Input;
+    data: SandboxTerminalInputRequest;
+} | {
+    event: SandboxTerminalClientEvent.Resize;
+    data: SandboxTerminalResizeRequest;
+} | {
+    event: SandboxTerminalClientEvent.Close;
+    data: SandboxTerminalCloseRequest;
+};
+export type SandboxTerminalServerMessage = {
+    event: SandboxTerminalServerEvent.Opened;
+    data: SandboxTerminalOpenedEvent;
+} | {
+    event: SandboxTerminalServerEvent.Output;
+    data: SandboxTerminalOutputEvent;
+} | {
+    event: SandboxTerminalServerEvent.Exit;
+    data: SandboxTerminalExitEvent;
+} | {
+    event: SandboxTerminalServerEvent.Error;
+    data: SandboxTerminalErrorEvent;
+} | {
+    event: SandboxTerminalServerEvent.Closed;
+    data: SandboxTerminalClosedEvent;
+};

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

@@ -53,6 +53,7 @@ export interface SkillMetadata {
     mcp?: {
         servers?: string[];
     };
+    provenance?: Record<string, unknown>;
 }
 export interface SkillResourcesIndex {
     files: Array<{

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

@@ -9,6 +9,69 @@ export interface IXpertTemplate extends IBasePerTenantEntityModel {
     visitCount: number;
     lastVisitedAt?: Date;
 }
+export type TemplateSkillSyncMode = 'incremental' | 'full';
+export type TemplateSkillSyncStatus = 'created' | 'updated' | 'unchanged' | 'missing' | 'failed';
+export interface ITemplateSkillSyncItemSummary {
+    created: number;
+    updated: number;
+    unchanged: number;
+    missing: number;
+    failed: number;
+}
+export interface ITemplateSkillSyncRepositoryResult {
+    name: string;
+    provider: string;
+    repositoryId?: string;
+    status: TemplateSkillSyncStatus;
+    message?: string;
+}
+export interface ITemplateSkillSyncIndexResult {
+    repositoryId?: string;
+    repositoryName: string;
+    provider: string;
+    mode: TemplateSkillSyncMode;
+    status: TemplateSkillSyncStatus;
+    syncedCount?: number;
+    message?: string;
+}
+export interface ITemplateSkillSyncBundleResult {
+    sharedSkillId: string;
+    provider: string;
+    repositoryName: string;
+    skillId: string;
+    status: TemplateSkillSyncStatus;
+    hash?: string;
+    repositoryId?: string;
+    indexId?: string;
+    message?: string;
+}
+export interface ITemplateSkillSyncRefResult {
+    provider: string;
+    repositoryName: string;
+    skillId: string;
+    status: TemplateSkillSyncStatus;
+    repositoryId?: string;
+    indexId?: string;
+    message?: string;
+}
+export interface ITemplateSkillSyncSummary {
+    repositories: ITemplateSkillSyncItemSummary;
+    indexes: ITemplateSkillSyncItemSummary;
+    bundles: ITemplateSkillSyncItemSummary;
+    featuredRefs: ITemplateSkillSyncItemSummary;
+    workspaceDefaults: ITemplateSkillSyncItemSummary;
+}
+export interface ITemplateSkillSyncResult {
+    mode: TemplateSkillSyncMode;
+    validateOnly: boolean;
+    fingerprint: string;
+    repositories: ITemplateSkillSyncRepositoryResult[];
+    indexes: ITemplateSkillSyncIndexResult[];
+    bundles: ITemplateSkillSyncBundleResult[];
+    featuredRefs: ITemplateSkillSyncRefResult[];
+    workspaceDefaults: ITemplateSkillSyncRefResult[];
+    summary: ITemplateSkillSyncSummary;
+}
 export type TTemplate = {
     id: string;
     name: string;

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

@@ -18,7 +18,7 @@ export interface IXpertWorkspace extends IBasePerTenantAndOrganizationEntityMode
 }
 export type TXpertWorkspaceSettings = {
     system?: {
-        kind?: 'org-default' | 'user-default';
+        kind?: 'org-default' | 'tenant-default' | 'user-default';
         userId?: string;
     };
 };

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

@@ -33,6 +33,10 @@ export type TXpertSandboxFeature = {
     enabled: boolean;
     provider?: string;
 };
+export type TXpertTitleFeature = {
+    enabled: boolean;
+    instruction?: string;
+};
 export type TXpertFeatures = {
     opener: {
         enabled: boolean;
@@ -66,6 +70,10 @@ export type TXpertFeatures = {
      * Sandbox feature
      */
     sandbox?: TXpertSandboxFeature;
+    /**
+     * Conversation title generation feature
+     */
+    title?: TXpertTitleFeature;
 };
 export type TXpertFeatureKey = keyof TXpertFeatures;
 export type TXpert = {
@@ -258,13 +266,6 @@ export type TXpertAgentConfig = {
      * Retrieval params for every knowledgebase
      */
     retrievals?: Record<string, TKBRetrievalSettings>;
-    /**
-     * Summarize the title of the conversation
-     */
-    summarizeTitle?: {
-        disable?: boolean;
-        instruction?: string;
-    };
     tools?: Record<string, {
         /**
          * Memory assigner for tool's results. (save result of tool call into state variable)
@@ -477,10 +478,6 @@ export type TChatOptions = {
      * Call from
      */
     from?: TChatFrom;
-    /**
-     * Whether to summarize the conversation title
-     */
-    summarizeTitle?: boolean;
     /**
      * Project ID, identify the project where the xpert invoked
      */

package/src/api-key.model.d.ts

@@ -13,6 +13,7 @@ export interface IApiKey extends IBasePerTenantAndOrganizationEntityModel {
     /**
      * Stable binding target id/code. Examples:
      * - assistant => xpertId
+     * - workspace => workspaceId
      * - integration => integrationId
      * - client => clientCode
      */
@@ -37,6 +38,7 @@ export declare const API_PRINCIPAL_USER_ID_HEADER = "x-principal-user-id";
  */
 export declare enum ApiKeyBindingType {
     ASSISTANT = "assistant",
+    WORKSPACE = "workspace",
     INTEGRATION = "integration",
     CLIENT = "client",
     /**

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

@@ -2,7 +2,7 @@ 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 FileUploadVolumeCatalog = 'projects' | 'users' | 'knowledges' | 'skills' | 'xperts';
 export type FileUploadSandboxMode = 'mounted_workspace' | 'backend_upload';
 export interface IFileAssetSource {
     kind: FileAssetSourceKind;
@@ -49,7 +49,9 @@ export interface IUploadFileVolumeTarget {
     catalog: FileUploadVolumeCatalog;
     projectId?: string;
     knowledgeId?: string;
+    xpertId?: string;
     userId?: string;
+    isolateByUser?: boolean;
     tenantId?: string;
     folder?: string;
     fileName?: string;

package/src/plugin.d.ts

@@ -107,6 +107,13 @@ export interface IPluginDescriptor {
     effectiveInCurrentScope: boolean;
     scopeRelation?: PluginScopeRelation;
 }
+export interface IPluginLatestVersionStatus {
+    organizationId?: string;
+    name: PluginName;
+    packageName?: string;
+    latestVersion?: string;
+    hasUpdate: boolean;
+}
 export interface IPluginConfiguration<TConfig extends Record<string, any> = Record<string, any>> {
     pluginName: PluginName;
     config: TConfig;