@xpert-ai/plugin-sdk 3.17.2 → 3.17.4

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @xpert-ai/plugin-sdk
 
+## 3.17.4
+
+### Patch Changes
+
+- 7b6954a: project
+- Updated dependencies [7b6954a]
+  - @xpert-ai/contracts@3.17.4
+
+## 3.17.3
+
+### Patch Changes
+
+- 754866e: Add reusable enterprise H5 identity and single-assistant session contracts.
+- Updated dependencies [754866e]
+  - @xpert-ai/contracts@3.17.3
+
 ## 3.17.2
 
 ### Patch Changes

package/index.cjs.js

@@ -5772,6 +5772,7 @@ exports.KnowledgebaseDocumentsRuntimeCapability = modelProvider.KnowledgebaseDoc
 exports.KnowledgebaseProvisioningRuntimeCapability = modelProvider.KnowledgebaseProvisioningRuntimeCapability;
 exports.KnowledgebaseRuntimeCapability = modelProvider.KnowledgebaseRuntimeCapability;
 exports.ModelProviderBuiltinToolset = modelProvider.ModelProviderBuiltinToolset;
+exports.ProjectProvisioningRuntimeCapability = modelProvider.ProjectProvisioningRuntimeCapability;
 exports.SANDBOX_JOB_ERROR_CODES = modelProvider.SANDBOX_JOB_ERROR_CODES;
 exports.SANDBOX_JOB_PROGRESS_PREFIX = modelProvider.SANDBOX_JOB_PROGRESS_PREFIX;
 exports.SandboxJobRuntimeError = modelProvider.SandboxJobRuntimeError;

package/index.esm.js

@@ -16,7 +16,7 @@ import fs__default from 'fs';
 import http from 'http';
 import https from 'https';
 import { c as createRuntimeCapability } from './model-provider.esm.js';
-export { A as ActorTokenRuntimeCapability, a as ArtifactsRuntimeCapability, B as BaseTool, b as BaseToolset, d as BuiltinToolset, D as DefaultAgentMiddlewareRuntimeCapabilityRegistry, D as DefaultRuntimeCapabilityRegistry, K as KnowledgeDocumentVisualAssetsRuntimeCapability, e as KnowledgebaseDocumentsRuntimeCapability, f as KnowledgebaseProvisioningRuntimeCapability, g as KnowledgebaseRuntimeCapability, M as ModelProviderBuiltinToolset, S as SANDBOX_JOB_ERROR_CODES, h as SANDBOX_JOB_PROGRESS_PREFIX, i as SandboxJobRuntimeError, j as SandboxJobsRuntimeCapability, W as WORKSPACE_FILES_SOURCE, k as WorkspaceFilesRuntimeCapability, X as XPERT_RUNTIME_CAPABILITIES_TOKEN, l as isSandboxJobRuntimeError } from './model-provider.esm.js';
+export { A as ActorTokenRuntimeCapability, a as ArtifactsRuntimeCapability, B as BaseTool, b as BaseToolset, d as BuiltinToolset, D as DefaultAgentMiddlewareRuntimeCapabilityRegistry, D as DefaultRuntimeCapabilityRegistry, K as KnowledgeDocumentVisualAssetsRuntimeCapability, e as KnowledgebaseDocumentsRuntimeCapability, f as KnowledgebaseProvisioningRuntimeCapability, g as KnowledgebaseRuntimeCapability, M as ModelProviderBuiltinToolset, P as ProjectProvisioningRuntimeCapability, S as SANDBOX_JOB_ERROR_CODES, h as SANDBOX_JOB_PROGRESS_PREFIX, i as SandboxJobRuntimeError, j as SandboxJobsRuntimeCapability, W as WORKSPACE_FILES_SOURCE, k as WorkspaceFilesRuntimeCapability, X as XPERT_RUNTIME_CAPABILITIES_TOKEN, l as isSandboxJobRuntimeError } from './model-provider.esm.js';
 import fsPromises from 'fs/promises';
 import * as path from 'path';
 import path__default, { join } from 'path';

package/model-provider.cjs.js

