@xpert-ai/plugin-sdk 3.18.4 → 3.18.6

package/model-provider.cjs.js

@@ -154,6 +154,8 @@ function createRuntimeCapability(id, options = {}) {
     });
 }
 const XPERT_RUNTIME_CAPABILITIES_TOKEN = 'XPERT_RUNTIME_CAPABILITIES';
+/** Metadata key under which RuntimeCapabilityProviderExplorer discovers capability providers. */ const RUNTIME_CAPABILITY_PROVIDER = 'XPERT_RUNTIME_CAPABILITY_PROVIDER';
+/** Tags a Nest provider as the platform implementation of a runtime capability. */ const RuntimeCapabilityProvider = (capability)=>common.SetMetadata(RUNTIME_CAPABILITY_PROVIDER, capability);
 class DefaultRuntimeCapabilityRegistry {
     register(key, implementation) {
         this.capabilities.set(runtimeCapabilityId(key), implementation);
@@ -192,6 +194,10 @@ const KnowledgebaseProvisioningRuntimeCapability = createRuntimeCapability('plat
     description: 'Idempotently provision managed platform knowledgebases and connect them to an Agent.'
 });
 
+const KnowledgeGraphRuntimeCapability = createRuntimeCapability('platform.knowledge-graph', {
+    description: 'Publish, inspect, and retract source-owned structured knowledge graphs without model extraction.'
+});
+
 const KnowledgebaseDocumentsRuntimeCapability = createRuntimeCapability('platform.knowledgebase.documents', {
     description: 'Upload, import, create, process, reprocess, inspect, and delete persistent knowledgebase documents.'
 });
@@ -389,12 +395,15 @@ exports.BuiltinToolset = BuiltinToolset;
 exports.DefaultRuntimeCapabilityRegistry = DefaultRuntimeCapabilityRegistry;
 exports.KnowledgeDocumentVisualAssetsRuntimeCapability = KnowledgeDocumentVisualAssetsRuntimeCapability;
 exports.KnowledgeDocumentVisualAssetsRuntimeFactoryCapability = KnowledgeDocumentVisualAssetsRuntimeFactoryCapability;
+exports.KnowledgeGraphRuntimeCapability = KnowledgeGraphRuntimeCapability;
 exports.KnowledgebaseDocumentsRuntimeCapability = KnowledgebaseDocumentsRuntimeCapability;
 exports.KnowledgebaseProvisioningRuntimeCapability = KnowledgebaseProvisioningRuntimeCapability;
 exports.KnowledgebaseRuntimeCapability = KnowledgebaseRuntimeCapability;
 exports.ModelProviderBuiltinToolset = ModelProviderBuiltinToolset;
 exports.ProjectAccessRuntimeCapability = ProjectAccessRuntimeCapability;
 exports.ProjectProvisioningRuntimeCapability = ProjectProvisioningRuntimeCapability;
+exports.RUNTIME_CAPABILITY_PROVIDER = RUNTIME_CAPABILITY_PROVIDER;
+exports.RuntimeCapabilityProvider = RuntimeCapabilityProvider;
 exports.SANDBOX_JOB_ERROR_CODES = SANDBOX_JOB_ERROR_CODES;
 exports.SANDBOX_JOB_PROGRESS_PREFIX = SANDBOX_JOB_PROGRESS_PREFIX;
 exports.SandboxJobRuntimeError = SandboxJobRuntimeError;

package/model-provider.esm.js

@@ -1,6 +1,6 @@
 import { _ as _extends } from './_extends.esm.js';
 import { AiModelTypeEnum } from '@xpert-ai/contracts';
-import { Logger } from '@nestjs/common';
+import { Logger, SetMetadata } from '@nestjs/common';
 import { BaseToolkit, StructuredTool } from '@langchain/core/tools';
 import { z } from 'zod/v3';
 
@@ -152,6 +152,8 @@ function createRuntimeCapability(id, options = {}) {
     });
 }
 const XPERT_RUNTIME_CAPABILITIES_TOKEN = 'XPERT_RUNTIME_CAPABILITIES';
