@xpert-ai/plugin-sdk 3.18.7 → 3.19.0

package/src/lib/agent/runtime/strategy.d.ts

@@ -0,0 +1,50 @@
+import { DiscoveryService, Reflector } from '@nestjs/core';
+import type { RuntimeCapabilityRegistry } from '../../core/runtime-capability';
+import { BaseStrategyRegistry, type StrategySource } from '../../strategy';
+import type { AgentInvocationInput, AgentInvocationScope, AgentJson, AgentRuntimeCapabilities, AgentRuntimeHandle, AgentRuntimeObservation, AgentTarget } from './types';
+/** Trusted per-operation host context, independent of graph and provider transport details. */
+export interface AgentRuntimeContext {
+    /** Durable host invocation ID used to correlate provider receipts. */
+    invocationId: string;
+    scope: Readonly<AgentInvocationScope>;
+    /** Cooperative cancellation; abort alone does not confirm remote termination. */
+    signal?: AbortSignal;
+    capabilities: RuntimeCapabilityRegistry;
+    /** Persist a receipt before waiting on long-running work. Await persistence and propagate failures. */
+    checkpoint(observation: AgentRuntimeObservation): Promise<void>;
+}
+/** Pinned launch/recovery input supplied after the host reserves the invocation. */
+export interface AgentRuntimeStart {
+    target: Readonly<AgentTarget>;
+    input: Readonly<AgentInvocationInput>;
+    /** Host invocation ID for provider idempotency; distinct from the caller callId. */
+    operationId: string;
+    /** Existing receipt for recovery. Reattach instead of resending the initial task. */
+    previous?: AgentRuntimeHandle;
+}
+/**
+ * Extension point for native and third-party runtimes. Strategies may serve concurrent calls;
+ * keep per-invocation state isolated. The host owns authorization and persistence.
+ */
+export interface IAgentRuntimeStrategy {
+    /** Support flags must agree with the optional methods implemented below. */
+    readonly capabilities: AgentRuntimeCapabilities;
+    /** Launch or recover approved work; checkpoint the handle as soon as it is known. */
+    start(request: AgentRuntimeStart, context: AgentRuntimeContext): Promise<AgentRuntimeObservation>;
+    /** Reconcile existing work without relaunching it. Return unknown if its outcome cannot be established. */
+    inspect(handle: AgentRuntimeHandle, context: AgentRuntimeContext): Promise<AgentRuntimeObservation>;
+    /** Required when cancellation is supported. Return cancelled only after termination is confirmed. */
+    cancel?(handle: AgentRuntimeHandle, context: AgentRuntimeContext): Promise<AgentRuntimeObservation>;
+    /** Required when interactions are supported. Validate the response against the pending interaction. */
+    respond?(handle: AgentRuntimeHandle, interactionId: string, response: AgentJson, context: AgentRuntimeContext): Promise<AgentRuntimeObservation>;
+}
+/** Nest discovery metadata key for runtime strategies. */
+export declare const AGENT_RUNTIME_STRATEGY = "AGENT_RUNTIME_STRATEGY";
+/** Associate a stable provider key with an adapter. Also declare @Injectable() and register the provider. */
+export declare const AgentRuntimeStrategy: (provider: string) => <TFunction extends Function, Y>(target: TFunction | object, propertyKey?: string | symbol, descriptor?: TypedPropertyDescriptor<Y>) => void;
+/** Scoped strategy registry with pinned provider/version lookup for continuation. */
+export declare class AgentRuntimeRegistry extends BaseStrategyRegistry<IAgentRuntimeStrategy> {
+    constructor(discoveryService: DiscoveryService, reflector: Reflector);
+    /** Find the exact original scope/plugin/version, without fallback. Returns undefined if unavailable. */
+    getPinned(provider: string, source: StrategySource): IAgentRuntimeStrategy | undefined;
+}

package/src/lib/agent/runtime/types.d.ts

