@metad/contracts 3.8.4 → 3.9.0-beta.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metad/contracts",
-  "version": "3.8.4",
+  "version": "3.9.0-beta.0",
   "license": "AGPL-3.0",
   "repository": {
     "type": "git",
@@ -10,12 +10,12 @@
     "url": "https://github.com/xpert-ai/xpert/issues"
   },
   "scripts": {
-    "docs": "yarn typedoc --out ./.docs"
+    "docs": "pnpm typedoc --out ./.docs"
   },
   "module": "./index.esm.js",
   "main": "./index.cjs.js",
   "dependencies": {
-    "@a2ui/lit": "^0.8.1",
-    "@xpert-ai/chatkit-types": "^0.0.12"
-  }
-}
+    "@xpert-ai/chatkit-types": "^0.0.17"
+  },
+  "types": "./index.d.ts"
+}

package/src/agent/graph.d.ts

@@ -1,10 +1,10 @@
 import { BaseMessage } from '@langchain/core/messages';
 import { RunnableConfig } from '@langchain/core/runnables';
-import { TMessageContentComplex } from '@xpert-ai/chatkit-types';
+import type { TMessageContentComplex } from '@xpert-ai/chatkit-types';
 import { Subscriber } from 'rxjs';
 import { ICopilotModel } from '../ai/copilot-model.model';
 import { TWorkflowVarGroup } from '../ai/xpert-workflow.model';
-import { TXpertGraph } from '../ai/xpert.model';
+import { TXpertGraph, TXpertTeamNode } from '../ai/xpert.model';
 import { IXpertAgent } from '../ai/xpert-agent.model';
 /**
  * @deprecated can use getCurrentTaskInput instead?
@@ -31,6 +31,9 @@ export type TMessageChannel = {
     summary?: string;
     error?: string | null;
 };
+export interface IBackendProtocol {
+    workingDirectory: string;
+}
 export type TSandboxConfigurable = {
     /**
      * Resolved sandbox provider type used for this backend acquisition.
@@ -78,6 +81,12 @@ export type TAgentRunnableConfigurable = {
     agentKey: string;
     xpertName?: string;
     toolName?: string;
+    /**
+     * Additional runtime context for middleware/tool execution.
+     */
+    context?: Record<string, unknown> & {
+        env?: Record<string, unknown>;
+    };
     copilotModel?: ICopilotModel;
     subscriber: Subscriber<any>;
     /**
@@ -148,14 +157,6 @@ export declare function getAgentVarGroup(key: string, graph: TXpertGraph): TWork
  */
 export declare function getSwarmPartners(graph: TXpertGraph, agentKey: string, partners: string[], leaderKey?: string): string[];
 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;
@@ -163,29 +164,19 @@ export declare function getWorkflowTriggers(graph: TXpertGraph, from: string): (
     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;
-    }))[];
+    nodes?: TXpertTeamNode[];
     connections?: import("../ai/xpert.model").TXpertTeamConnection[];
     expanded?: boolean;
 }) | (import("../ai/xpert.model").TXpertTeamNodeBase & {
     type: "workflow";
 } & {
     entity: import("../ai/xpert-workflow.model").IWorkflowNode;
+}) | (import("../ai/xpert.model").TXpertTeamNodeBase & {
+    type: "agent";
+} & {
+    entity: IXpertAgent;
+}) | (import("../ai/xpert.model").TXpertTeamNodeBase & {
+    type: "knowledge";
+} & {
+    entity: import("..").IKnowledgebase;
 }))[];

package/src/agent/token.d.ts

@@ -3,23 +3,6 @@ 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/assistant-binding.model.d.ts

