@xpert-ai/plugin-sdk 3.18.7 → 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

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

package/src/lib/agent/runtime/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

@@ -0,0 +1,156 @@
+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;
+};
+/** Host-authorized ownership and execution scope; never accept identities from model input. */
+export interface AgentInvocationScope {
+    tenantId: string;
+    organizationId: string;
+    userId: string;
+    workspaceId?: string;
+    projectId?: string;
+    /** Platform conversation ID, distinct from a provider session ID. */
+    conversationId?: string;
+    /** Opaque parent execution identity; host Task adapters may use logical IDs. */
+    parentExecutionId: string;
+    /** Calling Agent key or host-assigned background-task entry. */
+    callerAgentKey: string;
+    /** 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. */
+export interface AgentTarget {
+    /** Opaque host binding ID; do not assume UUID format or derive the provider from it. */
+    bindingId: string;
+    /** Registered AgentRuntimeStrategy key. */
+    provider: string;
+    /** Opaque configuration version, distinct from the invocation revision. */
+    revision: string;
+    /** Provider-specific target/profile reference. */
+    reference: string;
+    /** Validated configuration; use managed secret references instead of credentials. */
+    configuration: {
+        [key: string]: AgentJson;
+    };
+}
+/** Provider support flags; they do not grant caller permissions. */
+export interface AgentRuntimeCapabilities {
+    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.
+     */
+    recovery: 'checkpoint' | 'session' | 'none';
+    interactions: boolean;
+    /** Supports cancel requests; termination still requires provider confirmation. */
+    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;
+}
+/** 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;
+    };
+    context?: {
+        [key: string]: AgentJson;
+    };
+    /** Host-managed file references, authorized and materialized by the adapter. */
+    files?: Array<{
+        id: string;
+        name?: string;
+    }>;
+}
+/** Output or in-progress receipt. Check invocation status before treating it as final. */
+export interface AgentInvocationResult {
+    text: string;
+    /** 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?: 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?: {
+        [key: string]: AgentJson;
+    };
+}
+/** Pending question or approval. Respond using its exact ID and provider-defined data schema. */
+export interface AgentInteraction {
+    id: string;
+    kind: 'approval' | 'input';
+    prompt: string;
+    data?: AgentJson;
+}
+/**
+ * Partial provider observation; omitted fields may retain previously stored values.
+ * The host manages identity, revisions and persistence.
+ */
+export interface AgentRuntimeObservation {
+    /** succeeded requires a result, even for structured-only output. */
+    status: AgentInvocationStatus;
+    handle?: AgentRuntimeHandle;
+    result?: AgentInvocationResult;
+    interaction?: AgentInteraction;
+    /** Reported work/activity only; it never confirms business acceptance. */
+    progress?: AgentRuntimeProgress;
+    /** Safe diagnostic message without credentials or raw provider payloads. */
+    error?: string;
+}
+/** Request pinned by the host before dispatch. */
+export interface AgentInvocationRequest {
+    target: AgentTarget;
+    /**
+     * Idempotency key within the captured scope (max 1024 characters).
+     * Reuse for the same request; changed input or target is a conflict.
+     */
+    callId: string;
+    input: AgentInvocationInput;
+    /** 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. */
+    revision: number;
+    scope: AgentInvocationScope;
+    request: AgentInvocationRequest;
+    /** Host timestamps in ISO 8601 format. */
+    createdAt: string;
+    updatedAt: string;
+}
+/** Checks confirmed completion; unknown remains non-terminal. */
+export declare function isAgentInvocationTerminal(status: AgentInvocationStatus): boolean;

package/src/lib/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'];