@xpert-ai/plugin-sdk 3.18.7 → 3.20.0

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

@@ -0,0 +1,36 @@
+import type { RealtimeModelEvent, RealtimeToolResult, RealtimeTaskContext } from '@xpert-ai/contracts';
+import type { JSONSchema7 } from 'json-schema';
+export interface RealtimeSessionOptions {
+    voice: string;
+    instructions: string;
+    tools: {
+        name: string;
+        description: string;
+        parameters: JSONSchema7;
+    }[];
+}
+/** The host owns networking, credentials, backpressure and authorization. */
+export interface RealtimeProtocolSink {
+    send(event: object): void;
+    emit(event: RealtimeModelEvent): void;
+}
+export interface RealtimeProtocol {
+    start(): void;
+    receive(event: unknown): void;
+    appendAudio(audio: Uint8Array): void;
+    setMuted(muted: boolean): void;
+    cancelResponse(): void;
+    submitToolResults(results: RealtimeToolResult[]): void;
+    /** Synchronize task facts without requesting speech or emitting a user transcript. */
+    updateTaskContext?(tasks: RealtimeTaskContext[]): void;
+    notify(text: string): boolean;
+    close(): void;
+}
+/** Server-only connection descriptor. Never serialize this object to clients. */
+export interface RealtimeModelConnection {
+    url: string;
+    headers: {
+        [header: string]: string;
+    };
+    createProtocol(options: RealtimeSessionOptions, sink: RealtimeProtocolSink): RealtimeProtocol;
+}

package/src/lib/ai-model/token-usage.d.ts

@@ -0,0 +1,13 @@
+import type { TTokenUsage } from '@xpert-ai/contracts';
+export interface ResolvedTokenUsage {
+    usage: TTokenUsage;
+    source: 'provider' | 'estimated' | 'legacy' | 'unavailable';
+}
+/** Select a whole candidate. Never fill missing actual counts using estimates. */
+export declare function resolveTokenUsageCandidates(input: {
+    canonical?: Partial<TTokenUsage> | null;
+    actual?: Partial<TTokenUsage> | null;
+    estimated?: Partial<TTokenUsage> | null;
+    legacyTotal?: number;
+}): ResolvedTokenUsage;
+export declare function normalizeTokenUsage(candidate?: Partial<TTokenUsage> | null): TTokenUsage | null;

package/src/lib/assistant-capability/index.d.ts

@@ -0,0 +1,42 @@
+import { DiscoveryService, Reflector } from '@nestjs/core';
+import type { I18nObject, LanguagesEnum, ModelFeature, TXpertTeamDraft, TXpertTemplate } from '@xpert-ai/contracts';
+import { BaseStrategyRegistry } from '../strategy';
+export interface AssistantCapabilityContext {
+    template: TXpertTemplate;
+    draft: TXpertTeamDraft;
+    language: LanguagesEnum;
+    /** Provided again at installation; providers must not silently select a fallback. */
+    sandboxProviders?: {
+        type: string;
+    }[];
+}
+export interface AssistantCapabilityApplyContext extends AssistantCapabilityContext {
+    loadTemplate: (id: string) => Promise<TXpertTemplate>;
+}
+/** Optional capabilities default to off. IDs are stable machine-readable keys. */
+export interface IAssistantCapabilityProvider {
+    readonly key: string;
+    readonly label: string | I18nObject;
+    readonly description: string | I18nObject;
+    readonly requiredModelFeatures?: ModelFeature[];
+    /** Explicitly opt into the blank Assistant creation flow. */
+    readonly availableForBlankAssistant?: boolean;
+    /** Distribution extensions to specific templates, without changing their portable source. */
+    readonly templates?: {
+        templateId: string;
+        required: boolean;
+    }[];
+    /** Detect a capability already owned by the base workflow; it cannot be removed by a new overlay. */
+    isEnabled?(draft: TXpertTeamDraft): boolean;
+    check(context: AssistantCapabilityContext): Promise<{
+        available: boolean;
+        reason?: string;
+    }>;
+    /** Deterministic draft composition; never creates external resources. */
+    apply(context: AssistantCapabilityApplyContext): Promise<void>;
+}
+export declare const ASSISTANT_CAPABILITY_PROVIDER = "ASSISTANT_CAPABILITY_PROVIDER";
+export declare const AssistantCapabilityProvider: (key: string) => <TFunction extends Function, Y>(target: TFunction | object, propertyKey?: string | symbol, descriptor?: TypedPropertyDescriptor<Y>) => void;
+export declare class AssistantCapabilityProviderRegistry extends BaseStrategyRegistry<IAssistantCapabilityProvider> {
+    constructor(discovery: DiscoveryService, reflector: Reflector);
+}

