@xpert-ai/plugin-sdk 3.19.0 → 3.20.0

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

@@ -0,0 +1,335 @@
+import { z } from 'zod/v3';
+import { type AgentOutputDelivery } from '@xpert-ai/contracts';
+/** Opt in to the host's authorized, on-demand result View from middleware metadata. */
+export declare const AGENT_TASK_RESULTS_FEATURE = "agent_task_results";
+export { agentResultPathSchema, agentOutputDeliverySchema, type AgentOutputDelivery } from '@xpert-ai/contracts';
+/** Machine-readable result kind; file declarations are not committed artifacts or download grants. */
+export declare const agentResultItemSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+    type: z.ZodLiteral<"analysis">;
+    id: z.ZodString;
+    title: z.ZodString;
+    summary: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    type?: "analysis";
+    id?: string;
+    title?: string;
+    summary?: string;
+}, {
+    type?: "analysis";
+    id?: string;
+    title?: string;
+    summary?: string;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"changes">;
+    files: z.ZodArray<z.ZodObject<{
+        path: z.ZodEffects<z.ZodString, string, string>;
+        change: z.ZodEnum<["created", "modified", "deleted"]>;
+    }, "strict", z.ZodTypeAny, {
+        path?: string;
+        change?: "created" | "modified" | "deleted";
+    }, {
+        path?: string;
+        change?: "created" | "modified" | "deleted";
+    }>, "many">;
+    id: z.ZodString;
+    title: z.ZodString;
+    summary: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    type?: "changes";
+    id?: string;
+    title?: string;
+    summary?: string;
+    files?: {
+        path?: string;
+        change?: "created" | "modified" | "deleted";
+    }[];
+}, {
+    type?: "changes";
+    id?: string;
+    title?: string;
+    summary?: string;
+    files?: {
+        path?: string;
+        change?: "created" | "modified" | "deleted";
+    }[];
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"tests">;
+    status: z.ZodEnum<["passed", "failed", "skipped"]>;
+    command: z.ZodOptional<z.ZodString>;
+    id: z.ZodString;
+    title: z.ZodString;
+    summary: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    type?: "tests";
+    status?: "passed" | "failed" | "skipped";
+    id?: string;
+    title?: string;
+    summary?: string;
+    command?: string;
+}, {
+    type?: "tests";
+    status?: "passed" | "failed" | "skipped";
+    id?: string;
+    title?: string;
+    summary?: string;
+    command?: string;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"file">;
+    path: z.ZodEffects<z.ZodString, string, string>;
+    id: z.ZodString;
+    title: z.ZodString;
+    summary: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    type?: "file";
+    path?: string;
+    id?: string;
+    title?: string;
+    summary?: string;
+}, {
+    type?: "file";
+    path?: string;
+    id?: string;
+    title?: string;
+    summary?: string;
+}>]>;
+export type AgentResultItem = z.output<typeof agentResultItemSchema>;
+/** Explicit final response envelope shared by adapters; ordinary prose is never classified heuristically. */
+export declare const agentTaskResultSchema: z.ZodEffects<z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    summary: z.ZodString;
+    items: z.ZodArray<z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+        type: z.ZodLiteral<"analysis">;
+        id: z.ZodString;
+        title: z.ZodString;
+        summary: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        type?: "analysis";
+        id?: string;
+        title?: string;
+        summary?: string;
+    }, {
+        type?: "analysis";
+        id?: string;
+        title?: string;
+        summary?: string;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"changes">;
+        files: z.ZodArray<z.ZodObject<{
+            path: z.ZodEffects<z.ZodString, string, string>;
+            change: z.ZodEnum<["created", "modified", "deleted"]>;
+        }, "strict", z.ZodTypeAny, {
+            path?: string;
+            change?: "created" | "modified" | "deleted";
+        }, {
+            path?: string;
+            change?: "created" | "modified" | "deleted";
+        }>, "many">;
+        id: z.ZodString;
+        title: z.ZodString;
+        summary: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        type?: "changes";
+        id?: string;
+        title?: string;
+        summary?: string;
+        files?: {
+            path?: string;
+            change?: "created" | "modified" | "deleted";
+        }[];
+    }, {
+        type?: "changes";
+        id?: string;
+        title?: string;
+        summary?: string;
+        files?: {
+            path?: string;
+            change?: "created" | "modified" | "deleted";
+        }[];
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"tests">;
+        status: z.ZodEnum<["passed", "failed", "skipped"]>;
+        command: z.ZodOptional<z.ZodString>;
+        id: z.ZodString;
+        title: z.ZodString;
+        summary: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        type?: "tests";
+        status?: "passed" | "failed" | "skipped";
+        id?: string;
+        title?: string;
+        summary?: string;
+        command?: string;
+    }, {
+        type?: "tests";
+        status?: "passed" | "failed" | "skipped";
+        id?: string;
+        title?: string;
+        summary?: string;
+        command?: string;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"file">;
+        path: z.ZodEffects<z.ZodString, string, string>;
+        id: z.ZodString;
+        title: z.ZodString;
+        summary: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        type?: "file";
+        path?: string;
+        id?: string;
+        title?: string;
+        summary?: string;
+    }, {
+        type?: "file";
+        path?: string;
+        id?: string;
+        title?: string;
+        summary?: string;
+    }>]>, "many">;
+}, "strict", z.ZodTypeAny, {
+    summary?: string;
+    version?: 1;
+    items?: ({
+        type?: "analysis";
+        id?: string;
+        title?: string;
+        summary?: string;
+    } | {
+        type?: "changes";
+        id?: string;
+        title?: string;
+        summary?: string;
+        files?: {
+            path?: string;
+            change?: "created" | "modified" | "deleted";
+        }[];
+    } | {
+        type?: "tests";
+        status?: "passed" | "failed" | "skipped";
+        id?: string;
+        title?: string;
+        summary?: string;
+        command?: string;
+    } | {
+        type?: "file";
+        path?: string;
+        id?: string;
+        title?: string;
+        summary?: string;
+    })[];
+}, {
+    summary?: string;
+    version?: 1;
+    items?: ({
+        type?: "analysis";
+        id?: string;
+        title?: string;
+        summary?: string;
+    } | {
+        type?: "changes";
+        id?: string;
+        title?: string;
+        summary?: string;
+        files?: {
+            path?: string;
+            change?: "created" | "modified" | "deleted";
+        }[];
+    } | {
+        type?: "tests";
+        status?: "passed" | "failed" | "skipped";
+        id?: string;
+        title?: string;
+        summary?: string;
+        command?: string;
+    } | {
+        type?: "file";
+        path?: string;
+        id?: string;
+        title?: string;
+        summary?: string;
+    })[];
+}>, {
+    summary?: string;
+    version?: 1;
+    items?: ({
+        type?: "analysis";
+        id?: string;
+        title?: string;
+        summary?: string;
+    } | {
+        type?: "changes";
+        id?: string;
+        title?: string;
+        summary?: string;
+        files?: {
+            path?: string;
+            change?: "created" | "modified" | "deleted";
+        }[];
+    } | {
+        type?: "tests";
+        status?: "passed" | "failed" | "skipped";
+        id?: string;
+        title?: string;
+        summary?: string;
+        command?: string;
+    } | {
+        type?: "file";
+        path?: string;
+        id?: string;
+        title?: string;
+        summary?: string;
+    })[];
+}, {
+    summary?: string;
+    version?: 1;
+    items?: ({
+        type?: "analysis";
+        id?: string;
+        title?: string;
+        summary?: string;
+    } | {
+        type?: "changes";
+        id?: string;
+        title?: string;
+        summary?: string;
+        files?: {
+            path?: string;
+            change?: "created" | "modified" | "deleted";
+        }[];
+    } | {
+        type?: "tests";
+        status?: "passed" | "failed" | "skipped";
+        id?: string;
+        title?: string;
+        summary?: string;
+        command?: string;
+    } | {
+        type?: "file";
+        path?: string;
+        id?: string;
+        title?: string;
+        summary?: string;
+    })[];
+}>;
+export type AgentTaskResult = z.output<typeof agentTaskResultSchema>;
+/** Persist only after the platform has committed the artifact; never accept an ID invented by a model. */
+export interface AgentResultArtifact {
+    id: string;
+    name?: string;
+    mimeType?: string;
+    /** Required for downloads; optional only to read older task records without changing their meaning. */
+    versionId?: string;
+    /** Item paths included in this immutable artifact. */
+    paths?: string[];
+}
+export interface AgentArtifactSelection {
+    mode: 'files' | 'archive';
+    /** Exact relative files; the runner still enforces filesystem and delivery authorization. */
+    paths: string[];
+}
+/** Export outcome is independent of task success, so an export error cannot hide completed work. */
+export interface AgentOutputExport {
+    mode: AgentOutputDelivery['mode'];
+    status: 'not_requested' | 'completed' | 'failed' | 'unavailable';
+    /** Safe diagnostic only; execution status is independent of export status. */
+    error?: string;
+}

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