@@ -194,7 +194,7 @@ const ArtifactsRuntimeCapability = createRuntimeCapability('platform.artifacts',
 
 /** Stable source identifier for portable workspace file references. */ const WORKSPACE_FILES_SOURCE = 'platform.workspace.files';
 const WorkspaceFilesRuntimeCapability = createRuntimeCapability('platform.workspace.files', {
-    description: 'Upload, understand, resolve, read, and delete raw files in Xpert workspace volumes.'
+    description: 'Upload, understand, search parsed chunks, resolve, read, and delete files in Xpert workspace volumes.'
 });
 
 /** Stable machine-readable failures emitted by the Sandbox Jobs capability. */ const SANDBOX_JOB_ERROR_CODES = [
@@ -236,6 +236,10 @@ const SANDBOX_JOB_ERROR_CODE_SET = new Set(SANDBOX_JOB_ERROR_CODES);
     description: 'Run registered plugin actions in isolated, short-lived Sandbox Runtime jobs.'
 });
 
+const ProjectProvisioningRuntimeCapability = createRuntimeCapability('platform.project.provisioning', {
+    description: 'Idempotently provision a platform Chat Project and connect it to an Assistant.'
+});
+
 /**
  * Shared host-runtime plumbing for built-in tools backed by a configured model provider.
  * Provider request/response semantics remain owned by each plugin.
@@ -342,6 +346,7 @@ exports.KnowledgebaseDocumentsRuntimeCapability = KnowledgebaseDocumentsRuntimeC
 exports.KnowledgebaseProvisioningRuntimeCapability = KnowledgebaseProvisioningRuntimeCapability;
 exports.KnowledgebaseRuntimeCapability = KnowledgebaseRuntimeCapability;
 exports.ModelProviderBuiltinToolset = ModelProviderBuiltinToolset;
+exports.ProjectProvisioningRuntimeCapability = ProjectProvisioningRuntimeCapability;
 exports.SANDBOX_JOB_ERROR_CODES = SANDBOX_JOB_ERROR_CODES;
 exports.SANDBOX_JOB_PROGRESS_PREFIX = SANDBOX_JOB_PROGRESS_PREFIX;
 exports.SandboxJobRuntimeError = SandboxJobRuntimeError;

package/model-provider.esm.js

@@ -192,7 +192,7 @@ const ArtifactsRuntimeCapability = createRuntimeCapability('platform.artifacts',
 
 /** Stable source identifier for portable workspace file references. */ const WORKSPACE_FILES_SOURCE = 'platform.workspace.files';
 const WorkspaceFilesRuntimeCapability = createRuntimeCapability('platform.workspace.files', {
-    description: 'Upload, understand, resolve, read, and delete raw files in Xpert workspace volumes.'
+    description: 'Upload, understand, search parsed chunks, resolve, read, and delete files in Xpert workspace volumes.'
 });
 
 /** Stable machine-readable failures emitted by the Sandbox Jobs capability. */ const SANDBOX_JOB_ERROR_CODES = [
@@ -234,6 +234,10 @@ const SANDBOX_JOB_ERROR_CODE_SET = new Set(SANDBOX_JOB_ERROR_CODES);
     description: 'Run registered plugin actions in isolated, short-lived Sandbox Runtime jobs.'
 });
 
