@xpert-ai/plugin-sdk 3.18.7 → 3.20.0

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

@@ -1,4 +1,7 @@
-/** Host-authorized identity and execution binding; never accept this from tool arguments or HTTP bodies. */
+/**
+ * Trusted host context for scoped service factories. Each capability validates its required fields;
+ * missing values do not grant broader access. Do not accept this scope from model input.
+ */
 export type RuntimeIdentityScope = {
     tenantId?: string | null;
     organizationId?: string | null;
@@ -8,7 +11,10 @@ export type RuntimeIdentityScope = {
     xpertId?: string | null;
     xpertName?: string | null;
     conversationId?: string | null;
+    /** Platform checkpoint thread, distinct from a provider session ID. */
     threadId?: string | null;
+    /** Agent entry key within the calling Assistant. */
     agentKey?: string | null;
+    /** Current platform execution; trusted adapters may supply it lazily. */
     executionId?: string | null;
 };

package/src/lib/sandbox/execution-environment.d.ts

@@ -0,0 +1,12 @@
+/** Host-declared execution guarantees. Omitted fields mean unknown, not denied. */
+export interface SandboxExecutionEnvironment {
+    readonly os?: 'linux' | 'darwin' | 'windows';
+    readonly homeDirectory?: string;
+    readonly shell?: string;
+    readonly shellState?: 'per-command' | 'persistent';
+    readonly persistentDirectories?: readonly string[];
+    readonly canInstallSystemPackages?: boolean;
+    /** Explicit opt-in capabilities implemented by this execution backend. */
+    readonly capabilities?: readonly string[];
+    readonly desktop?: boolean;
+}

package/src/lib/sandbox/execution.d.ts

@@ -1,10 +1,16 @@
 export interface SandboxExecutionOptions {
+    /** Trusted host correlation/capabilities, never part of the model-visible command schema. */
+    executionScope?: SandboxExecutionScope;
     timeoutMs?: number;
     maxOutputBytes?: number;
+    /** Request cancellation; the backend must implement guest process termination. */
+    signal?: AbortSignal;
 }
 export interface ResolvedSandboxExecutionOptions {
+    executionScope?: SandboxExecutionScope;
     timeoutMs: number;
     maxOutputBytes: number;
+    signal?: AbortSignal;
 }
 export declare const SANDBOX_SHELL_TIMEOUT_LIMITS_SEC: {
     readonly min: 1;
@@ -25,3 +31,10 @@ export declare function formatSandboxTimeout(timeoutMs: number): string;
 export declare function buildSandboxTimeoutMessage(subject: string, timeoutMs: number): string;
 export declare function appendSandboxMessage(output: string, message: string): string;
 export declare function resolveSandboxExecutionOptions(options?: SandboxExecutionOptions, defaults?: SandboxExecutionOptions): ResolvedSandboxExecutionOptions;
+export interface SandboxExecutionScope {
+    parentExecutionId: string;
+    conversationId: string;
+    toolCallId: string;
+    /** Environment capabilities selected by the Assistant's middleware configuration. */
+    capabilities: readonly string[];
+}

package/src/lib/sandbox/index.d.ts

@@ -1,4 +1,5 @@
 export * from './execution';
+export * from './execution-environment';
 export * from './managed-service';
 export * from './protocol';
 export * from './sandbox';

package/src/lib/sandbox/managed-service.d.ts

@@ -50,6 +50,7 @@ export type SandboxManagedServiceRestartOptions = {
 export type SandboxManagedServiceStartResult = SandboxManagedServiceStateChange;
 export interface SandboxManagedServiceAdapter {
     getServiceLogs(options: SandboxManagedServiceLogsOptions): MaybePromise<TSandboxManagedServiceLogs>;
+    /** Inspect existing services only; do not create or recover a runtime during discovery. */
     listServices(options: SandboxManagedServiceListOptions): MaybePromise<SandboxManagedServiceListResult>;
     restartService(options: SandboxManagedServiceRestartOptions): MaybePromise<SandboxManagedServiceStartResult>;
     startService(options: SandboxManagedServiceStartOptions): MaybePromise<SandboxManagedServiceStartResult>;

package/src/lib/sandbox/protocol.d.ts

@@ -318,6 +318,8 @@ export interface BackendProtocol extends IBackendProtocol {
  * and communicate via defined interfaces.
  */
 export interface SandboxBackendProtocol extends BackendProtocol {
+    /** Optional host guarantees; do not infer missing facts from the backend ID. */
+    readonly executionEnvironment?: import('./execution-environment').SandboxExecutionEnvironment;
     /**
      * Execute a command in the sandbox.
      *

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

@@ -64,6 +64,12 @@ export interface XpertToolOptions<TInputSchema extends ZodTypeAny = ZodTypeAny,
     resultFormat?: 'dto' | 'tool_result';
     /** true uses the class default, a string selects a declared group, false disables Middleware exposure. */
     middleware?: true | string | false;
+    /** Native middleware App exposure; does not publish an MCP endpoint. */
+    app?: {
+        resourceKey?: string;
+        visibility: readonly ('model' | 'app')[];
+        approval?: 'required' | 'none';
+    };
     /** MCP exposure is opt-in. */
     mcp?: XpertMcpToolOptions | false;
     /** LangChain Tool metadata used only on the Agent Middleware surface. */

package/src/lib/types.d.ts

@@ -1,4 +1,4 @@
-import { IconDefinition, I18nObject, JsonSchemaObjectType, PluginMeta, PluginTargetApp, PluginTargetAppMeta, TAvatar, type TPromptWorkflow, XpertTemplatePluginDependencies, XpertTypeEnum } from '@xpert-ai/contracts';
+import { AssistantCapabilityDeclaration, IconDefinition, I18nObject, JsonSchemaObjectType, PluginMeta, PluginTargetApp, PluginTargetAppMeta, TAvatar, type TPromptWorkflow, XpertTemplatePluginDependencies, XpertTypeEnum } from '@xpert-ai/contracts';
 import type { DynamicModule, INestApplicationContext } from '@nestjs/common';
 import { ModuleRef } from '@nestjs/core';
 import type { ZodSchema } from 'zod/v3';
@@ -84,6 +84,7 @@ export interface XpertTemplateContribution {
     pluginVersion?: string;
     contentHash?: string;
     xpertName?: string;
+    capabilities?: AssistantCapabilityDeclaration[];
     dependencies?: XpertTemplatePluginDependencies;
     [key: string]: unknown;
 }

package/src/lib/workflow/trigger/strategy.interface.d.ts

@@ -1,4 +1,4 @@
-import { TWorkflowTriggerMeta, TXpertTeamNode } from '@xpert-ai/contracts';
+import { TWorkflowTriggerConnectionStatus, TWorkflowTriggerMeta, TXpertTeamNode } from '@xpert-ai/contracts';
 export type TWorkflowTriggerBootstrapMode = 'replay_publish' | 'skip';
 export type TWorkflowTriggerBootstrapConfig = {
     mode: TWorkflowTriggerBootstrapMode;
@@ -21,6 +21,7 @@ export interface IWorkflowTriggerStrategy<T> {
      */
     bootstrap?: TWorkflowTriggerBootstrapConfig;
     validate(payload: TWorkflowTriggerParams<T>): Promise<any[]>;
+    connectionStatus?(config: T): Promise<Pick<TWorkflowTriggerConnectionStatus, 'connected' | 'state'>>;
     /**
      * Initialize the trigger when publish xpert workflow
      *