@xpert-ai/plugin-sdk 3.17.0 → 3.17.2

package/model-provider.cjs.js

@@ -180,6 +180,10 @@ const KnowledgebaseDocumentsRuntimeCapability = createRuntimeCapability('platfor
     description: 'Upload, import, create, process, inspect, and delete persistent knowledgebase documents.'
 });
 
+const KnowledgeDocumentVisualAssetsRuntimeCapability = createRuntimeCapability('platform.knowledgebase.visual-assets', {
+    description: 'Issue execution-scoped logical KnowledgeDocument image paths and inject validated images without exposing host storage paths.'
+});
+
 const ActorTokenRuntimeCapability = createRuntimeCapability('platform.actor-token', {
     description: 'Mint a short-lived host-issued actor bearer token for outbound API calls.'
 });
@@ -333,6 +337,7 @@ exports.BaseTool = BaseTool;
 exports.BaseToolset = BaseToolset;
 exports.BuiltinToolset = BuiltinToolset;
 exports.DefaultRuntimeCapabilityRegistry = DefaultRuntimeCapabilityRegistry;
+exports.KnowledgeDocumentVisualAssetsRuntimeCapability = KnowledgeDocumentVisualAssetsRuntimeCapability;
 exports.KnowledgebaseDocumentsRuntimeCapability = KnowledgebaseDocumentsRuntimeCapability;
 exports.KnowledgebaseProvisioningRuntimeCapability = KnowledgebaseProvisioningRuntimeCapability;
 exports.KnowledgebaseRuntimeCapability = KnowledgebaseRuntimeCapability;

package/model-provider.esm.js

@@ -178,6 +178,10 @@ const KnowledgebaseDocumentsRuntimeCapability = createRuntimeCapability('platfor
     description: 'Upload, import, create, process, inspect, and delete persistent knowledgebase documents.'
 });
 
+const KnowledgeDocumentVisualAssetsRuntimeCapability = createRuntimeCapability('platform.knowledgebase.visual-assets', {
+    description: 'Issue execution-scoped logical KnowledgeDocument image paths and inject validated images without exposing host storage paths.'
+});
+
 const ActorTokenRuntimeCapability = createRuntimeCapability('platform.actor-token', {
     description: 'Mint a short-lived host-issued actor bearer token for outbound API calls.'
 });
@@ -325,4 +329,4 @@ function normalizeOptionalString(value) {
     return normalized || undefined;
 }
 
-export { ActorTokenRuntimeCapability as A, BaseTool as B, DefaultRuntimeCapabilityRegistry as D, KnowledgebaseDocumentsRuntimeCapability as K, ModelProviderBuiltinToolset as M, SANDBOX_JOB_ERROR_CODES as S, WORKSPACE_FILES_SOURCE as W, XPERT_RUNTIME_CAPABILITIES_TOKEN as X, ArtifactsRuntimeCapability as a, BaseToolset as b, createRuntimeCapability as c, BuiltinToolset as d, KnowledgebaseProvisioningRuntimeCapability as e, KnowledgebaseRuntimeCapability as f, SANDBOX_JOB_PROGRESS_PREFIX as g, SandboxJobRuntimeError as h, SandboxJobsRuntimeCapability as i, WorkspaceFilesRuntimeCapability as j, isSandboxJobRuntimeError as k };
+export { ActorTokenRuntimeCapability as A, BaseTool as B, DefaultRuntimeCapabilityRegistry as D, KnowledgeDocumentVisualAssetsRuntimeCapability as K, ModelProviderBuiltinToolset as M, SANDBOX_JOB_ERROR_CODES as S, WORKSPACE_FILES_SOURCE as W, XPERT_RUNTIME_CAPABILITIES_TOKEN as X, ArtifactsRuntimeCapability as a, BaseToolset as b, createRuntimeCapability as c, BuiltinToolset as d, KnowledgebaseDocumentsRuntimeCapability as e, KnowledgebaseProvisioningRuntimeCapability as f, KnowledgebaseRuntimeCapability as g, SANDBOX_JOB_PROGRESS_PREFIX as h, SandboxJobRuntimeError as i, SandboxJobsRuntimeCapability as j, WorkspaceFilesRuntimeCapability as k, isSandboxJobRuntimeError as l };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xpert-ai/plugin-sdk",
-  "version": "3.17.0",
+  "version": "3.17.2",
   "license": "AGPL-3.0",
   "repository": {
     "type": "git",
@@ -17,7 +17,7 @@
   },
   "dependencies": {
     "@langchain/openai": "0.6.9",
-    "@xpert-ai/contracts": "3.17.0",
+    "@xpert-ai/contracts": "3.17.2",
     "express": "^4.22.1",
     "js-tiktoken": "^1.0.21"
   },

