@xpert-ai/plugin-sdk 3.16.1 → 3.17.0

package/src/lib/ai-model/managed-aigc-job.d.ts

@@ -0,0 +1,37 @@
+import { type ModelUsageModality, type ModelUsageOperation, type ModelUsagePricingDimensions, type ModelUsagePricingSnapshot } from '@xpert-ai/contracts';
+import type { AgentMiddlewareModelProviderConnection } from '../agent/middleware/runtime';
+import type { ManagedQueueJob } from '../managed-queue';
+import type { AIGCModelObservation, AsyncAIGCModelClient } from './types/aigc';
+export type AsyncAIGCManagedJobPhase = 'queued' | 'submitted' | 'processing' | 'succeeded' | 'failed';
+/** Durable provider checkpoint stored inside the Managed Queue payload. */
+export type AsyncAIGCManagedJobPayload<TInput, TResult> = {
+    requestId: string;
+    model: string;
+    toolName: string;
+    modality: ModelUsageModality;
+    operation: ModelUsageOperation;
+    pricingDimensions?: ModelUsagePricingDimensions;
+    input: TInput;
+    phase: AsyncAIGCManagedJobPhase;
+    startedAt: string;
+    providerRequestId?: string;
+    providerState?: AIGCModelObservation['state'];
+    pricingSnapshot?: ModelUsagePricingSnapshot;
+    usageReported?: boolean;
+    result?: TResult;
+    errorCode?: string;
+};
+export type ProcessAsyncAIGCManagedJobOptions<TInput, TData, TResult> = {
+    client: AsyncAIGCModelClient<TInput, TData>;
+    provider: AgentMiddlewareModelProviderConnection;
+    pollIntervalMs?: number;
+    sleep?: (milliseconds: number) => Promise<void>;
+    finalize(data: TData): Promise<TResult>;
+    failureMessage?(data: TData, observation: AIGCModelObservation): string;
+};
+/**
+ * Runs one asynchronous provider request inside a Managed Queue job.
+ * Provider acceptance, terminal usage reporting, and result delivery are checkpointed so a queue retry resumes
+ * from the last durable provider request instead of intentionally submitting a second request.
+ */
+export declare function processAsyncAIGCManagedJob<TInput, TData, TResult>(job: ManagedQueueJob<AsyncAIGCManagedJobPayload<TInput, TResult>>, options: ProcessAsyncAIGCManagedJobOptions<TInput, TData, TResult>): Promise<TResult>;

package/src/lib/ai-model/model-provider-http-client.d.ts

@@ -0,0 +1,51 @@
+export type ModelProviderHttpClientOptions = {
+    provider: string;
+    baseUrl: string;
+    defaultHeaders?: Readonly<Record<string, string>>;
+    fetchImpl?: typeof fetch;
+    requestTimeoutMs?: number;
+};
+export type ModelProviderBufferOptions = {
+    maxBytes?: number;
+    maxBytesError?: string;
+    defaultMimeType?: string;
+};
+export type ModelProviderHttpResponse = {
+    ok: boolean;
+    status: number;
+    statusText: string;
+    headers: {
+        get(name: string): string | null;
+    };
+    text(): Promise<string>;
+    json(): Promise<unknown>;
+    arrayBuffer(): Promise<ArrayBuffer>;
+};
+export declare class ModelProviderHttpError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+/**
+ * Shared HTTP transport for model Provider adapters.
+ *
+ * Provider-specific authentication headers are supplied at construction time;
+ * response parsing, task semantics, and download URL policy stay in each adapter.
+ */
+export declare abstract class ModelProviderHttpClient {
+    protected readonly baseUrl: string;
+    private readonly provider;
+    private readonly defaultHeaders;
+    private readonly fetchImpl;
+    private readonly requestTimeoutMs?;
+    protected constructor(options: ModelProviderHttpClientOptions);
+    protected requestJson<T>(pathOrUrl: string, init: RequestInit, parse: (value: unknown) => T): Promise<T>;
+    protected fetchResponse(input: string | URL, init?: RequestInit, timeoutMs?: number): Promise<ModelProviderHttpResponse>;
+    protected readBufferResponse(response: ModelProviderHttpResponse, options?: ModelProviderBufferOptions): Promise<{
+        buffer: Buffer;
+        mimeType?: string;
+    }>;
+    protected createHttpError(response: ModelProviderHttpResponse): Promise<Error>;
+    protected createTimeoutError(timeoutMs: number): Error;
+    private resolveRequestUrl;
+    private mergeHeaders;
+}

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

