@xpert-ai/plugin-sdk 3.19.0 → 3.20.0

package/model-provider.cjs.js

@@ -272,6 +272,10 @@ const ProjectAccessRuntimeCapability = createRuntimeCapability('platform.project
     description: 'Resolve human Project membership for platform and plugin operations.'
 });
 
+const ToolImagesRuntimeCapability = createRuntimeCapability('platform.tool-images', {
+    description: 'Save scoped immutable tool images and materialize verified pixels for one model request.'
+});
+
 /**
  * Shared host-runtime plumbing for built-in tools backed by a configured model provider.
  * Provider request/response semantics remain owned by each plugin.
@@ -408,6 +412,7 @@ exports.SANDBOX_JOB_ERROR_CODES = SANDBOX_JOB_ERROR_CODES;
 exports.SANDBOX_JOB_PROGRESS_PREFIX = SANDBOX_JOB_PROGRESS_PREFIX;
 exports.SandboxJobRuntimeError = SandboxJobRuntimeError;
 exports.SandboxJobsRuntimeCapability = SandboxJobsRuntimeCapability;
+exports.ToolImagesRuntimeCapability = ToolImagesRuntimeCapability;
 exports.WORKSPACE_FILES_SOURCE = WORKSPACE_FILES_SOURCE;
 exports.WorkspaceFilesRuntimeCapability = WorkspaceFilesRuntimeCapability;
 exports.XPERT_RUNTIME_CAPABILITIES_TOKEN = XPERT_RUNTIME_CAPABILITIES_TOKEN;

package/model-provider.esm.js

@@ -270,6 +270,10 @@ const ProjectAccessRuntimeCapability = createRuntimeCapability('platform.project
     description: 'Resolve human Project membership for platform and plugin operations.'
 });
 
+const ToolImagesRuntimeCapability = createRuntimeCapability('platform.tool-images', {
+    description: 'Save scoped immutable tool images and materialize verified pixels for one model request.'
+});
+
 /**
  * Shared host-runtime plumbing for built-in tools backed by a configured model provider.
  * Provider request/response semantics remain owned by each plugin.
@@ -384,4 +388,4 @@ function normalizeWorkspaceScope(scope) {
     } : {});
 }
 
-export { ActorTokenRuntimeCapability as A, BuiltinToolset as B, DefaultRuntimeCapabilityRegistry as D, KnowledgeDocumentVisualAssetsRuntimeCapability as K, ModelProviderBuiltinToolset as M, ProjectAccessRuntimeCapability as P, RUNTIME_CAPABILITY_PROVIDER as R, SANDBOX_JOB_ERROR_CODES as S, WorkspaceFilesRuntimeCapability as W, XPERT_RUNTIME_CAPABILITIES_TOKEN as X, ActorTokenRuntimeFactoryCapability as a, ArtifactsRuntimeCapability as b, createRuntimeCapability as c, BaseTool as d, BaseToolset as e, KnowledgeDocumentVisualAssetsRuntimeFactoryCapability as f, KnowledgeGraphRuntimeCapability as g, KnowledgebaseDocumentsRuntimeCapability as h, KnowledgebaseProvisioningRuntimeCapability as i, KnowledgebaseRuntimeCapability as j, ProjectProvisioningRuntimeCapability as k, RuntimeCapabilityProvider as l, SANDBOX_JOB_PROGRESS_PREFIX as m, SandboxJobRuntimeError as n, SandboxJobsRuntimeCapability as o, WORKSPACE_FILES_SOURCE as p, isSandboxJobRuntimeError as q };
+export { ActorTokenRuntimeCapability as A, BuiltinToolset as B, DefaultRuntimeCapabilityRegistry as D, KnowledgeDocumentVisualAssetsRuntimeCapability as K, ModelProviderBuiltinToolset as M, ProjectAccessRuntimeCapability as P, RUNTIME_CAPABILITY_PROVIDER as R, SANDBOX_JOB_ERROR_CODES as S, ToolImagesRuntimeCapability as T, WorkspaceFilesRuntimeCapability as W, XPERT_RUNTIME_CAPABILITIES_TOKEN as X, ActorTokenRuntimeFactoryCapability as a, ArtifactsRuntimeCapability as b, createRuntimeCapability as c, BaseTool as d, BaseToolset as e, KnowledgeDocumentVisualAssetsRuntimeFactoryCapability as f, KnowledgeGraphRuntimeCapability as g, KnowledgebaseDocumentsRuntimeCapability as h, KnowledgebaseProvisioningRuntimeCapability as i, KnowledgebaseRuntimeCapability as j, ProjectProvisioningRuntimeCapability as k, RuntimeCapabilityProvider as l, SANDBOX_JOB_PROGRESS_PREFIX as m, SandboxJobRuntimeError as n, SandboxJobsRuntimeCapability as o, WORKSPACE_FILES_SOURCE as p, isSandboxJobRuntimeError as q };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xpert-ai/plugin-sdk",
-  "version": "3.19.0",
+  "version": "3.20.0",
   "license": "AGPL-3.0",
   "repository": {
     "type": "git",
@@ -19,6 +19,12 @@
       "import": "./index.cjs.mjs",
       "default": "./index.cjs.js"
     },
+    "./agent-results": {
+      "module": "./agent-results.esm.js",
+      "types": "./agent-results.d.ts",
+      "import": "./agent-results.cjs.mjs",
+      "default": "./agent-results.cjs.js"
+    },
     "./data-workbench": {
       "module": "./data-workbench.esm.js",
       "types": "./data-workbench.d.ts",
@@ -56,7 +62,7 @@
   },
   "dependencies": {
     "@langchain/openai": "0.6.9",
-    "@xpert-ai/contracts": "3.19.0",
+    "@xpert-ai/contracts": "3.20.0",
     "express": "^4.22.1",
     "js-tiktoken": "^1.0.21"
   },

package/results.cjs.js

@@ -0,0 +1,50 @@
+'use strict';
+
+var _extends = require('./_extends.cjs.js');
+var v3 = require('zod/v3');
+var contracts = require('@xpert-ai/contracts');
+
+/** Opt in to the host's authorized, on-demand result View from middleware metadata. */ const AGENT_TASK_RESULTS_FEATURE = 'agent_task_results';
+const common = {
+    id: v3.z.string().regex(/^[a-zA-Z0-9_-]{1,80}$/),
+    title: v3.z.string().min(1).max(200),
+    summary: v3.z.string().max(16000)
+};
+/** Machine-readable result kind; file declarations are not committed artifacts or download grants. */ const agentResultItemSchema = v3.z.discriminatedUnion('type', [
+    v3.z.object(_extends._extends({}, common, {
+        type: v3.z.literal('analysis')
+    })).strict(),
+    v3.z.object(_extends._extends({}, common, {
+        type: v3.z.literal('changes'),
+        files: v3.z.array(v3.z.object({
+            path: contracts.agentResultPathSchema,
+            change: v3.z.enum([
+                'created',
+                'modified',
+                'deleted'
+            ])
+        }).strict()).max(128)
+    })).strict(),
+    v3.z.object(_extends._extends({}, common, {
+        type: v3.z.literal('tests'),
+        status: v3.z.enum([
+            'passed',
+            'failed',
+            'skipped'
+        ]),
+        command: v3.z.string().max(2000).optional()
+    })).strict(),
+    v3.z.object(_extends._extends({}, common, {
+        type: v3.z.literal('file'),
+        path: contracts.agentResultPathSchema
+    })).strict()
+]);
+/** Explicit final response envelope shared by adapters; ordinary prose is never classified heuristically. */ const agentTaskResultSchema = v3.z.object({
+    version: v3.z.literal(1),
+    summary: v3.z.string().max(64000),
+    items: v3.z.array(agentResultItemSchema).max(32)
+}).strict().refine((value)=>new Set(value.items.map((item)=>item.id)).size === value.items.length, 'Result item IDs must be unique');
+
+exports.AGENT_TASK_RESULTS_FEATURE = AGENT_TASK_RESULTS_FEATURE;
+exports.agentResultItemSchema = agentResultItemSchema;
+exports.agentTaskResultSchema = agentTaskResultSchema;