+/** Metadata key under which RuntimeCapabilityProviderExplorer discovers capability providers. */ const RUNTIME_CAPABILITY_PROVIDER = 'XPERT_RUNTIME_CAPABILITY_PROVIDER';
+/** Tags a Nest provider as the platform implementation of a runtime capability. */ const RuntimeCapabilityProvider = (capability)=>SetMetadata(RUNTIME_CAPABILITY_PROVIDER, capability);
 class DefaultRuntimeCapabilityRegistry {
     register(key, implementation) {
         this.capabilities.set(runtimeCapabilityId(key), implementation);
@@ -190,6 +192,10 @@ const KnowledgebaseProvisioningRuntimeCapability = createRuntimeCapability('plat
     description: 'Idempotently provision managed platform knowledgebases and connect them to an Agent.'
 });
 
+const KnowledgeGraphRuntimeCapability = createRuntimeCapability('platform.knowledge-graph', {
+    description: 'Publish, inspect, and retract source-owned structured knowledge graphs without model extraction.'
+});
+
 const KnowledgebaseDocumentsRuntimeCapability = createRuntimeCapability('platform.knowledgebase.documents', {
     description: 'Upload, import, create, process, reprocess, inspect, and delete persistent knowledgebase documents.'
 });
@@ -378,4 +384,4 @@ function normalizeWorkspaceScope(scope) {
     } : {});
 }
 
-export { ActorTokenRuntimeCapability as A, BuiltinToolset as B, DefaultRuntimeCapabilityRegistry as D, KnowledgeDocumentVisualAssetsRuntimeCapability as K, ModelProviderBuiltinToolset as M, ProjectAccessRuntimeCapability as P, SANDBOX_JOB_ERROR_CODES as S, WORKSPACE_FILES_SOURCE as W, XPERT_RUNTIME_CAPABILITIES_TOKEN as X, ActorTokenRuntimeFactoryCapability as a, ArtifactsRuntimeCapability as b, createRuntimeCapability as c, BaseTool as d, BaseToolset as e, KnowledgeDocumentVisualAssetsRuntimeFactoryCapability as f, KnowledgebaseDocumentsRuntimeCapability as g, KnowledgebaseProvisioningRuntimeCapability as h, KnowledgebaseRuntimeCapability as i, ProjectProvisioningRuntimeCapability as j, SANDBOX_JOB_PROGRESS_PREFIX as k, SandboxJobRuntimeError as l, SandboxJobsRuntimeCapability as m, WorkspaceFilesRuntimeCapability as n, isSandboxJobRuntimeError as o };
+export { ActorTokenRuntimeCapability as A, BuiltinToolset as B, DefaultRuntimeCapabilityRegistry as D, KnowledgeDocumentVisualAssetsRuntimeCapability as K, ModelProviderBuiltinToolset as M, ProjectAccessRuntimeCapability as P, RUNTIME_CAPABILITY_PROVIDER as R, SANDBOX_JOB_ERROR_CODES as S, WorkspaceFilesRuntimeCapability as W, XPERT_RUNTIME_CAPABILITIES_TOKEN as X, ActorTokenRuntimeFactoryCapability as a, ArtifactsRuntimeCapability as b, createRuntimeCapability as c, BaseTool as d, BaseToolset as e, KnowledgeDocumentVisualAssetsRuntimeFactoryCapability as f, KnowledgeGraphRuntimeCapability as g, KnowledgebaseDocumentsRuntimeCapability as h, KnowledgebaseProvisioningRuntimeCapability as i, KnowledgebaseRuntimeCapability as j, ProjectProvisioningRuntimeCapability as k, RuntimeCapabilityProvider as l, SANDBOX_JOB_PROGRESS_PREFIX as m, SandboxJobRuntimeError as n, SandboxJobsRuntimeCapability as o, WORKSPACE_FILES_SOURCE as p, isSandboxJobRuntimeError as q };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xpert-ai/plugin-sdk",
-  "version": "3.18.4",
+  "version": "3.18.6",
   "license": "AGPL-3.0",
   "repository": {
     "type": "git",
@@ -11,32 +11,6 @@
   },
   "main": "./index.cjs.js",
   "module": "./index.esm.js",