@@ -0,0 +1,74 @@
+import { IBasePerTenantAndOrganizationEntityModel } from '../base-entity.model';
+import { IUser } from '../user.model';
+export declare enum AssistantCode {
+    CHAT_COMMON = "chat_common",
+    XPERT_SHARED = "xpert_shared",
+    CHATBI = "chatbi",
+    CLAWXPERT = "clawxpert"
+}
+export declare enum AssistantBindingScope {
+    TENANT = "tenant",
+    ORGANIZATION = "organization",
+    USER = "user"
+}
+export declare enum AssistantBindingSourceScope {
+    NONE = "none",
+    TENANT = "tenant",
+    ORGANIZATION = "organization"
+}
+export type AssistantManagement = 'system' | 'user';
+export interface IAssistantBindingToolsetPreference {
+    toolsetId?: string | null;
+    toolsetName: string;
+    disabledTools: string[];
+}
+export interface IAssistantBindingMiddlewarePreference {
+    provider: string;
+    disabledTools: string[];
+}
+export interface IAssistantBindingSkillPreference {
+    workspaceId: string;
+    disabledSkillIds: string[];
+}
+export interface IAssistantBindingToolPreferences {
+    version: 1;
+    toolsets?: Record<string, IAssistantBindingToolsetPreference>;
+    middlewares?: Record<string, IAssistantBindingMiddlewarePreference>;
+    skills?: Record<string, IAssistantBindingSkillPreference>;
+}
+export interface IAssistantBinding extends IBasePerTenantAndOrganizationEntityModel {
+    code: AssistantCode;
+    scope: AssistantBindingScope;
+    assistantId?: string | null;
+    enabled?: boolean | null;
+    userId?: string | null;
+    user?: IUser;
+    preferences?: IAssistantBindingUserPreference[];
+}
+export interface IAssistantBindingUserPreference extends IBasePerTenantAndOrganizationEntityModel {
+    assistantBindingId: string;
+    assistantBinding?: IAssistantBinding;
+    userId?: string | null;
+    user?: IUser;
+    soul?: string | null;
+    profile?: string | null;
+    toolPreferences?: IAssistantBindingToolPreferences | null;
+}
+export interface IResolvedAssistantBinding extends IAssistantBinding {
+    sourceScope: AssistantBindingSourceScope;
+}
+export interface IAssistantBindingUpsertInput {
+    code: AssistantCode;
+    scope: AssistantBindingScope;
+    assistantId?: string | null;
+    enabled?: boolean;
+}
+export interface IAssistantBindingUserPreferenceUpsertInput {
+    scope: AssistantBindingScope;
+    soul?: string | null;
+    profile?: string | null;
+    toolPreferences?: IAssistantBindingToolPreferences | null;
+}
+export declare function getAssistantManagement(code: AssistantCode): AssistantManagement;
+export declare function isUserManagedAssistant(code: AssistantCode): boolean;
+export declare function isSystemManagedAssistant(code: AssistantCode): boolean;

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

@@ -0,0 +1,8 @@
+import type { TChatEventMessage } from '@xpert-ai/chatkit-types';
+export declare const CHAT_EVENT_TYPE_THREAD_CONTEXT_USAGE: "thread_context_usage";
+export declare const CHAT_EVENT_TYPE_CONVERSATION_TITLE_SUMMARY: "conversation_title_summary";
+export type TConversationTitleSummaryEvent = TChatEventMessage & {
+    id?: string;
+    type: typeof CHAT_EVENT_TYPE_CONVERSATION_TITLE_SUMMARY;
+};
+export declare function createConversationTitleSummaryEvent(event: Omit<TConversationTitleSummaryEvent, 'type'>): TConversationTitleSummaryEvent;

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

@@ -1,11 +1,11 @@
 import { MessageType } from '@langchain/core/messages';