@@ -1,2 +1,14 @@
-import { PriceConfig, PriceInfo, PriceType } from '@xpert-ai/contracts';
+import { type ModelUsagePricingSnapshot, type ModelUsageMetric, type ModelUsagePriceRule, type ModelUsagePricingConfig, type ModelUsagePricingContext, type ModelUsagePricingStatus, PriceConfig, PriceInfo, PriceType } from '@xpert-ai/contracts';
 export declare function calculateModelPrice(pricing: PriceConfig, priceType: PriceType, tokens: number, inputTokens?: number): PriceInfo;
+export type ModelUsageChargeCalculation = {
+    pricingStatus: ModelUsagePricingStatus;
+    pricingRule?: ModelUsagePriceRule;
+    quantity: number;
+    unitSize?: number;
+    unitPrice?: number;
+    currency?: string;
+    amount?: number;
+};
+export declare function resolveModelUsagePricingSnapshot(pricing: PriceConfig | ModelUsagePricingConfig | undefined, context: ModelUsagePricingContext): ModelUsagePricingSnapshot;
+export declare function calculateModelUsageCharge(snapshot: ModelUsagePricingSnapshot | null | undefined, metric: ModelUsageMetric): ModelUsageChargeCalculation;
+export declare function isModelUsagePricingConfig(pricing: PriceConfig | ModelUsagePricingConfig | undefined): pricing is ModelUsagePricingConfig;

package/src/lib/ai-model/types/aigc.d.ts

@@ -0,0 +1,39 @@
+import type { ICopilotModel, ModelUsageMetric, ModelUsageOperation, ModelUsagePricingDimensions } from '@xpert-ai/contracts';
+import { AIModel } from '../ai-model';
+import type { TChatModelOptions } from './model';
+export type AIGCModelState = 'submitted' | 'processing' | 'succeeded' | 'failed' | 'cancelled';
+export type AIGCModelObservation = {
+    state: AIGCModelState;
+    metrics?: ModelUsageMetric[];
+    errorCode?: string;
+};
+export interface AIGCModelClient<TInput = unknown, TOutput = unknown> {
+    invoke(input: TInput): Promise<AIGCModelResult<TOutput>>;
+}
+export type AIGCModelResult<TData> = {
+    data: TData;
+    observation: AIGCModelObservation;
+};
+export type AsyncAIGCModelSubmission<TData> = {
+    providerRequestId: string;
+    data: TData;
+};
+export type AsyncAIGCModelQueryContext = {
+    operation?: ModelUsageOperation;
+    pricingDimensions?: ModelUsagePricingDimensions;
+};
+export type AsyncAIGCModelQueryResult<TData> = {
+    data: TData;
+    observation: AIGCModelObservation;
+};
+/** Provider adapter contract for APIs that submit and observe an asynchronous generation task. */
+export interface AsyncAIGCModelClient<TInput = unknown, TData = unknown> {
+    submit(input: TInput): Promise<AsyncAIGCModelSubmission<TData>>;
+    query(providerRequestId: string, context?: AsyncAIGCModelQueryContext): Promise<AsyncAIGCModelQueryResult<TData>>;
+}
+export declare abstract class ImageGenerationModel extends AIModel {
+    abstract getAIGCModel(copilotModel: ICopilotModel, options?: TChatModelOptions): AIGCModelClient;
+}
+export declare abstract class VideoGenerationModel extends AIModel {
+    abstract getAIGCModel(copilotModel: ICopilotModel, options?: TChatModelOptions): AsyncAIGCModelClient;
+}

package/src/lib/ai-model/types/index.d.ts

@@ -4,6 +4,7 @@ export * from './model';
 export * from './speech2text';
 export * from './tts';
 export * from './profile';
+export * from './aigc';
 export declare const PROVIDE_AI_MODEL_LLM = "provide_ai_model_llm";
 export declare const PROVIDE_AI_MODEL_MODERATION = "provide_ai_model_moderation";
 export declare const PROVIDE_AI_MODEL_SPEECH2TEXT = "provide_ai_model_speech2text";

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