-  "publishConfig": {
-    "access": "public",
-    "directory": "dist"
-  },
-  "dependencies": {
-    "@langchain/openai": "0.6.9",
-    "@xpert-ai/contracts": "3.18.4",
-    "express": "^4.22.1",
-    "js-tiktoken": "^1.0.21"
-  },
-  "peerDependencies": {
-    "@langchain/core": "*",
-    "@nestjs/common": "*",
-    "@nestjs/core": "*",
-    "@nestjs/cqrs": "*",
-    "ajv": "*",
-    "i18next": "*",
-    "i18next-fs-backend": "*",
-    "json-schema": "*",
-    "jsonwebtoken": "*",
-    "lodash-es": "*",
-    "passport-jwt": "*",
-    "rxjs": "*",
-    "yaml": "*",
-    "zod": "^3.25.0 || ^4.0.0"
-  },
   "exports": {
     "./package.json": "./package.json",
     ".": {
@@ -45,6 +19,12 @@
       "import": "./index.cjs.mjs",
       "default": "./index.cjs.js"
     },
+    "./data-workbench": {
+      "module": "./data-workbench.esm.js",
+      "types": "./data-workbench.d.ts",
+      "import": "./data-workbench.cjs.mjs",
+      "default": "./data-workbench.cjs.js"
+    },
     "./collaboration-client": {
       "module": "./collaboration-client.esm.js",
       "types": "./collaboration-client.d.ts",
@@ -70,5 +50,31 @@
       "default": "./model-provider-http-client.cjs.js"
     }
   },
+  "publishConfig": {
+    "access": "public",
+    "directory": "dist"
+  },
+  "dependencies": {
+    "@langchain/openai": "0.6.9",
+    "@xpert-ai/contracts": "3.18.6",
+    "express": "^4.22.1",
+    "js-tiktoken": "^1.0.21"
+  },
+  "peerDependencies": {
+    "@langchain/core": "*",
+    "@nestjs/common": "*",
+    "@nestjs/core": "*",
+    "@nestjs/cqrs": "*",
+    "ajv": "*",
+    "i18next": "*",
+    "i18next-fs-backend": "*",
+    "json-schema": "*",
+    "jsonwebtoken": "*",
+    "lodash-es": "*",
+    "passport-jwt": "*",
+    "rxjs": "*",
+    "yaml": "*",
+    "zod": "^3.25.0 || ^4.0.0"
+  },
   "types": "./index.d.ts"
 }

package/src/data-workbench.d.ts

@@ -0,0 +1,3 @@
+export * from './lib/data/datasource/workbench';
+export * from './lib/data/datasource/workbench-sql';
+export * from './lib/data/datasource/workbench-adapter';

package/src/lib/ai-model/utils/tokenizer.d.ts

@@ -1,4 +1,10 @@
 import type { TiktokenEncoding } from 'js-tiktoken';
+export declare function countTextTokens(text: string): number;
+/** Token boundaries that also end on complete Unicode characters, in UTF-16 source offsets. */
+export declare function textTokenBoundaries(text: string): {
+    offset: number;
+    tokens: number;
+}[];
 /**
  * Count tokens in text
  * 1) Preferred: js-tiktoken precise encoding

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

@@ -15,6 +15,10 @@ export interface RuntimeCapabilityRegistry {
 /** Read-only capability view accepted by plugin-side consumers. */
 export type RuntimeCapabilityResolver = Pick<RuntimeCapabilityRegistry, 'get'>;
 export declare const XPERT_RUNTIME_CAPABILITIES_TOKEN = "XPERT_RUNTIME_CAPABILITIES";