@@ -1,6 +1,7 @@
 import { DiscoveryService, Reflector } from '@nestjs/core';
 import type { RuntimeCapabilityRegistry } from '../../core/runtime-capability';
 import { BaseStrategyRegistry, type StrategySource } from '../../strategy';
+import type { AgentActivityRecorder } from './activity';
 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 {
@@ -10,6 +11,8 @@ export interface AgentRuntimeContext {
     /** Cooperative cancellation; abort alone does not confirm remote termination. */
     signal?: AbortSignal;
     capabilities: RuntimeCapabilityRegistry;
+    /** Available only for declared public activity; scoped by the host to this invocation. */
+    activity?: AgentActivityRecorder;
     /** Persist a receipt before waiting on long-running work. Await persistence and propagate failures. */
     checkpoint(observation: AgentRuntimeObservation): Promise<void>;
 }

package/src/lib/agent/runtime/task-wait.d.ts

@@ -0,0 +1,35 @@
+/** Provider-neutral dependency waiting. A wait ending does not terminate its tasks. */
+export type TaskWaitMode = 'any' | 'all';
+/** `completed` means terminal, not necessarily successful. `timeout` is a historical durable-wait deadline. */
+export type TaskWaitReason = 'completed' | 'pending' | 'attention' | 'timeout' | 'unavailable';
+export interface TaskWaitRequest {
+    /** Stable tool-call identity, assigned by the host rather than the model. */
+    callId: string;
+    /** Distinct handles owned by the caller; the invocation adapter accepts at most 32. */
+    taskIds: string[];
+    /** Whether one terminal task or all terminal tasks satisfy this wait. */
+    mode: TaskWaitMode;
+    /** Requested observation window, bounded by host policy; expiry returns pending, not an interrupt. */
+    timeoutMs?: number;
+}
+export interface TaskWaitResult<T> {
+    reason: TaskWaitReason;
+    /** Latest observed states, including unfinished tasks when mode is `any`. */
+    tasks: T[];
+}
+/** Host policy caps the requested observation window. */
+export interface TaskWaitPolicy {
+    /** Default initial observation window, in milliseconds. */
+    inlineWaitMs: number;
+    /** Maximum duration of a single observation call, in milliseconds. */
+    maxInlineWaitMs: number;
+    /** Interval between backend reads; each read must bound its own I/O. */
+    pollIntervalMs: number;
+    /** Historical persisted wait deadline, independent of a new status-call duration. */
+    maxWaitMs: number;
+    /** Historical grace period before an ambiguous outcome is reported unavailable. */
+    unknownGraceMs: number;
+}
+/** Domain adapters map their explicit states into these dependency states. */
+export type TaskDependencyState = 'pending' | 'completed' | 'attention' | 'unknown';
+export declare function taskWaitReason(states: readonly TaskDependencyState[], mode: TaskWaitMode): TaskWaitReason | undefined;

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

@@ -1,3 +1,8 @@
+import type { AgentInvocationStatus, AgentRuntimeProgress, ModelExecutionEnvironment, ExecutionActivityCapabilities } from '@xpert-ai/contracts';
+export type { AgentInvocationStatus, AgentRuntimeProgress } from '@xpert-ai/contracts';
+import type { AgentInvocationDispatchContext } from './dispatch';
+import type { AgentRunnerReceipt } from './execution-runner';
+import type { AgentOutputDelivery, AgentOutputExport, AgentResultArtifact, AgentResultItem } from './results';
 /** Serializable invocation data. Use finite numbers and plain objects; exclude credentials. */
 export type AgentJson = null | boolean | number | string | AgentJson[] | {
     [key: string]: AgentJson;
@@ -15,6 +20,8 @@ export interface AgentInvocationScope {
     parentExecutionId: string;
     /** Calling Agent key or host-assigned background-task entry. */
     callerAgentKey: string;
+    /** Omitted preserves existing Assistant callers. Project general agents have no fabricated Assistant ID. */
+    callerType?: 'xpert' | 'project_agent';
     callerXpertId?: string;
 }
 /** Authorized, version-pinned target. Pass the resolved snapshot unchanged. */
@@ -34,6 +41,13 @@ export interface AgentTarget {
 }
 /** Provider support flags; they do not grant caller permissions. */
 export interface AgentRuntimeCapabilities {
+    activity?: ExecutionActivityCapabilities;
+    /** Explicit adapter compatibility; does not install tools or grant model/environment access. */
+    executionTools?: Array<{
+        id: string;
+        versions: string[];
+        environments: ModelExecutionEnvironment['type'][];
+    }>;
     /**
      * Recovery by host checkpoint, existing provider session, or none.
      * Session recovery does not guarantee survival of a worker crash.
@@ -44,16 +58,16 @@ export interface AgentRuntimeCapabilities {
     cancellation: boolean;
     /** Work can continue after start() returns. */
     background: boolean;
+    /** Omitted means unsupported. This declaration alone does not enable a host message API. */
+    runningMessages?: boolean;
+    /** A new invocation may reuse a prior session only through an explicitly supported adapter path. */
+    sessionContinuation?: 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;
+    /** No export by default; files/archive require an explicit delivery request. */
+    delivery?: AgentOutputDelivery;
     parameters?: {
         [key: string]: AgentJson;
     };
@@ -69,17 +83,19 @@ export interface AgentInvocationInput {
 /** Output or in-progress receipt. Check invocation status before treating it as final. */
 export interface AgentInvocationResult {
     text: string;
+    /** Explicit adapter-normalized findings; display kind is never inferred from prose or titles. */
+    items?: AgentResultItem[];
+    /** Separate delivery outcome; task success does not imply that files were exported. */
+    export?: AgentOutputExport;
     /** Adapter-defined structured output. */
     data?: AgentJson;
     /** Host-managed output references; normal artifact authorization applies. */
-    artifacts?: Array<{
-        id: string;
-        name?: string;
-        mimeType?: string;
-    }>;
+    artifacts?: AgentResultArtifact[];
 }
 /** Persisted provider receipt. Session/run IDs are distinct from the host invocation ID. */
 export interface AgentRuntimeHandle {
+    /** Optional host-managed process receipt; direct remote runtimes need only their session/run IDs. */
+    runner?: AgentRunnerReceipt;
     sessionId: string;
     runId: string;
     metadata?: {
@@ -103,6 +119,8 @@ export interface AgentRuntimeObservation {
     handle?: AgentRuntimeHandle;
     result?: AgentInvocationResult;
     interaction?: AgentInteraction;
+    /** Reported work/activity only; it never confirms business acceptance. */
+    progress?: AgentRuntimeProgress;
     /** Safe diagnostic message without credentials or raw provider payloads. */
     error?: string;
 }
@@ -115,9 +133,15 @@ export interface AgentInvocationRequest {
      */
     callId: string;
     input: AgentInvocationInput;
+    /** Optional host-owned asynchronous reply and project association; not supplied by the execution Agent. */
+    dispatch?: AgentInvocationDispatchContext;
 }
 /** Host-owned invocation snapshot; not an update DTO. */
 export interface AgentInvocation extends AgentRuntimeObservation {
+    /** Pinned presentation contract remains readable after the runtime plugin is removed. */
+    activity?: ExecutionActivityCapabilities;
+    /** Host startup fence; intermediate receipts are not inspected until start returns or this deadline expires. */
+    startPendingUntil?: string;
     /** Host invocation ID used by inspect, cancel and respond. */
     id: string;
     /** Host-managed concurrency revision, distinct from the target version. */

package/src/lib/ai-model/ai-model-provider.interface.d.ts

@@ -4,7 +4,9 @@ import { Embeddings } from '@langchain/core/embeddings';
 import { BaseChatModel } from '@langchain/core/language_models/chat_models';
 import { AIGCModelClient, AsyncAIGCModelClient, IRerank } from './types';
 import { AIModel } from './ai-model';
+import type { NativeModelClientFactory } from './native-model';
 export interface IAIModelProviderStrategy {
+    getNativeModelClient?: NativeModelClientFactory;
     /**
      * Provider metadata
      */

package/src/lib/ai-model/ai-model.d.ts

@@ -1,4 +1,5 @@
 import { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import type { RealtimeModelConnection } from './realtime';
 import { AIModelEntity, AiModelTypeEnum, ICopilotModel, ModelUsagePricingContext, ModelUsagePricingSnapshot, ParameterRule, PriceInfo, PriceType } from '@xpert-ai/contracts';
 import { Logger } from '@nestjs/common';
 import { ModelProvider } from './abstract-provider';
@@ -13,6 +14,7 @@ export declare abstract class AIModel implements IAIModel {
     private positions;
     constructor(modelProvider: ModelProvider, modelType: AiModelTypeEnum);
     abstract validateCredentials(model: string, credentials: Record<string, any>): Promise<void>;
+    getRealtimeModel(_copilotModel: ICopilotModel): RealtimeModelConnection;
     getChatModel(copilotModel: ICopilotModel, options?: TChatModelOptions): BaseChatModel;
     getAIGCModel(copilotModel: ICopilotModel, options?: TChatModelOptions): AIGCModelClient | AsyncAIGCModelClient;
     getPrice(model: string, credentials: Record<string, any>, priceType: PriceType, tokens: number, inputTokens?: number): PriceInfo;

package/src/lib/ai-model/index.d.ts

@@ -12,3 +12,6 @@ export * from './openai-compatible';
 export * from './model-provider-http-client';
 export * from './utils/index';
 export * from './commands/index';
+export * from './token-usage';
+export * from './native-model';
+export * from './realtime';

package/src/lib/ai-model/llm.d.ts

@@ -40,6 +40,8 @@ export declare abstract class LargeLanguageModel extends AIModel {
     #private;
     protected startedAt: DOMHighResTimeStamp;
     protected _commonParameterRules(model: string): ParameterRule[];
+    /** Price already normalized provider facts without starting another inference or writing a ledger. */
+    priceActualTokenUsage(model: string, tokenUsage: TTokenUsage, context?: LLMPriceContext): ILLMUsage;
     protected calcResponseUsage(model: string, credentials: Record<string, any>, promptTokens: number, completionTokens: number, startedAt?: number, tokenUsage?: TTokenUsage, pricingContext?: LLMPriceContext): ILLMUsage;
     createHandleUsageCallbacks(copilot: ICopilot, model: string, credentials: any, handleLLMTokens: TChatModelOptions['handleLLMTokens'], pricingConfiguration?: LLMUsagePricingConfiguration): {
         name: string;
@@ -90,8 +92,8 @@ export declare abstract class LargeLanguageModel extends AIModel {
         handleRetrieverError?(err: any, runId: string, parentRunId?: string, tags?: string[]): Promise<any> | any;
         handleCustomEvent?(eventName: string, data: any, runId: string, tags?: string[], metadata?: Record<string, any>): Promise<any> | any;
     }[];
-    createHandleLLMErrorCallbacks(fields: any, logger?: Logger): {
-        handleLLMError: (err: any) => void;
+    createHandleLLMErrorCallbacks(_fields: unknown, logger?: Logger): {
+        handleLLMError: (error: unknown) => void;
     };
     protected getCustomizableModelSchemaFromCredentials(model: string, credentials: Record<string, any>): AIModelEntity | null;
     protected createHandleVerboseCallbacks(enabled?: boolean, logger?: Logger): {

package/src/lib/ai-model/native-model.d.ts

@@ -0,0 +1,22 @@
+import type { ICopilotModel, ILLMUsage, LLMPriceContext, ModelExecutionProtocol, TTokenUsage } from '@xpert-ai/contracts';
+export type NativeModelProtocol = Extract<ModelExecutionProtocol, 'openai_responses' | 'anthropic_messages'>;
+export type NativeModelJson = null | boolean | number | string | NativeModelJson[] | {
+    [key: string]: NativeModelJson;
+};
+export type NativeModelBody = {
+    [key: string]: NativeModelJson;
+};
+/** Server-only capability. Provider credentials and configured upstream URLs never leave this closure. */
+export interface NativeModelClient {
+    readonly protocol: NativeModelProtocol;
+    generate(body: NativeModelBody, headers: Readonly<Record<string, string>>, signal: AbortSignal): Promise<Response>;
+    priceUsage(usage: TTokenUsage, context?: LLMPriceContext): ILLMUsage;
+}
+export type NativeModelClientFactory = (protocol: NativeModelProtocol, model: ICopilotModel) => Promise<NativeModelClient>;
+/** A single fetch is one billable attempt. No SDK retries or redirects to another credential origin. */
+export declare function nativeModelTransport(input: {
+    protocol: NativeModelProtocol;
+    baseUrl: string;
+    authorization: string;
+    fetch?: typeof fetch;
+}): NativeModelClient['generate'];

package/src/lib/ai-model/realtime.d.ts

@@ -0,0 +1,36 @@
+import type { RealtimeModelEvent, RealtimeToolResult, RealtimeTaskContext } from '@xpert-ai/contracts';
+import type { JSONSchema7 } from 'json-schema';
+export interface RealtimeSessionOptions {
+    voice: string;
+    instructions: string;
+    tools: {
+        name: string;
+        description: string;
+        parameters: JSONSchema7;
+    }[];
+}
+/** The host owns networking, credentials, backpressure and authorization. */
+export interface RealtimeProtocolSink {
+    send(event: object): void;
+    emit(event: RealtimeModelEvent): void;
+}
+export interface RealtimeProtocol {
+    start(): void;
+    receive(event: unknown): void;
+    appendAudio(audio: Uint8Array): void;
+    setMuted(muted: boolean): void;
+    cancelResponse(): void;
+    submitToolResults(results: RealtimeToolResult[]): void;
+    /** Synchronize task facts without requesting speech or emitting a user transcript. */
+    updateTaskContext?(tasks: RealtimeTaskContext[]): void;
+    notify(text: string): boolean;
+    close(): void;
+}
+/** Server-only connection descriptor. Never serialize this object to clients. */
+export interface RealtimeModelConnection {
+    url: string;
+    headers: {
+        [header: string]: string;
+    };
+    createProtocol(options: RealtimeSessionOptions, sink: RealtimeProtocolSink): RealtimeProtocol;
+}

package/src/lib/ai-model/token-usage.d.ts

@@ -0,0 +1,13 @@
+import type { TTokenUsage } from '@xpert-ai/contracts';
+export interface ResolvedTokenUsage {
+    usage: TTokenUsage;
+    source: 'provider' | 'estimated' | 'legacy' | 'unavailable';
+}
+/** Select a whole candidate. Never fill missing actual counts using estimates. */
+export declare function resolveTokenUsageCandidates(input: {
+    canonical?: Partial<TTokenUsage> | null;
+    actual?: Partial<TTokenUsage> | null;
+    estimated?: Partial<TTokenUsage> | null;
+    legacyTotal?: number;
+}): ResolvedTokenUsage;
+export declare function normalizeTokenUsage(candidate?: Partial<TTokenUsage> | null): TTokenUsage | null;

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

@@ -1,3 +1,4 @@
+import type { I18nObject, TMcpAppRefresh } from '@xpert-ai/contracts';
 export interface McpAppCsp {
     connectDomains?: string[];
     resourceDomains?: string[];
@@ -11,8 +12,10 @@ export interface McpAppPermissions {
 export interface McpAppDefinition {
     key: string;
     entry: string;
-    title?: string;
+    title?: string | I18nObject;
     description?: string;
+    /** Read-only tool called by the host Refresh action; never replays the entry tool. */
+    refresh?: TMcpAppRefresh;
     csp?: McpAppCsp;
     permissions?: McpAppPermissions;
 }

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

@@ -1,5 +1,5 @@
 import { DiscoveryService, Reflector } from '@nestjs/core';
-import type { ProjectTaskGraph, ProjectTaskGraphChange, ProjectTaskExecutionTarget, TXpertProjectTaskStatus } from '@xpert-ai/contracts';
+import type { ProjectTaskGraph, ProjectTaskGraphChange, ProjectTaskExecutionTarget, ProjectTaskTypeDefinition, TXpertProjectTaskStatus } from '@xpert-ai/contracts';
 import { BaseStrategyRegistry } from '../strategy';
 import type { ProjectAccessActor } from '../runtime/capabilities/project-access';
 export interface ProjectTaskContext {
@@ -10,7 +10,11 @@ export interface ProjectTaskProjection {
     key: string;
     title: string;
     status: TXpertProjectTaskStatus;
+    /** Completion percentage (0–100), independent of status. Omit to preserve; null clears it. */
+    progress?: number | null;
     kind: 'task' | 'summary' | 'milestone';
+    /** Registered business type; omitted values preserve legacy persisted types. Null explicitly clears it. */
+    taskType?: string | null;
     parentKey?: string;
     predecessorKeys: string[];
     diagnostic?: string;
@@ -37,6 +41,8 @@ export interface ProjectTaskSnapshot {
 }
 export interface IProjectTaskProvider {
     readonly key: string;
+    /** Presentation declarations belong to this provider and never contain executable icon code. */
+    readonly taskTypes?: readonly ProjectTaskTypeDefinition[];
     /** 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. */
@@ -45,6 +51,7 @@ export interface IProjectTaskProvider {
         taskId: string;
     }>): Promise<void>;
 }
+export type { ProjectTaskIconName, ProjectTaskTypeDefinition, ProjectTaskTypePresentation } from '@xpert-ai/contracts';
 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> {