@xpert-ai/plugin-sdk 3.17.1 → 3.17.3

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.'
 });
@@ -190,7 +194,7 @@ const ArtifactsRuntimeCapability = createRuntimeCapability('platform.artifacts',
 
 /** Stable source identifier for portable workspace file references. */ const WORKSPACE_FILES_SOURCE = 'platform.workspace.files';
 const WorkspaceFilesRuntimeCapability = createRuntimeCapability('platform.workspace.files', {
-    description: 'Upload, understand, resolve, read, and delete raw files in Xpert workspace volumes.'
+    description: 'Upload, understand, search parsed chunks, resolve, read, and delete files in Xpert workspace volumes.'
 });
 
 /** Stable machine-readable failures emitted by the Sandbox Jobs capability. */ const SANDBOX_JOB_ERROR_CODES = [
@@ -232,6 +236,10 @@ const SANDBOX_JOB_ERROR_CODE_SET = new Set(SANDBOX_JOB_ERROR_CODES);
     description: 'Run registered plugin actions in isolated, short-lived Sandbox Runtime jobs.'
 });
 
+const ProjectProvisioningRuntimeCapability = createRuntimeCapability('platform.project.provisioning', {
+    description: 'Idempotently provision a platform Chat Project and connect it to an Assistant.'
+});
+
 /**
  * Shared host-runtime plumbing for built-in tools backed by a configured model provider.
  * Provider request/response semantics remain owned by each plugin.
@@ -333,10 +341,12 @@ exports.BaseTool = BaseTool;
 exports.BaseToolset = BaseToolset;
 exports.BuiltinToolset = BuiltinToolset;
 exports.DefaultRuntimeCapabilityRegistry = DefaultRuntimeCapabilityRegistry;
+exports.KnowledgeDocumentVisualAssetsRuntimeCapability = KnowledgeDocumentVisualAssetsRuntimeCapability;
 exports.KnowledgebaseDocumentsRuntimeCapability = KnowledgebaseDocumentsRuntimeCapability;
 exports.KnowledgebaseProvisioningRuntimeCapability = KnowledgebaseProvisioningRuntimeCapability;
 exports.KnowledgebaseRuntimeCapability = KnowledgebaseRuntimeCapability;
 exports.ModelProviderBuiltinToolset = ModelProviderBuiltinToolset;
+exports.ProjectProvisioningRuntimeCapability = ProjectProvisioningRuntimeCapability;
 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

@@ -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.'
 });
@@ -188,7 +192,7 @@ const ArtifactsRuntimeCapability = createRuntimeCapability('platform.artifacts',
 
 /** Stable source identifier for portable workspace file references. */ const WORKSPACE_FILES_SOURCE = 'platform.workspace.files';
 const WorkspaceFilesRuntimeCapability = createRuntimeCapability('platform.workspace.files', {
-    description: 'Upload, understand, resolve, read, and delete raw files in Xpert workspace volumes.'
+    description: 'Upload, understand, search parsed chunks, resolve, read, and delete files in Xpert workspace volumes.'
 });
 
 /** Stable machine-readable failures emitted by the Sandbox Jobs capability. */ const SANDBOX_JOB_ERROR_CODES = [
@@ -230,6 +234,10 @@ const SANDBOX_JOB_ERROR_CODE_SET = new Set(SANDBOX_JOB_ERROR_CODES);
     description: 'Run registered plugin actions in isolated, short-lived Sandbox Runtime jobs.'
 });
 
+const ProjectProvisioningRuntimeCapability = createRuntimeCapability('platform.project.provisioning', {
+    description: 'Idempotently provision a platform Chat Project and connect it to an Assistant.'
+});
+
 /**
  * Shared host-runtime plumbing for built-in tools backed by a configured model provider.
  * Provider request/response semantics remain owned by each plugin.
@@ -325,4 +333,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, ProjectProvisioningRuntimeCapability as P, 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.1",
+  "version": "3.17.3",
   "license": "AGPL-3.0",
   "repository": {
     "type": "git",
@@ -17,7 +17,7 @@
   },
   "dependencies": {
     "@langchain/openai": "0.6.9",
-    "@xpert-ai/contracts": "3.17.1",
+    "@xpert-ai/contracts": "3.17.3",
     "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, ModelUsagePricingContext, ModelUsagePricingSnapshot, ParameterRule, 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;

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

@@ -1,4 +1,4 @@
-import { IIntegration, TIntegrationProvider } from '@xpert-ai/contracts';
+import { IIntegration, TEnterpriseH5IdentityGrant, TIntegrationProvider } from '@xpert-ai/contracts';
 export type TIntegrationStrategyParams = {
     query: string;
 };
@@ -14,10 +14,30 @@ export type IntegrationTestResult = {
     warnings?: string[];
     probe?: IntegrationTestProbe;
 } & Record<string, unknown>;
+/** Identity proof accepted by an integration strategy for enterprise H5 exchange. */
+export type IntegrationIdentityGrant = TEnterpriseH5IdentityGrant;
+/** Public integration data required before the browser requests an identity grant. */
+export type IntegrationIdentityBootstrap = {
+    externalOrganizationId: string;
+    clientConfig: Record<string, unknown>;
+};
+/** Enterprise identity verified by an integration, with optional Xpert account binding. */
+export type IntegrationExternalIdentity = {
+    provider: string;
+    externalOrganizationId: string;
+    subjectId: string;
+    displayName?: string;
+    accountBinding?: {
+        provider: string;
+        subjectId: string;
+    };
+};
 export interface IntegrationStrategy<T = unknown> {
     meta: TIntegrationProvider;
     execute(integration: IIntegration<T>, payload: TIntegrationStrategyParams): Promise<any>;
     onUpdate?(previous: IIntegration<T>, current: IIntegration<any>): Promise<void> | void;
     onDelete?(integration: IIntegration<T>): Promise<void> | void;
     validateConfig?(config: T, integration?: IIntegration<T>): Promise<void | IntegrationTestResult>;
+    getIdentityBootstrap?(integration: IIntegration<T>): Promise<IntegrationIdentityBootstrap>;
+    exchangeIdentity?(integration: IIntegration<T>, grant: IntegrationIdentityGrant): Promise<IntegrationExternalIdentity>;
 }

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

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

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>;

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