@@ -1,22 +1,28 @@
-import { BaseChatModel } from "@langchain/core/language_models/chat_models";
-import { AIModelEntity, ICopilot, ICopilotModel, ILLMUsage, ParameterType, PriceInfo, PriceType } from "@xpert-ai/contracts";
+import { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import { AIModelEntity, ICopilot, ICopilotModel, ILLMUsage, ModelUsagePricingSnapshot, ModelUsagePricingContext, ParameterType, PriceInfo, PriceType } from '@xpert-ai/contracts';
+export type TModelUsageType = 'estimated';
+export type TLLMUsage = ILLMUsage & {
+    type?: TModelUsageType;
+};
 export type TChatModelOptions = {
     modelProperties: Record<string, any>;
     handleLLMTokens: (input: {
         copilot: ICopilot;
         model?: string;
-        usage?: ILLMUsage;
+        requestId?: string;
+        usage?: TLLMUsage;
         /**
          * @deprecated use usage
          */
         tokenUsed?: number;
-    }) => void;
+    }) => void | Promise<void>;
     verbose: boolean;
 };
 export interface IAIModel {
     validateCredentials(model: string, credentials: Record<string, any>): Promise<void>;
     getChatModel(copilotModel: ICopilotModel, options?: TChatModelOptions): BaseChatModel;
     predefinedModels(): AIModelEntity[];
+    getUsagePricingSnapshot(model: string, credentials: Record<string, any>, context: ModelUsagePricingContext): ModelUsagePricingSnapshot;
     getPrice(model: string, credentials: Record<string, any>, priceType: PriceType, tokens: number, inputTokens?: number): PriceInfo;
 }
 export declare const CommonParameterRules: {

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

@@ -12,6 +12,8 @@ export interface RuntimeCapabilityRegistry {
     get<T>(key: RuntimeCapabilityKey<T> | string): T | undefined;
     require<T>(key: RuntimeCapabilityKey<T> | string): T;
 }
+/** 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";
 export declare class DefaultRuntimeCapabilityRegistry implements RuntimeCapabilityRegistry {
     private readonly capabilities;

package/src/lib/evolution/index.d.ts

@@ -0,0 +1,4 @@
+export * from './provider.decorator';
+export * from './provider.registry';
+export * from './runtime-capability';
+export type { EvolutionBaselineExporter, EvolutionCandidateBuilder, EvolutionProvider, EvolutionReleaseProvider, EvolutionReplayEvaluator, EvolutionTargetProvider } from '@xpert-ai/contracts';

package/src/lib/evolution/provider.decorator.d.ts

@@ -0,0 +1,2 @@
+export declare const EVOLUTION_TARGET_PROVIDER = "EVOLUTION_TARGET_PROVIDER";
+export declare const EvolutionTargetProviderStrategy: (providerKey: string) => <TFunction extends Function, Y>(target: TFunction | object, propertyKey?: string | symbol, descriptor?: TypedPropertyDescriptor<Y>) => void;

package/src/lib/evolution/provider.registry.d.ts

@@ -0,0 +1,7 @@
+import { EvolutionTargetProvider } from '@xpert-ai/contracts';
+import { DiscoveryService, Reflector } from '@nestjs/core';
+import { BaseStrategyRegistry } from '../strategy';
+export declare class EvolutionTargetProviderRegistry extends BaseStrategyRegistry<EvolutionTargetProvider> {
+    constructor(discoveryService: DiscoveryService, reflector: Reflector);
+    listDescriptors(organizationId?: string): import("@xpert-ai/contracts").EvolutionTargetDescriptor[];
+}

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

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

package/src/lib/managed-queue/index.d.ts

@@ -80,6 +80,8 @@ export type ManagedQueueJob<TPayload = unknown> = {
     data: TPayload;
     attemptsMade: number;
     opts?: Record<string, unknown>;
+    /** Persist a processor checkpoint without changing queue ownership metadata. */
+    updateData(data: TPayload): Promise<void>;
 };
 export type ManagedQueueJobContext = {
     pluginName: string;
@@ -92,7 +94,7 @@ export type ManagedQueueJobContext = {
     /** Business actor captured when the logical job was enqueued. */
     userId?: string | null;
 };
-export type ManagedQueueJobSnapshot<TPayload = unknown> = ManagedQueueJob<TPayload> & {
+export type ManagedQueueJobSnapshot<TPayload = unknown> = Omit<ManagedQueueJob<TPayload>, 'updateData'> & {
     state?: string;
     /** BullMQ terminal failure text, when the physical job is in the failed state. */
     failedReason?: string;

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

@@ -1,4 +1,4 @@
-import { JSONValue } from '@xpert-ai/contracts';
+import { type I18nObject, JSONValue } from '@xpert-ai/contracts';
 export type KnowledgebaseDocumentFile = {
     buffer: Buffer;
     originalname?: string;
@@ -24,6 +24,7 @@ export type KnowledgebaseDocumentDraft = {
 };
 export type KnowledgebaseDocumentRecord = {
     id: string;
+    version?: number;
     name?: string;
     type?: string;
     category?: string | null;
@@ -35,9 +36,63 @@ export type KnowledgebaseDocumentRecord = {
     status?: string | null;
     progress?: number | null;
     processMsg?: string | null;
+    /** Safe transformer provider key resolved from the document parser configuration. */
+    processorType?: string | null;
+    /** Localized label declared by the resolved transformer provider. */
+    processorLabel?: I18nObject | null;
     knowledgebaseId?: string;
+    sourceHash?: string | null;
+    contentHash?: string | null;
+    tokenNum?: number | null;
+    chunkNum?: number | null;
+    disabled?: boolean;
+    createdAt?: string;
+    updatedAt?: string;
+    /** Stable knowledgebase-relative directory containing the document. */
+    folderPath?: string | null;
+    /** Immediate folder document id when the parent relation was requested. */
+    parentId?: string | null;
     metadata?: KnowledgebaseDocumentMetadata;
 };
+export type KnowledgebaseListDocumentsInput = {
+    knowledgebaseId: string;
+    page?: number;
+    pageSize?: number;
+    search?: string;
+    includeFolders?: boolean;
+    /** List direct children of this folder. Use null for the knowledgebase root. */
+    parentId?: string | null;
+    /** Restrict results to a stable knowledgebase-relative folder path. */
+    folderPath?: string;
+    /** Defaults to direct. Descendants includes the selected folder and all child folders. */
+    folderMode?: 'direct' | 'descendants';
+};
+export type KnowledgebaseListDocumentsResult = {
+    documents: KnowledgebaseDocumentRecord[];
+    total: number;
+    page: number;
+    pageSize: number;
+};
+export type KnowledgebaseCreateFolderInput = {
+    knowledgebaseId: string;
+    name: string;
+    parentId?: string | null;
+};
+export type KnowledgebaseCreateFolderResult = {
+    knowledgebaseId: string;
+    folder: KnowledgebaseDocumentRecord;
+};
+export type KnowledgebaseMoveDocumentInput = {
+    knowledgebaseId: string;
+    documentId: string;
+    parentId?: string | null;
+    expectedVersion?: number;
+};
+export type KnowledgebaseMoveDocumentResult = {
+    knowledgebaseId: string;
+    document: KnowledgebaseDocumentRecord;
+    affectedDocumentIds: string[];
+};
 export type KnowledgebaseUploadFileInput = {
     knowledgebaseId: string;
     file: KnowledgebaseDocumentFile;
@@ -111,6 +166,9 @@ export type KnowledgebaseDeleteDocumentsResult = {
     missingDocumentIds?: string[];
 };
 export interface KnowledgebaseDocumentsApi {
+    listDocuments(input: KnowledgebaseListDocumentsInput): Promise<KnowledgebaseListDocumentsResult>;
+    createFolder(input: KnowledgebaseCreateFolderInput): Promise<KnowledgebaseCreateFolderResult>;
+    moveDocument(input: KnowledgebaseMoveDocumentInput): Promise<KnowledgebaseMoveDocumentResult>;
     uploadFile(input: KnowledgebaseUploadFileInput): Promise<KnowledgebaseUploadedFile>;
     importArchive(input: KnowledgebaseImportArchiveInput): Promise<KnowledgebaseImportArchiveResult>;
     createDocuments(input: KnowledgebaseCreateDocumentsInput): Promise<KnowledgebaseCreateDocumentsResult>;

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

@@ -1,4 +1,4 @@
-import { JSONValue } from '@xpert-ai/contracts';
+import { JSONValue, KnowledgeFilterDiagnostics, KnowledgeFilterNode } from '@xpert-ai/contracts';
 export type KnowledgebaseRetrievalMode = 'vector' | 'graph' | 'hybrid';
 export type KnowledgebaseMetadata = Record<string, JSONValue>;
 export type KnowledgebaseRetrievalSettings = {
@@ -15,7 +15,7 @@ export type KnowledgebaseSearchInput = {
     query: string;
     k?: number;
     score?: number;
-    filter?: KnowledgebaseMetadata;
+    filter?: KnowledgeFilterNode;
     retrieval?: KnowledgebaseRetrievalSettings;
     source: string;
     requestId?: string;
@@ -25,6 +25,10 @@ export type KnowledgebaseDocument = {
     pageContent: string;
     metadata?: Record<string, unknown>;
 };
+export type KnowledgebaseSearchResult = {
+    documents: KnowledgebaseDocument[];
+    diagnostics: KnowledgeFilterDiagnostics[];
+};
 export type KnowledgebaseListInput = {
     workspaceId?: string | null;
     published?: boolean;
@@ -55,12 +59,27 @@ export type KnowledgebaseWriteChunkInput = {
     title?: string;
     metadata?: KnowledgebaseMetadata;
     writeKey: string;
+    /**
+     * Optional system-managed document target. When omitted, the chunk is written to the
+     * Agent's shared writer document for backwards compatibility. A stable key creates an
+     * independently managed document that can be placed in a knowledgebase folder.
+     */
+    document?: {
+        key: string;
+        name: string;
+        parentId?: string | null;
+        metadata?: KnowledgebaseMetadata;
+    };
     executionId?: string;
     threadId?: string;
 };
 export type KnowledgebaseWriteChunkResult = {
     status?: 'created' | 'skipped';
     chunkId?: string;
+    knowledgebaseId?: string;
+    knowledgebaseName?: string;
+    documentId?: string;
+    writeKey?: string;
     message?: string;
 };
 export type KnowledgebaseDeleteChunksInput = {
@@ -70,6 +89,10 @@ export type KnowledgebaseDeleteChunksInput = {
     knowledgebaseId: string;
     writeKeys?: string[];
     writeKeyPrefix?: string;
+    /** Restrict deletion to a dedicated system-managed document created by writeChunk. */
+    documentKey?: string;
+    /** Remove the managed document after deletion when it has no chunks left. */
+    deleteDocumentIfEmpty?: boolean;
 };
 export type KnowledgebaseDeleteChunksResult = {
     deletedCount: number;
@@ -77,11 +100,80 @@ export type KnowledgebaseDeleteChunksResult = {
     documentId?: string;
     writeKeys?: string[];
     writeKeyPrefix?: string;
+    documentDeleted?: boolean;
+};
+export type KnowledgebaseProvisioningPermission = 'private' | 'organization' | 'public';
+export type KnowledgebaseProvisioningMetadataField = {
+    key: string;
+    label?: {
+        en_US?: string;
+        zh_Hans?: string;
+    };
+    type: 'string' | 'number' | 'boolean' | 'enum' | 'datetime' | 'string[]' | 'number[]' | 'object';
+    scope?: 'document' | 'chunk';
+    enumValues?: string[];
+    description?: string;
+};
+export type KnowledgebaseProvisioningSpec = {
+    key: string;
+    name: string;
+    description: string;
+    permission: KnowledgebaseProvisioningPermission;
+    language?: 'Chinese' | 'English';
+    chunkSize?: number;
+    chunkOverlap?: number;
+    delimiter?: string;
+    topK?: number;
+    score?: number;
+    metadataSchema?: KnowledgebaseProvisioningMetadataField[];
+    incrementalSyncEnabled?: 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.
+     */
+    inheritEmbeddingModel?: boolean;
+    knowledgebases: KnowledgebaseProvisioningSpec[];
+};
+export type KnowledgebaseEnsureItem = KnowledgebaseListItem & {
+    key: string;
+    operation: 'created' | 'updated';
+};
+export type KnowledgebaseEnsureResult = {
+    namespace: string;
+    workspaceId: string;
+    knowledgebases: KnowledgebaseEnsureItem[];
+};
+export type KnowledgebaseConnectAgentInput = {
+    workspaceId: string;
+    xpertId: string;
+    agentKey: string;
+    knowledgebaseIds: string[];
+    /** Optional administrator-owned retrieval policies keyed by knowledgebase id. */
+    retrievals?: Record<string, KnowledgebaseRetrievalSettings & {
+        fixedFilter?: KnowledgeFilterNode;
+        allowAgentFilter?: boolean;
+    }>;
+};
+export type KnowledgebaseConnectAgentResult = {
+    xpertId: string;
+    agentKey: string;
+    knowledgebaseIds: string[];
+    addedKnowledgebaseIds: string[];
+};
+export interface KnowledgebaseProvisioningApi {
+    ensure(input: KnowledgebaseEnsureInput): Promise<KnowledgebaseEnsureResult>;
+    connectAgent(input: KnowledgebaseConnectAgentInput): Promise<KnowledgebaseConnectAgentResult>;
+}
 export interface KnowledgebaseApi {
     list(input: KnowledgebaseListInput): Promise<KnowledgebaseListItem[]>;
-    search(input: KnowledgebaseSearchInput): Promise<KnowledgebaseDocument[]>;
+    search(input: KnowledgebaseSearchInput): Promise<KnowledgebaseSearchResult>;
     writeChunk(input: KnowledgebaseWriteChunkInput): Promise<KnowledgebaseWriteChunkResult>;
     deleteChunks(input: KnowledgebaseDeleteChunksInput): Promise<KnowledgebaseDeleteChunksResult>;
 }
 export declare const KnowledgebaseRuntimeCapability: import("../../core/runtime-capability").RuntimeCapabilityKey<KnowledgebaseApi>;
+export declare const KnowledgebaseProvisioningRuntimeCapability: import("../../core/runtime-capability").RuntimeCapabilityKey<KnowledgebaseProvisioningApi>;

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

@@ -228,4 +228,9 @@ export interface WorkspaceFilesApi {
         reference: WorkspacePortableFileReference;
     }>;
 }
+/** Workspace file operations used by media generation tools. */
+export type WorkspaceMediaFilesApi<TLocator extends WorkspaceFileLocator = WorkspaceFileLocator> = Pick<WorkspaceFilesApi, 'uploadBuffer' | 'readBuffer'> & {
+    readRuntimeBuffer?: (input: TLocator) => Promise<WorkspaceFileBuffer>;
+    deleteFile?: WorkspaceFilesApi['deleteFile'];
+};
 export declare const WorkspaceFilesRuntimeCapability: import("../../core/runtime-capability").RuntimeCapabilityKey<WorkspaceFilesApi>;

package/src/lib/toolset/builtin.d.ts

@@ -4,13 +4,38 @@ import { I18nObject, IXpertToolset, ToolProviderCredentials, TToolCredentials, T
 import { Logger } from '@nestjs/common';
 import { CommandBus, QueryBus } from '@nestjs/cqrs';
 import { BaseToolset } from './toolset';
+import type { AgentMiddlewareModelProviderConnection, AgentMiddlewareRuntimeApi } from '../agent/middleware/runtime';
+import type { ManagedQueueService } from '../managed-queue';
 /**
  * The context params of creating toolset
  */
+export type TToolTokenUsage = {
+    type?: 'estimated';
+    requestId: string;
+    provider: string;
+    model?: string;
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+};
+export type TToolModelUsageReporter = (usage: TToolTokenUsage) => void | Promise<void>;
+export type TToolModelProviderRuntime = AgentMiddlewareModelProviderConnection;
+export type TToolModelRuntime = {
+    /** Use the host's configured model provider; tool plugins must not handle provider API keys. */
+    createModelClient: AgentMiddlewareRuntimeApi['createModelClient'];
+    /** Resolve the host model provider account required by a direct Provider API tool. */
+    getModelProvider?: (provider: string) => Promise<TToolModelProviderRuntime>;
+    /** Report usage only for model APIs called directly by the tool. */
+    reportUsage?: TToolModelUsageReporter;
+};
 export type TBuiltinToolsetParams = TToolsetParams & {
     commandBus: CommandBus;
     queryBus: QueryBus;
     store?: BaseStore;
+    modelRuntime?: TToolModelRuntime;
+    managedQueue?: ManagedQueueService;
+    /** Installation scope used to route jobs back to this plugin instance. */
+    pluginScopeKey?: string;
 };
 export interface IBuiltinToolset {
     validateCredentials(credentials: TToolCredentials): Promise<void>;
@@ -30,6 +55,9 @@ export declare abstract class BuiltinToolset<T extends StructuredToolInterface =
     get commandBus(): CommandBus<import("@nestjs/cqrs").ICommand>;
     get queryBus(): QueryBus<import("@nestjs/cqrs").IQuery>;
     get xpertId(): string;
+    get modelRuntime(): TToolModelRuntime;
+    get managedQueue(): ManagedQueueService;
+    get pluginScopeKey(): string;
     constructor(providerName: string, toolset?: IXpertToolset, params?: TBuiltinToolsetParams);
     validateCredentials(credentials: C): Promise<void>;
     _validateCredentials(credentials: C): Promise<void>;

package/src/lib/toolset/index.d.ts

@@ -2,4 +2,5 @@ export * from './strategy.decorator';
 export * from './strategy.interface';
 export * from './strategy.registry';
 export * from './builtin';
+export * from './model-provider';
 export * from './toolset';

package/src/lib/toolset/model-provider.d.ts

@@ -0,0 +1,31 @@
+import type { StructuredToolInterface } from '@langchain/core/tools';
+import { type IXpertToolset, type TToolCredentials } from '@xpert-ai/contracts';
+import { type AIGCModelClient, type AsyncAIGCModelClient } from '../ai-model';
+import { type RuntimeCapabilityResolver, type WorkspaceFileScope, type WorkspaceFilesApi } from '../runtime';
+import { BuiltinToolset, type TBuiltinToolsetParams, type TToolModelProviderRuntime } from './builtin';
+export type ModelProviderAuthorizationScheme = 'Bearer' | 'ApiKey';
+export type ModelProviderBuiltinToolsetOptions = {
+    toolsetProviderName: string;
+    modelProviderName: string;
+    authorizationScheme: ModelProviderAuthorizationScheme;
+    invalidCredentialsMessage: string;
+    missingProviderMessage: string;
+    missingWorkspaceMessage: string;
+};
+/**
+ * Shared host-runtime plumbing for built-in tools backed by a configured model provider.
+ * Provider request/response semantics remain owned by each plugin.
+ */
+export declare abstract class ModelProviderBuiltinToolset<T extends StructuredToolInterface = StructuredToolInterface, C = TToolCredentials> extends BuiltinToolset<T, C> {
+    private readonly modelProviderOptions;
+    private readonly runtimeCapabilities?;
+    private modelProvider?;
+    constructor(modelProviderOptions: ModelProviderBuiltinToolsetOptions, toolset?: IXpertToolset, runtimeCapabilities?: RuntimeCapabilityResolver, params?: TBuiltinToolsetParams);
+    _validateCredentials(_credentials: C): Promise<void>;
+    protected getModelProviderRuntime(): Promise<TToolModelProviderRuntime>;
+    protected getModelProviderCredential(modelProvider: TToolModelProviderRuntime): string;
+    protected getWorkspaceFiles(): WorkspaceFilesApi;
+    protected createWorkspaceScope(): WorkspaceFileScope | undefined;
+    protected createAsyncModelClient<TInput, TData>(model: string, modality: 'image' | 'video', purpose?: 'invoke' | 'observe'): Promise<AsyncAIGCModelClient<TInput, TData>>;
+    protected createModelClient<TInput, TData>(model: string, modality: 'image' | 'video'): Promise<AIGCModelClient<TInput, TData>>;
+}

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

@@ -13,6 +13,9 @@ export interface IVectorStoreStrategy<TConfig extends {
      */
     readonly name: string;
     readonly description?: string;
+    readonly capabilities?: {
+        supportsFilterV2: boolean;
+    };
     /**
      * Validate configuration for VectorStore
      */

package/src/model-provider-http-client.d.ts

@@ -0,0 +1 @@
+export * from './lib/ai-model/model-provider-http-client';

package/src/model-provider-toolset.d.ts

@@ -0,0 +1 @@
+export * from './lib/toolset/model-provider';