@@ -0,0 +1,132 @@
+/** Serializable invocation data. Use finite numbers and plain objects; exclude credentials. */
+export type AgentJson = null | boolean | number | string | AgentJson[] | {
+    [key: string]: AgentJson;
+};
+/** Host-authorized ownership and execution scope; never accept identities from model input. */
+export interface AgentInvocationScope {
+    tenantId: string;
+    organizationId: string;
+    userId: string;
+    workspaceId?: string;
+    projectId?: string;
+    /** Platform conversation ID, distinct from a provider session ID. */
+    conversationId?: string;
+    /** Opaque parent execution identity; host Task adapters may use logical IDs. */
+    parentExecutionId: string;
+    /** Calling Agent key or host-assigned background-task entry. */
+    callerAgentKey: string;
+    callerXpertId?: string;
+}
+/** Authorized, version-pinned target. Pass the resolved snapshot unchanged. */
+export interface AgentTarget {
+    /** Opaque host binding ID; do not assume UUID format or derive the provider from it. */
+    bindingId: string;
+    /** Registered AgentRuntimeStrategy key. */
+    provider: string;
+    /** Opaque configuration version, distinct from the invocation revision. */
+    revision: string;
+    /** Provider-specific target/profile reference. */
+    reference: string;
+    /** Validated configuration; use managed secret references instead of credentials. */
+    configuration: {
+        [key: string]: AgentJson;
+    };
+}
+/** Provider support flags; they do not grant caller permissions. */
+export interface AgentRuntimeCapabilities {
+    /**
+     * Recovery by host checkpoint, existing provider session, or none.
+     * Session recovery does not guarantee survival of a worker crash.
+     */
+    recovery: 'checkpoint' | 'session' | 'none';
+    interactions: boolean;
+    /** Supports cancel requests; termination still requires provider confirmation. */
+    cancellation: boolean;
+    /** Work can continue after start() returns. */
+    background: boolean;
+}
+/**
+ * Only succeeded, failed and cancelled are terminal.
+ * waiting requires continuation; cancelling awaits confirmation.
+ * unknown means the outcome is uncertain: reconcile before launching new work.
+ */
+export type AgentInvocationStatus = 'queued' | 'running' | 'waiting' | 'cancelling' | 'succeeded' | 'failed' | 'cancelled' | 'unknown';
+/** Provider-neutral task payload; supported structured fields depend on the adapter. */
+export interface AgentInvocationInput {
+    prompt: string;
+    parameters?: {
+        [key: string]: AgentJson;
+    };
+    context?: {
+        [key: string]: AgentJson;
+    };
+    /** Host-managed file references, authorized and materialized by the adapter. */
+    files?: Array<{
+        id: string;
+        name?: string;
+    }>;
+}
+/** Output or in-progress receipt. Check invocation status before treating it as final. */
+export interface AgentInvocationResult {
+    text: string;
+    /** Adapter-defined structured output. */
+    data?: AgentJson;
+    /** Host-managed output references; normal artifact authorization applies. */
+    artifacts?: Array<{
+        id: string;
+        name?: string;
+        mimeType?: string;
+    }>;
+}
+/** Persisted provider receipt. Session/run IDs are distinct from the host invocation ID. */
+export interface AgentRuntimeHandle {
+    sessionId: string;
+    runId: string;
+    metadata?: {
+        [key: string]: AgentJson;
+    };
+}
+/** Pending question or approval. Respond using its exact ID and provider-defined data schema. */
+export interface AgentInteraction {
+    id: string;
+    kind: 'approval' | 'input';
+    prompt: string;
+    data?: AgentJson;
+}
+/**
+ * Partial provider observation; omitted fields may retain previously stored values.
+ * The host manages identity, revisions and persistence.
+ */
+export interface AgentRuntimeObservation {
+    /** succeeded requires a result, even for structured-only output. */
+    status: AgentInvocationStatus;
+    handle?: AgentRuntimeHandle;
+    result?: AgentInvocationResult;
+    interaction?: AgentInteraction;
+    /** Safe diagnostic message without credentials or raw provider payloads. */
+    error?: string;
+}
+/** Request pinned by the host before dispatch. */
+export interface AgentInvocationRequest {
+    target: AgentTarget;
+    /**
+     * Idempotency key within the captured scope (max 1024 characters).
+     * Reuse for the same request; changed input or target is a conflict.
+     */
+    callId: string;
+    input: AgentInvocationInput;
+}
+/** Host-owned invocation snapshot; not an update DTO. */
+export interface AgentInvocation extends AgentRuntimeObservation {
+    /** Host invocation ID used by inspect, cancel and respond. */
+    id: string;
+    /** Host-managed concurrency revision, distinct from the target version. */
+    revision: number;
+    scope: AgentInvocationScope;
+    request: AgentInvocationRequest;
+    /** Host timestamps in ISO 8601 format. */
+    createdAt: string;
+    updatedAt: string;
+}
+/** Checks confirmed completion; unknown remains non-terminal. */
+export declare function isAgentInvocationTerminal(status: AgentInvocationStatus): boolean;