@@ -0,0 +1,30 @@
+/** Lifecycle states that plugin-managed Projects may synchronize to the platform. */
+export type ProjectProvisioningStatus = 'active' | 'archived';
+/** Stable identity and desired state for an idempotently provisioned Chat Project. */
+export type ProjectEnsureInput = {
+    /** Caller-generated id reused across retries to prevent duplicate Projects. */
+    projectId: string;
+    /** Workspace that owns both the Project and connected Assistant. */
+    workspaceId: string;
+    /** Assistant that must be connected to the Project. */
+    xpertId: string;
+    /** Current business-project display name. */
+    name: string;
+    /** Current business-project lifecycle state. */
+    status: ProjectProvisioningStatus;
+};
+/** Effective Project state after an idempotent ensure operation. */
+export type ProjectEnsureResult = {
+    projectId: string;
+    workspaceId: string;
+    /** Complete set of Assistants connected after synchronization. */
+    xpertIds: string[];
+    /** Whether this call inserted the Project or reconciled an existing one. */
+    operation: 'created' | 'updated';
+};
+/** Host API exposed to plugins that own one-to-one business Project mappings. */
+export interface ProjectProvisioningApi {
+    /** Create or reconcile a Chat Project without changing its caller-supplied id. */
+    ensure(input: ProjectEnsureInput): Promise<ProjectEnsureResult>;
+}
+export declare const ProjectProvisioningRuntimeCapability: import("../../core/runtime-capability").RuntimeCapabilityKey<ProjectProvisioningApi>;

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

@@ -184,6 +184,49 @@ export type WorkspaceValidatedUnderstandingReference = {
     anchor?: Record<string, unknown>;
     excerpt: string;
 };
+/** Scoped, bounded FileChunk DTO for plugin-owned evidence mapping. */
+export type WorkspaceUnderstandingChunk = {
+    /** FileAsset that owns the parsed chunk. */
+    fileAssetId: string;
+    /** Stable FileChunk identifier suitable for evidence references. */
+    chunkId: string;
+    /** Parser order within the source document. */
+    orderNo: number;
+    /** Parser-specific page, sheet, slide, or block location. */
+    anchor?: Record<string, unknown>;
+    /** Bounded source text; callers must not assume it contains the whole file. */
+    content: string;
+};
+/** Input for paging an already parsed FileAsset without creating a second index. */
+export type WorkspaceListUnderstandingChunksInput = WorkspaceFileScope & {
+    fileAssetId: string;
+    /** One-based page number. */
+    page?: number;
+    /** Page size clamped by the host. */
+    pageSize?: number;
+    /** Maximum characters returned for each chunk. */
+    contentLength?: number;
+};
+/** One bounded page from the FileAsset's existing FileChunk index. */
+export type WorkspaceUnderstandingChunkPage = {
+    fileAssetId: string;
+    /** Chunks in parser order for the requested page. */
+    items: WorkspaceUnderstandingChunk[];
+    page: number;
+    pageSize: number;
+    /** True when another bounded page can be requested. */
+    hasMore: boolean;
+};
+/** Input for hybrid search over a FileAsset's existing FileChunk index. */
+export type WorkspaceSearchUnderstandingChunksInput = WorkspaceFileScope & {
+    fileAssetId: string;
+    /** Natural-language or keyword query evaluated by the platform hybrid index. */
+    query: string;
+    /** Result count clamped by the host. */
+    limit?: number;
+    /** Maximum characters returned for each matching chunk. */
+    contentLength?: number;
+};
 /**
  * Runtime capability contract for reading, writing, uploading, deleting, and
  * understanding files in Xpert workspace Volumes.
@@ -199,6 +242,10 @@ export interface WorkspaceFilesApi {
     retryUnderstanding(input: WorkspaceRetryUnderstandingInput): Promise<WorkspaceUnderstandingStatus>;
     /** Validate bounded FileAsset/chunk evidence without returning complete file contents. */
     validateUnderstandingReferences(input: WorkspaceValidateUnderstandingReferencesInput): Promise<WorkspaceValidatedUnderstandingReference[]>;
+    /** List one bounded page of parsed chunks after enforcing FileAsset workspace scope. */
+    listUnderstandingChunks(input: WorkspaceListUnderstandingChunksInput): Promise<WorkspaceUnderstandingChunkPage>;
+    /** Search the existing FileChunk hybrid index without creating another embedding index. */
+    searchUnderstandingChunks(input: WorkspaceSearchUnderstandingChunksInput): Promise<WorkspaceUnderstandingChunk[]>;
     /**
      * Resolve metadata and an openable URL for an explicitly scoped workspace
      * file without reading its bytes into the API process.