package/src/lib/agent/middleware/runtime.d.ts

@@ -3,7 +3,7 @@ import { BaseLanguageModel } from '@langchain/core/language_models/base';
 import { BaseChatModel } from '@langchain/core/language_models/chat_models';
 import type { Runtime as LangGraphRuntime } from '@langchain/langgraph';
 import type { BaseMessage } from '@langchain/core/messages';
-import { ICopilotModel, IXpertAgentExecution, JSONValue, ModelUsagePricingSnapshot, ModelUsageReport, ModelUsageReportResult, ModelUsagePricingContext, TSandboxConfigurable } from '@xpert-ai/contracts';
+import { ICopilotModel, IModelAccessResolution, IXpertAgentExecution, JSONValue, ModelUsagePricingSnapshot, ModelUsageReport, ModelUsageReportResult, ModelUsagePricingContext, TSandboxConfigurable } from '@xpert-ai/contracts';
 import { Subscriber } from 'rxjs';
 import { AIGCModelClient, AsyncAIGCModelClient, IRerank, TLLMUsage } from '../../ai-model/types';
 import type { RuntimeCapabilityRegistry } from '../../core';
@@ -71,6 +71,9 @@ export type AgentMiddlewareCreateModelClientOptions = {
     /** `observe` reads an existing asynchronous task and must not consume generation quota. */
     purpose?: 'invoke' | 'observe';
 };
