@xpert-ai/plugin-sdk 3.18.3 → 3.18.4

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