@xpert-ai/plugin-sdk 3.18.3 → 3.18.4

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @xpert-ai/plugin-sdk
 
+## 3.18.4
+
+### Patch Changes
+
+- 3f72082: Add opt-in lazy template catalogs, summary pagination, explicit prompt locales and source revision tracking. Existing eager template providers remain compatible.
+
+  Restore role skill bindings when switching templates and preserve localized skill names during installation and selection.
+
+- 4be390b: Release Xpert 3.18.4 with aligned contracts, plugin-sdk, and Web application versions.
+
+- 63cd444: Allow host-enabled graph Connector providers in scoped runtime credentials while preserving explicit binding checks. Existing Connector APIs remain compatible.
+- Updated dependencies [3f72082]
+- Updated dependencies [7b97fee]
+- Updated dependencies [4be390b]
+- Updated dependencies [4e8c7ed]
+  - @xpert-ai/contracts@3.18.4
+
 ## 3.18.3
 
 ### Patch Changes

package/README.md

@@ -1,5 +1,9 @@
 # Plugin SDK
 
+## Runtime capabilities
+
+See [platform capabilities and scoped factories](./runtime-capabilities.md) for domain registration, execution-scoped APIs and usage outside Agent middleware.
+
 ## Building
 
 Run `nx build plugin-sdk` to build the library.
@@ -61,7 +65,9 @@ export class OrderOperationsTools {
 }
 ```
 
-MCP exposure is explicit. Provide strict Zod input/output schemas and return an allowlisted DTO; the host validates the output and maps it to `structuredContent`. Invocation context is constructed for every call and must never be cached on the Provider singleton. `getMiddlewareExtensions()` may add Agent-only hooks such as `wrapToolCall`, but business-critical behavior belongs in the method or shared service.
+MCP exposure is explicit. Provide strict Zod input/output schemas and return an allowlisted DTO; the host validates the output and maps it to `structuredContent` and a JSON `TextContent` block so clients that only expose text can still read the result. With `resultFormat: 'tool_result'`, image and other content blocks are preserved and the validated structured metadata also receives a JSON text fallback. Invocation context is constructed for every call and must never be cached on the Provider singleton. `getMiddlewareExtensions()` may add Agent-only hooks such as `wrapToolCall`, but business-critical behavior belongs in the method or shared service.
+
+For completed operations, `prepareToolResult(() => project(result), () => minimalReceipt)` defers output mapping to the adapter. The normal path maps and validates once; projection, validation or JSON serialization failures recover a bounded receipt without executing the business method again. Declare `outputSchema: z.union([normalSchema, receiptSchema])`, with strict objects in every branch. The fallback is validated too. Business exceptions thrown before the method returns remain errors. With `tool_result`, both callbacks return the content envelope and the union describes its structured metadata. The MCP protocol still validates the published JSON Schema; custom Zod refinements remain enforced by the SDK. Do not put side effects inside either callback.
 
 For a host-native MCP App, declare each static HTML bundle once in the Provider's `apps` array, then bind a Tool with `mcp.app.resourceKey` and include `app` visibility. The App key must exist in the same Provider and its entry must be a relative `.html` path inside the packaged plugin. The host publishes the bundle as a `ui://` resource; plugins must not create a stdio server or put CSP/credentials in Tool results.
 
