@xpert-ai/plugin-sdk 3.18.2 → 3.18.4

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

@@ -7,6 +7,7 @@ import { ICopilotModel, IModelAccessResolution, IXpertAgentExecution, JSONValue,
 import { Subscriber } from 'rxjs';
 import { AIGCModelClient, AsyncAIGCModelClient, IRerank, TLLMUsage } from '../../ai-model/types';
 import type { RuntimeCapabilityRegistry } from '../../core';
+import type { ConnectorRuntimeScope } from '../../connector/runtime-capability';
 import type { WorkspaceFileCatalog } from '../../runtime/capabilities/workspace-files';
 export * from './runtime-capability';
 export * from './capabilities';
@@ -92,27 +93,14 @@ export type AgentMiddlewareModelProviderConnection = {
     /** Persist final authoritative usage and calculate its charge exactly once. */
     reportUsage(report: ModelUsageReport, modelAccess?: IModelAccessResolution): Promise<ModelUsageReportResult>;
 };
-export type AgentMiddlewareRuntimeScope = {
-    tenantId?: string | null;
-    organizationId?: string | null;
+export type AgentMiddlewareRuntimeScope = ConnectorRuntimeScope & {
     providerScopeId?: string | null;
-    userId?: string | null;
-    workspaceId?: string | null;
-    projectId?: string | null;
-    xpertId?: string | null;
     /** Authoritative Volume catalog for runtime workspace files. */
     catalog?: WorkspaceFileCatalog | null;
     /** Authoritative catalog identity for portable workspace references. */
     scopeId?: string | null;
     /** Legacy xperts catalog compatibility flag; new runtimes use user-xperts instead. */
     isolateByUser?: boolean | null;
-    xpertName?: string | null;
-    conversationId?: string | null;
-    threadId?: string | null;
-    agentKey?: string | null;
-    executionId?: string | null;
-    /** Connector bindings selected for this conversation. An empty list denies connector resolution. */
-    connectorBindingIds?: string[] | null;
     usageCallback?: (usage: TLLMUsage) => void | Promise<void>;
     workspaceRoot?: string | null;
     workspacePath?: string | null;

package/src/lib/agent/middleware/strategy.interface.d.ts

@@ -25,5 +25,7 @@ export interface IAgentMiddlewareContext {
 }
 export interface IAgentMiddlewareStrategy<T = unknown> {
     meta: TAgentMiddlewareMeta;
+    /** Static Tool names exposed by this Middleware, for capability summaries without creating a runtime instance. */
+    getToolNames?(options: T): readonly string[];
     createMiddleware(options: T, context: IAgentMiddlewareContext): PromiseOrValue<AgentMiddleware>;
 }

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

@@ -4,6 +4,7 @@ import { AIModel } from '../ai-model';
 import { TChatModelOptions } from './model';
 export type RerankResult = {
     index: number;
+    /** Relevance score reported by the rerank provider. Higher values are more relevant. */
     relevanceScore: number;
     document?: Document<Record<string, any>>;
 };
@@ -14,6 +15,7 @@ export declare abstract class RerankModel extends AIModel {
 export interface IRerank {
     rerank(docs: Document<Record<string, any>>[], query: string, options: {
         topN?: number;
+        /** Minimum relevanceScore, applied before the Top N limit. */
         scoreThreshold?: number;
         model?: string;
     }): Promise<RerankResult[]>;

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

@@ -16,8 +16,9 @@ export interface RuntimeCapabilityRegistry {
 export type RuntimeCapabilityResolver = Pick<RuntimeCapabilityRegistry, 'get'>;
 export declare const XPERT_RUNTIME_CAPABILITIES_TOKEN = "XPERT_RUNTIME_CAPABILITIES";
 export declare class DefaultRuntimeCapabilityRegistry implements RuntimeCapabilityRegistry {
+    private readonly parent?;
     private readonly capabilities;
-    constructor(entries?: Array<[RuntimeCapabilityKey<unknown> | string, unknown]>);
+    constructor(entries?: Array<[RuntimeCapabilityKey<unknown> | string, unknown]>, parent?: RuntimeCapabilityResolver);
     register<T>(key: RuntimeCapabilityKey<T> | string, implementation: T): this;
     has<T>(key: RuntimeCapabilityKey<T> | string): boolean;
     get<T>(key: RuntimeCapabilityKey<T> | string): T | undefined;

package/src/lib/data/datasource/types.d.ts

@@ -1,7 +1,7 @@
 import * as _axios from 'axios';
 import { Readable } from 'stream';
-import { IColumnDef, IDSSchema, IDSTable } from '@xpert-ai/contracts';
-export { IColumnDef, IDSSchema, IDSTable } from '@xpert-ai/contracts';
+import { IColumnDef, IDataSourceCapabilityQuery, IDSSchema, IDSTable } from '@xpert-ai/contracts';
+export { IColumnDef, IDataSourceCapabilityQuery, IDSSchema, IDSTable } from '@xpert-ai/contracts';
 /**
  * The base options for DB adapters
  */
@@ -82,6 +82,11 @@ export interface DBQueryRunner {
      * @param tableName
      */
     getSchema(catalog?: string, tableName?: string): Promise<IDSSchema[]>;
+    /**
+     * Runs an adapter-owned, read-only capability without exposing its domain
+     * contract through the host platform.
+     */
+    queryCapability?(query: IDataSourceCapabilityQuery): Promise<unknown>;
     /**
      * Describe a sql query result schema
      *

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

@@ -6,3 +6,4 @@ export * from './artifacts';
 export * from './workspace-files';
 export * from './sandbox-jobs';
 export * from './project-provisioning';
+export * from './project-access';

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

@@ -1,5 +1,5 @@
 import { JSONValue, KnowledgeFilterDiagnostics, KnowledgeFilterNode } from '@xpert-ai/contracts';
-export type KnowledgebaseRetrievalMode = 'vector' | 'graph' | 'hybrid';
+export type KnowledgebaseRetrievalMode = 'vector' | 'keyword' | 'graph' | 'hybrid';
 export type KnowledgebaseMetadata = Record<string, JSONValue>;
 export type KnowledgebaseRetrievalSettings = {
     mode?: KnowledgebaseRetrievalMode;
@@ -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/project-access.d.ts

@@ -0,0 +1,30 @@
+/** Trusted server actor. View providers derive this from host context; jobs persist that actor. */
+export interface ProjectAccessActor {
+    tenantId: string;
+    organizationId?: string | null;
+    userId: string;
+}
+export interface ProjectHumanAccess {
+    projectId: string;
+    role: 'owner' | 'manager' | 'editor' | 'member';
+    canManage: boolean;
+    archived: boolean;
+    /** Explicit Project bindings, for plugins that choose to use assignment as business policy. */
+    assistantIds?: string[];
+}
+/** Human membership only. Assistant assignment and business authorization remain plugin-owned. */
+export interface ProjectAccessApi {
+    listReadable(input: {
+        actor: ProjectAccessActor;
+        projectIds?: string[];
+    }): Promise<ProjectHumanAccess[]>;
+    assertEdit(input: {
+        actor: ProjectAccessActor;
+        projectId: string;
+    }): Promise<ProjectHumanAccess>;
+    assertManage(input: {
+        actor: ProjectAccessActor;
+        projectId: string;
+    }): Promise<ProjectHumanAccess>;
+}
+export declare const ProjectAccessRuntimeCapability: import("../../core/runtime-capability").RuntimeCapabilityKey<ProjectAccessApi>;

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

@@ -37,5 +37,13 @@ export type ProjectEnsureResult = {
 export interface ProjectProvisioningApi {
     /** Create or reconcile a Chat Project without changing its caller-supplied id. */
     ensure(input: ProjectEnsureInput): Promise<ProjectEnsureResult>;
+    /** Owner-only physical deletion of an archived plugin-bound Project and its workspace. */
+    purge?(input: {
+        projectId: string;
+        xpertId: string;
+    }): Promise<{
+        projectId: string;
+        deleted: boolean;
+    }>;
 }
 export declare const ProjectProvisioningRuntimeCapability: import("../../core/runtime-capability").RuntimeCapabilityKey<ProjectProvisioningApi>;

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

@@ -23,5 +23,6 @@ export declare class DecoratedAgentMiddlewareStrategy implements IAgentMiddlewar
     readonly provider: string;
     readonly meta: any;
     constructor(instance: XpertToolProviderInstance, descriptor: XpertToolProviderDescriptor, provider: string);
+    getToolNames(): readonly string[];
     createMiddleware(options: unknown, context: IAgentMiddlewareContext): Promise<AgentMiddleware>;
 }

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;