+import type { TChatMessageStep, TMessageContent, TMessageContentReasoning } from '@xpert-ai/chatkit-types';
 import { IBasePerTenantAndOrganizationEntityModel } from '../base-entity.model';
 import { IChatConversation } from './chat.model';
 import { LongTermMemoryTypeEnum } from './xpert.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';
 export type TSummaryJob = Record<LongTermMemoryTypeEnum, {
     jobId: number | string;
     status: string;

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

@@ -2,5 +2,9 @@ export declare enum AiFeatureEnum {
     FEATURE_COPILOT = "FEATURE_COPILOT",
     FEATURE_COPILOT_KNOWLEDGEBASE = "FEATURE_COPILOT_KNOWLEDGEBASE",
     FEATURE_COPILOT_CHAT = "FEATURE_COPILOT_CHAT",
-    FEATURE_XPERT = "FEATURE_XPERT"
+    FEATURE_XPERT = "FEATURE_XPERT",
+    FEATURE_XPERT_CHATBI = "FEATURE_XPERT_CHATBI",
+    FEATURE_XPERT_CLAWXPERT = "FEATURE_XPERT_CLAWXPERT",
+    FEATURE_XPERT_CODEXPERT = "FEATURE_XPERT_CODEXPERT",
+    FEATURE_XPERT_DEEP_RESEARCH = "FEATURE_XPERT_DEEP_RESEARCH"
 }

package/src/ai/index.d.ts

@@ -1,7 +1,44 @@
-export * from '@xpert-ai/chatkit-types';
+export declare const STATE_VARIABLE_HUMAN = "human";
+export declare enum ChatMessageTypeEnum {
+    MESSAGE = "message",
+    EVENT = "event"
+}
+export declare enum ChatMessageEventTypeEnum {
+    ON_CONVERSATION_START = "on_conversation_start",
+    ON_CONVERSATION_END = "on_conversation_end",
+    ON_MESSAGE_START = "on_message_start",
+    ON_MESSAGE_END = "on_message_end",
+    ON_TOOL_START = "on_tool_start",
+    ON_TOOL_END = "on_tool_end",
+    ON_TOOL_ERROR = "on_tool_error",
+    ON_TOOL_MESSAGE = "on_tool_message",
+    ON_AGENT_START = "on_agent_start",
+    ON_AGENT_END = "on_agent_end",
+    ON_RETRIEVER_START = "on_retriever_start",
+    ON_RETRIEVER_END = "on_retriever_end",
+    ON_RETRIEVER_ERROR = "on_retriever_error",
+    ON_INTERRUPT = "on_interrupt",
+    ON_ERROR = "on_error",
+    ON_CHAT_EVENT = "on_chat_event",
+    ON_CLIENT_EFFECT = "on_client_effect"
+}
+export declare enum ChatMessageStepCategory {
+    List = "list",
+    WebSearch = "web_search",
+    Files = "files",
+    File = "file",
+    Program = "program",
+    Iframe = "iframe",
+    Memory = "memory",
+    Tasks = "tasks",
+    Knowledges = "knowledges"
+}
+export type * from '@xpert-ai/chatkit-types';
 export type { TChatRequest } from './xpert-chat.model';
+export * from './assistant-binding.model';
 export * from './ai-model.model';
 export * from './ai.model';
+export * from './chat-event.model';
 export * from './chat.model';
 export * from './chat-message.model';
 export * from './chat-message-feedback.model';

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

@@ -1,4 +1,4 @@
-import { TMessageContent, TMessageContentComplex } from '@xpert-ai/chatkit-types';
+import type { TMessageContent, TMessageContentComplex } from '@xpert-ai/chatkit-types';
 import { CopilotChatMessage } from './chat-message.model';
 export type TMessageJoinHint = 'none' | 'space' | 'line' | 'paragraph';
 export type TMessageAppendContext = {
@@ -48,5 +48,11 @@ export declare function createMessageAppendContextTracker(initial?: TMessageAppe
  */
 export declare function appendMessageContent(aiMessage: CopilotChatMessage, incoming: string | TMessageContentComplex, context?: TAppendMessageContentOptions): void;
 export declare function appendMessagePlainText(accumulator: string, incoming: string | TMessageContentComplex, context?: TMessageAppendContext): string;
+/**
+ * Creates a display-only content view that reassembles text chunks belonging to
+ * the same stream id. This preserves markdown continuity without changing the
+ * underlying stored/streamed message structure.
+ */
+export declare function mergeMessageContentForDisplay(content: TMessageContent | TMessageContentComplex | null | undefined): TMessageContentComplex[] | null;
 export declare function stringifyMessageContent(content: TMessageContent | TMessageContentComplex): string;
 export declare function filterMessageText(content: TMessageContent | TMessageContentComplex): string;

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

@@ -4,12 +4,28 @@ import { JsonSchemaObjectType } from "./types";
 import { IWorkflowNode, WorkflowNodeTypeEnum } from "./xpert-workflow.model";
 import { IBasePerWorkspaceEntityModel } from "./xpert-workspace.model";
 export type SkillId = string;
+export interface ISkillRepositoryIndexStats {
+    comments?: number;
+    downloads?: number;
+    installsAllTime?: number;
+    installsCurrent?: number;
+    stars?: number;
+    versions?: number;
+}
+export interface ISkillRepositoryIndexPublisher {
+    handle?: string;
+    displayName?: string;
+    name?: string;
+    image?: string;
+    kind?: string;
+}
 export interface SkillMetadata {
     name: string;
     displayName?: I18nObject;
     version: string;
     summary?: I18nObject;
     description?: I18nObject;
+    icon?: IconDefinition;
     tags?: string[];
     author?: {
         name: string;
@@ -59,15 +75,15 @@ export interface TSkillPackage {
         owners: string[];
         readers: string[];
         writers: string[];
-        policies?: any;
+        policies?: Record<string, unknown>;
     };
     signatures?: string[];
-    provenance?: any;
+    provenance?: Record<string, unknown>;
 }
 /**
- * 表示一个仓库（如 anthropics/skills）
+ * Represents a repository (e.g. anthropics/skills)
  */
-export interface ISkillRepository<O = Record<string, any>, C = Record<string, any>> extends IBasePerTenantAndOrganizationEntityModel {
+export interface ISkillRepository<O = Record<string, unknown>, C = Record<string, unknown>> extends IBasePerTenantAndOrganizationEntityModel {
     name: string;
     provider: string;
     /**
@@ -78,11 +94,11 @@ export interface ISkillRepository<O = Record<string, any>, C = Record<string, an
      * Options configured using the strategy's configSchema
      */
     options?: O;
-    lastSyncAt?: string;
+    lastSyncAt?: Date;
     deletedAt?: Date;
 }
 /**
- * 仓库同步扫描得到的技能索引（每个技能目录一条）
+ * Skill index produced by repository sync scan (one per skill directory)
  */
 export interface ISkillRepositoryIndex extends IBasePerTenantAndOrganizationEntityModel {
     repositoryId: string;
@@ -90,35 +106,38 @@ export interface ISkillRepositoryIndex extends IBasePerTenantAndOrganizationEnti
     skillPath: string;
     skillId: string;
     name?: string;
+    link?: string;
+    publisher?: ISkillRepositoryIndexPublisher;
     description?: string;
     license?: string;
     tags?: string[];
     version?: string;
-    resources?: any[];
+    stats?: ISkillRepositoryIndexStats;
+    resources?: Array<Record<string, unknown>>;
     deletedAt?: Date;
 }
 /**
- * 安装后的技能包主记录（skill.yaml）
+ * Installed skill package record (skill.yaml)
  */
 export interface ISkillPackage extends IBasePerWorkspaceEntityModel, TSkillPackage {
     skillIndexId?: SkillId;
     skillIndex?: ISkillRepositoryIndex;
-    name?: any;
+    name?: string;
     visibility: 'private' | 'team' | 'tenant';
     packagePath?: string;
 }
 /**
- * 技能的版本（1个 Skill 多版本共存）
+ * Skill version (multiple versions can coexist per skill)
  */
 export interface ISkillVersion extends IBasePerWorkspaceEntityModel {
     packageId: string;
     version: string;
-    metadata: any;
-    instructions: any;
+    metadata: SkillMetadata;
+    instructions: TSkillPackage['instructions'];
     installedAt?: string;
 }
 /**
- * 技能资源文件（scripts/templates/assets）记录
+ * Skill resource file record (scripts/templates/assets)
  */
 export interface ISkillResource extends IBasePerWorkspaceEntityModel {
     versionId: string;
@@ -126,10 +145,10 @@ export interface ISkillResource extends IBasePerWorkspaceEntityModel {
     type: 'script' | 'template' | 'asset' | 'doc';
     hash?: string;
     size?: number;
-    meta?: any;
+    meta?: Record<string, unknown>;
 }
 /**
- * 租户/组织/团队/用户安装行为记录
+ * Tenant/organization/team/user installation record
  */
 export interface ISkillInstallation extends IBasePerTenantAndOrganizationEntityModel {
     versionId: string;
@@ -139,7 +158,7 @@ export interface ISkillInstallation extends IBasePerTenantAndOrganizationEntityM
     status: 'pending' | 'installed' | 'failed';
 }
 /**
- * 技能安装过程中详细日志
+ * Detailed logs during skill installation
  */
 export interface ISkillInstallLog extends IBasePerTenantAndOrganizationEntityModel {
     installationId: string;
@@ -148,14 +167,14 @@ export interface ISkillInstallLog extends IBasePerTenantAndOrganizationEntityMod
     timestamp: string;
 }
 /**
- * 技能运行期审计日志
+ * Runtime audit log for skills
  */
 export interface ISkillAuditLog extends IBasePerTenantAndOrganizationEntityModel {
     skillId: string;
     versionId: string;
     sessionId: string;
     eventType: string;
-    metadata: any;
+    metadata: Record<string, unknown>;
 }
 export type TSkillSourceMeta = {
     /**

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

@@ -27,6 +27,15 @@ export type TXpertExecution = {
     xpertId?: string;
     parentId?: string;
 };
+export type TXpertAgentExecutionCheckpoint = {
+    threadId: string;
+    checkpointNs: string;
+    checkpointId: string;
+    parentCheckpointId?: string | null;
+    createdAt?: string | null;
+    metadata?: Record<string, unknown> | null;
+    isCurrent?: boolean;
+};
 /**
  * Corresponds to the run in the [Agent Protocol](https://github.com/langchain-ai/agent-protocol).
  */

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

@@ -1,4 +1,5 @@
-import { STATE_VARIABLE_HUMAN, TChatRequestHuman, TInterruptCommand } from '@xpert-ai/chatkit-types';
+import type { TChatRequestHuman, TInterruptCommand } from '@xpert-ai/chatkit-types';
+import { STATE_VARIABLE_HUMAN } from '@xpert-ai/chatkit-types';
 export type TXpertChatState = {
     [STATE_VARIABLE_HUMAN]?: TChatRequestHuman;
 } & Record<string, any>;
@@ -40,6 +41,7 @@ export type TXpertChatRetryRequest = {
     conversationId: string;
     source: TXpertChatSource;
     environmentId?: string;
+    checkpointId?: string;
 };
 export type TChatRequest = TXpertChatSendRequest | TXpertChatResumeRequest | TXpertChatRetryRequest;
 export type TXpertAgentChatRunRequest = {

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

@@ -16,7 +16,12 @@ export interface IXpertWorkspace extends IBasePerTenantAndOrganizationEntityMode
     environments?: IEnvironment[];
     members?: IUser[];
 }
-export type TXpertWorkspaceSettings = {};
+export type TXpertWorkspaceSettings = {
+    system?: {
+        kind?: 'org-default' | 'user-default';
+        userId?: string;
+    };
+};
 export type TXpertWorkspaceStatus = 'active' | 'deprecated' | 'archived';
 export interface IBasePerWorkspaceEntityModel extends IBasePerTenantAndOrganizationEntityModel {
     workspaceId?: string;

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

@@ -3,6 +3,7 @@ import { RunnableToolLike } from '@langchain/core/runnables';
 import { StructuredToolInterface } from '@langchain/core/tools';
 import { ITag } from '../tag-entity.model';
 import { IUser, LanguagesEnum } from '../user.model';
+import { IUserGroup } from '../user-group.model';
 import { ICopilotModel, TCopilotModel } from './copilot-model.model';
 import { IKnowledgebase, TKBRecallParams } from './knowledgebase.model';
 import { ChecklistItem, I18nObject, IPoint, ISize, TAvatar } from '../types';
@@ -159,9 +160,9 @@ export type TXpert = {
     knowledgebases?: IKnowledgebase[];
     toolsets?: IXpertToolset[];
     /**
-     * The corresponding person in charge, whose has the authority to execute this digital expert
+     * User groups that are allowed to use this published digital expert.
      */
-    managers?: IUser[];
+    userGroups?: IUserGroup[];
     /**
      * Integrations for this xpert
      */
@@ -180,6 +181,11 @@ export interface IXpert extends IBasePerWorkspaceEntityModel, TXpert {
     knowledgebase?: IKnowledgebase;
 }
 export type TXpertOptions = {
+    bootstrap?: {
+        source: 'template';
+        templateKey: string;
+        workspaceKind: 'org-default';
+    };
     knowledge?: Record<string, {
         position?: IPoint;
         size?: ISize;
@@ -482,6 +488,10 @@ export type TChatOptions = {
      * Specify additional tools
      */
     tools?: (StructuredToolInterface | RunnableToolLike)[];
+    /**
+     * Per-request runtime context forwarded to agent middleware/tools.
+     */
+    context?: Record<string, unknown>;
 };
 /**
  * Knowledgebase retrieval settings

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

@@ -1,6 +1,6 @@
 import { IPoint } from '../types';
 import { IXpertAgent } from './xpert-agent.model';
-import { IXpert, TXpertTeamNode } from './xpert.model';
+import { IXpert, TXpertTeamConnection, TXpertTeamDraft, TXpertTeamNode } from './xpert.model';
 export declare function omitXpertRelations(xpert: Partial<IXpert>): {
     environmentId?: string;
     workspaceId?: string;
@@ -11,10 +11,10 @@ export declare function omitXpertRelations(xpert: Partial<IXpert>): {
     organization?: import("..").IOrganization;
     tenantId?: string;
     tenant?: import("..").ITenant;
-    id?: string;
-    createdById?: string;
+    id?: import("../types").ID;
+    createdById?: import("../types").ID;
     createdBy?: import("..").IUser;
-    updatedById?: string;
+    updatedById?: import("../types").ID;
     updatedBy?: import("..").IUser;
     createdAt?: Date;
     updatedAt?: Date;
@@ -59,7 +59,7 @@ export declare function createXpertGraph(xpert: IXpert, position: IPoint): {
         width: number;
         height: number;
     };
-    connections: import("./xpert.model").TXpertTeamConnection[];
+    connections: TXpertTeamConnection[];
 };
 export declare function locateNodes(nodes: TXpertTeamNode[], position: IPoint): {
     size: {
@@ -82,3 +82,6 @@ export declare function createXpertNodes(xpert: IXpert, position: IPoint): {
     };
 };
 export declare function createAgentConnections(agent: IXpertAgent, collaborators: IXpert[]): any[];
+export declare function replaceAgentInDraft(draft: TXpertTeamDraft, sourceKey: string, agent: Partial<IXpertAgent>, options?: {
+    requireNode?: boolean;
+}): TXpertTeamDraft;

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

@@ -1,10 +1,68 @@
 import { IBasePerTenantAndOrganizationEntityModel } from './base-entity.model';
+import { IUser } from './user.model';
+/**
+ * Represents an API key used for authentication and authorization.
+ */
 export interface IApiKey extends IBasePerTenantAndOrganizationEntityModel {
     token: string;
     name?: string;
-    type?: string;
+    /**
+     * Stable binding kind for resolving the technical principal behind this key.
+     */
+    type?: ApiKeyBindingType;
+    /**
+     * Stable binding target id/code. Examples:
+     * - assistant => xpertId
+     * - integration => integrationId
+     * - client => clientCode
+     */
     entityId?: string;
     validUntil?: Date;
     expired?: boolean;
     lastUsedAt?: Date;
+    /**
+     * Explicit technical principal bound to this apiKey.
+     * When set, it takes precedence over type/entityId resolution.
+     */
+    userId?: string;
+    user?: IUser;
+}
+/**
+ * Optional request header used by third-party callers to explicitly set the
+ * business user represented by the current request context.
+ */
+export declare const API_PRINCIPAL_USER_ID_HEADER = "x-principal-user-id";
+/**
+ * Stable binding kinds used to resolve long-lived technical principals.
+ */
+export declare enum ApiKeyBindingType {
+    ASSISTANT = "assistant",
+    INTEGRATION = "integration",
+    CLIENT = "client",
+    /**
+     * @deprecated legacy type, do not use for new keys. Will be resolved as assistant for backward compatibility.
+     */
+    KNOWLEDGEBASE = "knowledgebase"
+}
+export type ApiPrincipalType = 'api_key' | 'client_secret';
+export interface IApiPrincipal extends IUser {
+    apiKey: IApiKey;
+    principalType: ApiPrincipalType;
+    /**
+     * Resource owner / key creator. Used for audit and ownership metadata.
+     */
+    ownerUserId?: string | null;
+    /**
+     * Technical principal resolved from apiKey.userId or stable type/entityId binding.
+     */
+    apiKeyUserId?: string | null;
+    /**
+     * Explicit business user id requested by the caller via x-principal-user-id.
+     */
+    requestedUserId?: string | null;
+    /**
+     * Original organization context requested by the caller before api-key
+     * authentication normalized the request into tenant scope.
+     */
+    requestedOrganizationId?: string | null;
 }