package/src/lib/connector/runtime-capability.d.ts

@@ -3,6 +3,8 @@ import type { ConnectorRuntimeApi } from './strategy.interface';
 export declare const ConnectorRuntimeCapability: import("../core").RuntimeCapabilityKey<ConnectorRuntimeApi>;
 /** No binding or provider grants means no connector access. */
 export type ConnectorRuntimeScope = RuntimeIdentityScope & {
+    /** Host-validated Agent Plugin dependencies may use their workspace binding in an authorized project. */
+    allowWorkspaceBindingsInProject?: boolean;
     /** Host-selected bindings, including IDs pinned by enabled graph Connector nodes. */
     connectorBindingIds?: string[] | null;
     /** Providers configured by enabled graph Connector nodes without a pinned ID. */

package/src/lib/connector/strategy.interface.d.ts

@@ -72,6 +72,7 @@ export type ConnectorPermissionDeclaration = {
     required?: boolean;
 };
 export type ConnectorDefinitionBase = {
+    runtimeUsage?: 'middleware' | 'credential';
     provider: string;
     label: RuntimeI18nText;
     description?: RuntimeI18nText;
@@ -139,6 +140,10 @@ export type ConnectorBindingCreateRequest = {
     authorizationMode: ConnectorAuthorizationMode;
 };
 export type ConnectorRuntimeOption = {
+    scope?: ConnectorScope;
+    canManage?: boolean;
+    managementUrl?: string;
+    runtimeUsage?: 'middleware' | 'credential';
     bindingId: string;
     provider: string;
     authorizationMode: ConnectorAuthorizationMode;
@@ -152,6 +157,9 @@ export type ConnectorRuntimeOption = {
     profile?: ConnectorProfile | null;
 };
 export type ConnectorRuntimeOptions = {
+    workspaceScope?: ConnectorScope;
+    canManageWorkspace?: boolean;
+    managementUrl?: string;
     scope: ConnectorScope;
     items: ConnectorRuntimeOption[];
 };

package/src/lib/core/context/request-context.d.ts

@@ -28,6 +28,11 @@ export declare class RequestContext {
     static isTenantScope(): boolean;
     static isOrganizationScope(): boolean;
     static requireOrganizationScope(): string;
+    /**
+     * Check the authenticated principal's enabled role permissions, matching the
+     * server RequestContext. Authentication guards resolve JWTs, API keys and
+     * ChatKit client secrets before this check; the bearer is not always a JWT.
+     */
     static hasPermissions(findPermissions: Array<PermissionsEnum | string>, throwError?: boolean): boolean;
     static hasAnyPermission(findPermissions: PermissionsEnum[], throwError?: boolean): boolean;
     static currentToken(throwError?: boolean): any;
@@ -46,6 +51,7 @@ export declare class RequestContext {
      * @returns True if any of the required roles are found, otherwise false.
      */
     static hasRoles(roles: RolesEnum[], throwError?: boolean): boolean;
+    private static currentPermissions;
 }
 /**
  * One process-wide context store shared by source, built, and dynamically loaded

package/src/lib/core/strategy-bus.d.ts

@@ -11,9 +11,6 @@ export type StrategyBusEvent<S = any> = {
     cause?: 'refresh' | 'uninstall';
 };
 export declare class StrategyBus {
-    private readonly removalGuards;
-    registerRemovalGuard(guard: (scopeKey: string, pluginNames: readonly string[]) => Promise<void>): () => void;
-    assertCanRemove(scopeKey: string, pluginNames: readonly string[]): Promise<void>;
     private readonly subject;
     readonly events$: import("rxjs").Observable<StrategyBusEvent<any>>;
     upsert<S>(strategyType: string, entry: StrategyEntry<S>): void;

package/src/lib/evolution/runtime-capability.d.ts

@@ -1,4 +1,5 @@
-import type { EvolutionRuntimeApi, EvolutionChangeRuntimeApi } from '@xpert-ai/contracts';
+import type { EvolutionRuntimeApi, EvolutionChangeRuntimeApi, EvolutionBaselineRuntimeApi } from '@xpert-ai/contracts';
 export declare const EVOLUTION_RUNTIME_SERVICE_TOKEN = "XPERT_EVOLUTION_RUNTIME_SERVICE";
+export declare const EvolutionBaselineRuntimeCapability: import("../core").RuntimeCapabilityKey<EvolutionBaselineRuntimeApi>;
 export declare const EvolutionRuntimeCapability: import("../core").RuntimeCapabilityKey<EvolutionRuntimeApi>;
 export declare const EvolutionChangeRuntimeCapability: import("../core").RuntimeCapabilityKey<EvolutionChangeRuntimeApi>;

package/src/lib/integration/strategy.interface.d.ts

@@ -40,4 +40,26 @@ export interface IntegrationStrategy<T = unknown> {
     validateConfig?(config: T, integration?: IIntegration<T>): Promise<void | IntegrationTestResult>;
     getIdentityBootstrap?(integration: IIntegration<T>): Promise<IntegrationIdentityBootstrap>;
     exchangeIdentity?(integration: IIntegration<T>, grant: IntegrationIdentityGrant): Promise<IntegrationExternalIdentity>;
+    beginQrAuthorization?(): Promise<IntegrationQrAuthorization>;
+    pollQrAuthorization?(deviceCode: string): Promise<IntegrationQrAuthorizationResult>;
+    /** Stable provider account identity used to reuse integrations within the same tenant and organization. */
+    getQrAuthorizationIdentity?(options: unknown): string | null;
 }
+/** Server-only setup contract. Never forward deviceCode or options to the browser. */
+export interface IntegrationQrAuthorization {
+    deviceCode: string;
+    authorizationUrl: string;
+    expiresInSeconds: number;
+    intervalSeconds: number;
+}
+export type IntegrationQrAuthorizationResult = 
+/** Additive provider backoff, persisted by the host for the rest of the session. */
+{
+    status: 'waiting';
+    intervalIncrementSeconds?: number;
+} | {
+    status: 'expired' | 'denied' | 'failed';
+} | {
+    status: 'authorized';
+    options: Record<string, unknown>;
+};

package/src/lib/mcp/app.d.ts

@@ -1,3 +1,4 @@
+import type { I18nObject, TMcpAppRefresh } from '@xpert-ai/contracts';
 export interface McpAppCsp {
     connectDomains?: string[];
     resourceDomains?: string[];
@@ -11,9 +12,21 @@ export interface McpAppPermissions {
 export interface McpAppDefinition {
     key: string;
     entry: string;
-    title?: string;
+    title?: string | I18nObject;
     description?: string;
+    /** Read-only tool called by the host Refresh action; never replays the entry tool. */
+    refresh?: TMcpAppRefresh;
     csp?: McpAppCsp;
     permissions?: McpAppPermissions;
 }
+/** App exposure is independent of publishing a tool on an external MCP server. */
+export interface MiddlewareMcpApps {
+    definitions: readonly McpAppDefinition[];
+    tools: Readonly<Record<string, {
+        resourceKey?: string;
+        visibility: readonly ('model' | 'app')[];
+        /** Trusted plugin policy; omitted writes use the host approval flow. */
+        approval?: 'required' | 'none';
+    }>>;
+}
 export declare function defineMcpApp(definition: McpAppDefinition): Readonly<McpAppDefinition>;

package/src/lib/project-task/index.d.ts

@@ -0,0 +1,66 @@
+import { DiscoveryService, Reflector } from '@nestjs/core';
+import type { ProjectTaskGraph, ProjectTaskGraphChange, ProjectTaskExecutionTarget, ProjectTaskTypeDefinition, TXpertProjectTaskStatus } from '@xpert-ai/contracts';
+import { BaseStrategyRegistry } from '../strategy';
+import type { ProjectAccessActor } from '../runtime/capabilities/project-access';
+export interface ProjectTaskContext {
+    actor: ProjectAccessActor;
+    projectId: string;
+}
+export interface ProjectTaskProjection {
+    key: string;
+    title: string;
+    status: TXpertProjectTaskStatus;
+    /** Completion percentage (0–100), independent of status. Omit to preserve; null clears it. */
+    progress?: number | null;
+    kind: 'task' | 'summary' | 'milestone';
+    /** Registered business type; omitted values preserve legacy persisted types. Null explicitly clears it. */
+    taskType?: string | null;
+    parentKey?: string;
+    predecessorKeys: string[];
+    diagnostic?: string;
+    assigneeXpertId?: string;
+    executions: Array<{
+        key: string;
+        attempt: number;
+        agentExecutionId?: string;
+        conversationId?: string;
+        threadId?: string;
+        xpertId?: string;
+        agentKey?: string;
+        status: 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled';
+        startedAt?: string;
+        completedAt?: string;
+        error?: string;
+        outputSummary?: string;
+    }>;
+}
+/** Domain facts remain durable in the provider; projection can be replayed after interruption. */
+export interface ProjectTaskSnapshot {
+    revision: string;
+    tasks: ProjectTaskProjection[];
+}
+export interface IProjectTaskProvider {
+    readonly key: string;
+    /** Presentation declarations belong to this provider and never contain executable icon code. */
+    readonly taskTypes?: readonly ProjectTaskTypeDefinition[];
+    /** Return null when the project is not owned by this provider. Always scope domain reads. */
+    snapshot(context: ProjectTaskContext): Promise<ProjectTaskSnapshot | null>;
+    /** Called after projection commits; retries must be idempotent. Never start work here. */
+    linked?(context: ProjectTaskContext, links: Array<{
+        sourceKey: string;
+        taskId: string;
+    }>): Promise<void>;
+}
+export type { ProjectTaskIconName, ProjectTaskTypeDefinition, ProjectTaskTypePresentation } from '@xpert-ai/contracts';
+export declare const PROJECT_TASK_PROVIDER = "PROJECT_TASK_PROVIDER";
+export declare const ProjectTaskProvider: (key: string) => <TFunction extends Function, Y>(target: TFunction | object, propertyKey?: string | symbol, descriptor?: TypedPropertyDescriptor<Y>) => void;
+export declare class ProjectTaskProviderRegistry extends BaseStrategyRegistry<IProjectTaskProvider> {
+    constructor(discovery: DiscoveryService, reflector: Reflector);
+}
+/** ORM-independent project task management; actor values come from trusted server context. */
+export interface ProjectTasksApi {
+    graph(context: ProjectTaskContext): Promise<ProjectTaskGraph>;
+    change(context: ProjectTaskContext, input: ProjectTaskGraphChange): Promise<ProjectTaskGraph>;
+    resolveExecution(context: ProjectTaskContext, taskExecutionId: string): Promise<ProjectTaskExecutionTarget>;
+}
+export declare const ProjectTasksRuntimeCapability: import("../core/runtime-capability").RuntimeCapabilityKey<ProjectTasksApi>;

package/src/lib/project-type/index.d.ts

@@ -0,0 +1,71 @@
+import { DiscoveryService, Reflector } from '@nestjs/core';
+import type { XpertProjectTypeRef, ConversationResourceCard } from '@xpert-ai/contracts';
+import { BaseStrategyRegistry } from '../strategy';
+export type { XpertProjectTypeRef, ConversationResourceCard };
+export interface ProjectTypeContext extends XpertProjectTypeRef {
+    tenantId: string;
+    organizationId?: string | null;
+    userId: string;
+    xpertId: string;
+    purpose: 'provision' | 'open' | 'create';
+}
+export interface ProjectTypeBinding {
+    /** Persisted business Assistant used when opening a Project from the global list. */
+    xpertId?: string;
+    viewKey: string;
+    selectionId?: string;
+}
+/**
+ * ORM-independent write access to the host's current creation transaction.
+ * The host owns commit/rollback; this object is valid only during the awaited
+ * creation hook. Entities must be instances of registered plugin entity classes.
+ */
+export interface ProjectCreationTransaction {
+    /** Save an entity and return its persisted values without committing the transaction. */
+    save<T extends object>(entity: T): Promise<T>;
+}
+/** Host-owned identity and transaction for an empty conversation's first send. */
+export interface ConversationProjectCreation {
+    projectId: string;
+    conversationId: string;
+    workspaceId: string;
+    name: string;
+    /** Present only for a human-confirmed setup; the application validates its own configuration. */
+    confirmation?: {
+        id: string;
+        configuration: object;
+    };
+    /**
+     * Persist only application records through this writer. The host creates the
+     * platform Project and binds the conversation in the same transaction. Do not
+     * call provisioning, start agents, or perform external I/O from this hook.
+     */
+    transaction: ProjectCreationTransaction;
+}
+/** Host calls this provider before claiming or synchronizing an entity Project. */
+export interface IProjectTypeProvider {
+    /** Must verify the persisted domain-to-project link and actor before returning. */
+    resolve(context: ProjectTypeContext, projectId: string): Promise<ProjectTypeBinding & {
+        name: string;
+        status: 'active' | 'archived';
+    }>;
+    /** Opens the application's governed creation workflow. */
+    createEntry(context: ProjectTypeContext): Promise<ProjectTypeBinding>;
+    /**
+     * Optional opt-in to first-send creation. Persist the business entity and its
+     * link to input.projectId atomically using input.transaction, then return its entry
+     * and desired name. Exceptions roll back the whole bootstrap. The host checks
+     * permissions and serializes retries with a conversation row lock first.
+     */
+    createForConversation?(context: ProjectTypeContext, input: ConversationProjectCreation): Promise<ProjectTypeBinding & {
+        name: string;
+        status: 'active';
+        resourceCards?: ConversationResourceCard[];
+    }>;
+}
+export declare const PROJECT_TYPE_PROVIDER = "PROJECT_TYPE_PROVIDER";
+/** Register the stable provider key used by entity-backed App project type declarations. */
+export declare const ProjectTypeProvider: (key: string) => <TFunction extends Function, Y>(target: TFunction | object, propertyKey?: string | symbol, descriptor?: TypedPropertyDescriptor<Y>) => void;
+export declare class ProjectTypeProviderRegistry extends BaseStrategyRegistry<IProjectTypeProvider> {
+    constructor(discovery: DiscoveryService, reflector: Reflector);
+}

package/src/lib/resource-card-provider/index.d.ts

@@ -0,0 +1,3 @@
+export * from './types';
+export * from './provider.decorator';
+export * from './provider.registry';

package/src/lib/resource-card-provider/provider.decorator.d.ts

@@ -0,0 +1,4 @@
+import type { ResourceCardType } from './types';
+export declare const RESOURCE_CARD_PROVIDER = "RESOURCE_CARD_PROVIDER";
+/** Register exact resource types whose message cards opt in to live refresh. */
+export declare const ResourceCardProvider: (...resources: ResourceCardType[]) => <TFunction extends Function, Y>(target: TFunction | object, propertyKey?: string | symbol, descriptor?: TypedPropertyDescriptor<Y>) => void;

package/src/lib/resource-card-provider/provider.registry.d.ts

@@ -0,0 +1,14 @@
+import { type OnModuleDestroy } from '@nestjs/common';
+import { DiscoveryService, Reflector } from '@nestjs/core';
+import { BaseStrategyRegistry } from '../strategy';
+import type { IResourceCardProvider, ResourceCardType } from './types';
+export declare class ResourceCardProviderRegistry extends BaseStrategyRegistry<IResourceCardProvider> implements OnModuleDestroy {
+    private readonly resourceLogger;
+    private subscription?;
+    constructor(discovery: DiscoveryService, reflector: Reflector);
+    onModuleInit(): void;
+    onModuleDestroy(): void;
+    remove(scopeKey: string, pluginName: string): void;
+    upsert(instance: unknown): void;
+    find(resource: ResourceCardType, organizationId?: string): IResourceCardProvider | undefined;
+}

package/src/lib/resource-card-provider/types.d.ts

@@ -0,0 +1,36 @@
+import type { ConversationResourceCard } from '@xpert-ai/contracts';
+export interface ResourceCardType {
+    namespace: string;
+    type: string;
+}
+export interface ResourceCardContext {
+    tenantId: string;
+    organizationId?: string | null;
+    userId: string;
+    conversationId: string;
+    threadId: string;
+    projectId?: string | null;
+    /** Stop external reads when the host's observation deadline expires. */
+    signal: AbortSignal;
+}
+export interface ResourceCardReadRequest {
+    /** Opaque correlation key. Echo it; never choose another message binding. */
+    key: string;
+    card: ConversationResourceCard;
+    messageId: string;
+    executionId?: string;
+}
+export type ResourceCardResolution = {
+    key: string;
+} & ({
+    status: 'resolved';
+    card: ConversationResourceCard;
+} | {
+    status: 'unavailable';
+    reason: 'forbidden' | 'not_found';
+});
+/** Optional live presentation of committed resources; never starts work or changes business state. */
+export interface IResourceCardProvider {
+    /** Recheck resource access for the host-supplied actor and return one result per request. */
+    resolveMany(context: ResourceCardContext, requests: readonly ResourceCardReadRequest[]): Promise<readonly ResourceCardResolution[]>;
+}

package/src/lib/resource-card.d.ts

@@ -0,0 +1,6 @@
+import type { RunnableConfig } from '@langchain/core/runnables';
+import { type ConversationResourceCard } from '@xpert-ai/contracts';
+export { createResourceCardContent, parseResourceCard, resourceCardId } from '@xpert-ai/contracts';
+export type { ConversationResourceCard, ResourceCardContent, ResourceCardField, ResourceCardFile, ResourceCardFileReference, ResourceCardImage, ResourceCardOpenTarget, ResourceCardScalar, TMessageContentResourceCard } from '@xpert-ai/contracts';
+/** Call after the business mutation commits. A display failure must not retry that mutation. */
+export declare function emitResourceCard(card: ConversationResourceCard, config?: RunnableConfig): Promise<void>;

package/src/lib/runtime/capabilities/index.d.ts

@@ -8,3 +8,4 @@ export * from './workspace-files';
 export * from './sandbox-jobs';
 export * from './project-provisioning';
 export * from './project-access';
+export * from './tool-images';

package/src/lib/runtime/capabilities/knowledge-graph.d.ts

@@ -46,6 +46,9 @@ export type KnowledgeGraphPublicationResult = {
     error?: string | null;
 };
 export interface KnowledgeGraphApi {
+    /** Bounded, source-version-checked reads; the host verifies the current Agent's KB connection. */
+    queryEntities?(input: KnowledgeGraphEntityQuery): Promise<KnowledgeGraphReadResult>;
+    readNeighborhood?(input: KnowledgeGraphNeighborhoodQuery): Promise<KnowledgeGraphReadResult>;
     /** Atomically accepts a complete, validated snapshot. Indexing is durable and retryable. */
     publish(input: KnowledgeGraphPublishInput): Promise<KnowledgeGraphPublicationResult>;
     status(input: KnowledgeGraphPublicationOwner): Promise<KnowledgeGraphPublicationResult | null>;
@@ -56,4 +59,60 @@ export interface KnowledgeGraphApi {
         chunkIds: string[];
     }): Promise<KnowledgeGraphPublicationResult>;
 }
+export type KnowledgeGraphReadScope = {
+    knowledgebaseId: string;
+    xpertId: string;
+    agentKey: string;
+    sources: {
+        documentId: string;
+        sourceVersion: string;
+    }[];
+};
+export type KnowledgeGraphEntityQuery = KnowledgeGraphReadScope & {
+    entityIds?: string[];
+    namespace?: string;
+    nodeKey?: string;
+    type?: string;
+    search?: string;
+    /** Opaque continuation bound to this query and its source versions. */
+    cursor?: string;
+    limit?: number;
+};
+export type KnowledgeGraphNeighborhoodQuery = KnowledgeGraphReadScope & {
+    entityIds: string[];
+    relationTypes: string[];
+    depth?: number;
+    direction?: 'incoming' | 'outgoing' | 'both';
+    /** Continuation is supported for one-hop reads only. */
+    cursor?: string;
+    limit?: number;
+};
+export type KnowledgeGraphReadEntity = {
+    id: string;
+    name: string;
+    type: string;
+    properties: Record<string, JSONValue>;
+    documentId: string;
+    documentIds?: string[];
+};
+export type KnowledgeGraphReadRelation = {
+    id: string;
+    source: string;
+    target: string;
+    type: string;
+    properties: Record<string, JSONValue>;
+    documentId: string;
+    documentIds?: string[];
+};
+export type KnowledgeGraphReadResult = {
+    entities: KnowledgeGraphReadEntity[];
+    relations: KnowledgeGraphReadRelation[];
+    truncated: boolean;
+    nextCursor?: string;
+    sources: {
+        documentId: string;
+        sourceVersion: string;
+        status: KnowledgeGraphPublicationResult['status'] | 'unavailable' | 'stale';
+    }[];
+};
 export declare const KnowledgeGraphRuntimeCapability: import("../../core/runtime-capability").RuntimeCapabilityKey<KnowledgeGraphApi>;

package/src/lib/runtime/capabilities/knowledgebase-documents.d.ts

@@ -219,6 +219,25 @@ export type KnowledgebaseReadTextResult = {
         version: number;
     }>;
 };
+/** Pre-split conversion evidence. Index chunk size and embedding models do not affect this view. */
+export type KnowledgebaseReadSourceInput = KnowledgebaseReadTextInput & {
+    /** Pin all pages to the revision returned by the first page. */
+    revision?: string;
+};
+export type KnowledgebaseReadSourceResult = {
+    knowledgebaseId: string;
+    documentId: string;
+    /** Content identity of the complete parsed source, independent of index/document versions. */
+    revision: string;
+    sourceHash?: string | null;
+    total: number;
+    /** Complete converter blocks in source order, never vector fragments or overlapping windows. */
+    chunks: Array<{
+        id: string;
+        text: string;
+        page?: number;
+    }>;
+};
 export type KnowledgebaseProcessingOptionsInput = {
     knowledgebaseId: string;
     fileName: string;
@@ -249,6 +268,8 @@ export type KnowledgebaseProcessingOptionsResult = {
 export interface KnowledgebaseDocumentsApi {
     getProcessingOptions(input: KnowledgebaseProcessingOptionsInput): Promise<KnowledgebaseProcessingOptionsResult>;
     readText(input: KnowledgebaseReadTextInput): Promise<KnowledgebaseReadTextResult>;
+    /** Missing/stale conversion snapshots fail explicitly; this never falls back to indexed chunks. */
+    readSource(input: KnowledgebaseReadSourceInput): Promise<KnowledgebaseReadSourceResult>;
     listDocuments(input: KnowledgebaseListDocumentsInput): Promise<KnowledgebaseListDocumentsResult>;
     createFolder(input: KnowledgebaseCreateFolderInput): Promise<KnowledgebaseCreateFolderResult>;
     moveDocument(input: KnowledgebaseMoveDocumentInput): Promise<KnowledgebaseMoveDocumentResult>;

package/src/lib/runtime/capabilities/knowledgebase.d.ts

@@ -129,14 +129,19 @@ export type KnowledgebaseProvisioningSpec = {
     score?: number;
     metadataSchema?: KnowledgebaseProvisioningMetadataField[];
     incrementalSyncEnabled?: boolean;
+    /** Set the graph switch without replacing existing graph retrieval or extraction settings. */
+    graphRag?: {
+        enabled: boolean;
+    };
 };
 export type KnowledgebaseEnsureInput = {
     workspaceId: string;
     namespace: string;
     /**
-     * Reuse the most recently updated accessible knowledgebase embedding-model configuration when
-     * creating a managed set. This keeps one-click provisioning usable without exposing provider
-     * credentials to plugins. Provisioning fails explicitly when no configured model is available.
+     * Fill missing embedding bindings from the current user's available Copilot provider catalog,
+     * falling back to the most recently updated ordinary knowledgebase in this workspace.
+     * Existing bindings are preserved. No provider credentials are exposed to plugins.
+     * Provisioning fails explicitly when a missing binding cannot be resolved.
      */
     inheritEmbeddingModel?: boolean;
     knowledgebases: KnowledgebaseProvisioningSpec[];

package/src/lib/runtime/capabilities/project-access.d.ts

@@ -1,10 +1,11 @@
+import type { XpertProjectClassification } from '@xpert-ai/contracts';
 /** Trusted server actor. View providers derive this from host context; jobs persist that actor. */
 export interface ProjectAccessActor {
     tenantId: string;
     organizationId?: string | null;
     userId: string;
 }
-export interface ProjectHumanAccess {
+export interface ProjectHumanAccess extends XpertProjectClassification {
     projectId: string;
     role: 'owner' | 'manager' | 'editor' | 'member';
     canManage: boolean;

package/src/lib/runtime/capabilities/project-provisioning.d.ts

@@ -1,3 +1,4 @@
+import type { XpertProjectTypeRef } from '@xpert-ai/contracts';
 /** Lifecycle states that plugin-managed Projects may synchronize to the platform. */
 export type ProjectProvisioningStatus = 'active' | 'archived';
 /** Portable identity of one required, direct External Assistant binding. */
@@ -8,6 +9,8 @@ export type ProjectExternalAssistantExpectation = {
 };
 /** Stable identity and desired state for an idempotently provisioned Chat Project. */
 export type ProjectEnsureInput = {
+    /** Registered application type. Omission preserves legacy unclassified callers. */
+    projectType?: XpertProjectTypeRef;
     /** Caller-generated id reused across retries to prevent duplicate Projects. */
     projectId: string;
     /** @deprecated Projects no longer belong to a Workspace. Accepted only for legacy callers. */
@@ -35,6 +38,16 @@ export type ProjectEnsureResult = {
 };
 /** Host API exposed to plugins that own one-to-one business Project mappings. */
 export interface ProjectProvisioningApi {
+    /** App-only confirmation of a pending conversation's first Project; never moves an existing binding. */
+    confirmConversation?(input: {
+        conversationId: string;
+        xpertId: string;
+        confirmationId: string;
+        name: string;
+        configuration: object;
+    }): Promise<{
+        projectId: string;
+    }>;
     /** Create or reconcile a Chat Project without changing its caller-supplied id. */
     ensure(input: ProjectEnsureInput): Promise<ProjectEnsureResult>;
     /** Owner-only physical deletion of an archived plugin-bound Project and its workspace. */

package/src/lib/runtime/capabilities/tool-images.d.ts

@@ -0,0 +1,24 @@
+import type { BaseMessage } from '@langchain/core/messages';
+import type { ToolOutputImageAttachment, ToolOutputPresentation } from '@xpert-ai/chatkit-types';
+import type { ModelRequirements } from '../../agent/middleware/model-requirements';
+export type { ToolOutputImageAttachment, ToolOutputPresentation } from '@xpert-ai/chatkit-types';
+export type ToolImageModelInput = {
+    messages: BaseMessage[];
+    requirements?: ModelRequirements;
+};
+/** Images stay in immutable Artifacts; tool results and graph checkpoints contain references only. */
+export interface ToolImagesApi {
+    /** Host identity, conversation and Workspace scope are bound to the current execution. */
+    save(input: {
+        buffer: Buffer;
+        mimeType: ToolOutputImageAttachment['mimeType'];
+        title: string;
+    }): Promise<ToolOutputPresentation>;
+    /**
+     * Project the current complete tool round into one outbound model request. Names identify tools
+     * whose successful result must contain an image presentation; error results remain text.
+     * Never persist the returned messages. Merge requirements into the request with mergeModelRequirements.
+     */
+    prepareModelInput(messages: BaseMessage[], toolNames: readonly string[]): Promise<ToolImageModelInput>;
+}
+export declare const ToolImagesRuntimeCapability: import("../../core/runtime-capability").RuntimeCapabilityKey<ToolImagesApi>;