package/src/lib/assistant-capability/index.d.ts

@@ -0,0 +1,42 @@
+import { DiscoveryService, Reflector } from '@nestjs/core';
+import type { I18nObject, LanguagesEnum, ModelFeature, TXpertTeamDraft, TXpertTemplate } from '@xpert-ai/contracts';
+import { BaseStrategyRegistry } from '../strategy';
+export interface AssistantCapabilityContext {
+    template: TXpertTemplate;
+    draft: TXpertTeamDraft;
+    language: LanguagesEnum;
+    /** Provided again at installation; providers must not silently select a fallback. */
+    sandboxProviders?: {
+        type: string;
+    }[];
+}
+export interface AssistantCapabilityApplyContext extends AssistantCapabilityContext {
+    loadTemplate: (id: string) => Promise<TXpertTemplate>;
+}
+/** Optional capabilities default to off. IDs are stable machine-readable keys. */
+export interface IAssistantCapabilityProvider {
+    readonly key: string;
+    readonly label: string | I18nObject;
+    readonly description: string | I18nObject;
+    readonly requiredModelFeatures?: ModelFeature[];
+    /** Explicitly opt into the blank Assistant creation flow. */
+    readonly availableForBlankAssistant?: boolean;
+    /** Distribution extensions to specific templates, without changing their portable source. */
+    readonly templates?: {
+        templateId: string;
+        required: boolean;
+    }[];
+    /** Detect a capability already owned by the base workflow; it cannot be removed by a new overlay. */
+    isEnabled?(draft: TXpertTeamDraft): boolean;
+    check(context: AssistantCapabilityContext): Promise<{
+        available: boolean;
+        reason?: string;
+    }>;
+    /** Deterministic draft composition; never creates external resources. */
+    apply(context: AssistantCapabilityApplyContext): Promise<void>;
+}
+export declare const ASSISTANT_CAPABILITY_PROVIDER = "ASSISTANT_CAPABILITY_PROVIDER";
+export declare const AssistantCapabilityProvider: (key: string) => <TFunction extends Function, Y>(target: TFunction | object, propertyKey?: string | symbol, descriptor?: TypedPropertyDescriptor<Y>) => void;
+export declare class AssistantCapabilityProviderRegistry extends BaseStrategyRegistry<IAssistantCapabilityProvider> {
+    constructor(discovery: DiscoveryService, reflector: Reflector);
+}

package/src/lib/connector/runtime-capability.d.ts

