@xpert-ai/plugin-sdk 3.19.0 → 3.20.0

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/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

@@ -8,3 +8,4 @@ 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/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>;