@@ -85,3 +91,22 @@ import {
 ```
 
 This entry point excludes the NestJS and Node.js dependencies used by the server SDK.
+
+### Native MCP invocation defaults
+
+A decorated tool can declare `mcp.defaultApprovalMode: 'allow' | 'confirm' | 'deny'`.
+The native capability descriptor carries this default through auto-publication and
+provider synchronization. Explicit Publication administrator policies take
+precedence. Omitting the field retains the existing risk defaults: reads allow,
+writes confirm, and dangerous tools deny. A dangerous tool can run directly only
+when its owner explicitly declares `allow`; risk annotations remain unchanged.
+Manual Publications review changes to this declaration before adopting them.
+
+For public Artifact links authorized by trusted application policy, runtime callers
+may pass `access.publicLinkAuthorization: 'application_policy'` instead of
+asserting `userConfirmedPublicLink`. This field must be derived by trusted plugin
+code, never exposed as a tool argument. Existing user-confirmation calls retain
+their behavior; user identity and Artifact scope checks still apply.
+
+These additions require matching host contracts/runtime support and an SDK build
+containing these interfaces. They are not part of the published SDK 3.18.3 baseline.

package/index.cjs.js

@@ -37,7 +37,7 @@ var base$1 = require('@langchain/core/language_models/base');
 var connector = require('./connector.cjs.js');
 var collaborationClient = require('./collaboration-client.cjs.js');
 var tools = require('@langchain/core/tools');
-require('zod/v3');
+var v3 = require('zod/v3');
 
 function _interopNamespaceDefault(e) {
     var n = Object.create(null);
@@ -3597,17 +3597,11 @@ class OpenAICompatibleReranker {
             if (!Array.isArray(output)) {
                 throw new Error('Invalid response format: missing results array');
             }
-            // Collect raw scores and normalize them.
-            const scores = output.map((r)=>r.relevance_score);
-            const minScore = Math.min(...scores);
-            const maxScore = Math.max(...scores);
-            const scoreRange = maxScore !== minScore ? maxScore - minScore : 1.0;
             const reranked = output.map((r)=>{
                 const index = r.index;
-                const normalizedScore = (r.relevance_score - minScore) / scoreRange;
                 const result = {
                     index,
-                    relevanceScore: normalizedScore
+                    relevanceScore: r.relevance_score
                 };
                 if (options.returnDocuments) {
                     var _r_document, _docs_index, _docs_index1;
@@ -4121,6 +4115,9 @@ exports.SSOProviderRegistry = __decorate([
 const ConnectorRuntimeCapability = modelProvider.createRuntimeCapability('platform.connector', {
     description: 'Resolve connector credentials for agent middleware.'
 });
+const ConnectorRuntimeFactoryCapability = modelProvider.createRuntimeCapability('platform.connector.factory', {
+    description: 'Create a connector API restricted to host-granted connectors and the authorized execution identity.'
+});
 
 const CONNECTOR_STRATEGY = 'CONNECTOR_STRATEGY';
 const ConnectorStrategyKey = (provider)=>common.applyDecorators(common.SetMetadata(CONNECTOR_STRATEGY, provider), common.SetMetadata(STRATEGY_META_KEY, CONNECTOR_STRATEGY));
@@ -5884,6 +5881,9 @@ const EVOLUTION_RUNTIME_SERVICE_TOKEN = 'XPERT_EVOLUTION_RUNTIME_SERVICE';
 const EvolutionRuntimeCapability = modelProvider.createRuntimeCapability('platform.agent-evolution', {
     description: 'Ingest learning signals and resolve immutable capability versions for domain runtimes.'
 });
+const EvolutionChangeRuntimeCapability = modelProvider.createRuntimeCapability('platform.agent-evolution.changes', {
+    description: 'Prepare, evaluate and publish versioned changes through target-owned validators and effect providers.'
+});
 
 function defineMcpApp(definition) {
     return Object.freeze(definition);
@@ -6047,6 +6047,12 @@ function validateProviderOptions(options) {
 }
 function validateToolOptions(options, methodName) {
     var _options_description;
+    if (options.resultFormat && options.resultFormat !== 'dto' && options.resultFormat !== 'tool_result') {
+        throw new Error(`Tool '${options.name}' declares an invalid resultFormat.`);
+    }
+    if (options.resultFormat === 'tool_result' && !options.outputSchema) {
+        throw new Error(`Tool '${options.name}' requires outputSchema for tool_result.`);
+    }
     if (!TOOL_NAME_PATTERN.test(options.name) || options.name.length > 191) {
         throw new Error(`Method '${methodName}' declares invalid Tool name '${options.name}'.`);
     }
@@ -6062,6 +6068,9 @@ function validateToolOptions(options, methodName) {
         throw new Error(`MCP Tool '${options.name}' requires at least one execution context.`);
     }
     if (options.mcp) {
+        if (options.mcp.defaultApprovalMode !== undefined && !includesValue(contracts.MCP_CAPABILITY_APPROVAL_MODES, options.mcp.defaultApprovalMode)) {
+            throw new Error(`MCP Tool '${options.name}' declares invalid defaultApprovalMode.`);
+        }
         const behavior = options.mcp.behavior;
         if (!includesValue(contracts.MCP_TOOL_RISKS, behavior == null ? void 0 : behavior.risk) || !includesValue(contracts.MCP_TOOL_SIDE_EFFECTS, behavior == null ? void 0 : behavior.sideEffect) || !includesValue(contracts.MCP_TOOL_IDEMPOTENCY, behavior == null ? void 0 : behavior.idempotency)) {
             throw new Error(`MCP Tool '${options.name}' requires valid behavior annotations.`);
@@ -6088,6 +6097,19 @@ function assertStrictObjectSchema(schema, toolName, role) {
     if (!schema || typeof Reflect.get(schema, 'parseAsync') !== 'function') {
         throw new Error(`Tool '${toolName}' requires a Zod ${role} schema.`);
     }
+    // Refinements preserve the strict object shape while enforcing cross-field invariants.
+    // Plugins can load a different physical copy of Zod; use its explicit type tag.
+    while(schema._def.typeName === 'ZodEffects'){
+        const refinement = schema;
+        if (refinement._def.effect.type !== 'refinement') break;
+        schema = refinement.innerType();
+    }
+    if (role === 'output' && schema._def.typeName === 'ZodUnion') {
+        // Recovery receipts may have a different shape, but every branch must reject extra fields.
+        const union = schema;
+        for (const option of union.options)assertStrictObjectSchema(option, toolName, role);
+        return;
+    }
     const definition = Reflect.get(schema, '_def');
     if (!definition || Reflect.get(definition, 'unknownKeys') !== 'strict') {
         throw new Error(`Tool '${toolName}' ${role} schema must be a strict Zod object.`);
@@ -6161,6 +6183,141 @@ exports.XpertToolProviderRegistry = __decorate([
     ])
 ], exports.XpertToolProviderRegistry);
 
+// Invariants: recovery starts only after the business method returns successfully.
+// Projection and recovery callbacks must be free of business side effects.
+// The adapter validates normal output once and validates any fallback separately;
+// neither path may rerun the operation or suppress input, authorization or commit failures.
+// Installed plugins may resolve a different physical SDK copy from the host.
+const PREPARED_RESULT = Symbol.for('xpert.tool.prepared-result.v1');
+/** Defer output projection until the adapter can validate and recover its result. */ function prepareToolResult(project, recover) {
+    return {
+        [PREPARED_RESULT]: true,
+        project,
+        recover
+    };
+}
+function isPrepared(value) {
+    return typeof value === 'object' && value !== null && PREPARED_RESULT in value && value[PREPARED_RESULT] === true && 'project' in value && typeof value.project === 'function' && 'recover' in value && typeof value.recover === 'function';
+}
+async function resolveToolResult(value, validate) {
+    if (!isPrepared(value)) return validate(value);
+    try {
+        return await validate(await value.project());
+    } catch (error) {
+        const diagnostic = {
+            code: 'tool_output_invalid',
+            issues: error instanceof v3.ZodError ? error.issues.slice(0, 10).map((issue)=>({
+                    path: issue.path.join('.').slice(0, 240),
+                    code: issue.code
+                })) : []
+        };
+        // A malformed fallback is a programming error too; never send unchecked data.
+        return validate(await value.recover(diagnostic));
+    }
+}
+
+// Why this exists: MCP media blocks and business metadata have different contracts.
+// Validate metadata with the declared output schema, preserve bounded media blocks,
+// and include the same DTO in text for clients that hide structuredContent.
+const XPERT_TOOL_RESULT_FORMAT_VERSION = 1;
+const contentSchema = v3.z.discriminatedUnion('type', [
+    v3.z.object({
+        type: v3.z.literal('text'),
+        text: v3.z.string().max(2 * 1024 * 1024)
+    }).strict(),
+    v3.z.object({
+        type: v3.z.literal('image'),
+        data: v3.z.string().min(1).max(8 * 1024 * 1024),
+        mimeType: v3.z.enum([
+            'image/png',
+            'image/jpeg',
+            'image/webp',
+            'image/gif'
+        ])
+    }).strict(),
+    v3.z.object({
+        type: v3.z.literal('audio'),
+        data: v3.z.string().min(1).max(8 * 1024 * 1024),
+        mimeType: v3.z.string().min(1).max(100)
+    }).strict(),
+    v3.z.object({
+        type: v3.z.literal('resource_link'),
+        uri: v3.z.string().min(1).max(4096),
+        name: v3.z.string().max(240).optional()
+    }).strict()
+]);
+/** Validate the envelope separately so binary content never enters the business DTO. */ async function parseDecoratedToolResult(value, outputSchema) {
+    var _result_content;
+    const envelope = v3.z.object({
+        content: v3.z.array(contentSchema).max(32).optional(),
+        structuredContent: outputSchema,
+        isError: v3.z.boolean().optional()
+    }).strict();
+    const result = await envelope.parseAsync(value);
+    var _result_content_map;
+    const content = (_result_content_map = (_result_content = result.content) == null ? void 0 : _result_content.map((item)=>{
+        switch(item.type){
+            case 'text':
+                return {
+                    type: 'text',
+                    text: item.text
+                };
+            case 'image':
+                return {
+                    type: 'image',
+                    data: item.data,
+                    mimeType: item.mimeType
+                };
+            case 'audio':
+                return {
+                    type: 'audio',
+                    data: item.data,
+                    mimeType: item.mimeType
+                };
+            case 'resource_link':
+                return _extends._extends({
+                    type: 'resource_link',
+                    uri: item.uri
+                }, item.name ? {
+                    name: item.name
+                } : {});
+        }
+    })) != null ? _result_content_map : [];
+    // MCP clients may expose only content to the model. Keep the validated DTO
+    // readable there too, while retaining binary blocks and App structured data.
+    const text = JSON.stringify(result.structuredContent);
+    if (!content.some((item)=>item.type === 'text' && item.text === text)) content.push({
+        type: 'text',
+        text
+    });
+    return _extends._extends({
+        structuredContent: result.structuredContent,
+        content
+    }, result.isError === undefined ? {} : {
+        isError: result.isError
+    });
+}
+function agentContent(content) {
+    return (content != null ? content : []).map((item)=>{
+        if (item.type === 'image') return {
+            type: 'image_url',
+            image_url: {
+                url: `data:${item.mimeType};base64,${item.data}`
+            }
+        };
+        if (item.type === 'text') return item;
+        var _item_name;
+        if (item.type === 'resource_link') return {
+            type: 'text',
+            text: `${(_item_name = item.name) != null ? _item_name : 'Resource'}: ${item.uri}`
+        };
+        return {
+            type: 'text',
+            text: `Audio content (${item.mimeType}) is available through MCP.`
+        };
+    });
+}
+
 class DecoratedToolsetStrategy {
     validateConfig() {
         return Promise.resolve();
@@ -6265,13 +6422,27 @@ function createAgentTool(instance, descriptor, middlewareContext, middlewareOpti
     return tools.tool(async (input, config)=>{
         const parsedInput = await descriptor.options.inputSchema.parseAsync(input);
         const output = await invoke(parsedInput, agentExecutionContext(middlewareContext, middlewareOptions, config));
-        const parsedOutput = descriptor.options.outputSchema ? await descriptor.options.outputSchema.parseAsync(output) : output;
-        return stringifyDto(parsedOutput, descriptor.options.name);
+        if (descriptor.options.resultFormat === 'tool_result' && descriptor.options.outputSchema) {
+            const result = await resolveToolResult(output, (value)=>parseDecoratedToolResult(value, descriptor.options.outputSchema));
+            var _result_isError;
+            return [
+                agentContent(result.content),
+                {
+                    structuredContent: result.structuredContent,
+                    isError: (_result_isError = result.isError) != null ? _result_isError : false
+                }
+            ];
+        }
+        return resolveToolResult(output, async (value)=>{
+            const parsedOutput = descriptor.options.outputSchema ? await descriptor.options.outputSchema.parseAsync(value) : value;
+            return stringifyDto(parsedOutput, descriptor.options.name);
+        });
     }, _extends._extends({
         name: descriptor.options.name,
         description: descriptor.options.description,
         schema: descriptor.options.inputSchema,
-        verboseParsingErrors: true
+        verboseParsingErrors: true,
+        responseFormat: descriptor.options.resultFormat === 'tool_result' ? 'content_and_artifact' : 'content'
     }, descriptor.options.metadata ? {
         metadata: descriptor.options.metadata
     } : {}));
@@ -6295,7 +6466,10 @@ function createMcpTool(instance, descriptor) {
                 eligible: true
             }
         },
-        behavior: mcp.behavior,
+        behavior: mcp.behavior
+    }, mcp.defaultApprovalMode ? {
+        defaultApprovalMode: mcp.defaultApprovalMode
+    } : {}, {
         requiredContext: [
             ...mcp.requiredContext
         ],
@@ -6315,18 +6489,23 @@ function createMcpTool(instance, descriptor) {
         execute: async (input, context)=>{
             const parsedInput = await descriptor.options.inputSchema.parseAsync(input);
             const output = await invoke(parsedInput, mcpExecutionContext(context));
-            const parsedOutput = await outputSchema.parseAsync(output);
-            const dto = jsonDto(parsedOutput, descriptor.options.name);
-            var _descriptor_options_title;
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: `${(_descriptor_options_title = descriptor.options.title) != null ? _descriptor_options_title : descriptor.options.name} completed. See structuredContent for the result.`
-                    }
-                ],
-                structuredContent: dto
-            };
+            if (descriptor.options.resultFormat === 'tool_result') {
+                return resolveToolResult(output, (value)=>parseDecoratedToolResult(value, outputSchema));
+            }
+            return resolveToolResult(output, async (value)=>{
+                const parsedOutput = await outputSchema.parseAsync(value);
+                // Serialize once so text-only clients and MCP Apps receive the same JSON-safe DTO.
+                const text = stringifyDto(parsedOutput, descriptor.options.name);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text
+                        }
+                    ],
+                    structuredContent: JSON.parse(text)
+                };
+            });
         }
     });
 }
@@ -6391,9 +6570,6 @@ function stringifyDto(value, toolName) {
     if (result === undefined) throw new Error(`Tool '${toolName}' returned a non-JSON value.`);
     return result;
 }
-function jsonDto(value, toolName) {
-    return JSON.parse(stringifyDto(value, toolName));
-}
 function asI18n(value) {
     return {
         en_US: value,
@@ -6482,6 +6658,7 @@ Object.defineProperty(exports, "ASSISTANT_CONTEXT_SET_COMMAND", {
     get: function () { return contracts.ASSISTANT_CONTEXT_SET_COMMAND; }
 });
 exports.ActorTokenRuntimeCapability = modelProvider.ActorTokenRuntimeCapability;
+exports.ActorTokenRuntimeFactoryCapability = modelProvider.ActorTokenRuntimeFactoryCapability;
 exports.ArtifactsRuntimeCapability = modelProvider.ArtifactsRuntimeCapability;
 exports.BaseTool = modelProvider.BaseTool;
 exports.BaseToolset = modelProvider.BaseToolset;
@@ -6489,6 +6666,7 @@ exports.BuiltinToolset = modelProvider.BuiltinToolset;
 exports.DefaultAgentMiddlewareRuntimeCapabilityRegistry = modelProvider.DefaultRuntimeCapabilityRegistry;
 exports.DefaultRuntimeCapabilityRegistry = modelProvider.DefaultRuntimeCapabilityRegistry;
 exports.KnowledgeDocumentVisualAssetsRuntimeCapability = modelProvider.KnowledgeDocumentVisualAssetsRuntimeCapability;
+exports.KnowledgeDocumentVisualAssetsRuntimeFactoryCapability = modelProvider.KnowledgeDocumentVisualAssetsRuntimeFactoryCapability;
 exports.KnowledgebaseDocumentsRuntimeCapability = modelProvider.KnowledgebaseDocumentsRuntimeCapability;
 exports.KnowledgebaseProvisioningRuntimeCapability = modelProvider.KnowledgebaseProvisioningRuntimeCapability;
 exports.KnowledgebaseRuntimeCapability = modelProvider.KnowledgebaseRuntimeCapability;
@@ -6547,6 +6725,7 @@ exports.CollaborationDocumentProvider = CollaborationDocumentProvider;
 exports.CollaborationRuntimeCapability = CollaborationRuntimeCapability;
 exports.CommonParameterRules = CommonParameterRules;
 exports.ConnectorRuntimeCapability = ConnectorRuntimeCapability;
+exports.ConnectorRuntimeFactoryCapability = ConnectorRuntimeFactoryCapability;
 exports.ConnectorStrategyKey = ConnectorStrategyKey;
 exports.CreateModelClientCommand = CreateModelClientCommand;
 exports.CredentialsValidateFailedError = CredentialsValidateFailedError;
@@ -6571,6 +6750,7 @@ exports.DocumentSourceStrategy = DocumentSourceStrategy;
 exports.DocumentTransformerStrategy = DocumentTransformerStrategy;
 exports.EVOLUTION_RUNTIME_SERVICE_TOKEN = EVOLUTION_RUNTIME_SERVICE_TOKEN;
 exports.EVOLUTION_TARGET_PROVIDER = EVOLUTION_TARGET_PROVIDER;
+exports.EvolutionChangeRuntimeCapability = EvolutionChangeRuntimeCapability;
 exports.EvolutionRuntimeCapability = EvolutionRuntimeCapability;
 exports.EvolutionTargetProviderStrategy = EvolutionTargetProviderStrategy;
 exports.FILE_STORAGE_PROVIDER = FILE_STORAGE_PROVIDER;
@@ -6669,6 +6849,7 @@ exports.XPERT_AGENT_MIDDLEWARE_RUNTIME_TOKEN = XPERT_AGENT_MIDDLEWARE_RUNTIME_TO
 exports.XPERT_TOOL_METHOD_METADATA = XPERT_TOOL_METHOD_METADATA;
 exports.XPERT_TOOL_PROVIDER = XPERT_TOOL_PROVIDER;
 exports.XPERT_TOOL_PROVIDER_METADATA = XPERT_TOOL_PROVIDER_METADATA;
+exports.XPERT_TOOL_RESULT_FORMAT_VERSION = XPERT_TOOL_RESULT_FORMAT_VERSION;
 exports.XpFileSystem = XpFileSystem;
 exports.XpertServerPlugin = XpertServerPlugin;
 exports.XpertTool = XpertTool;
@@ -6722,6 +6903,7 @@ exports.mergeCredentials = mergeCredentials;
 exports.mergeParentChildChunks = mergeParentChildChunks;
 exports.normalizeContextSize = normalizeContextSize;
 exports.pluginArtifactTableName = pluginArtifactTableName;
+exports.prepareToolResult = prepareToolResult;
 exports.processAsyncAIGCManagedJob = processAsyncAIGCManagedJob;
 exports.renderRemoteModuleIframeHtml = renderRemoteModuleIframeHtml;
 exports.renderRemoteReactIframeHtml = renderRemoteReactIframeHtml;