@xpert-ai/plugin-sdk 3.19.0 → 3.21.0

package/src/lib/agent/handoff/agent-runtime-message.contract.d.ts

@@ -0,0 +1,319 @@
+import { z } from 'zod/v3';
+import { type AgentRuntimeReplyTarget } from '../runtime/dispatch';
+export declare const AGENT_RUNTIME_EVENT_MESSAGE_TYPE: import("./message-type").StructuredHandoffMessageType;
+/** Host-produced references. Consumers reload and authorize the invocation and its pinned observation. */
+export declare const agentRuntimeEventSchema: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+    kind: z.ZodLiteral<"progress">;
+    progress: z.ZodObject<{
+        source: z.ZodEnum<["executor", "host"]>;
+        observedAt: z.ZodString;
+        startedAt: z.ZodOptional<z.ZodString>;
+        phase: z.ZodOptional<z.ZodString>;
+        summary: z.ZodOptional<z.ZodString>;
+        steps: z.ZodOptional<z.ZodEffects<z.ZodObject<{
+            completed: z.ZodNumber;
+            total: z.ZodNumber;
+        }, "strict", z.ZodTypeAny, {
+            total?: number;
+            completed?: number;
+        }, {
+            total?: number;
+            completed?: number;
+        }>, {
+            total?: number;
+            completed?: number;
+        }, {
+            total?: number;
+            completed?: number;
+        }>>;
+    }, "strict", z.ZodTypeAny, {
+        source?: "executor" | "host";
+        startedAt?: string;
+        summary?: string;
+        steps?: {
+            total?: number;
+            completed?: number;
+        };
+        observedAt?: string;
+        phase?: string;
+    }, {
+        source?: "executor" | "host";
+        startedAt?: string;
+        summary?: string;
+        steps?: {
+            total?: number;
+            completed?: number;
+        };
+        observedAt?: string;
+        phase?: string;
+    }>;
+    version: z.ZodLiteral<1>;
+    invocationId: z.ZodString;
+    /** Revision of the persisted observation, never a queue delivery attempt. */
+    revision: z.ZodNumber;
+    projectTask: z.ZodOptional<z.ZodObject<{
+        projectId: z.ZodString;
+        projectTaskId: z.ZodString;
+        taskExecutionId: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        projectId?: string;
+        projectTaskId?: string;
+        taskExecutionId?: string;
+    }, {
+        projectId?: string;
+        projectTaskId?: string;
+        taskExecutionId?: string;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    version?: 1;
+    kind?: "progress";
+    projectTask?: {
+        projectId?: string;
+        projectTaskId?: string;
+        taskExecutionId?: string;
+    };
+    progress?: {
+        source?: "executor" | "host";
+        startedAt?: string;
+        summary?: string;
+        steps?: {
+            total?: number;
+            completed?: number;
+        };
+        observedAt?: string;
+        phase?: string;
+    };
+    invocationId?: string;
+    revision?: number;
+}, {
+    version?: 1;
+    kind?: "progress";
+    projectTask?: {
+        projectId?: string;
+        projectTaskId?: string;
+        taskExecutionId?: string;
+    };
+    progress?: {
+        source?: "executor" | "host";
+        startedAt?: string;
+        summary?: string;
+        steps?: {
+            total?: number;
+            completed?: number;
+        };
+        observedAt?: string;
+        phase?: string;
+    };
+    invocationId?: string;
+    revision?: number;
+}>, z.ZodObject<{
+    kind: z.ZodLiteral<"result">;
+    status: z.ZodEnum<["succeeded", "failed", "cancelled"]>;
+    version: z.ZodLiteral<1>;
+    invocationId: z.ZodString;
+    /** Revision of the persisted observation, never a queue delivery attempt. */
+    revision: z.ZodNumber;
+    projectTask: z.ZodOptional<z.ZodObject<{
+        projectId: z.ZodString;
+        projectTaskId: z.ZodString;
+        taskExecutionId: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        projectId?: string;
+        projectTaskId?: string;
+        taskExecutionId?: string;
+    }, {
+        projectId?: string;
+        projectTaskId?: string;
+        taskExecutionId?: string;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    status?: "failed" | "succeeded" | "cancelled";
+    version?: 1;
+    kind?: "result";
+    projectTask?: {
+        projectId?: string;
+        projectTaskId?: string;
+        taskExecutionId?: string;
+    };
+    invocationId?: string;
+    revision?: number;
+}, {
+    status?: "failed" | "succeeded" | "cancelled";
+    version?: 1;
+    kind?: "result";
+    projectTask?: {
+        projectId?: string;
+        projectTaskId?: string;
+        taskExecutionId?: string;
+    };
+    invocationId?: string;
+    revision?: number;
+}>, z.ZodObject<{
+    kind: z.ZodLiteral<"input_request">;
+    interactionId: z.ZodString;
+    version: z.ZodLiteral<1>;
+    invocationId: z.ZodString;
+    /** Revision of the persisted observation, never a queue delivery attempt. */
+    revision: z.ZodNumber;
+    projectTask: z.ZodOptional<z.ZodObject<{
+        projectId: z.ZodString;
+        projectTaskId: z.ZodString;
+        taskExecutionId: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        projectId?: string;
+        projectTaskId?: string;
+        taskExecutionId?: string;
+    }, {
+        projectId?: string;
+        projectTaskId?: string;
+        taskExecutionId?: string;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    version?: 1;
+    kind?: "input_request";
+    projectTask?: {
+        projectId?: string;
+        projectTaskId?: string;
+        taskExecutionId?: string;
+    };
+    invocationId?: string;
+    revision?: number;
+    interactionId?: string;
+}, {
+    version?: 1;
+    kind?: "input_request";
+    projectTask?: {
+        projectId?: string;
+        projectTaskId?: string;
+        taskExecutionId?: string;
+    };
+    invocationId?: string;
+    revision?: number;
+    interactionId?: string;
+}>]>;
+export type AgentRuntimeEvent = z.output<typeof agentRuntimeEventSchema>;
+/** Same observation always has the same HandoffMessage.id across retries and process restarts. */
+export declare function agentRuntimeEventMessageId(event: Pick<AgentRuntimeEvent, 'invocationId' | 'revision' | 'kind'>): string;
+/** Transport states are deliberately separate from Task and Invocation status. */
+export declare const agentRuntimeDeliveryStateSchema: z.ZodEnum<["pending", "received", "blocked", "failed"]>;
+export declare const agentRuntimeConsumptionStateSchema: z.ZodEnum<["pending", "processing", "processed", "blocked", "failed"]>;
+export type AgentRuntimeDeliveryState = z.output<typeof agentRuntimeDeliveryStateSchema>;
+export type AgentRuntimeConsumptionState = z.output<typeof agentRuntimeConsumptionStateSchema>;
+/** Store under a unique scoped key in the same transaction as the continuation reservation. */
+export declare const agentRuntimeResultClaimSchema: z.ZodObject<{
+    invocationId: z.ZodString;
+    resultRevision: z.ZodNumber;
+    recipient: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+        type: z.ZodOptional<z.ZodLiteral<"xpert">>;
+        xpertId: z.ZodString;
+        agentKey: z.ZodString;
+        conversationId: z.ZodString;
+        threadId: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        type?: "xpert";
+        threadId?: string;
+        conversationId?: string;
+        xpertId?: string;
+        agentKey?: string;
+    }, {
+        type?: "xpert";
+        threadId?: string;
+        conversationId?: string;
+        xpertId?: string;
+        agentKey?: string;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"project_agent">;
+        projectId: z.ZodString;
+        agentKey: z.ZodLiteral<"general_agent">;
+        conversationId: z.ZodString;
+        threadId: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        type?: "project_agent";
+        threadId?: string;
+        conversationId?: string;
+        projectId?: string;
+        agentKey?: "general_agent";
+    }, {
+        type?: "project_agent";
+        threadId?: string;
+        conversationId?: string;
+        projectId?: string;
+        agentKey?: "general_agent";
+    }>]>;
+    consumer: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+        type: z.ZodLiteral<"follow_up">;
+        executionId: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        type?: "follow_up";
+        executionId?: string;
+    }, {
+        type?: "follow_up";
+        executionId?: string;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"wait">;
+        executionId: z.ZodString;
+        callId: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        type?: "wait";
+        executionId?: string;
+        callId?: string;
+    }, {
+        type?: "wait";
+        executionId?: string;
+        callId?: string;
+    }>]>;
+}, "strict", z.ZodTypeAny, {
+    invocationId?: string;
+    resultRevision?: number;
+    recipient?: {
+        type?: "xpert";
+        threadId?: string;
+        conversationId?: string;
+        xpertId?: string;
+        agentKey?: string;
+    } | {
+        type?: "project_agent";
+        threadId?: string;
+        conversationId?: string;
+        projectId?: string;
+        agentKey?: "general_agent";
+    };
+    consumer?: {
+        type?: "follow_up";
+        executionId?: string;
+    } | {
+        type?: "wait";
+        executionId?: string;
+        callId?: string;
+    };
+}, {
+    invocationId?: string;
+    resultRevision?: number;
+    recipient?: {
+        type?: "xpert";
+        threadId?: string;
+        conversationId?: string;
+        xpertId?: string;
+        agentKey?: string;
+    } | {
+        type?: "project_agent";
+        threadId?: string;
+        conversationId?: string;
+        projectId?: string;
+        agentKey?: "general_agent";
+    };
+    consumer?: {
+        type?: "follow_up";
+        executionId?: string;
+    } | {
+        type?: "wait";
+        executionId?: string;
+        callId?: string;
+    };
+}>;
+export type AgentRuntimeResultClaim = z.output<typeof agentRuntimeResultClaimSchema>;
+/**
+ * Wait and asynchronous reply compete for this same key, regardless of delivery revision.
+ * The storage key must additionally include tenant, organization and owner from trusted scope.
+ */
+export declare function agentRuntimeResultConsumptionKey(invocationId: string, recipient: AgentRuntimeReplyTarget): string;

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

@@ -1,5 +1,6 @@
 export * from './message-type';
 export * from './agent-chat.contract';
+export * from './agent-runtime-message.contract';
 export * from './handoff.interface';
 export * from './handoff-processor.decorator';
 export * from './handoff-processor.registry';

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

@@ -2,3 +2,4 @@ export * from './skill/index';
 export * from './middleware';
 export * from './handoff';
 export * from './runtime';
+export * from './resource-card';

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 [
@@ -117,6 +118,12 @@ export interface ModelRequest<TState extends Record<string, unknown> = Record<st
      * 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;
     /**
      * Portable tool choice configuration, applied by the host after selection.

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

@@ -1,7 +1,11 @@
 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. */
@@ -12,11 +16,15 @@ export interface AgentInvocationApi {
     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>;
-    /**
-     * Optional checkpoint-aware wait; returns a terminal or unknown observation.
-     * Allow host suspension to propagate instead of treating it as a tool failure.
-     */
-    awaitResult?(invocationId: string): 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>;

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