+export type AgentMiddlewareModelAccessContext = ModelUsagePricingContext & {
+    requestId: string;
+};
 export type AgentMiddlewareModelProviderConnection = {
     /** Stable host-owned model provider configuration boundary. */
     providerScopeId: string;
@@ -81,10 +84,12 @@ export type AgentMiddlewareModelProviderConnection = {
     provider: string;
     baseURL: string;
     authorization: string;
+    /** Resolve and freeze the host-owned Direct/Grant access decision before provider invocation. */
+    resolveModelAccess?: (context: AgentMiddlewareModelAccessContext) => Promise<IModelAccessResolution>;
     /** Resolve the model YAML price rule and freeze it for one invocation. */
     resolvePricingSnapshot?: (context: ModelUsagePricingContext) => Promise<ModelUsagePricingSnapshot>;
     /** Persist final authoritative usage and calculate its charge exactly once. */
-    reportUsage(report: ModelUsageReport): Promise<ModelUsageReportResult>;
+    reportUsage(report: ModelUsageReport, modelAccess?: IModelAccessResolution): Promise<ModelUsageReportResult>;
 };
 export type AgentMiddlewareRuntimeScope = {
     tenantId?: string | null;

package/src/lib/ai-model/ai-model-provider.interface.d.ts

@@ -8,6 +8,10 @@ export interface IAIModelProviderStrategy {
     /**
      * Provider metadata
      */
+    /**
+     * Stable provider identifier from the provider schema.
+     */
+    readonly name: string;
     /**
      * Validate whether the credentials are valid
      */
@@ -35,7 +39,7 @@ export interface IAIModelProviderStrategy {
     /**
      * Return the defined provider models (metadata)
      */
-    getProviderModels?(modelType?: AiModelTypeEnum, onlyActive?: boolean): ProviderModel[];
+    getProviderModels(modelType?: AiModelTypeEnum, onlyActive?: boolean): ProviderModel[];
     getProviderSchema(): IAiProviderEntity;
     getProviderServerPath(): string;
     getModelManager<T extends AIModel>(modelType: AiModelTypeEnum): T;

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

@@ -1,6 +1,7 @@
 export * from './ai-model-provider.interface';
 export * from './ai-model-provider.decorator';
 export * from './ai-model-provider.registry';
+export * from './ai-model';
 export * from './abstract-provider';
 export * from './types';
 export * from './llm';

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

@@ -1,4 +1,4 @@
-import { AIModelEntity, ICopilot, ILLMUsage, ParameterRule, TTokenUsage } from '@xpert-ai/contracts';
+import { AIModelEntity, ICopilot, ILLMUsage, LLMPriceContext, LLMReportedPrice, ParameterRule, TTokenUsage } from '@xpert-ai/contracts';
 import { Logger } from '@nestjs/common';
 import { BaseCallbackHandler } from '@langchain/core/callbacks/base';
 import { LLMResult } from '@langchain/core/outputs';
@@ -8,6 +8,13 @@ export type CommonChatModelParameters = {
     temperature: number;
     maxRetries?: number | null;
 };
+export type LLMUsagePricingOptions = {
+    context?: LLMPriceContext;
+    resolveContext?: (output: LLMResult) => LLMPriceContext;
+    resolveReportedPrice?: (output: LLMResult) => LLMReportedPrice | undefined;
+    reportedPriceRequired?: boolean;
+};
+export type LLMUsagePricingConfiguration = LLMPriceContext | LLMUsagePricingOptions;
 export declare class LLMUsage implements ILLMUsage {
     /**
      * Model class for llm usage.
@@ -33,8 +40,8 @@ export declare abstract class LargeLanguageModel extends AIModel {
     #private;
     protected startedAt: DOMHighResTimeStamp;
     protected _commonParameterRules(model: string): ParameterRule[];
-    protected calcResponseUsage(model: string, credentials: Record<string, any>, promptTokens: number, completionTokens: number, startedAt?: number): ILLMUsage;
-    createHandleUsageCallbacks(copilot: ICopilot, model: string, credentials: any, handleLLMTokens: TChatModelOptions['handleLLMTokens']): {
+    protected calcResponseUsage(model: string, credentials: Record<string, any>, promptTokens: number, completionTokens: number, startedAt?: number, tokenUsage?: TTokenUsage, pricingContext?: LLMPriceContext): ILLMUsage;
+    createHandleUsageCallbacks(copilot: ICopilot, model: string, credentials: any, handleLLMTokens: TChatModelOptions['handleLLMTokens'], pricingConfiguration?: LLMUsagePricingConfiguration): {
         name: string;
         lc_serializable: boolean;
         readonly lc_namespace: ["langchain_core", "callbacks", string];

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

@@ -1,4 +1,4 @@
-import { type ModelUsageModality, type ModelUsageOperation, type ModelUsagePricingDimensions, type ModelUsagePricingSnapshot } from '@xpert-ai/contracts';
+import { type IModelAccessResolution, 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';
@@ -16,6 +16,7 @@ export type AsyncAIGCManagedJobPayload<TInput, TResult> = {
     startedAt: string;
     providerRequestId?: string;
     providerState?: AIGCModelObservation['state'];
+    modelAccess?: IModelAccessResolution;
     pricingSnapshot?: ModelUsagePricingSnapshot;
     usageReported?: boolean;
     result?: TResult;

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

@@ -1,5 +1,6 @@
-import { type ModelUsagePricingSnapshot, type ModelUsageMetric, type ModelUsagePriceRule, type ModelUsagePricingConfig, type ModelUsagePricingContext, type ModelUsagePricingStatus, PriceConfig, PriceInfo, PriceType } from '@xpert-ai/contracts';
+import { type LLMPriceCalculation, type LLMPriceContext, type ModelUsagePricingSnapshot, type ModelUsageMetric, type ModelUsagePriceRule, type ModelUsagePricingConfig, type ModelUsagePricingContext, type ModelUsagePricingStatus, PriceConfig, PriceInfo, PriceType, type TTokenUsage } from '@xpert-ai/contracts';
 export declare function calculateModelPrice(pricing: PriceConfig, priceType: PriceType, tokens: number, inputTokens?: number): PriceInfo;
+export declare function calculateLLMUsagePrice(pricing: PriceConfig, usage: TTokenUsage, context?: LLMPriceContext): LLMPriceCalculation;
 export type ModelUsageChargeCalculation = {
     pricingStatus: ModelUsagePricingStatus;
     pricingRule?: ModelUsagePriceRule;

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

@@ -1,11 +1,15 @@
 import { BaseChatModel } from '@langchain/core/language_models/chat_models';
-import { AIModelEntity, ICopilot, ICopilotModel, ILLMUsage, ModelUsagePricingSnapshot, ModelUsagePricingContext, ParameterType, PriceInfo, PriceType } from '@xpert-ai/contracts';
+import { AIModelEntity, ICopilot, ICopilotModel, ILLMUsage, ModelUsageReport, ModelUsagePricingContext, ModelUsagePricingSnapshot, ParameterRule, ParameterType, PriceInfo, PriceType } from '@xpert-ai/contracts';
 export type TModelUsageType = 'estimated';
 export type TLLMUsage = ILLMUsage & {
     type?: TModelUsageType;
 };
 export type TChatModelOptions = {
     modelProperties: Record<string, any>;
+    /** Final authoritative usage for non-LLM model clients. */
+    handleModelUsage?: (report: ModelUsageReport) => void | Promise<void>;
+    /** Freeze the active usage price rules at invocation start. */
+    resolveUsagePricingSnapshot?: (context: ModelUsagePricingContext) => ModelUsagePricingSnapshot | Promise<ModelUsagePricingSnapshot>;
     handleLLMTokens: (input: {
         copilot: ICopilot;
         model?: string;
@@ -22,6 +26,7 @@ export interface IAIModel {
     validateCredentials(model: string, credentials: Record<string, any>): Promise<void>;
     getChatModel(copilotModel: ICopilotModel, options?: TChatModelOptions): BaseChatModel;
     predefinedModels(): AIModelEntity[];
+    getParameterRules(model: string, credentials: Record<string, string>): ParameterRule[];
     getUsagePricingSnapshot(model: string, credentials: Record<string, any>, context: ModelUsagePricingContext): ModelUsagePricingSnapshot;
     getPrice(model: string, credentials: Record<string, any>, priceType: PriceType, tokens: number, inputTokens?: number): PriceInfo;
 }

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

@@ -1,5 +1,6 @@
 export * from './knowledgebase';
 export * from './knowledgebase-documents';
+export * from './knowledge-document-visual-assets';
 export * from './actor-token';
 export * from './artifacts';
 export * from './workspace-files';

package/src/lib/runtime/capabilities/knowledge-document-visual-assets.d.ts

@@ -0,0 +1,78 @@
+import type { WorkspacePortableFileReference } from './workspace-files';
+export type KnowledgeDocumentVisualCandidateReason = 'same_block' | 'same_chunk' | 'same_page' | 'adjacent_page' | 'visual_summary_match' | 'visual_only_fallback';
+export type KnowledgeDocumentVisualTextAnchor = {
+    page?: number;
+    chunkId?: string;
+    sourceBlockIds?: string[];
+};
+export type KnowledgeDocumentVisualBusinessScope = {
+    namespace: 'bom.requirement-evidence';
+    caseId: string;
+    baselineId: string;
+    runId: string;
+    sourceDocumentId: string;
+};
+export type KnowledgeDocumentVisualCandidateRequest = {
+    knowledgebaseId: string;
+    knowledgeDocumentId: string;
+    query: string;
+    textAnchors: KnowledgeDocumentVisualTextAnchor[];
+    maxAssets: number;
+    businessScope: KnowledgeDocumentVisualBusinessScope;
+};
+export type KnowledgeDocumentVisualCandidate = {
+    /**
+     * Execution-scoped logical path returned by a governed KnowledgeDocument search. This is not a
+     * host filesystem path and can only be resolved again by the knowledgebase image viewer.
+     */
+    filePath: string;
+    knowledgeDocumentId: string;
+    sourceDocumentId: string;
+    page?: number;
+    chunkId?: string;
+    sourceBlockIds: string[];
+    visualAssetId: string;
+    candidateReason: KnowledgeDocumentVisualCandidateReason;
+    summary?: string;
+};
+export type KnowledgeDocumentVisualCandidateResult = {
+    candidates: KnowledgeDocumentVisualCandidate[];
+    warnings: string[];
+};
+export type KnowledgeDocumentViewImagesInput = {
+    filePaths: string[];
+};
+export type KnowledgeDocumentViewedImage = Omit<KnowledgeDocumentVisualCandidate, 'filePath'> & {
+    index: number;
+    mimeType: 'image/png' | 'image/jpeg' | 'image/webp';
+    size: number;
+    width?: number;
+    height?: number;
+    sha256: string;
+};
+/**
+ * Server-only materialization data used to create an immutable ArtifactVersion.
+ *
+ * This value is returned through the in-process runtime capability and must not
+ * be copied into ToolMessage content or persisted chat metadata.
+ */
+export type KnowledgeDocumentPreparedImageArtifact = {
+    index: number;
+    fileName: string;
+    workspaceFileRef: WorkspacePortableFileReference;
+};
+export type KnowledgeDocumentViewImagesResult = {
+    batchRef: string;
+    images: KnowledgeDocumentViewedImage[];
+    artifactInputs: KnowledgeDocumentPreparedImageArtifact[];
+};
+export type KnowledgeDocumentVisualImagePayload = KnowledgeDocumentViewedImage & {
+    dataBase64: string;
+};
+export interface KnowledgeDocumentVisualAssetsApi {
+    issueCandidates(input: KnowledgeDocumentVisualCandidateRequest): Promise<KnowledgeDocumentVisualCandidateResult>;
+    prepareImages(input: KnowledgeDocumentViewImagesInput): Promise<KnowledgeDocumentViewImagesResult>;
+    consumeImageBatch(batchRef: string): Promise<KnowledgeDocumentVisualImagePayload[]>;
+    discardImageBatch(batchRef: string): Promise<void>;
+}
+export declare const KnowledgeDocumentVisualAssetsRuntimeCapability: import("../../core/runtime-capability").RuntimeCapabilityKey<KnowledgeDocumentVisualAssetsApi>;