@xpert-ai/plugin-sdk 3.18.1 → 3.18.2

package/model-provider.esm.js

@@ -364,4 +364,4 @@ function normalizeWorkspaceScope(scope) {
     } : {});
 }
 
-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 };
+export { ActorTokenRuntimeCapability as A, BuiltinToolset 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, BaseTool as b, createRuntimeCapability as c, BaseToolset 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.18.1",
+  "version": "3.18.2",
   "license": "AGPL-3.0",
   "repository": {
     "type": "git",
@@ -17,7 +17,7 @@
   },
   "dependencies": {
     "@langchain/openai": "0.6.9",
-    "@xpert-ai/contracts": "3.18.0",
+    "@xpert-ai/contracts": "3.18.1",
     "express": "^4.22.1",
     "js-tiktoken": "^1.0.21"
   },

package/src/index.d.ts

@@ -26,3 +26,4 @@ export * from './lib/view-extension/index';
 export * from './lib/collaboration/index';
 export * from './lib/evolution/index';
 export * from './lib/mcp/index';
+export * from './lib/tool-provider/index';

package/src/lib/ai-model/entities/defaults.d.ts

@@ -1,3 +1,3 @@
-import { ParameterRule } from "@xpert-ai/contracts";
-import { DefaultParameterName } from "./model_entities";
+import { ParameterRule } from '@xpert-ai/contracts';
+import { DefaultParameterName } from './model_entities';
 export declare const PARAMETER_RULE_TEMPLATE: Record<DefaultParameterName, ParameterRule>;

package/src/lib/core/strategy-bus.d.ts

@@ -8,10 +8,11 @@ export type StrategyBusEvent<S = any> = {
     strategyType?: string;
     pluginName: string;
     orgId: string;
+    cause?: 'refresh' | 'uninstall';
 };
 export declare class StrategyBus {
     private readonly subject;
     readonly events$: import("rxjs").Observable<StrategyBusEvent<any>>;
     upsert<S>(strategyType: string, entry: StrategyEntry<S>): void;
-    remove(orgId: string, pluginName: string): void;
+    remove(orgId: string, pluginName: string, cause?: 'refresh' | 'uninstall'): void;
 }

package/src/lib/strategy.d.ts

@@ -18,9 +18,16 @@ export declare class BaseStrategyRegistry<S> implements OnModuleInit {
     protected readonly bus: StrategyBus;
     protected strategies: Map<string, Map<string, S>>;
     protected pluginStrategies: Map<string, Set<string>>;
+    private readonly explicitSources;
     constructor(strategyKey: string, discoveryService: DiscoveryService, reflector: Reflector);
     onModuleInit(): void;
     upsert(instance: unknown): void;
+    /** Registers a host-generated adapter without mutating shared class metadata. */
+    register(type: string, instance: S, source: StrategySource): S;
+    /** Preflights adapter batches so a provider is expanded atomically across registries. */
+    assertCanRegister(type: string, instance: S, source: StrategySource): void;
+    /** Removes one exact programmatic registration without affecting fallback scopes. */
+    unregister(type: string, source: StrategySource, expected?: S): boolean;
     /** Returns the explicit registry provenance attached by the plugin loader. */
     getSource(instance: S): StrategySource;
     /**
@@ -48,6 +55,18 @@ export declare class BaseStrategyRegistry<S> implements OnModuleInit {
      * @returns
      */
     list(organizationId?: string): S[];
+    listRegistrations(organizationId?: string): Array<{
+        type: string;
+        strategy: S;
+        source: StrategySource;
+    }>;
+    /** Returns every direct registration without applying request-scope fallback rules. */
+    listAllRegistrations(): Array<{
+        type: string;
+        strategy: S;
+        source: StrategySource;
+    }>;
+    private store;
 }
 /** Returns whether a discovered provider can carry decorator metadata. */
 export declare function isStrategyInstance(instance: unknown): instance is object;

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

@@ -0,0 +1,27 @@
+import { type DynamicStructuredTool } from '@langchain/core/tools';
+import type { IXpertToolset } from '@xpert-ai/contracts';
+import type { ZodSchema } from 'zod/v3';
+import type { IAgentMiddlewareContext, IAgentMiddlewareStrategy } from '../agent/middleware/strategy.interface';
+import type { AgentMiddleware } from '../agent/middleware/types';
+import { BuiltinToolset, type TBuiltinToolsetParams } from '../toolset/builtin';
+import type { IToolsetStrategy } from '../toolset/strategy.interface';
+import type { XpertToolProviderDescriptor, XpertToolProviderInstance } from './types';
+export declare class DecoratedToolsetStrategy implements IToolsetStrategy<IXpertToolset> {
+    private readonly instance;
+    private readonly pluginName?;
+    private readonly pluginVersion?;
+    readonly descriptor: XpertToolProviderDescriptor;
+    readonly meta: IToolsetStrategy<IXpertToolset>['meta'];
+    constructor(instance: XpertToolProviderInstance, pluginName?: string, pluginVersion?: string);
+    validateConfig(): Promise<void>;
+    create(toolset: IXpertToolset, params?: TBuiltinToolsetParams): Promise<BuiltinToolset>;
+    createTools(): DynamicStructuredTool<ZodSchema>[];
+}
+export declare class DecoratedAgentMiddlewareStrategy implements IAgentMiddlewareStrategy<unknown> {
+    private readonly instance;
+    private readonly descriptor;
+    readonly provider: string;
+    readonly meta: any;
+    constructor(instance: XpertToolProviderInstance, descriptor: XpertToolProviderDescriptor, provider: string);
+    createMiddleware(options: unknown, context: IAgentMiddlewareContext): Promise<AgentMiddleware>;
+}

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

@@ -0,0 +1,20 @@
+import { OnModuleDestroy, OnModuleInit } from '@nestjs/common';
+import { DiscoveryService } from '@nestjs/core';
+import { AgentMiddlewareRegistry } from '../agent/middleware/strategy.registry';
+import { StrategyBus } from '../core/strategy-bus';
+import { ToolsetRegistry } from '../toolset/strategy.registry';
+import { XpertToolProviderRegistry } from './registry';
+/** Expands one decorated business provider into the existing Toolset and Middleware registries. */
+export declare class XpertToolProviderCoordinator implements OnModuleInit, OnModuleDestroy {
+    private readonly discovery;
+    private readonly bus;
+    private readonly providerRegistry;
+    private readonly toolsetRegistry;
+    private readonly middlewareRegistry;
+    private subscription?;
+    private readonly processed;
+    constructor(discovery: DiscoveryService, bus: StrategyBus, providerRegistry: XpertToolProviderRegistry, toolsetRegistry: ToolsetRegistry, middlewareRegistry: AgentMiddlewareRegistry);
+    onModuleInit(): void;
+    onModuleDestroy(): void;
+    private expand;
+}

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

@@ -0,0 +1,8 @@
+import type { XpertToolOptions, XpertToolProviderOptions } from './types';
+export declare const XPERT_TOOL_PROVIDER = "XPERT_TOOL_PROVIDER";
+export declare const XPERT_TOOL_PROVIDER_METADATA = "XPERT_TOOL_PROVIDER_METADATA";
+export declare const XPERT_TOOL_METHOD_METADATA = "XPERT_TOOL_METHOD_METADATA";
+/** Marks one injectable business service as a reusable Tool provider and one native MCP service. */
+export declare const XpertToolProvider: (options: XpertToolProviderOptions) => ClassDecorator;
+/** Exposes one business method through an Agent Middleware, native MCP, or both. */
+export declare const XpertTool: (options: XpertToolOptions) => MethodDecorator;

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

@@ -0,0 +1,3 @@
+import type { XpertDecoratedToolDescriptor, XpertToolProviderDescriptor } from './types';
+export declare function describeXpertToolProvider(instance: object): XpertToolProviderDescriptor;
+export declare function getXpertToolMethod(instance: object, descriptor: XpertDecoratedToolDescriptor): (input: unknown, context: unknown) => unknown;

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

@@ -0,0 +1,6 @@
+export * from './types';
+export * from './decorators';
+export * from './descriptor';
+export * from './registry';
+export * from './adapters';
+export * from './coordinator';

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

@@ -0,0 +1,10 @@
+import { DiscoveryService, Reflector } from '@nestjs/core';
+import { BaseStrategyRegistry } from '../strategy';
+import type { XpertToolProviderInstance } from './types';
+export declare class XpertToolProviderRegistry extends BaseStrategyRegistry<XpertToolProviderInstance> {
+    private readonly replacements;
+    constructor(discoveryService: DiscoveryService, reflector: Reflector);
+    upsert(candidate: unknown): void;
+    rollback(instance: XpertToolProviderInstance): void;
+    private assertUniqueClaims;
+}

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

@@ -0,0 +1,98 @@
+import type { IconDefinition, I18nObject, JsonSchemaObjectType, McpRequiredContext, 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';
+import type { IAgentMiddlewareContext } from '../agent/middleware/strategy.interface';
+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 { PromiseOrValue } from '../types';
+export type XpertBusinessToolSurface = 'middleware' | 'mcp';
+export interface XpertToolProviderMiddlewareDefinition {
+    provider: string;
+    meta: TAgentMiddlewareMeta;
+}
+export interface XpertToolProviderOptions {
+    /** Stable Builtin Toolset provider key. */
+    provider: string;
+    /** Stable plugin resource identity. */
+    componentKey: string;
+    /** Human-readable MCP service name. */
+    name: string;
+    description?: string;
+    instructions?: string;
+    /**
+     * Legacy display hint. The host owns the public Publication slug and derives it from
+     * artifactNamespace, provider, and plugin scope.
+     * @deprecated Do not couple Provider definitions to a client or public endpoint name.
+     */
+    slug?: string;
+    author?: string;
+    tags?: string[];
+    label?: I18nObject;
+    icon?: IconDefinition;
+    configSchema?: JsonSchemaObjectType;
+    defaultMiddleware?: string;
+    middlewares?: readonly XpertToolProviderMiddlewareDefinition[];
+    /** Static MCP App bundles published with this host-native Provider. */
+    apps?: readonly McpAppDefinition[];
+}
+export interface XpertMcpToolOptions {
+    behavior: McpToolBehavior;
+    requiredContext: readonly McpRequiredContext[];
+    visibility?: readonly XpertToolVisibility[];
+    /** Associates this Tool with one App declared by the owning Provider. */
+    app?: XpertToolAppBinding;
+}
+export interface XpertToolOptions<TInputSchema extends ZodTypeAny = ZodTypeAny, TOutputSchema extends ZodTypeAny = ZodTypeAny> {
+    name: string;
+    title?: string;
+    description: string;
+    inputSchema: TInputSchema;
+    outputSchema?: TOutputSchema;
+    /** true uses the class default, a string selects a declared group, false disables Middleware exposure. */
+    middleware?: true | string | false;
+    /** MCP exposure is opt-in. */
+    mcp?: XpertMcpToolOptions | false;
+    /** LangChain Tool metadata used only on the Agent Middleware surface. */
+    metadata?: Record<string, unknown>;
+}
+export interface XpertBusinessToolContext {
+    surface: XpertBusinessToolSurface;
+    tenantId: string;
+    organizationId?: string | null;
+    principal: ToolPrincipal;
+    workspaceId?: string;
+    projectId?: string;
+    conversationId?: string;
+    threadId?: string;
+    xpertId?: string;
+    agentKey?: string;
+    executionId?: string;
+    requestId?: string;
+    traceId?: string;
+    signal?: AbortSignal;
+    host: ToolHostApi;
+    middlewareOptions?: unknown;
+}
+export type XpertDecoratedToolMethod<TInputSchema extends ZodTypeAny = ZodTypeAny, TOutputSchema extends ZodTypeAny = ZodTypeAny> = (input: ZodInfer<TInputSchema>, context: XpertBusinessToolContext) => PromiseOrValue<ZodInfer<TOutputSchema>>;
+export interface XpertToolProviderInstance {
+    getMiddlewareExtensions?(provider: string, options: unknown, context: IAgentMiddlewareContext): PromiseOrValue<Omit<AgentMiddleware, 'name' | 'tools'>>;
+}
+export interface XpertDecoratedToolDescriptor {
+    methodName: string;
+    middlewareProvider?: string;
+    options: Readonly<XpertToolOptions>;
+}
+export interface XpertToolProviderDescriptor {
+    options: Readonly<XpertToolProviderOptions>;
+    tools: readonly XpertDecoratedToolDescriptor[];
+}
+export interface XpertAgentToolRunnableConfig extends RunnableConfig {
+    configurable?: RunnableConfig['configurable'] & {
+        tool_call_id?: string;
+        executionId?: string;
+        traceId?: string;
+    };
+}
+export type XpertMcpExecutionContext = ToolExecutionContext;