package/results.esm.js

@@ -0,0 +1,46 @@
+import { _ as _extends } from './_extends.esm.js';
+import { z } from 'zod/v3';
+import { agentResultPathSchema } from '@xpert-ai/contracts';
+
+/** Opt in to the host's authorized, on-demand result View from middleware metadata. */ const AGENT_TASK_RESULTS_FEATURE = 'agent_task_results';
+const common = {
+    id: z.string().regex(/^[a-zA-Z0-9_-]{1,80}$/),
+    title: z.string().min(1).max(200),
+    summary: z.string().max(16000)
+};
+/** Machine-readable result kind; file declarations are not committed artifacts or download grants. */ const agentResultItemSchema = z.discriminatedUnion('type', [
+    z.object(_extends({}, common, {
+        type: z.literal('analysis')
+    })).strict(),
+    z.object(_extends({}, common, {
+        type: z.literal('changes'),
+        files: z.array(z.object({
+            path: agentResultPathSchema,
+            change: z.enum([
+                'created',
+                'modified',
+                'deleted'
+            ])
+        }).strict()).max(128)
+    })).strict(),
+    z.object(_extends({}, common, {
+        type: z.literal('tests'),
+        status: z.enum([
+            'passed',
+            'failed',
+            'skipped'
+        ]),
+        command: z.string().max(2000).optional()
+    })).strict(),
+    z.object(_extends({}, common, {
+        type: z.literal('file'),
+        path: agentResultPathSchema
+    })).strict()
+]);
+/** Explicit final response envelope shared by adapters; ordinary prose is never classified heuristically. */ const agentTaskResultSchema = z.object({
+    version: z.literal(1),
+    summary: z.string().max(64000),
+    items: z.array(agentResultItemSchema).max(32)
+}).strict().refine((value)=>new Set(value.items.map((item)=>item.id)).size === value.items.length, 'Result item IDs must be unique');
+
+export { AGENT_TASK_RESULTS_FEATURE as A, agentResultItemSchema as a, agentTaskResultSchema as b };

