@xpert-ai/plugin-sdk 3.19.0 → 3.21.0

package/src/lib/project-task/index.d.ts

@@ -1,5 +1,5 @@
 import { DiscoveryService, Reflector } from '@nestjs/core';
-import type { ProjectTaskGraph, ProjectTaskGraphChange, ProjectTaskExecutionTarget, TXpertProjectTaskStatus } from '@xpert-ai/contracts';
+import type { ProjectTaskGraph, ProjectTaskGraphChange, ProjectTaskExecutionTarget, ProjectTaskTypeDefinition, TXpertProjectTaskStatus } from '@xpert-ai/contracts';
 import { BaseStrategyRegistry } from '../strategy';
 import type { ProjectAccessActor } from '../runtime/capabilities/project-access';
 export interface ProjectTaskContext {
@@ -10,7 +10,11 @@ export interface ProjectTaskProjection {
     key: string;
     title: string;
     status: TXpertProjectTaskStatus;
+    /** Completion percentage (0–100), independent of status. Omit to preserve; null clears it. */
+    progress?: number | null;
     kind: 'task' | 'summary' | 'milestone';
+    /** Registered business type; omitted values preserve legacy persisted types. Null explicitly clears it. */
+    taskType?: string | null;
     parentKey?: string;
     predecessorKeys: string[];
     diagnostic?: string;
@@ -37,6 +41,8 @@ export interface ProjectTaskSnapshot {
 }
 export interface IProjectTaskProvider {
     readonly key: string;
+    /** Presentation declarations belong to this provider and never contain executable icon code. */
+    readonly taskTypes?: readonly ProjectTaskTypeDefinition[];
     /** Return null when the project is not owned by this provider. Always scope domain reads. */
     snapshot(context: ProjectTaskContext): Promise<ProjectTaskSnapshot | null>;
     /** Called after projection commits; retries must be idempotent. Never start work here. */
@@ -45,6 +51,7 @@ export interface IProjectTaskProvider {
         taskId: string;
     }>): Promise<void>;
 }
+export type { ProjectTaskIconName, ProjectTaskTypeDefinition, ProjectTaskTypePresentation } from '@xpert-ai/contracts';
 export declare const PROJECT_TASK_PROVIDER = "PROJECT_TASK_PROVIDER";
 export declare const ProjectTaskProvider: (key: string) => <TFunction extends Function, Y>(target: TFunction | object, propertyKey?: string | symbol, descriptor?: TypedPropertyDescriptor<Y>) => void;
 export declare class ProjectTaskProviderRegistry extends BaseStrategyRegistry<IProjectTaskProvider> {

package/src/lib/project-type/index.d.ts

@@ -1,6 +1,7 @@
 import { DiscoveryService, Reflector } from '@nestjs/core';
-import type { XpertProjectTypeRef } from '@xpert-ai/contracts';
+import type { XpertProjectTypeRef, ConversationResourceCard } from '@xpert-ai/contracts';
 import { BaseStrategyRegistry } from '../strategy';
+export type { XpertProjectTypeRef, ConversationResourceCard };
 export interface ProjectTypeContext extends XpertProjectTypeRef {
     tenantId: string;
     organizationId?: string | null;
@@ -29,6 +30,11 @@ export interface ConversationProjectCreation {
     conversationId: string;
     workspaceId: string;
     name: string;
+    /** Present only for a human-confirmed setup; the application validates its own configuration. */
+    confirmation?: {
+        id: string;
+        configuration: object;
+    };
     /**
      * Persist only application records through this writer. The host creates the
      * platform Project and binds the conversation in the same transaction. Do not
@@ -54,6 +60,7 @@ export interface IProjectTypeProvider {
     createForConversation?(context: ProjectTypeContext, input: ConversationProjectCreation): Promise<ProjectTypeBinding & {
         name: string;
         status: 'active';
+        resourceCards?: ConversationResourceCard[];
     }>;
 }
 export declare const PROJECT_TYPE_PROVIDER = "PROJECT_TYPE_PROVIDER";

package/src/lib/rag/capability/index.d.ts

@@ -0,0 +1,5 @@
+export * from './knowledgebase';
+export * from './knowledge-graph';
+export * from './knowledgebase-documents';
+export * from './knowledge-upload-sessions';
+export * from './knowledge-document-visual-assets';

package/src/lib/{runtime/capabilities → rag/capability}/knowledge-document-visual-assets.d.ts

@@ -1,5 +1,5 @@
-import type { RuntimeIdentityScope } from '../runtime-scope';
-import type { WorkspaceFilesApi, WorkspacePortableFileReference } from './workspace-files';
+import type { RuntimeIdentityScope } from '../../runtime/runtime-scope';
+import type { WorkspaceFilesApi, WorkspacePortableFileReference } from '../../runtime/capabilities/workspace-files';
 export type KnowledgeDocumentVisualCandidateReason = 'same_block' | 'same_chunk' | 'same_page' | 'adjacent_page' | 'visual_summary_match' | 'visual_only_fallback';
 export type KnowledgeDocumentVisualTextAnchor = {
     page?: number;

package/src/lib/rag/capability/knowledge-upload-sessions.d.ts

@@ -0,0 +1,71 @@
+/** Persisted upload progress within one knowledgebase; completion does not imply document import or processing. */
+export type KnowledgeUploadSession = {
+    /** Host-generated session UUID, used together with the owning knowledgebaseId. */
+    id: string;
+    /** Display file name; not a storage path. */
+    name: string;
+    /** Expected total file size in bytes. */
+    size: number;
+    /** Host-selected part size in bytes; only the final part may be shorter. */
+    chunkSize: number;
+    /** Persisted zero-based part indexes, sorted in ascending order; gaps identify missing parts. */
+    received: number[];
+    /** Lowercase hexadecimal SHA-256 of each received part, keyed by its decimal index. */
+    partHashes: Record<string, string>;
+    /** True after complete() verifies all expected parts and records the whole-file hash. */
+    complete: boolean;
+    /** Lowercase hexadecimal SHA-256 of the whole file, available after successful completion. */
+    sha256?: string;
+};
+/** Server-only staged uploads exposed through Documents.uploads. Every operation revalidates Knowledge write access. */
+export interface KnowledgeUploadSessionsApi {
+    /**
+     * Create a new upload session without creating or processing a document.
+     * size is the total byte count (positive, currently at most 2 GiB); use the returned chunkSize for part boundaries.
+     */
+    create(input: {
+        knowledgebaseId: string;
+        name: string;
+        size: number;
+    }): Promise<KnowledgeUploadSession>;
+    /** Read persisted progress and part hashes to resume an existing session, including after a server restart. */
+    status(input: {
+        knowledgebaseId: string;
+        sessionId: string;
+    }): Promise<KnowledgeUploadSession>;
+    /**
+     * Persist one zero-based part; parts may arrive out of order.
+     * buffer must match the expected part length and sha256 must be its lowercase hexadecimal SHA-256.
+     * Retrying identical bytes is safe; conflicting bytes for an existing index are rejected.
+     */
+    append(input: {
+        knowledgebaseId: string;
+        sessionId: string;
+        index: number;
+        buffer: Buffer;
+        sha256: string;
+    }): Promise<void>;
+    /**
+     * Verify all parts and their lengths, then record the whole-file SHA-256 and mark the session complete.
+     * Incomplete uploads fail; repeated completion is safe. Does not import documents or start processing.
+     */
+    complete(input: {
+        knowledgebaseId: string;
+        sessionId: string;
+    }): Promise<KnowledgeUploadSession>;
+    /**
+     * Read bytes from a completed upload, including ranges that cross part boundaries, for streaming ZIP readers.
+     * offset is zero-based; length is nonnegative, at most chunkSize, and offset + length must not exceed size.
+     */
+    read(input: {
+        knowledgebaseId: string;
+        sessionId: string;
+        offset: number;
+        length: number;
+    }): Promise<Buffer>;
+    /** Delete an existing session and its staged bytes; previously imported documents are unaffected. */
+    remove(input: {
+        knowledgebaseId: string;
+        sessionId: string;
+    }): Promise<void>;
+}

package/src/lib/{runtime/capabilities → rag/capability}/knowledgebase-documents.d.ts

@@ -1,5 +1,6 @@
 import { type I18nObject, type DocumentTextParserConfig, type DocumentSheetParserConfig, JSONValue } from '@xpert-ai/contracts';
-import type { WorkspacePortableFileReference } from './workspace-files';
+import type { WorkspacePortableFileReference } from '../../runtime/capabilities/workspace-files';
+import type { KnowledgeUploadSessionsApi } from './knowledge-upload-sessions';
 export type KnowledgebaseDocumentFile = {
     buffer: Buffer;
     originalname?: string;
@@ -60,6 +61,9 @@ export type KnowledgebaseListDocumentsInput = {
     page?: number;
     pageSize?: number;
     search?: string;
+    /** Literal substring search; paths include the logical folder and imported originalRelativePath. */
+    searchFields?: Array<'name' | 'path'>;
+    mimeTypes?: string[];
     includeFolders?: boolean;
     /** List direct children of this folder. Use null for the knowledgebase root. */
     parentId?: string | null;
@@ -110,6 +114,8 @@ export type KnowledgebaseUploadedFile = {
 };
 export type KnowledgebaseCreateDocumentsInput = {
     knowledgebaseId: string;
+    /** Retry key, scoped to this Knowledge base. Repeated creation returns the original documents. */
+    idempotencyKey?: string;
     documents: KnowledgebaseDocumentDraft[];
     parserConfig?: KnowledgebaseDocumentParserConfig;
     metadata?: KnowledgebaseDocumentMetadata;
@@ -266,6 +272,8 @@ export type KnowledgebaseProcessingOptionsResult = {
     parserConfig: DocumentTextParserConfig & Partial<DocumentSheetParserConfig>;
 };
 export interface KnowledgebaseDocumentsApi {
+    /** Stage resumable uploads without starting document processing. */
+    readonly uploads: KnowledgeUploadSessionsApi;
     getProcessingOptions(input: KnowledgebaseProcessingOptionsInput): Promise<KnowledgebaseProcessingOptionsResult>;
     readText(input: KnowledgebaseReadTextInput): Promise<KnowledgebaseReadTextResult>;
     /** Missing/stale conversion snapshots fail explicitly; this never falls back to indexed chunks. */

package/src/lib/{runtime/capabilities → rag/capability}/knowledgebase.d.ts

@@ -31,6 +31,8 @@ export type KnowledgebaseSearchResult = {
     diagnostics: KnowledgeFilterDiagnostics[];
 };
 export type KnowledgebaseListInput = {
+    /** Tenant-owned public libraries, readable by tenant members. */
+    scope?: 'workspace' | 'tenant';
     workspaceId?: string | null;
     published?: boolean;
     limit?: number;
@@ -135,6 +137,8 @@ export type KnowledgebaseProvisioningSpec = {
     };
 };
 export type KnowledgebaseEnsureInput = {
+    /** Tenant provisioning requires SUPER_ADMIN already in tenant request scope; workspaceId supplies model discovery only. */
+    scope?: 'workspace' | 'tenant';
     workspaceId: string;
     namespace: string;
     /**

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

@@ -6,3 +6,4 @@ export * from './types';
 export * from './image/index';
 export * from './knowledge/index';
 export * from './analyzer/index';
+export * from './capability/index';

package/src/lib/resource-card-provider/index.d.ts

@@ -0,0 +1,3 @@
+export * from './types';
+export * from './provider.decorator';
+export * from './provider.registry';

package/src/lib/resource-card-provider/provider.decorator.d.ts

@@ -0,0 +1,4 @@
+import type { ResourceCardType } from './types';
+export declare const RESOURCE_CARD_PROVIDER = "RESOURCE_CARD_PROVIDER";
+/** Register exact resource types whose message cards opt in to live refresh. */
+export declare const ResourceCardProvider: (...resources: ResourceCardType[]) => <TFunction extends Function, Y>(target: TFunction | object, propertyKey?: string | symbol, descriptor?: TypedPropertyDescriptor<Y>) => void;

package/src/lib/resource-card-provider/provider.registry.d.ts

@@ -0,0 +1,14 @@
+import { type OnModuleDestroy } from '@nestjs/common';
+import { DiscoveryService, Reflector } from '@nestjs/core';
+import { BaseStrategyRegistry } from '../strategy';
+import type { IResourceCardProvider, ResourceCardType } from './types';
+export declare class ResourceCardProviderRegistry extends BaseStrategyRegistry<IResourceCardProvider> implements OnModuleDestroy {
+    private readonly resourceLogger;
+    private subscription?;
+    constructor(discovery: DiscoveryService, reflector: Reflector);
+    onModuleInit(): void;
+    onModuleDestroy(): void;
+    remove(scopeKey: string, pluginName: string): void;
+    upsert(instance: unknown): void;
+    find(resource: ResourceCardType, organizationId?: string): IResourceCardProvider | undefined;
+}

package/src/lib/resource-card-provider/types.d.ts

@@ -0,0 +1,36 @@
+import type { ConversationResourceCard } from '@xpert-ai/contracts';
+export interface ResourceCardType {
+    namespace: string;
+    type: string;
+}
+export interface ResourceCardContext {
+    tenantId: string;
+    organizationId?: string | null;
+    userId: string;
+    conversationId: string;
+    threadId: string;
+    projectId?: string | null;
+    /** Stop external reads when the host's observation deadline expires. */
+    signal: AbortSignal;
+}
+export interface ResourceCardReadRequest {
+    /** Opaque correlation key. Echo it; never choose another message binding. */
+    key: string;
+    card: ConversationResourceCard;
+    messageId: string;
+    executionId?: string;
+}
+export type ResourceCardResolution = {
+    key: string;
+} & ({
+    status: 'resolved';
+    card: ConversationResourceCard;
+} | {
+    status: 'unavailable';
+    reason: 'forbidden' | 'not_found';
+});
+/** Optional live presentation of committed resources; never starts work or changes business state. */
+export interface IResourceCardProvider {
+    /** Recheck resource access for the host-supplied actor and return one result per request. */
+    resolveMany(context: ResourceCardContext, requests: readonly ResourceCardReadRequest[]): Promise<readonly ResourceCardResolution[]>;
+}

package/src/lib/resource-card.d.ts

@@ -0,0 +1,6 @@
+import type { RunnableConfig } from '@langchain/core/runnables';
+import { type ConversationResourceCard } from '@xpert-ai/contracts';
+export { createResourceCardContent, parseResourceCard, resourceCardId } from '@xpert-ai/contracts';
+export type { ConversationResourceCard, ResourceCardContent, ResourceCardField, ResourceCardFile, ResourceCardFileReference, ResourceCardImage, ResourceCardOpenTarget, ResourceCardScalar, TMessageContentResourceCard } from '@xpert-ai/contracts';
+/** Call after the business mutation commits. A display failure must not retry that mutation. */
+export declare function emitResourceCard(card: ConversationResourceCard, config?: RunnableConfig): Promise<void>;

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

@@ -1,10 +1,7 @@
-export * from './knowledgebase';
-export * from './knowledge-graph';
-export * from './knowledgebase-documents';
-export * from './knowledge-document-visual-assets';
 export * from './actor-token';
 export * from './artifacts';
 export * from './workspace-files';
 export * from './sandbox-jobs';
 export * from './project-provisioning';
 export * from './project-access';
+export * from './tool-images';

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

@@ -38,6 +38,16 @@ export type ProjectEnsureResult = {
 };
 /** Host API exposed to plugins that own one-to-one business Project mappings. */
 export interface ProjectProvisioningApi {
+    /** App-only confirmation of a pending conversation's first Project; never moves an existing binding. */
+    confirmConversation?(input: {
+        conversationId: string;
+        xpertId: string;
+        confirmationId: string;
+        name: string;
+        configuration: object;
+    }): Promise<{
+        projectId: string;
+    }>;
     /** 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. */

package/src/lib/runtime/capabilities/tool-images.d.ts

@@ -0,0 +1,24 @@
+import type { BaseMessage } from '@langchain/core/messages';
+import type { ToolOutputImageAttachment, ToolOutputPresentation } from '@xpert-ai/chatkit-types';
+import type { ModelRequirements } from '../../agent/middleware/model-requirements';
+export type { ToolOutputImageAttachment, ToolOutputPresentation } from '@xpert-ai/chatkit-types';
+export type ToolImageModelInput = {
+    messages: BaseMessage[];
+    requirements?: ModelRequirements;
+};
+/** Images stay in immutable Artifacts; tool results and graph checkpoints contain references only. */
+export interface ToolImagesApi {
+    /** Host identity, conversation and Workspace scope are bound to the current execution. */
+    save(input: {
+        buffer: Buffer;
+        mimeType: ToolOutputImageAttachment['mimeType'];
+        title: string;
+    }): Promise<ToolOutputPresentation>;
+    /**
+     * Project the current complete tool round into one outbound model request. Names identify tools
+     * whose successful result must contain an image presentation; error results remain text.
+     * Never persist the returned messages. Merge requirements into the request with mergeModelRequirements.
+     */
+    prepareModelInput(messages: BaseMessage[], toolNames: readonly string[]): Promise<ToolImageModelInput>;
+}
+export declare const ToolImagesRuntimeCapability: import("../../core/runtime-capability").RuntimeCapabilityKey<ToolImagesApi>;

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

@@ -253,9 +253,13 @@ export interface WorkspaceFilesApi {
      * file without reading its bytes into the API process.
      */
     resolveFile(input: WorkspaceFileReference): Promise<WorkspaceFile>;
-    /** Read raw bytes from an explicitly scoped workspace file reference. */
+    /**
+     * Read raw bytes from an explicitly scoped workspace file reference.
+     * Missing paths or an uninitialized volume root reject with `error.code === 'ENOENT'`
+     * in-process; other validation/access failures must not be treated as missing files.
+     */
     readBuffer(input: WorkspaceFileReference): Promise<WorkspaceFileBuffer>;
-    /** Delete an explicitly scoped workspace file. */
+    /** Delete an explicitly scoped workspace file; missing paths/roots reject with code ENOENT in-process. */
     deleteFile(input: WorkspaceFileReference): Promise<void>;
     /**
      * Normalize a runtime locator into a portable, scope-aware reference without
@@ -267,6 +271,8 @@ export interface WorkspaceFilesApi {
      *
      * This is the preferred API for plugin tools that receive `/workspace/...`
      * paths from sandbox commands.
+     * After resolving the locator, missing paths/roots reject with code ENOENT in-process.
+     * Callers must not infer missing files from localized validation or access errors.
      */
     readRuntimeBuffer(input: WorkspaceFileLocator): Promise<WorkspaceRuntimeFileBuffer>;
     /**

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

@@ -6,5 +6,7 @@ export interface SandboxExecutionEnvironment {
     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,13 @@
 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;
@@ -28,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/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>;