@xpert-ai/plugin-sdk 3.18.3 → 3.18.5

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

@@ -1,2 +1,21 @@
+import type { RuntimeIdentityScope } from '../runtime/runtime-scope';
 import type { ConnectorRuntimeApi } from './strategy.interface';
 export declare const ConnectorRuntimeCapability: import("../core").RuntimeCapabilityKey<ConnectorRuntimeApi>;
+/** No binding or provider grants means no connector access. */
+export type ConnectorRuntimeScope = RuntimeIdentityScope & {
+    /** Host-selected bindings, including IDs pinned by enabled graph Connector nodes. */
+    connectorBindingIds?: string[] | null;
+    /** Providers configured by enabled graph Connector nodes without a pinned ID. */
+    connectorProviders?: string[] | null;
+};
+export type SelectedRuntimeConnectorBinding = {
+    bindingId: string;
+    provider: string;
+};
+export interface ConnectorRuntimeFactory {
+    /** Snapshot the authorized identity and connector grants for this runtime. */
+    createScopedApi(scope: ConnectorRuntimeScope): ConnectorRuntimeApi;
+    /** Preflight selected bindings through the same identity, project and credential checks. */
+    resolveSelectedRuntimeBindings(bindingIds: string[] | null | undefined, scope: ConnectorRuntimeScope): Promise<SelectedRuntimeConnectorBinding[]>;
+}
+export declare const ConnectorRuntimeFactoryCapability: import("../core").RuntimeCapabilityKey<ConnectorRuntimeFactory>;

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

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

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/actor-token.d.ts