+const ProjectProvisioningRuntimeCapability = createRuntimeCapability('platform.project.provisioning', {
+    description: 'Idempotently provision a platform Chat Project and connect it to an Assistant.'
+});
+
 /**
  * Shared host-runtime plumbing for built-in tools backed by a configured model provider.
  * Provider request/response semantics remain owned by each plugin.
@@ -329,4 +333,4 @@ function normalizeOptionalString(value) {
     return normalized || undefined;
 }
 
-export { ActorTokenRuntimeCapability as A, BaseTool as B, DefaultRuntimeCapabilityRegistry as D, KnowledgeDocumentVisualAssetsRuntimeCapability as K, ModelProviderBuiltinToolset as M, 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, 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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xpert-ai/plugin-sdk",
-  "version": "3.17.2",
+  "version": "3.17.4",
   "license": "AGPL-3.0",
   "repository": {
     "type": "git",
@@ -17,7 +17,7 @@
   },
   "dependencies": {
     "@langchain/openai": "0.6.9",
-    "@xpert-ai/contracts": "3.17.2",
+    "@xpert-ai/contracts": "3.17.4",
     "express": "^4.22.1",
     "js-tiktoken": "^1.0.21"
   },

package/src/lib/agent/middleware/capabilities/assistant-task.d.ts

@@ -12,6 +12,17 @@ export type AgentMiddlewareAssistantTaskFile = {
     size?: number;
     role?: string;
 };
+/**
+ * Stable plugin skill reference used by Assistant Tasks.
+ *
+ * Plugin-owned callers must not persist workspace-local SkillPackage UUIDs.
+ * The host resolves this portable identity to the installed package and verifies
+ * that the target Agent is directly connected to the owning Skills Middleware.
+ */
+export type AgentMiddlewareAssistantTaskSkillRef = {
+    pluginName: string;
+    componentKey: string;
+};
 export type AgentMiddlewareAssistantTaskInput = {
     xpertId: string;
     agentKey?: string;
@@ -22,6 +33,8 @@ export type AgentMiddlewareAssistantTaskInput = {
     clientMessageId?: string;
     prompt: string;
     files?: AgentMiddlewareAssistantTaskFile[];
+    /** Skills that this task is expected to load through its target Agent's Skills Middleware. */
+    selectedSkillRefs?: AgentMiddlewareAssistantTaskSkillRef[];
     /** Additional bounded human-input fields exposed to runtime-state fixed filters. */
     humanInput?: Record<string, JSONValue>;
     context?: Record<string, unknown>;

package/src/lib/integration/strategy.interface.d.ts

@@ -1,4 +1,4 @@
-import { IIntegration, TIntegrationProvider } from '@xpert-ai/contracts';
+import { IIntegration, TEnterpriseH5IdentityGrant, TIntegrationProvider } from '@xpert-ai/contracts';
 export type TIntegrationStrategyParams = {
     query: string;
 };
@@ -14,10 +14,30 @@ export type IntegrationTestResult = {
     warnings?: string[];
     probe?: IntegrationTestProbe;
 } & Record<string, unknown>;
+/** Identity proof accepted by an integration strategy for enterprise H5 exchange. */
+export type IntegrationIdentityGrant = TEnterpriseH5IdentityGrant;
+/** Public integration data required before the browser requests an identity grant. */
+export type IntegrationIdentityBootstrap = {
+    externalOrganizationId: string;
+    clientConfig: Record<string, unknown>;
+};
+/** Enterprise identity verified by an integration, with optional Xpert account binding. */
+export type IntegrationExternalIdentity = {
+    provider: string;
+    externalOrganizationId: string;
+    subjectId: string;
+    displayName?: string;
+    accountBinding?: {
+        provider: string;
+        subjectId: string;
+    };
+};
 export interface IntegrationStrategy<T = unknown> {
     meta: TIntegrationProvider;
     execute(integration: IIntegration<T>, payload: TIntegrationStrategyParams): Promise<any>;
     onUpdate?(previous: IIntegration<T>, current: IIntegration<any>): Promise<void> | void;
     onDelete?(integration: IIntegration<T>): Promise<void> | void;
     validateConfig?(config: T, integration?: IIntegration<T>): Promise<void | IntegrationTestResult>;
+    getIdentityBootstrap?(integration: IIntegration<T>): Promise<IntegrationIdentityBootstrap>;
+    exchangeIdentity?(integration: IIntegration<T>, grant: IntegrationIdentityGrant): Promise<IntegrationExternalIdentity>;
 }

package/src/lib/runtime/capabilities/index.d.ts

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

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

@@ -0,0 +1,30 @@
+/** Lifecycle states that plugin-managed Projects may synchronize to the platform. */
+export type ProjectProvisioningStatus = 'active' | 'archived';
+/** Stable identity and desired state for an idempotently provisioned Chat Project. */
+export type ProjectEnsureInput = {
+    /** Caller-generated id reused across retries to prevent duplicate Projects. */
+    projectId: string;
+    /** Workspace that owns both the Project and connected Assistant. */
+    workspaceId: string;
+    /** Assistant that must be connected to the Project. */
+    xpertId: string;
+    /** Current business-project display name. */
+    name: string;
+    /** Current business-project lifecycle state. */
+    status: ProjectProvisioningStatus;
+};
+/** Effective Project state after an idempotent ensure operation. */
+export type ProjectEnsureResult = {
+    projectId: string;
+    workspaceId: string;
+    /** Complete set of Assistants connected after synchronization. */
+    xpertIds: string[];
+    /** Whether this call inserted the Project or reconciled an existing one. */
+    operation: 'created' | 'updated';
+};
+/** Host API exposed to plugins that own one-to-one business Project mappings. */
+export interface ProjectProvisioningApi {
+    /** Create or reconcile a Chat Project without changing its caller-supplied id. */
+    ensure(input: ProjectEnsureInput): Promise<ProjectEnsureResult>;
+}
+export declare const ProjectProvisioningRuntimeCapability: import("../../core/runtime-capability").RuntimeCapabilityKey<ProjectProvisioningApi>;

package/src/lib/runtime/capabilities/workspace-files.d.ts

@@ -184,6 +184,49 @@ export type WorkspaceValidatedUnderstandingReference = {
     anchor?: Record<string, unknown>;
     excerpt: string;
 };
+/** Scoped, bounded FileChunk DTO for plugin-owned evidence mapping. */
+export type WorkspaceUnderstandingChunk = {
+    /** FileAsset that owns the parsed chunk. */
+    fileAssetId: string;
+    /** Stable FileChunk identifier suitable for evidence references. */
+    chunkId: string;
+    /** Parser order within the source document. */
+    orderNo: number;
+    /** Parser-specific page, sheet, slide, or block location. */
+    anchor?: Record<string, unknown>;
+    /** Bounded source text; callers must not assume it contains the whole file. */
+    content: string;
+};
+/** Input for paging an already parsed FileAsset without creating a second index. */
+export type WorkspaceListUnderstandingChunksInput = WorkspaceFileScope & {
+    fileAssetId: string;
+    /** One-based page number. */
+    page?: number;
+    /** Page size clamped by the host. */
+    pageSize?: number;
+    /** Maximum characters returned for each chunk. */
+    contentLength?: number;
+};
+/** One bounded page from the FileAsset's existing FileChunk index. */
+export type WorkspaceUnderstandingChunkPage = {
+    fileAssetId: string;
+    /** Chunks in parser order for the requested page. */
+    items: WorkspaceUnderstandingChunk[];
+    page: number;
+    pageSize: number;
+    /** True when another bounded page can be requested. */
+    hasMore: boolean;
+};
+/** Input for hybrid search over a FileAsset's existing FileChunk index. */
+export type WorkspaceSearchUnderstandingChunksInput = WorkspaceFileScope & {
+    fileAssetId: string;
+    /** Natural-language or keyword query evaluated by the platform hybrid index. */
+    query: string;
+    /** Result count clamped by the host. */
+    limit?: number;
+    /** Maximum characters returned for each matching chunk. */
+    contentLength?: number;
+};
 /**
  * Runtime capability contract for reading, writing, uploading, deleting, and
  * understanding files in Xpert workspace Volumes.
@@ -199,6 +242,10 @@ export interface WorkspaceFilesApi {
     retryUnderstanding(input: WorkspaceRetryUnderstandingInput): Promise<WorkspaceUnderstandingStatus>;
     /** Validate bounded FileAsset/chunk evidence without returning complete file contents. */
     validateUnderstandingReferences(input: WorkspaceValidateUnderstandingReferencesInput): Promise<WorkspaceValidatedUnderstandingReference[]>;
+    /** List one bounded page of parsed chunks after enforcing FileAsset workspace scope. */
+    listUnderstandingChunks(input: WorkspaceListUnderstandingChunksInput): Promise<WorkspaceUnderstandingChunkPage>;
+    /** Search the existing FileChunk hybrid index without creating another embedding index. */
+    searchUnderstandingChunks(input: WorkspaceSearchUnderstandingChunksInput): Promise<WorkspaceUnderstandingChunk[]>;
     /**
      * Resolve metadata and an openable URL for an explicitly scoped workspace
      * file without reading its bytes into the API process.