package/src/agent-results.d.ts

@@ -0,0 +1,2 @@
+/** Browser-safe result contracts. Keep this entry independent of the server SDK barrel. */
+export * from './lib/agent/runtime/results';

package/src/index.d.ts

@@ -2,6 +2,8 @@ export * from './lib/plugin';
 export * from './lib/plugin.interface';
 export * from './lib/plugin-metadata';
 export * from './lib/artifact-namespace';
+export * from './lib/resource-card';
+export * from './lib/resource-card-provider';
 export * from './lib/types';
 export * from './lib/logger';
 export * from './lib/integration/index';

package/src/lib/agent/handoff/agent-chat.contract.d.ts

@@ -1,4 +1,4 @@
-import { TChatOptions, TChatRequest, TChatRuntimePrincipal, TChatSourceAuditOptions } from '@xpert-ai/contracts';
+import { TChatMessageEnvelope, TChatOptions, TChatRequest, TChatRuntimePrincipal, TChatSourceAuditOptions } from '@xpert-ai/contracts';
 export declare const AGENT_CHAT_DISPATCH_MESSAGE_TYPE: import("./message-type").StructuredHandoffMessageType;
 export declare const AGENT_CHAT_DISPATCH_ERROR_STEER_TARGET_NOT_RUNNING = "steer_target_not_running";
 export interface AgentChatHandoffMessageCallbackTarget {
@@ -16,11 +16,16 @@ export type AgentChatRuntimePrincipal = TChatRuntimePrincipal;
 export interface AgentChatDispatchPayload extends Record<string, unknown> {
     request: TChatRequest;
     options: TChatOptions & TChatSourceAuditOptions & {
+        /** Host-resolved runtime branch, independent of the conversation root. */
+        threadId?: string;
+        isDerivedThread?: boolean;
         xpertId?: string;
         isDraft?: boolean;
         from?: string;
         fromEndUserId?: string;
         runtimePrincipal?: AgentChatRuntimePrincipal;
+        /** Host-resolved provenance and presentation; never grants routing or execution privileges. */
+        messageEnvelope?: TChatMessageEnvelope;
         execution?: {
             id: string;
         };

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