@@ -1,7 +1,9 @@
+import type { RuntimeIdentityScope } from '../runtime-scope';
 export type ActorTokenAct = Record<string, string | number | boolean | null | undefined>;
 export interface ActorTokenRequest {
     audience?: string | string[];
     ttlSeconds?: number;
+    /** Extra delegation metadata; cannot replace claims fixed by the host when creating the API. */
     act?: ActorTokenAct;
 }
 export interface ActorTokenResult {
@@ -13,3 +15,13 @@ export interface ActorTokenApi {
     getToken(input?: ActorTokenRequest): Promise<ActorTokenResult>;
 }
 export declare const ActorTokenRuntimeCapability: import("../../core/runtime-capability").RuntimeCapabilityKey<ActorTokenApi>;
+/** Host-defined delegation claims are fixed when the API is created. */
+export type ActorTokenRuntimeScope = RuntimeIdentityScope & {
+    act?: ActorTokenAct;
+};
+export interface ActorTokenRuntimeFactory {
+    /** Create one independent token cache for a host-authorized caller/execution. */
+    createScopedApi(scope: ActorTokenRuntimeScope): ActorTokenApi;
+}
+/** Platform registry entry. The operation capability above is bound only inside a caller runtime. */
+export declare const ActorTokenRuntimeFactoryCapability: import("../../core/runtime-capability").RuntimeCapabilityKey<ActorTokenRuntimeFactory>;

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

@@ -54,6 +54,8 @@ export type ArtifactLinkAccessInput = {
     expiresAt?: string | Date | null;
     ttlSeconds?: number | null;
     userConfirmedPublicLink?: boolean | null;
+    /** Trusted application authorization; must never be populated from untrusted tool arguments. */
+    publicLinkAuthorization?: 'application_policy';
 };
 /** Browser response hints and HTML safety profile for an Artifact link. */
 export type ArtifactLinkPresentationInput = {

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

@@ -1,4 +1,5 @@
-import type { WorkspacePortableFileReference } from './workspace-files';
+import type { RuntimeIdentityScope } from '../runtime-scope';
+import type { WorkspaceFilesApi, 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;
@@ -6,10 +7,9 @@ export type KnowledgeDocumentVisualTextAnchor = {
     sourceBlockIds?: string[];
 };
 export type KnowledgeDocumentVisualBusinessScope = {
-    namespace: 'bom.requirement-evidence';
-    caseId: string;
-    baselineId: string;
-    runId: string;
+    /** Plugin-owned audit namespace; document authorization remains host-owned. */
+    namespace: string;
+    attributes: Record<string, string>;
     sourceDocumentId: string;
 };
 export type KnowledgeDocumentVisualCandidateRequest = {
@@ -76,3 +76,14 @@ export interface KnowledgeDocumentVisualAssetsApi {
     discardImageBatch(batchRef: string): Promise<void>;
 }
 export declare const KnowledgeDocumentVisualAssetsRuntimeCapability: import("../../core/runtime-capability").RuntimeCapabilityKey<KnowledgeDocumentVisualAssetsApi>;
+export type KnowledgeDocumentVisualAssetsRuntimeDependencies = {
+    /** File writer already bound to the authorized project/workspace. */
+    workspaceFiles: WorkspaceFilesApi;
+    /** Optional host resolver for child executions whose identity is assigned after graph construction. */
+    resolveExecutionScope?: () => RuntimeIdentityScope;
+};
+export interface KnowledgeDocumentVisualAssetsRuntimeFactory {
+    /** Every API owns a fresh allow-list; supplied scope must identify an authorized execution. */
+    createScopedApi(scope: RuntimeIdentityScope, dependencies: KnowledgeDocumentVisualAssetsRuntimeDependencies): KnowledgeDocumentVisualAssetsApi;
+}
+export declare const KnowledgeDocumentVisualAssetsRuntimeFactoryCapability: import("../../core/runtime-capability").RuntimeCapabilityKey<KnowledgeDocumentVisualAssetsRuntimeFactory>;

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

@@ -1,4 +1,4 @@
-import { type I18nObject, JSONValue } from '@xpert-ai/contracts';
+import { type I18nObject, type DocumentTextParserConfig, type DocumentSheetParserConfig, JSONValue } from '@xpert-ai/contracts';
 import type { WorkspacePortableFileReference } from './workspace-files';
 export type KnowledgebaseDocumentFile = {
     buffer: Buffer;
@@ -199,7 +199,56 @@ export type KnowledgebaseReadImageResult = {
     reference: WorkspacePortableFileReference;
     buffer: Buffer;
 };
+/** Bounded, ordered source text. The host checks document read access on every page. */
+export type KnowledgebaseReadTextInput = {
+    knowledgebaseId: string;
+    documentId: string;
+    offset?: number;
+    limit?: number;
+};
+export type KnowledgebaseReadTextResult = {
+    knowledgebaseId: string;
+    documentId: string;
+    version: number;
+    sourceHash?: string | null;
+    total: number;
+    chunks: Array<{
+        id: string;
+        text: string;
+        page?: number;
+        version: number;
+    }>;
+};
+export type KnowledgebaseProcessingOptionsInput = {
+    knowledgebaseId: string;
+    fileName: string;
+    /** Omit to use the Knowledge base's default for this file type. */
+    processor?: string;
+    transformerIntegration?: string;
+};
+export type KnowledgebaseProcessingOptionsResult = {
+    fileType: string;
+    defaultProcessor: string;
+    processor: string;
+    defaultSource: 'knowledgebase' | 'platform';
+    providers: Array<{
+        name: string;
+        label: I18nObject;
+        integrationProvider?: string;
+    }>;
+    integrations: Array<{
+        id: string;
+        name: string;
+        provider: string;
+    }>;
+    integrationRequired: boolean;
+    selectedIntegrationId?: string;
+    /** Server-only resolved settings. Do not expose configuration/credentials to an iframe. */
+    parserConfig: DocumentTextParserConfig & Partial<DocumentSheetParserConfig>;
+};
 export interface KnowledgebaseDocumentsApi {
+    getProcessingOptions(input: KnowledgebaseProcessingOptionsInput): Promise<KnowledgebaseProcessingOptionsResult>;
+    readText(input: KnowledgebaseReadTextInput): Promise<KnowledgebaseReadTextResult>;
     listDocuments(input: KnowledgebaseListDocumentsInput): Promise<KnowledgebaseListDocumentsResult>;
     createFolder(input: KnowledgebaseCreateFolderInput): Promise<KnowledgebaseCreateFolderResult>;
     moveDocument(input: KnowledgebaseMoveDocumentInput): Promise<KnowledgebaseMoveDocumentResult>;

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

@@ -15,6 +15,7 @@ export type KnowledgebaseSearchInput = {
     query: string;
     k?: number;
     score?: number;
+    rerankThreshold?: number;
     filter?: KnowledgeFilterNode;
     retrieval?: KnowledgebaseRetrievalSettings;
     source: string;

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/runtime/index.d.ts

@@ -1,2 +1,3 @@
 export * from './runtime-capability';
+export * from './runtime-scope';
 export * from './capabilities';

package/src/lib/runtime/runtime-scope.d.ts

@@ -0,0 +1,14 @@
+/** Host-authorized identity and execution binding; never accept this from tool arguments or HTTP bodies. */
+export type RuntimeIdentityScope = {
+    tenantId?: string | null;
+    organizationId?: string | null;
+    userId?: string | null;
+    workspaceId?: string | null;
+    projectId?: string | null;
+    xpertId?: string | null;
+    xpertName?: string | null;
+    conversationId?: string | null;
+    threadId?: string | null;
+    agentKey?: string | null;
+    executionId?: string | null;
+};

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

@@ -4,3 +4,5 @@ export * from './descriptor';
 export * from './registry';
 export * from './adapters';
 export * from './coordinator';
+export { XPERT_TOOL_RESULT_FORMAT_VERSION } from './tool-result';
+export { prepareToolResult, type XpertPreparedToolResult, type XpertOutputDiagnostic } from './prepared-result';

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

@@ -0,0 +1,18 @@
+import type { PromiseOrValue } from '../types';
+declare const PREPARED_RESULT: unique symbol;
+export interface XpertOutputDiagnostic {
+    code: 'tool_output_invalid';
+    issues: {
+        path: string;
+        code: string;
+    }[];
+}
+export interface XpertPreparedToolResult<T = unknown> {
+    readonly [PREPARED_RESULT]: true;
+    project(): PromiseOrValue<T>;
+    recover(diagnostic: XpertOutputDiagnostic): PromiseOrValue<T>;
+}
+/** Defer output projection until the adapter can validate and recover its result. */
+export declare function prepareToolResult<T, TRecovery>(project: () => PromiseOrValue<T>, recover: (diagnostic: XpertOutputDiagnostic) => PromiseOrValue<TRecovery>): XpertPreparedToolResult<T | TRecovery>;
+export declare function resolveToolResult<T>(value: unknown, validate: (output: unknown) => Promise<T>): Promise<T>;
+export {};

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

@@ -0,0 +1,16 @@
+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 agentContent(content: XpertToolContent[] | undefined): ({
+    type: string;
+    image_url: {
+        url: string;
+    };
+    text?: undefined;
+} | {
+    type: string;
+    text: string;
+    image_url?: undefined;
+})[];

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

@@ -1,4 +1,4 @@
-import type { IconDefinition, I18nObject, JsonSchemaObjectType, McpRequiredContext, McpToolBehavior, TAgentMiddlewareMeta } from '@xpert-ai/contracts';
+import type { IconDefinition, I18nObject, JsonSchemaObjectType, McpRequiredContext, McpCapabilityApprovalMode, McpToolBehavior, TAgentMiddlewareMeta } from '@xpert-ai/contracts';
 import type { RunnableConfig } from '@langchain/core/runnables';
 import type { ZodTypeAny, infer as ZodInfer } from 'zod/v3';
 import type { AgentMiddleware } from '../agent/middleware/types';
@@ -6,6 +6,8 @@ import type { IAgentMiddlewareContext } from '../agent/middleware/strategy.inter
 import type { McpAppDefinition } from '../mcp/app';
 import type { ToolExecutionContext, ToolHostApi, ToolPrincipal } from '../toolset/tool-execution-context';
 import type { XpertToolAppBinding, XpertToolVisibility } from '../toolset/define-tool';
+import type { XpertToolResult } from '../toolset/tool-result';
+import type { XpertPreparedToolResult } from './prepared-result';
 import type { PromiseOrValue } from '../types';
 export type XpertBusinessToolSurface = 'middleware' | 'mcp';
 export interface XpertToolProviderMiddlewareDefinition {
@@ -38,6 +40,8 @@ export interface XpertToolProviderOptions {
     apps?: readonly McpAppDefinition[];
 }
 export interface XpertMcpToolOptions {
+    /** Default for auto-published tools; explicit administrator policy takes precedence. */
+    defaultApprovalMode?: McpCapabilityApprovalMode;
     behavior: McpToolBehavior;
     requiredContext: readonly McpRequiredContext[];
     visibility?: readonly XpertToolVisibility[];
@@ -50,6 +54,8 @@ export interface XpertToolOptions<TInputSchema extends ZodTypeAny = ZodTypeAny,
     description: string;
     inputSchema: TInputSchema;
     outputSchema?: TOutputSchema;
+    /** Opt in to standard content blocks; outputSchema validates structuredContent. */
+    resultFormat?: 'dto' | 'tool_result';
     /** true uses the class default, a string selects a declared group, false disables Middleware exposure. */
     middleware?: true | string | false;
     /** MCP exposure is opt-in. */
@@ -75,7 +81,7 @@ export interface XpertBusinessToolContext {
     host: ToolHostApi;
     middlewareOptions?: unknown;
 }
-export type XpertDecoratedToolMethod<TInputSchema extends ZodTypeAny = ZodTypeAny, TOutputSchema extends ZodTypeAny = ZodTypeAny> = (input: ZodInfer<TInputSchema>, context: XpertBusinessToolContext) => PromiseOrValue<ZodInfer<TOutputSchema>>;
+export type XpertDecoratedToolMethod<TInputSchema extends ZodTypeAny = ZodTypeAny, TOutputSchema extends ZodTypeAny = ZodTypeAny> = (input: ZodInfer<TInputSchema>, context: XpertBusinessToolContext) => PromiseOrValue<ZodInfer<TOutputSchema> | XpertToolResult<ZodInfer<TOutputSchema>> | XpertPreparedToolResult>;
 export interface XpertToolProviderInstance {
     getMiddlewareExtensions?(provider: string, options: unknown, context: IAgentMiddlewareContext): PromiseOrValue<Omit<AgentMiddleware, 'name' | 'tools'>>;
 }

package/src/lib/toolset/define-tool.d.ts

@@ -1,4 +1,4 @@
-import type { McpRequiredContext, McpToolBehavior } from '@xpert-ai/contracts';
+import type { McpCapabilityApprovalMode, McpRequiredContext, McpToolBehavior } from '@xpert-ai/contracts';
 import type { ZodTypeAny, infer as ZodInfer } from 'zod/v3';
 import type { McpTaskExecutionPolicy } from '../mcp/task';
 import type { ToolExecutionContext } from './tool-execution-context';
@@ -21,6 +21,7 @@ export interface XpertToolDefinition<TInputSchema extends ZodTypeAny, TOutputSch
     outputSchema?: TOutputSchema;
     exposure: XpertToolExposure;
     behavior: McpToolBehavior;
+    defaultApprovalMode?: McpCapabilityApprovalMode;
     requiredContext: McpRequiredContext[];
     visibility?: XpertToolVisibility[];
     app?: XpertToolAppBinding;

package/src/lib/types.d.ts

@@ -51,7 +51,7 @@ export interface XpertPlugin<TConfig extends object = any> extends PluginLifecyc
      * template ids as `${pluginName}:${key}` when exposing them through the
      * xpert-template API.
      */
-    templates?: XpertTemplateContribution[] | XpertTemplateProvider;
+    templates?: XpertTemplateContribution[] | XpertTemplateProvider | XpertTemplateCatalogProvider;
     /** Declares the required system-level permissions for this plugin. */
     permissions?: Permissions;
     /** Returns the DynamicModule to be mounted to the main application (can be set as global) */
@@ -78,6 +78,11 @@ export interface XpertTemplateContribution {
     startPrompts?: string[];
     promptWorkflows?: TPromptWorkflow[];
     releaseNotes?: string;
+    availableLocales?: string[];
+    defaultLocale?: string;
+    locale?: string;
+    pluginVersion?: string;
+    contentHash?: string;
     xpertName?: string;
     dependencies?: XpertTemplatePluginDependencies;
     [key: string]: unknown;
@@ -85,6 +90,12 @@ export interface XpertTemplateContribution {
 export interface XpertTemplateProvider {
     listTemplates(ctx: PluginContext): PromiseOrValue<XpertTemplateContribution[]>;
 }
+/** Lists metadata without DSL; resolves exactly one immutable language variant on demand. */
+export interface XpertTemplateCatalogProvider {
+    kind: 'catalog';
+    listTemplates(ctx: PluginContext): PromiseOrValue<XpertTemplateContribution[]>;
+    resolveTemplate(ctx: PluginContext, key: string, locale?: string): PromiseOrValue<XpertTemplateContribution>;
+}
 export interface PluginContext<TConfig extends object = any> {
     module: ModuleRef;
     app?: INestApplicationContext;