@xpert-ai/plugin-sdk 3.18.7 → 3.20.0

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

@@ -1,5 +1,7 @@
 import type { JSONValue, TAvatar } from '@xpert-ai/contracts';
+/** Task lifecycle snapshot. interrupted means paused; unknown does not confirm failure. */
 export type AgentMiddlewareAssistantTaskStatus = 'queued' | 'running' | 'succeeded' | 'failed' | 'interrupted' | 'unknown';
+/** Existing platform file reference; access remains subject to host authorization. */
 export type AgentMiddlewareAssistantTaskFile = {
     id?: string;
     fileId?: string;
@@ -13,33 +15,27 @@ export type AgentMiddlewareAssistantTaskFile = {
     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.
+ * Portable plugin skill identity, resolved through the target Agent's connected Skills Middleware.
+ * Do not persist workspace-local SkillPackage UUIDs in plugin configuration.
  */
 export type AgentMiddlewareAssistantTaskSkillRef = {
     pluginName: string;
     componentKey: string;
 };
-/**
- * Portable role identity used to resolve an organization-owned Assistant.
- * Instance UUIDs stay out of plugin contracts so the same workflow is deployable across organizations.
- */
+/** Portable plugin/template/Agent identity used to resolve a deployed Assistant. */
 export type AgentMiddlewareExternalAssistantExpectation = {
     pluginName: string;
     templateKey: string;
     agentKey: string;
 };
-/** Resolve the executor from the requester's required, direct external-Xpert connections. */
+/** Resolve the executor from the requester's required, direct published external-Assistant connections. */
 export type AgentMiddlewareAssistantTaskTarget = {
     kind: 'external_assistant';
     requesterXpertId: string;
     requesterAgentKey: string;
     expectation: AgentMiddlewareExternalAssistantExpectation;
 };
-/** Stable plugin-owned identity for reconciling platform executions with a domain operation. */
+/** Plugin-owned operation identity for reconciling executions with a domain subject. */
 export type AgentMiddlewareExecutionCorrelation = {
     namespace: string;
     operationId: string;
@@ -48,7 +44,7 @@ export type AgentMiddlewareExecutionCorrelation = {
 };
 /** Availability of a resolved external Assistant binding. */
 export type AgentMiddlewareExternalAssistantBindingStatus = 'available' | 'incompatible' | 'unpublished' | 'cross_organization';
-/** Safe external Assistant metadata that may cross plugin and View Host boundaries. */
+/** Binding display metadata; intentionally omits the deployed Assistant instance ID. */
 export type AgentMiddlewareExternalAssistantBinding = {
     title: string;
     name: string;
@@ -63,12 +59,12 @@ export type AgentMiddlewareExternalAssistantBinding = {
     publishedVersion?: string;
     status: AgentMiddlewareExternalAssistantBindingStatus;
 };
-/** Identifies the requester whose required direct bindings should be listed. */
+/** Requester whose required direct external-Assistant bindings should be listed. */
 export type AgentMiddlewareListExternalAssistantBindingsInput = {
     requesterXpertId: string;
     requesterAgentKey: string;
 };
-/** Selects correlated executions for one requester-owned domain subject. */
+/** Requester-scoped execution lookup for a plugin namespace and domain subject. */
 export type AgentMiddlewareListCorrelatedExecutionsInput = {
     requesterXpertId: string;
     requesterAgentKey: string;
@@ -76,7 +72,7 @@ export type AgentMiddlewareListCorrelatedExecutionsInput = {
     subjectId: string;
     limit?: number;
 };
-/** Safe execution summary returned to a plugin for domain reconciliation. */
+/** Execution receipt for domain reconciliation; executor fields identify the resolved published Assistant. */
 export type AgentMiddlewareCorrelatedExecution = {
     operationId: string;
     subjectId: string;
@@ -93,27 +89,32 @@ export type AgentMiddlewareCorrelatedExecution = {
     startedAt?: string;
     updatedAt?: string;
 };
+/** Start an asynchronous task on the current Assistant or a resolved external Assistant. */
 export type AgentMiddlewareAssistantTaskInput = {
+    /** Current/requesting Assistant ID; must match target.requesterXpertId when target is supplied. */
     xpertId: string;
-    /** Selects the Assistant base and Primary models; child Agents retain authored models. */
+    /** Selects the base/Primary model; child Agents retain authored models. */
     modelId?: string;
+    /** Entry Agent for the current Assistant; external targets use their resolved primary Agent. */
     agentKey?: string;
-    /** Resolve an organization-owned external Assistant from the requester's published graph. */
+    /** Optional external executor resolved from the requester's published graph. */
     target?: AgentMiddlewareAssistantTaskTarget;
     conversationId?: string | null;
     executionId?: string | null;
     projectId?: string | null;
     taskId?: string;
+    /** Per-run idempotency key. Otherwise correlation.operationId or executionId is used; taskId alone is insufficient. */
     clientMessageId?: string;
     prompt: string;
     files?: AgentMiddlewareAssistantTaskFile[];
-    /** Skills that this task is expected to load through its target Agent's Skills Middleware. */
+    /** Skills expected to load through the target Agent's connected Skills Middleware. */
     selectedSkillRefs?: AgentMiddlewareAssistantTaskSkillRef[];
-    /** Additional bounded human-input fields exposed to runtime-state fixed filters. */
+    /** Additional bounded runtime input; does not override the task prompt or files. */
     humanInput?: Record<string, JSONValue>;
     context?: Record<string, unknown>;
     correlation?: AgentMiddlewareExecutionCorrelation;
 };
+/** Task receipt, not necessarily a completed result. Use status and execution identifiers to follow progress. */
 export type AgentMiddlewareAssistantTaskResult = {
     status: AgentMiddlewareAssistantTaskStatus;
     taskId?: string;
@@ -127,6 +128,7 @@ export type AgentMiddlewareAssistantTaskResult = {
     executorAssistantTitle?: string;
     executorPublishedVersion?: string;
 };
+/** Host task/execution identifiers for lookup. Cancellation requires an execution, conversation or thread ID. */
 export type AgentMiddlewareAssistantTaskStatusInput = {
     taskId?: string;
     executionId?: string;
@@ -135,17 +137,50 @@ export type AgentMiddlewareAssistantTaskStatusInput = {
     clientMessageId?: string;
     xpertId?: string;
 };
+/** Platform executions affected by the cancellation request. */
 export type AgentMiddlewareAssistantTaskCancelResult = {
     canceledExecutionIds: string[];
 };
+/** Host Assistant Task API. Feature-detect optional methods before calling them. */
 export interface AgentMiddlewareAssistantTaskApi {
+    /**
+     * Verify that a running native delegate is the requester's bound external role.
+     *
+     * Re-resolves the requester's direct, required external-Assistant connections on
+     * every call. Exactly one candidate must match the plugin, template and primary
+     * Agent identity, be published and active in the same organization, and have
+     * the same instance ID as the actual executor. This only validates a binding;
+     * it does not create a task, invoke an Assistant or authorize domain artifacts.
+     *
+     * @param input - Requester identity, actual runtime executor and expected role.
+     * @param input.requesterXpertId - Assistant that owns the external connection.
+     * @param input.requesterAgentKey - The requesting Assistant's primary Agent key.
+     * @param input.executorXpertId - Actual executor ID from the trusted runtime context.
+     * @param input.expectation - Portable plugin, template and primary Agent identity.
+     * @returns Validated binding metadata with instance and workspace IDs omitted.
+     * @throws If the binding is missing, ambiguous, unpublished, incompatible, or
+     * the resolved instance differs from the runtime executor.
+     */
+    assertExternalAssistantBinding?(input: {
+        requesterXpertId: string;
+        requesterAgentKey: string;
+        executorXpertId: string;
+        expectation: {
+            pluginName: string;
+            templateKey: string;
+            agentKey: string;
+        };
+    }): Promise<AgentMiddlewareExternalAssistantBinding>;
     getModels?(xpertId: string): Promise<import('@xpert-ai/contracts').TAssistantModelsResponse>;
+    /** Submit once and retain the receipt; use getTaskStatus to follow asynchronous progress. */
     startTask(input: AgentMiddlewareAssistantTaskInput): Promise<AgentMiddlewareAssistantTaskResult>;
-    /** Return only safe binding descriptors; internal Assistant instance IDs are intentionally omitted. */
+    /** List safe binding descriptors without deployed Assistant instance IDs. */
     listExternalAssistantBindings?(input: AgentMiddlewareListExternalAssistantBindingsInput): Promise<AgentMiddlewareExternalAssistantBinding[]>;
     /** Read executions owned by the requester and its currently bound external Assistants. */
     listCorrelatedExecutions?(input: AgentMiddlewareListCorrelatedExecutionsInput): Promise<AgentMiddlewareCorrelatedExecution[]>;
+    /** Return the current receipt, or null if no matching task is found. */
     getTaskStatus?(input: AgentMiddlewareAssistantTaskStatusInput): Promise<AgentMiddlewareAssistantTaskResult | null>;
     cancelTask?(input: AgentMiddlewareAssistantTaskStatusInput): Promise<AgentMiddlewareAssistantTaskCancelResult>;
 }
+/** Scoped runtime capability for platform Assistant tasks. */
 export declare const AssistantTaskRuntimeCapability: import("../../../core/runtime-capability").RuntimeCapabilityKey<AgentMiddlewareAssistantTaskApi>;

package/src/lib/agent/middleware/index.d.ts

@@ -4,3 +4,4 @@ export * from './strategy.registry';
 export * from './types';
 export * from './runtime';
 export * from './model-output-validation-error';
+export * from './model-requirements';

package/src/lib/agent/middleware/model-requirements.d.ts

@@ -0,0 +1,9 @@
+import type { ModelFeature } from '@xpert-ai/contracts';
+/** Expand only when the host can validate the feature at every model invocation. */
+export type ModelRequirementFeature = ModelFeature.VISION;
+/** Hard requirements for one model call, including retries and fallbacks. */
+export interface ModelRequirements {
+    readonly features?: readonly ModelRequirementFeature[];
+}
+/** Combine middleware contributions without mutating or weakening existing requirements. */
+export declare function mergeModelRequirements(...requirements: readonly (ModelRequirements | undefined)[]): ModelRequirements | undefined;

package/src/lib/agent/middleware/strategy.interface.d.ts

@@ -5,6 +5,7 @@ import { BaseStore } from '@langchain/langgraph';
 import { AgentMiddleware } from './types';
 import { PromiseOrValue } from '../../types';
 import { AgentMiddlewareRuntimeApi } from './runtime';
+import type { AgentInvocationScope } from '../runtime/types';
 export interface IAgentMiddlewareContext {
     tenantId: string;
     organizationId?: string | null;
@@ -12,6 +13,9 @@ export interface IAgentMiddlewareContext {
     workspaceId?: string;
     projectId?: string;
     conversationId?: string;
+    executionId?: string;
+    /** Omitted for legacy Assistant hosts. Project general agents must explicitly use project_agent. */
+    callerType?: AgentInvocationScope['callerType'];
     threadId?: string;
     xpertId?: string;
     workspaceDataScope?: XpertWorkspaceDataScope | null;

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

@@ -8,6 +8,7 @@ import { Command } from '@langchain/langgraph';
 import type { JsonSchemaObjectType } from '@xpert-ai/contracts';
 import { AgentBuiltInState, Runtime } from './runtime';
 import { PromiseOrValue } from '../../types';
+import type { ModelRequirements } from './model-requirements';
 export type ServerTool = Record<string, unknown>;
 export type ClientTool = StructuredToolInterface | DynamicTool | RunnableToolLike;
 export type NormalizedSchemaInput<TSchema extends InteropZodObject | undefined | never = any> = [TSchema] extends [
@@ -107,16 +108,26 @@ export type AfterAgentHook<TSchema extends InteropZodObject | undefined = undefi
  */
 export interface ModelRequest<TState extends Record<string, unknown> = Record<string, unknown>, TContext = unknown> {
     /**
-     * The model to use for this step.
+     * The unbound model to use for this step. Middleware may replace it before
+     * the host binds the final tool selection or structured output schema.
+     * Replacements must expose bindTools/withStructuredOutput when those features
+     * are used. A plain Runnable is supported for calls without either feature.
      */
     model: LanguageModelLike;
     /**
      * The messages to send to the model.
      */
     messages: BaseMessage[];
+    /**
+     * Hard capability requirements for this call. The host unions middleware
+     * contributions and checks every selected model, including fallbacks.
+     * Required capabilities cannot be silently dropped or replaced by a static response.
+     */
+    requirements?: ModelRequirements;
     systemMessage?: SystemMessage;
     /**
-     * Tool choice configuration (model-specific format).
+     * Portable tool choice configuration, applied by the host after selection.
+     * A named tool must remain selected; "required" needs a non-empty selection.
      * Can be one of:
      * - `"auto"`: means the model can pick between generating a message or calling one or more tools.
      * - `"none"`: means the model will not call any tool and instead generates a message.
@@ -130,7 +141,11 @@ export interface ModelRequest<TState extends Record<string, unknown> = Record<st
         };
     };
     /**
-     * The tools to make available for this step.
+     * The registered tools to make available for this step. Return a subset of
+     * these instances (or an empty array) to change the model's available tools.
+     * New definitions, cloned tools and schema replacements require separate
+     * runtime registration so that every advertised tool has an execution route.
+     * Selection does not replace authorization at the tool execution boundary.
      */
     tools: (ServerTool | ClientTool)[];
     /**
@@ -225,6 +240,8 @@ export interface AgentMiddleware<TSchema extends InteropZodObject | undefined =
      */
     contextSchema?: TContextSchema;
     tools?: DynamicStructuredTool[];
+    /** Resource-backed MCP Apps and explicit model/App tool visibility. */
+    apps?: import('../../mcp/app').MiddlewareMcpApps;
     beforeAgent?: BeforeAgentHook<TSchema, TFullContext>;
     beforeModel?: BeforeModelHook<TSchema, TFullContext>;
     afterModel?: AfterModelHook<TSchema, TFullContext>;

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

@@ -0,0 +1,3 @@
+/** Older runtime plugins can still send this event; new emissions use ON_CHAT_EVENT. */
+export declare const RESOURCE_CARD_EVENT = "xpert.resource_card";
+export { emitResourceCard } from '../resource-card';

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

@@ -0,0 +1,6 @@
+import type { ExecutionActivityBatch, ExecutionActivityCheckpoint } from '@xpert-ai/contracts';
+/** Optional, invocation-bound public activity sink. Does not alter execution or business status. */
+export interface AgentActivityRecorder {
+    readCheckpoint(): Promise<ExecutionActivityCheckpoint>;
+    append(batch: ExecutionActivityBatch): Promise<ExecutionActivityCheckpoint>;
+}

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

@@ -0,0 +1,37 @@
+import type { AgentInvocation, AgentInvocationRequest, AgentJson, AgentTarget } from './types';
+import type { RuntimeIdentityScope } from '../../runtime/runtime-scope';
+import type { TaskWaitRequest, TaskWaitResult } from './task-wait';
+import type { ConversationResourceCard } from '@xpert-ai/contracts';
+/** Invocation API bound to one authorized caller/execution. Each operation revalidates access. */
+export interface AgentInvocationApi {
+    /** Create a host-owned presentation receipt after a successful dispatch, without inspecting the runtime. */
+    getResourceCard?(invocationId: string): Promise<ConversationResourceCard | null>;
+    /** Resolve a binding to a pinned target. Optional on hosts with pre-resolved native targets. */
+    resolve?(bindingId: string): Promise<AgentTarget>;
+    /** Start or recover an idempotent request. The returned snapshot may still be running. */
+    start(request: AgentInvocationRequest): Promise<AgentInvocation>;
+    /** Refresh an existing invocation, possibly persisting provider observations. Never relaunches work. */
+    inspect(invocationId: string): Promise<AgentInvocation>;
+    /** Request supported cancellation; cancelling does not confirm termination. */
+    cancel(invocationId: string): Promise<AgentInvocation>;
+    /** Answer the current interaction using its exact ID and provider-defined response schema. */
+    respond(invocationId: string, interactionId: string, response: AgentJson): Promise<AgentInvocation>;
+    /** Bounded observation; may return a running task. Only human interactions may suspend the graph. */
+    awaitResult?(invocationId: string, options?: {
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }): Promise<AgentInvocation>;
+    /** Wait for dependencies within a bounded window. The Agent may wait again when the result is pending. */
+    waitForTasks?(request: TaskWaitRequest, options?: {
+        signal?: AbortSignal;
+    }): Promise<TaskWaitResult<AgentInvocation>>;
+}
+/** Caller-scoped API obtained through runtime.capabilities.require(...). */
+export declare const AgentInvocationRuntimeCapability: import("../../core/runtime-capability").RuntimeCapabilityKey<AgentInvocationApi>;
+/** Trusted host factory; scope must come from authenticated context, not model arguments. */
+export interface AgentRuntimeFactory {
+    /** Create an API per caller/execution. Do not cache it as a global singleton. */
+    createScopedApi(scope: RuntimeIdentityScope): AgentInvocationApi;
+}
+/** Platform factory capability. The wire key is stable across SDK naming changes. */
+export declare const AgentRuntimeFactoryCapability: import("../../core/runtime-capability").RuntimeCapabilityKey<AgentRuntimeFactory>;

package/src/lib/agent/runtime/cli-model-profile.d.ts

@@ -0,0 +1,62 @@
+import type { ModelExecutionModel, ModelExecutionLimits, ModelExecutionProtocol, ModelFeature, CliPermissionMode } from '@xpert-ai/contracts';
+/** Configuration adapters describe secrets by reference; only the host materializes credentials. */
+export declare const CLI_MODEL_TOKEN_REFERENCE = "${XPERT_EXECUTION_TOKEN}";
+export interface CliModelConfiguration {
+    args: string[];
+    environment: Record<string, string>;
+    files: Array<{
+        name: string;
+        content: string;
+    }>;
+}
+export interface CliModelConfigurationInput {
+    directory: string;
+    gatewayBaseUrl: string;
+    defaultModelId?: string;
+    models: Array<Pick<ModelExecutionModel, 'id' | 'protocols' | 'contextWindow' | 'outputTokenLimit'>>;
+    /** @deprecated Legacy input only. Use the selected model's catalog metadata. */
+    limits?: Partial<ModelExecutionLimits> & {
+        maxOutputTokens?: number;
+    };
+    managed: boolean;
+    /** Host-resolved background approval policy; omitted preserves interactive/shell behavior. */
+    permissionMode?: CliPermissionMode;
+}
+/** Installed trusted code; neither an executable path nor a model permission comes from this adapter. */
+export interface CliModelProfile {
+    id: string;
+    revision: string;
+    command: string;
+    protocol: Extract<ModelExecutionProtocol, 'openai_chat' | 'openai_responses' | 'anthropic_messages'>;
+    requiredCapabilities: ModelFeature[];
+    /** Modes this profile explicitly implements; unsupported modes must not be silently ignored. */
+    permissionModes?: readonly CliPermissionMode[];
+    chatBridge?: {
+        versions: readonly string[];
+        requiredCapabilities: ModelFeature[];
+    };
+    /** Optional host-managed background transport. Arguments are trusted profile code, never model input. */
+    background?: {
+        versions: readonly string[];
+    } & ({
+        transport: 'opencode';
+    } | {
+        transport: 'jsonl';
+        args: readonly string[];
+        /** For CLIs without stdin prompt support. Host appends one literal argv value, never shell text. */
+        promptArgument?: string;
+    });
+    /** Exact complete argv sequences that never need a model grant. */
+    offlineArguments: readonly (readonly string[])[];
+    /** Exact accepted stdout values for a policy-pinned version probe. */
+    versionOutputs(version: string): string[];
+    configure(input: CliModelConfigurationInput): CliModelConfiguration;
+}
+export interface CliModelProfiles {
+    get(id: string): CliModelProfile | undefined;
+}
+export declare const CliModelProfilesCapability: import("../../core/runtime-capability").RuntimeCapabilityKey<CliModelProfiles>;
+/** Additional execution sources can validate lifecycle without making OS depend on Pro entities. */
+export declare const ShellModelExecutionSourceCapability: import("../../core/runtime-capability").RuntimeCapabilityKey<{
+    assertCurrent(context: import("@xpert-ai/contracts").ModelExecutionContext, preparing?: boolean): Promise<void>;
+}>;