@@ -3,6 +3,8 @@ import type { ConnectorRuntimeApi } from './strategy.interface';
 export declare const ConnectorRuntimeCapability: import("../core").RuntimeCapabilityKey<ConnectorRuntimeApi>;
 /** No binding or provider grants means no connector access. */
 export type ConnectorRuntimeScope = RuntimeIdentityScope & {
+    /** Host-validated Agent Plugin dependencies may use their workspace binding in an authorized project. */
+    allowWorkspaceBindingsInProject?: boolean;
     /** Host-selected bindings, including IDs pinned by enabled graph Connector nodes. */
     connectorBindingIds?: string[] | null;
     /** Providers configured by enabled graph Connector nodes without a pinned ID. */

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

@@ -72,6 +72,7 @@ export type ConnectorPermissionDeclaration = {
     required?: boolean;
 };
 export type ConnectorDefinitionBase = {
+    runtimeUsage?: 'middleware' | 'credential';
     provider: string;
     label: RuntimeI18nText;
     description?: RuntimeI18nText;
@@ -139,6 +140,10 @@ export type ConnectorBindingCreateRequest = {
     authorizationMode: ConnectorAuthorizationMode;
 };
 export type ConnectorRuntimeOption = {
+    scope?: ConnectorScope;
+    canManage?: boolean;
+    managementUrl?: string;
+    runtimeUsage?: 'middleware' | 'credential';
     bindingId: string;
     provider: string;
     authorizationMode: ConnectorAuthorizationMode;
@@ -152,6 +157,9 @@ export type ConnectorRuntimeOption = {
     profile?: ConnectorProfile | null;
 };
 export type ConnectorRuntimeOptions = {
+    workspaceScope?: ConnectorScope;
+    canManageWorkspace?: boolean;
+    managementUrl?: string;
     scope: ConnectorScope;
     items: ConnectorRuntimeOption[];
 };

package/src/lib/core/context/request-context.d.ts

@@ -28,6 +28,11 @@ export declare class RequestContext {
     static isTenantScope(): boolean;
     static isOrganizationScope(): boolean;
     static requireOrganizationScope(): string;
+    /**
+     * Check the authenticated principal's enabled role permissions, matching the
+     * server RequestContext. Authentication guards resolve JWTs, API keys and
+     * ChatKit client secrets before this check; the bearer is not always a JWT.
+     */
     static hasPermissions(findPermissions: Array<PermissionsEnum | string>, throwError?: boolean): boolean;
     static hasAnyPermission(findPermissions: PermissionsEnum[], throwError?: boolean): boolean;
     static currentToken(throwError?: boolean): any;
@@ -46,6 +51,7 @@ export declare class RequestContext {
      * @returns True if any of the required roles are found, otherwise false.
      */
     static hasRoles(roles: RolesEnum[], throwError?: boolean): boolean;
+    private static currentPermissions;
 }
 /**
  * One process-wide context store shared by source, built, and dynamically loaded

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

@@ -11,9 +11,6 @@ export type StrategyBusEvent<S = any> = {
     cause?: 'refresh' | 'uninstall';
 };
 export declare class StrategyBus {
-    private readonly removalGuards;
-    registerRemovalGuard(guard: (scopeKey: string, pluginNames: readonly string[]) => Promise<void>): () => void;
-    assertCanRemove(scopeKey: string, pluginNames: readonly string[]): Promise<void>;
     private readonly subject;
     readonly events$: import("rxjs").Observable<StrategyBusEvent<any>>;
     upsert<S>(strategyType: string, entry: StrategyEntry<S>): void;

package/src/lib/evolution/runtime-capability.d.ts

@@ -1,4 +1,5 @@
-import type { EvolutionRuntimeApi, EvolutionChangeRuntimeApi } from '@xpert-ai/contracts';
+import type { EvolutionRuntimeApi, EvolutionChangeRuntimeApi, EvolutionBaselineRuntimeApi } from '@xpert-ai/contracts';
 export declare const EVOLUTION_RUNTIME_SERVICE_TOKEN = "XPERT_EVOLUTION_RUNTIME_SERVICE";
+export declare const EvolutionBaselineRuntimeCapability: import("../core").RuntimeCapabilityKey<EvolutionBaselineRuntimeApi>;
 export declare const EvolutionRuntimeCapability: import("../core").RuntimeCapabilityKey<EvolutionRuntimeApi>;
 export declare const EvolutionChangeRuntimeCapability: import("../core").RuntimeCapabilityKey<EvolutionChangeRuntimeApi>;

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

@@ -40,4 +40,26 @@ export interface IntegrationStrategy<T = unknown> {
     validateConfig?(config: T, integration?: IIntegration<T>): Promise<void | IntegrationTestResult>;
     getIdentityBootstrap?(integration: IIntegration<T>): Promise<IntegrationIdentityBootstrap>;
     exchangeIdentity?(integration: IIntegration<T>, grant: IntegrationIdentityGrant): Promise<IntegrationExternalIdentity>;
+    beginQrAuthorization?(): Promise<IntegrationQrAuthorization>;
+    pollQrAuthorization?(deviceCode: string): Promise<IntegrationQrAuthorizationResult>;
+    /** Stable provider account identity used to reuse integrations within the same tenant and organization. */
+    getQrAuthorizationIdentity?(options: unknown): string | null;
 }
+/** Server-only setup contract. Never forward deviceCode or options to the browser. */
+export interface IntegrationQrAuthorization {
+    deviceCode: string;
+    authorizationUrl: string;
+    expiresInSeconds: number;
+    intervalSeconds: number;
+}
+export type IntegrationQrAuthorizationResult = 
+/** Additive provider backoff, persisted by the host for the rest of the session. */
+{
+    status: 'waiting';
+    intervalIncrementSeconds?: number;
+} | {
+    status: 'expired' | 'denied' | 'failed';
+} | {
+    status: 'authorized';
+    options: Record<string, unknown>;
+};

package/src/lib/mcp/app.d.ts

@@ -16,4 +16,14 @@ export interface McpAppDefinition {
     csp?: McpAppCsp;
     permissions?: McpAppPermissions;
 }
+/** App exposure is independent of publishing a tool on an external MCP server. */
+export interface MiddlewareMcpApps {
+    definitions: readonly McpAppDefinition[];
+    tools: Readonly<Record<string, {
+        resourceKey?: string;
+        visibility: readonly ('model' | 'app')[];
+        /** Trusted plugin policy; omitted writes use the host approval flow. */
+        approval?: 'required' | 'none';
+    }>>;
+}
 export declare function defineMcpApp(definition: McpAppDefinition): Readonly<McpAppDefinition>;

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

@@ -0,0 +1,59 @@
+import { DiscoveryService, Reflector } from '@nestjs/core';
+import type { ProjectTaskGraph, ProjectTaskGraphChange, ProjectTaskExecutionTarget, TXpertProjectTaskStatus } from '@xpert-ai/contracts';
+import { BaseStrategyRegistry } from '../strategy';
+import type { ProjectAccessActor } from '../runtime/capabilities/project-access';
+export interface ProjectTaskContext {
+    actor: ProjectAccessActor;
+    projectId: string;
+}
+export interface ProjectTaskProjection {
+    key: string;
+    title: string;
+    status: TXpertProjectTaskStatus;
+    kind: 'task' | 'summary' | 'milestone';
+    parentKey?: string;
+    predecessorKeys: string[];
+    diagnostic?: string;
+    assigneeXpertId?: string;
+    executions: Array<{
+        key: string;
+        attempt: number;
+        agentExecutionId?: string;
+        conversationId?: string;
+        threadId?: string;
+        xpertId?: string;
+        agentKey?: string;
+        status: 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled';
+        startedAt?: string;
+        completedAt?: string;
+        error?: string;
+        outputSummary?: string;
+    }>;
+}
+/** Domain facts remain durable in the provider; projection can be replayed after interruption. */
+export interface ProjectTaskSnapshot {
+    revision: string;
+    tasks: ProjectTaskProjection[];
+}
+export interface IProjectTaskProvider {
+    readonly key: string;
+    /** 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. */
+    linked?(context: ProjectTaskContext, links: Array<{
+        sourceKey: string;
+        taskId: string;
+    }>): Promise<void>;
+}
+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> {
+    constructor(discovery: DiscoveryService, reflector: Reflector);
+}
+/** ORM-independent project task management; actor values come from trusted server context. */
+export interface ProjectTasksApi {
+    graph(context: ProjectTaskContext): Promise<ProjectTaskGraph>;
+    change(context: ProjectTaskContext, input: ProjectTaskGraphChange): Promise<ProjectTaskGraph>;
+    resolveExecution(context: ProjectTaskContext, taskExecutionId: string): Promise<ProjectTaskExecutionTarget>;
+}
+export declare const ProjectTasksRuntimeCapability: import("../core/runtime-capability").RuntimeCapabilityKey<ProjectTasksApi>;

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

@@ -0,0 +1,64 @@
+import { DiscoveryService, Reflector } from '@nestjs/core';
+import type { XpertProjectTypeRef } from '@xpert-ai/contracts';
+import { BaseStrategyRegistry } from '../strategy';
+export interface ProjectTypeContext extends XpertProjectTypeRef {
+    tenantId: string;
+    organizationId?: string | null;
+    userId: string;
+    xpertId: string;
+    purpose: 'provision' | 'open' | 'create';
+}
+export interface ProjectTypeBinding {
+    /** Persisted business Assistant used when opening a Project from the global list. */
+    xpertId?: string;
+    viewKey: string;
+    selectionId?: string;
+}
+/**
+ * ORM-independent write access to the host's current creation transaction.
+ * The host owns commit/rollback; this object is valid only during the awaited
+ * creation hook. Entities must be instances of registered plugin entity classes.
+ */
+export interface ProjectCreationTransaction {
+    /** Save an entity and return its persisted values without committing the transaction. */
+    save<T extends object>(entity: T): Promise<T>;
+}
+/** Host-owned identity and transaction for an empty conversation's first send. */
+export interface ConversationProjectCreation {
+    projectId: string;
+    conversationId: string;
+    workspaceId: string;
+    name: string;
+    /**
+     * Persist only application records through this writer. The host creates the
+     * platform Project and binds the conversation in the same transaction. Do not
+     * call provisioning, start agents, or perform external I/O from this hook.
+     */
+    transaction: ProjectCreationTransaction;
+}
+/** Host calls this provider before claiming or synchronizing an entity Project. */
+export interface IProjectTypeProvider {
+    /** Must verify the persisted domain-to-project link and actor before returning. */
+    resolve(context: ProjectTypeContext, projectId: string): Promise<ProjectTypeBinding & {
+        name: string;
+        status: 'active' | 'archived';
+    }>;
+    /** Opens the application's governed creation workflow. */
+    createEntry(context: ProjectTypeContext): Promise<ProjectTypeBinding>;
+    /**
+     * Optional opt-in to first-send creation. Persist the business entity and its
+     * link to input.projectId atomically using input.transaction, then return its entry
+     * and desired name. Exceptions roll back the whole bootstrap. The host checks
+     * permissions and serializes retries with a conversation row lock first.
+     */
+    createForConversation?(context: ProjectTypeContext, input: ConversationProjectCreation): Promise<ProjectTypeBinding & {
+        name: string;
+        status: 'active';
+    }>;
+}
+export declare const PROJECT_TYPE_PROVIDER = "PROJECT_TYPE_PROVIDER";
+/** Register the stable provider key used by entity-backed App project type declarations. */
+export declare const ProjectTypeProvider: (key: string) => <TFunction extends Function, Y>(target: TFunction | object, propertyKey?: string | symbol, descriptor?: TypedPropertyDescriptor<Y>) => void;
+export declare class ProjectTypeProviderRegistry extends BaseStrategyRegistry<IProjectTypeProvider> {
+    constructor(discovery: DiscoveryService, reflector: Reflector);
+}

package/src/lib/runtime/capabilities/knowledge-graph.d.ts

@@ -46,6 +46,9 @@ export type KnowledgeGraphPublicationResult = {
     error?: string | null;
 };
 export interface KnowledgeGraphApi {
+    /** Bounded, source-version-checked reads; the host verifies the current Agent's KB connection. */
+    queryEntities?(input: KnowledgeGraphEntityQuery): Promise<KnowledgeGraphReadResult>;
+    readNeighborhood?(input: KnowledgeGraphNeighborhoodQuery): Promise<KnowledgeGraphReadResult>;
     /** Atomically accepts a complete, validated snapshot. Indexing is durable and retryable. */
     publish(input: KnowledgeGraphPublishInput): Promise<KnowledgeGraphPublicationResult>;
     status(input: KnowledgeGraphPublicationOwner): Promise<KnowledgeGraphPublicationResult | null>;
@@ -56,4 +59,60 @@ export interface KnowledgeGraphApi {
         chunkIds: string[];
     }): Promise<KnowledgeGraphPublicationResult>;
 }
+export type KnowledgeGraphReadScope = {
+    knowledgebaseId: string;
+    xpertId: string;
+    agentKey: string;
+    sources: {
+        documentId: string;
+        sourceVersion: string;
+    }[];
+};
+export type KnowledgeGraphEntityQuery = KnowledgeGraphReadScope & {
+    entityIds?: string[];
+    namespace?: string;
+    nodeKey?: string;
+    type?: string;
+    search?: string;
+    /** Opaque continuation bound to this query and its source versions. */
+    cursor?: string;
+    limit?: number;
+};
+export type KnowledgeGraphNeighborhoodQuery = KnowledgeGraphReadScope & {
+    entityIds: string[];
+    relationTypes: string[];
+    depth?: number;
+    direction?: 'incoming' | 'outgoing' | 'both';
+    /** Continuation is supported for one-hop reads only. */
+    cursor?: string;
+    limit?: number;
+};
+export type KnowledgeGraphReadEntity = {
+    id: string;
+    name: string;
+    type: string;
+    properties: Record<string, JSONValue>;
+    documentId: string;
+    documentIds?: string[];
+};
+export type KnowledgeGraphReadRelation = {
+    id: string;
+    source: string;
+    target: string;
+    type: string;
+    properties: Record<string, JSONValue>;
+    documentId: string;
+    documentIds?: string[];
+};
+export type KnowledgeGraphReadResult = {
+    entities: KnowledgeGraphReadEntity[];
+    relations: KnowledgeGraphReadRelation[];
+    truncated: boolean;
+    nextCursor?: string;
+    sources: {
+        documentId: string;
+        sourceVersion: string;
+        status: KnowledgeGraphPublicationResult['status'] | 'unavailable' | 'stale';
+    }[];
+};
 export declare const KnowledgeGraphRuntimeCapability: import("../../core/runtime-capability").RuntimeCapabilityKey<KnowledgeGraphApi>;

package/src/lib/runtime/capabilities/knowledgebase-documents.d.ts

@@ -219,6 +219,25 @@ export type KnowledgebaseReadTextResult = {
         version: number;
     }>;
 };
+/** Pre-split conversion evidence. Index chunk size and embedding models do not affect this view. */
+export type KnowledgebaseReadSourceInput = KnowledgebaseReadTextInput & {
+    /** Pin all pages to the revision returned by the first page. */
+    revision?: string;
+};
+export type KnowledgebaseReadSourceResult = {
+    knowledgebaseId: string;
+    documentId: string;
+    /** Content identity of the complete parsed source, independent of index/document versions. */
+    revision: string;
+    sourceHash?: string | null;
+    total: number;
+    /** Complete converter blocks in source order, never vector fragments or overlapping windows. */
+    chunks: Array<{
+        id: string;
+        text: string;
+        page?: number;
+    }>;
+};
 export type KnowledgebaseProcessingOptionsInput = {
     knowledgebaseId: string;
     fileName: string;
@@ -249,6 +268,8 @@ export type KnowledgebaseProcessingOptionsResult = {
 export interface KnowledgebaseDocumentsApi {
     getProcessingOptions(input: KnowledgebaseProcessingOptionsInput): Promise<KnowledgebaseProcessingOptionsResult>;
     readText(input: KnowledgebaseReadTextInput): Promise<KnowledgebaseReadTextResult>;
+    /** Missing/stale conversion snapshots fail explicitly; this never falls back to indexed chunks. */
+    readSource(input: KnowledgebaseReadSourceInput): Promise<KnowledgebaseReadSourceResult>;
     listDocuments(input: KnowledgebaseListDocumentsInput): Promise<KnowledgebaseListDocumentsResult>;
     createFolder(input: KnowledgebaseCreateFolderInput): Promise<KnowledgebaseCreateFolderResult>;
     moveDocument(input: KnowledgebaseMoveDocumentInput): Promise<KnowledgebaseMoveDocumentResult>;

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

@@ -129,14 +129,19 @@ export type KnowledgebaseProvisioningSpec = {
     score?: number;
     metadataSchema?: KnowledgebaseProvisioningMetadataField[];
     incrementalSyncEnabled?: boolean;
+    /** Set the graph switch without replacing existing graph retrieval or extraction settings. */
+    graphRag?: {
+        enabled: boolean;
+    };
 };
 export type KnowledgebaseEnsureInput = {
     workspaceId: string;
     namespace: string;
     /**
-     * Reuse the most recently updated accessible knowledgebase embedding-model configuration when
-     * creating a managed set. This keeps one-click provisioning usable without exposing provider
-     * credentials to plugins. Provisioning fails explicitly when no configured model is available.
+     * Fill missing embedding bindings from the current user's available Copilot provider catalog,
+     * falling back to the most recently updated ordinary knowledgebase in this workspace.
+     * Existing bindings are preserved. No provider credentials are exposed to plugins.
+     * Provisioning fails explicitly when a missing binding cannot be resolved.
      */
     inheritEmbeddingModel?: boolean;
     knowledgebases: KnowledgebaseProvisioningSpec[];

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

@@ -1,10 +1,11 @@
+import type { XpertProjectClassification } from '@xpert-ai/contracts';
 /** Trusted server actor. View providers derive this from host context; jobs persist that actor. */
 export interface ProjectAccessActor {
     tenantId: string;
     organizationId?: string | null;
     userId: string;
 }
-export interface ProjectHumanAccess {
+export interface ProjectHumanAccess extends XpertProjectClassification {
     projectId: string;
     role: 'owner' | 'manager' | 'editor' | 'member';
     canManage: boolean;

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

@@ -1,3 +1,4 @@
+import type { XpertProjectTypeRef } from '@xpert-ai/contracts';
 /** Lifecycle states that plugin-managed Projects may synchronize to the platform. */
 export type ProjectProvisioningStatus = 'active' | 'archived';
 /** Portable identity of one required, direct External Assistant binding. */
@@ -8,6 +9,8 @@ export type ProjectExternalAssistantExpectation = {
 };
 /** Stable identity and desired state for an idempotently provisioned Chat Project. */
 export type ProjectEnsureInput = {
+    /** Registered application type. Omission preserves legacy unclassified callers. */
+    projectType?: XpertProjectTypeRef;
     /** Caller-generated id reused across retries to prevent duplicate Projects. */
     projectId: string;
     /** @deprecated Projects no longer belong to a Workspace. Accepted only for legacy callers. */

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;
 };