+/** Metadata key under which RuntimeCapabilityProviderExplorer discovers capability providers. */
+export declare const RUNTIME_CAPABILITY_PROVIDER = "XPERT_RUNTIME_CAPABILITY_PROVIDER";
+/** Tags a Nest provider as the platform implementation of a runtime capability. */
+export declare const RuntimeCapabilityProvider: <T>(capability: RuntimeCapabilityKey<T>) => import("@nestjs/common").CustomDecorator<string>;
 export declare class DefaultRuntimeCapabilityRegistry implements RuntimeCapabilityRegistry {
     private readonly parent?;
     private readonly capabilities;

package/src/lib/data/datasource/index.d.ts

@@ -3,3 +3,6 @@ export * from './strategy.interface';
 export * from './strategy.registry';
 export * from './adapter.strategy';
 export * from './types';
+export * from './workbench';
+export * from './workbench-sql';
+export * from './workbench-adapter';

package/src/lib/data/datasource/types.d.ts

@@ -1,5 +1,6 @@
 import * as _axios from 'axios';
 import { Readable } from 'stream';
+import type { DatabaseWorkbenchAdapter } from './workbench';
 import { IColumnDef, IDataSourceCapabilityQuery, IDSSchema, IDSTable } from '@xpert-ai/contracts';
 export { IColumnDef, IDataSourceCapabilityQuery, IDSSchema, IDSTable } from '@xpert-ai/contracts';
 /**
@@ -48,6 +49,7 @@ export interface QueryResult<T = unknown> {
  * - Connect different types of data sources
  */
 export interface DBQueryRunner {
+    getWorkbenchAdapter?(): DatabaseWorkbenchAdapter;
     type: string;
     name: string;
     syntax: DBSyntaxEnum;

package/src/lib/data/datasource/workbench-adapter.d.ts

@@ -0,0 +1,39 @@
+import type { DatabaseCapabilities, DatabaseEngine, DatabaseImportInput, DatabaseImportReceipt, DatabaseLocation, DatabaseObjectDetail, DatabaseObjectPage, DatabaseObjectRef, DatabaseQueryInput, DatabaseResult, DatabaseValue, DatabaseWorkbenchAdapter } from './workbench';
+export interface WorkbenchTransport {
+    execute(sql: string, parameters: DatabaseValue[], options: {
+        timeoutMs: number;
+        maxRows: number;
+        signal?: AbortSignal;
+    }): Promise<DatabaseResult>;
+    close(): Promise<void>;
+    importRows?(input: DatabaseImportInput, signal?: AbortSignal): Promise<DatabaseImportReceipt>;
+}
+/** One adapter per physical connection. A host session must not share it across users. */
+export declare class SqlDatabaseWorkbenchAdapter implements DatabaseWorkbenchAdapter {
+    readonly engine: DatabaseEngine;
+    private readonly transport;
+    private readonly initial;
+    private version?;
+    private transactionOpen;
+    private busy;
+    private closed;
+    constructor(engine: DatabaseEngine, transport: WorkbenchTransport, initial?: DatabaseLocation);
+    private quote;
+    private ref;
+    private assertLocation;
+    private raw;
+    capabilities(): Promise<DatabaseCapabilities>;
+    locations(): Promise<DatabaseLocation[]>;
+    objects(input: DatabaseLocation & {
+        search?: string;
+        page?: number;
+        pageSize?: number;
+    }): Promise<DatabaseObjectPage>;
+    describe(object: DatabaseObjectRef): Promise<DatabaseObjectDetail>;
+    query(input: DatabaseQueryInput, signal?: AbortSignal): Promise<DatabaseResult>;
+    explain(input: Omit<DatabaseQueryInput, 'mode'>, signal?: AbortSignal): Promise<DatabaseResult>;
+    transaction(action: 'begin' | 'commit' | 'rollback'): Promise<void>;
+    importRows(input: DatabaseImportInput, signal?: AbortSignal): Promise<DatabaseImportReceipt>;
+    cancel(): Promise<void>;
+    close(): Promise<void>;
+}

package/src/lib/data/datasource/workbench-sql.d.ts

@@ -0,0 +1,12 @@
+/** Invariants: comments/literals are lexed, never stripped with a keyword regex.
+ * This guard is defense in depth; the database principal remains an authority boundary.
+ * Unrecognized statements fail closed. Driver multi-statements stay disabled.
+ */
+export interface SqlStatement {
+    sql: string;
+    words: string[];
+    effect: 'read' | 'write' | 'unsupported';
+}
+export declare function splitWorkbenchSql(source: string): SqlStatement[];
+export declare function requireReadStatement(sql: string): string;
+export declare function quoteDatabaseIdentifier(name: string, engine: 'doris' | 'mysql' | 'postgres'): string;

package/src/lib/data/datasource/workbench.d.ts

@@ -0,0 +1,133 @@
+/** Shared wire contract. Credentials and driver objects never cross this boundary. */
+export type DatabaseEngine = 'doris' | 'mysql' | 'postgres';
+export type DatabaseValue = string | number | boolean | null;
+export type DatabaseObjectKind = 'table' | 'view';
+export interface DatabaseLocation {
+    database?: string;
+    schema?: string;
+    /** Doris external catalog; legacy QueryOptions.catalog continues to mean database. */
+    engineCatalog?: string;
+}
+export interface DatabaseObjectRef extends DatabaseLocation {
+    name: string;
+    kind: DatabaseObjectKind;
+}
+export interface DatabaseColumn {
+    id: string;
+    name: string;
+    dataType: string;
+    nullable?: boolean;
+    ordinal?: number;
+    defaultValue?: string | null;
+    comment?: string;
+    sourceColumn?: string;
+    sourceTable?: string;
+}
+export interface DatabaseKey {
+    name: string;
+    kind: 'primary' | 'unique' | 'index' | 'foreign';
+    columns: string[];
+    referencedTable?: DatabaseObjectRef;
+    referencedColumns?: string[];
+}
+export interface DatabaseObjectDetail {
+    object: DatabaseObjectRef;
+    columns: DatabaseColumn[];
+    keys: DatabaseKey[];
+    definition: string;
+    model?: 'unique' | 'duplicate' | 'aggregate';
+    editable: boolean;
+    diagnostics: string[];
+}
+export interface DatabaseCapabilities {
+    engine: DatabaseEngine;
+    version: string;
+    query: boolean;
+    explain: boolean;
+    transactions: boolean;
+    cancel: boolean;
+    import: boolean;
+    writes: boolean;
+    nativeReadOnly: boolean;
+    objectKinds: DatabaseObjectKind[];
+    diagnostics: string[];
+}
+export interface DatabaseResult {
+    columns: DatabaseColumn[];
+    rows: DatabaseValue[][];
+    affectedRows?: number;
+    durationMs: number;
+    hasMore: boolean;
+    truncated: boolean;
+    /** Driver-derived state, never inferred from HTTP success. */
+    outcome: 'succeeded' | 'pending' | 'unknown';
+    diagnostics: string[];
+}
+export interface DatabaseQueryInput extends DatabaseLocation {
+    sql: string;
+    parameters?: DatabaseValue[];
+    mode: 'read' | 'write';
+    limit?: number;
+    offset?: number;
+    timeoutMs?: number;
+}
+export interface DatabaseImportInput extends DatabaseLocation {
+    table: string;
+    columns: string[];
+    rows: DatabaseValue[][];
+    operationId: string;
+}
+export interface DatabaseImportReceipt {
+    outcome: 'succeeded' | 'pending' | 'unknown';
+    loadedRows?: number;
+    filteredRows?: number;
+    label: string;
+    diagnostics: string[];
+}
+export interface DatabaseObjectPage {
+    items: DatabaseObjectRef[];
+    page: number;
+    pageSize: number;
+    hasMore: boolean;
+}
+export interface DatabaseWorkbenchAdapter {
+    readonly engine: DatabaseEngine;
+    capabilities(): Promise<DatabaseCapabilities>;
+    locations(): Promise<DatabaseLocation[]>;
+    objects(input: DatabaseLocation & {
+        search?: string;
+        page?: number;
+        pageSize?: number;
+    }): Promise<DatabaseObjectPage>;
+    describe(object: DatabaseObjectRef): Promise<DatabaseObjectDetail>;
+    query(input: DatabaseQueryInput, signal?: AbortSignal): Promise<DatabaseResult>;
+    explain(input: Omit<DatabaseQueryInput, 'mode'>, signal?: AbortSignal): Promise<DatabaseResult>;
+    transaction(action: 'begin' | 'commit' | 'rollback'): Promise<void>;
+    cancel(): Promise<void>;
+    importRows(input: DatabaseImportInput, signal?: AbortSignal): Promise<DatabaseImportReceipt>;
+    close(): Promise<void>;
+}
+export interface DataSourceActor {
+    tenantId: string;
+    organizationId: string;
+    userId: string;
+}
+export interface DataSourceSummary {
+    id: string;
+    name: string;
+    engine: DatabaseEngine;
+}
+export interface DataSourceWorkbenchScope {
+    location?: DatabaseLocation;
+    actor: DataSourceActor;
+    dataSourceId: string;
+}
+export interface DataSourceRuntimeApi {
+    list(actor: DataSourceActor): Promise<DataSourceSummary[]>;
+    open(input: DataSourceWorkbenchScope): Promise<DatabaseWorkbenchAdapter>;
+}
+export declare const DataSourceRuntimeCapability: Readonly<{
+    id: "platform.datasource.workbench";
+    description: "Scoped database workbench access; credentials remain host-owned.";
+    __type: DataSourceRuntimeApi | undefined;
+}>;

package/src/lib/mcp/resource-template.d.ts

@@ -1,7 +1,6 @@
 import type { McpRequiredContext } from '@xpert-ai/contracts';
-import type { ToolExecutionContext } from '../toolset/tool-execution-context';
 import type { McpCompletionHandler } from './completion';
-import type { McpResourceReadResult } from './resource';
+import type { McpResourceReadResult, ResourceReadContext } from './resource';
 export interface McpResourceTemplateArgument {
     required: boolean;
     description?: string;
@@ -15,7 +14,7 @@ export interface McpResourceTemplateDefinition {
     arguments: Record<string, McpResourceTemplateArgument>;
     requiredContext?: McpRequiredContext[];
     cacheTtlMs?: number;
-    read(arguments_: Record<string, string>, context: ToolExecutionContext): McpResourceReadResult | Promise<McpResourceReadResult>;
+    read(arguments_: Record<string, string>, context: ResourceReadContext): McpResourceReadResult | Promise<McpResourceReadResult>;
     complete?: McpCompletionHandler;
 }
 export declare function defineMcpResourceTemplate(definition: McpResourceTemplateDefinition): Readonly<McpResourceTemplateDefinition>;

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

@@ -1,5 +1,9 @@
 import type { JSONValue, McpRequiredContext } from '@xpert-ai/contracts';
 import type { ToolExecutionContext } from '../toolset/tool-execution-context';
+export interface ResourceReadContext extends ToolExecutionContext {
+    /** Exact URI requested by resources/read, including query parameters. */
+    resourceUri: string;
+}
 export interface McpResourceContent {
     uri: string;
     mimeType?: string;
@@ -18,6 +22,6 @@ export interface McpResourceDefinition {
     mimeType?: string;
     requiredContext?: McpRequiredContext[];
     cacheTtlMs?: number;
-    read(context: ToolExecutionContext): McpResourceReadResult | Promise<McpResourceReadResult>;
+    read(context: ResourceReadContext): McpResourceReadResult | Promise<McpResourceReadResult>;
 }
 export declare function defineMcpResource(definition: McpResourceDefinition): Readonly<McpResourceDefinition>;

package/src/lib/rag/textsplitter/strategy.interface.d.ts

@@ -1,6 +1,19 @@
-import { IDocumentChunkerProvider, KnowledgeStructureEnum } from '@xpert-ai/contracts';
+import { IDocumentChunkerProvider, KnowledgeChunkingDecision, KnowledgeChunkLanguage, KnowledgeChunkLanguageHint, KnowledgeChunkLanguageDecision, KnowledgeStructureEnum } from '@xpert-ai/contracts';
 import { DocumentInterface } from '@langchain/core/documents';
 import { ChunkMetadata } from '../types';
+export interface TextSplitterExecutionContext {
+    /** Public parser-level token cap. Providers must not persist a second copy in their own options. */
+    maxChunkTokens?: number;
+    languageHint?: KnowledgeChunkLanguageHint;
+    /** Resolved once at the execution boundary, shared by all fragments of a document. */
+    resolvedLanguage?: KnowledgeChunkLanguage;
+    resolvedLanguages?: ReadonlyMap<DocumentInterface, KnowledgeChunkLanguage>;
+}
+export interface TextSplitterResult {
+    chunks: DocumentInterface<ChunkMetadata>[];
+    decisions?: KnowledgeChunkingDecision[];
+    languages?: KnowledgeChunkLanguageDecision[];
+}
 /**
  * Split text content into chunks for embedding and retrieval
  */
@@ -17,7 +30,5 @@ export interface ITextSplitterStrategy<TConfig = any> {
     /**
      * Split a text into chunks and pages (if applicable)
      */
-    splitDocuments(documents: DocumentInterface[], options?: TConfig): Promise<{
-        chunks: DocumentInterface<ChunkMetadata>[];
-    }>;
+    splitDocuments(documents: DocumentInterface[], options?: TConfig, context?: TextSplitterExecutionContext): Promise<TextSplitterResult>;
 }

package/src/lib/rag/transformer/strategy.interface.d.ts

@@ -1,9 +1,12 @@
 import { IDocumentProcessorProvider, IIntegration, IKnowledgeDocument } from '@xpert-ai/contracts';
 import { Permissions, XpFileSystem } from '../../core/index';
+import type { WorkspaceFileScope } from '../../runtime/capabilities/workspace-files';
 import { ChunkMetadata } from '../types';
 export type TDocumentTransformerConfig = {
     stage: 'test' | 'prod';
     tempDir?: string;
+    /** Trusted host scope for background transforms using Workspace Files and Sandbox Jobs. */
+    fileScope?: WorkspaceFileScope;
     permissions?: {
         fileSystem?: XpFileSystem;
         integration?: IIntegration;

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

@@ -1,4 +1,5 @@
 export * from './knowledgebase';
+export * from './knowledge-graph';
 export * from './knowledgebase-documents';
 export * from './knowledge-document-visual-assets';
 export * from './actor-token';

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

@@ -0,0 +1,59 @@
+import type { JSONValue } from '@xpert-ai/contracts';
+export type KnowledgeGraphPublicationOwner = {
+    knowledgebaseId: string;
+    documentId: string;
+    xpertId: string;
+    agentKey: string;
+};
+export type KnowledgeGraphPublishedEntity = {
+    /** Local reference within this publication. */
+    id: string;
+    /** Stable, issuer-scoped business identity. Occurrences must include assembly/revision scope. */
+    namespace: string;
+    nodeKey: string;
+    type: string;
+    name: string;
+    description?: string;
+    properties?: Record<string, JSONValue>;
+    chunkIds: string[];
+};
+export type KnowledgeGraphPublishedRelation = {
+    source: string;
+    target: string;
+    type: string;
+    description?: string;
+    properties?: Record<string, JSONValue>;
+    chunkIds: string[];
+};
+export type KnowledgeGraphPublishInput = KnowledgeGraphPublicationOwner & {
+    publicationKey: string;
+    sourceVersion: string;
+    /** Complete source chunk manifest; publication rejects concurrent or incomplete writes. */
+    chunkIds: string[];
+    entities: KnowledgeGraphPublishedEntity[];
+    relations: KnowledgeGraphPublishedRelation[];
+};
+export type KnowledgeGraphPublicationResult = {
+    documentId: string;
+    publicationId: string;
+    publicationKey: string;
+    sourceVersion: string;
+    contentHash: string;
+    status: 'queued' | 'running' | 'success' | 'failed' | 'cancelled';
+    entityCount: number;
+    relationCount: number;
+    unchanged: boolean;
+    error?: string | null;
+};
+export interface KnowledgeGraphApi {
+    /** Atomically accepts a complete, validated snapshot. Indexing is durable and retryable. */
+    publish(input: KnowledgeGraphPublishInput): Promise<KnowledgeGraphPublicationResult>;
+    status(input: KnowledgeGraphPublicationOwner): Promise<KnowledgeGraphPublicationResult | null>;
+    /** Publishes an empty replacement; leaves source chunks and other publishers intact. */
+    retract(input: KnowledgeGraphPublicationOwner & {
+        publicationKey: string;
+        sourceVersion: string;
+        chunkIds: string[];
+    }): Promise<KnowledgeGraphPublicationResult>;
+}
+export declare const KnowledgeGraphRuntimeCapability: import("../../core/runtime-capability").RuntimeCapabilityKey<KnowledgeGraphApi>;

package/src/lib/runtime/capabilities/workspace-files.d.ts

@@ -232,6 +232,8 @@ export type WorkspaceSearchUnderstandingChunksInput = WorkspaceFileScope & {
  * understanding files in Xpert workspace Volumes.
  */
 export interface WorkspaceFilesApi {
+    /** Host-bound storage identity for restoring the same scope in durable jobs. */
+    readonly scope?: Readonly<WorkspaceFileScope>;
     /** Upload raw bytes into an explicitly scoped workspace Volume. */
     uploadBuffer(input: WorkspaceUploadBufferInput): Promise<WorkspaceFile>;
     /** Register an existing workspace file with the platform understanding pipeline. */

package/src/lib/tool-provider/component.d.ts

@@ -0,0 +1,2 @@
+import { type IPluginComponentDefinition } from '@xpert-ai/contracts';
+export declare function runtimeToolProviderComponent(provider: object): IPluginComponentDefinition;

package/src/lib/tool-provider/decorators.d.ts

@@ -2,7 +2,7 @@ import type { XpertToolOptions, XpertToolProviderOptions } from './types';
 export declare const XPERT_TOOL_PROVIDER = "XPERT_TOOL_PROVIDER";
 export declare const XPERT_TOOL_PROVIDER_METADATA = "XPERT_TOOL_PROVIDER_METADATA";
 export declare const XPERT_TOOL_METHOD_METADATA = "XPERT_TOOL_METHOD_METADATA";
-/** Marks one injectable business service as a reusable Tool provider and one native MCP service. */
+/** Marks one injectable business service as a shared Tool, Resource and Prompt provider. */
 export declare const XpertToolProvider: (options: XpertToolProviderOptions) => ClassDecorator;
 /** Exposes one business method through an Agent Middleware, native MCP, or both. */
 export declare const XpertTool: (options: XpertToolOptions) => MethodDecorator;

package/src/lib/tool-provider/index.d.ts

@@ -6,3 +6,6 @@ export * from './adapters';
 export * from './coordinator';
 export { XPERT_TOOL_RESULT_FORMAT_VERSION } from './tool-result';
 export { prepareToolResult, type XpertPreparedToolResult, type XpertOutputDiagnostic } from './prepared-result';
+export { runtimeToolProviderComponent } from './component';
+export { XpertResource, XpertResourceTemplate, XpertPrompt, resolveXpertMcpExtensions } from './mcp-methods';
+export type { XpertResourceOptions, XpertResourceTemplateOptions, XpertPromptOptions, XpertDecoratedMcpDescriptor } from './mcp-methods';

package/src/lib/tool-provider/mcp-methods.d.ts

@@ -0,0 +1,39 @@
+import type { McpResourceDefinition } from '../mcp/resource';
+import type { McpResourceTemplateDefinition } from '../mcp/resource-template';
+import type { McpPromptDefinition } from '../mcp/prompt';
+import type { XpertToolProviderDescriptor } from './types';
+export type XpertResourceOptions = Omit<McpResourceDefinition, 'read'>;
+export type XpertResourceTemplateOptions = Omit<McpResourceTemplateDefinition, 'read' | 'complete'> & {
+    /** Optional instance method implementing McpCompletionHandler. */
+    completionMethod?: string;
+};
+export type XpertPromptOptions = Omit<McpPromptDefinition, 'get' | 'complete'> & {
+    completionMethod?: string;
+};
+type McpMethod = {
+    kind: 'resource';
+    options: Readonly<XpertResourceOptions>;
+} | {
+    kind: 'resource-template';
+    options: Readonly<XpertResourceTemplateOptions>;
+} | {
+    kind: 'prompt';
+    options: Readonly<XpertPromptOptions>;
+};
+export type XpertDecoratedMcpDescriptor = McpMethod & {
+    methodName: string;
+};
+/** The decorated method receives ResourceReadContext and returns McpResourceReadResult. */
+export declare const XpertResource: (options: XpertResourceOptions) => MethodDecorator;
+/** The decorated method receives URI arguments and ResourceReadContext. */
+export declare const XpertResourceTemplate: (options: XpertResourceTemplateOptions) => MethodDecorator;
+/** The decorated method receives prompt arguments and ToolExecutionContext. */
+export declare const XpertPrompt: (options: XpertPromptOptions) => MethodDecorator;
+export declare function describeXpertMcpMethods(instance: object): readonly XpertDecoratedMcpDescriptor[];
+/** One catalog for runtime publication and fingerprinting; legacy declarations remain supported. */
+export declare function resolveXpertMcpExtensions(instance: object, descriptor?: XpertToolProviderDescriptor): {
+    resources: McpResourceDefinition[];
+    resourceTemplates: McpResourceTemplateDefinition[];
+    prompts: McpPromptDefinition[];
+};
+export {};

package/src/lib/tool-provider/provider-methods.d.ts

@@ -0,0 +1,5 @@
+/** Child overrides hide parent declarations, including undecorated overrides and accessors. */
+export declare function collectProviderMethods(instance: object): {
+    methodName: string;
+    method: object;
+}[];

package/src/lib/tool-provider/tool-result.d.ts

@@ -2,7 +2,7 @@ import type { ZodTypeAny } from 'zod/v3';
 import type { XpertToolContent, XpertToolResult } from '../toolset/tool-result';
 export declare const XPERT_TOOL_RESULT_FORMAT_VERSION = 1;
 /** Validate the envelope separately so binary content never enters the business DTO. */
-export declare function parseDecoratedToolResult(value: unknown, outputSchema: ZodTypeAny): Promise<XpertToolResult>;
+export declare function parseDecoratedToolResult(value: unknown, outputSchema?: ZodTypeAny): Promise<XpertToolResult>;
 export declare function agentContent(content: XpertToolContent[] | undefined): ({
     type: string;
     image_url: {