@xenosystem/agent-sdk 0.8.12

package/dist/providers/index.d.ts

@@ -0,0 +1,462 @@
+interface ToolDefinition {
+    name: string;
+    description: string;
+    input_schema: {
+        type: "object";
+        properties: Record<string, unknown>;
+        required?: string[];
+        additionalProperties?: boolean | Record<string, unknown>;
+        [keyword: string]: unknown;
+    };
+}
+interface ImageUrlBlock {
+    type: "image_url";
+    image_url: {
+        url: string;
+        detail?: "auto" | "low" | "high";
+    };
+}
+interface ResourceContentBlock {
+    type: "resource";
+    uri?: string;
+    mimeType?: string;
+    text?: string;
+    data?: string;
+}
+type ToolAssistantContentBlock = TextBlock | ImageUrlBlock | ResourceContentBlock;
+type ToolResultContent = string | ToolAssistantContentBlock[];
+interface TextBlock {
+    type: "text";
+    text: string;
+}
+interface ToolUseBlock {
+    type: "tool_use";
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+    provider_metadata?: Record<string, unknown>;
+}
+type ContentBlock = TextBlock | ToolUseBlock;
+interface ApiTextContentBlock {
+    type: "text";
+    text: string;
+}
+interface ApiToolUseContentBlock {
+    type: "tool_use";
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+    provider_metadata?: Record<string, unknown>;
+}
+interface ApiToolResultContentBlock {
+    type: "tool_result";
+    tool_use_id: string;
+    content: ToolResultContent;
+    assistant_content?: ToolAssistantContentBlock[];
+    assistant_only_content?: ToolAssistantContentBlock[];
+    is_error?: boolean;
+}
+type ApiMessage = {
+    role: "user" | "assistant";
+    content: string | Array<ApiTextContentBlock | ApiToolUseContentBlock | ApiToolResultContentBlock>;
+};
+interface StreamResult {
+    content: ContentBlock[];
+    stopReason: "end_turn" | "tool_use" | "max_tokens" | "stop_sequence";
+    inputTokens: number;
+    outputTokens: number;
+}
+type LLMProviderMessage = ApiMessage;
+type LLMCompletionResult = StreamResult;
+type ProviderStreamEvent = {
+    type: "message.started";
+    providerMessageId?: string;
+} | {
+    type: "text.delta";
+    text: string;
+} | {
+    type: "reasoning.delta";
+    text: string;
+} | {
+    type: "tool_call.started";
+    index: number;
+    toolCallId: string;
+    name: string;
+} | {
+    type: "tool_call.arguments.delta";
+    index: number;
+    toolCallId: string;
+    delta: string;
+} | {
+    type: "tool_call.completed";
+    index: number;
+    toolCallId: string;
+    name: string;
+    input: Record<string, unknown>;
+} | {
+    type: "usage.updated";
+    inputTokens: number;
+    outputTokens: number;
+} | {
+    type: "provider.warning";
+    code: string;
+    message: string;
+} | {
+    type: "provider.retry";
+    retryAfterMs?: number;
+    reason: string;
+} | {
+    type: "message.completed";
+    stopReason: LLMCompletionResult["stopReason"];
+} | {
+    type: "provider.error";
+    code: string;
+    category: string;
+    retryable: boolean;
+} | {
+    type: "provider.cancelled";
+};
+interface LLMProviderRequestContext {
+    systemPrompt: string;
+    attemptId?: string;
+    onEvent?: (event: ProviderStreamEvent) => void | Promise<void>;
+}
+interface LLMProviderCapabilities {
+    readonly streaming?: boolean;
+    readonly textInput?: boolean;
+    readonly tools?: boolean;
+    readonly parallelToolCalls?: boolean;
+    readonly vision?: boolean;
+    readonly imageInput?: boolean;
+    readonly structuredOutput?: boolean;
+    readonly reasoningMetadata?: boolean;
+    readonly usageAccounting?: boolean;
+    readonly cancellation?: boolean;
+    readonly retryAfter?: boolean;
+    readonly promptCaching?: boolean;
+    readonly [capability: string]: boolean | undefined;
+}
+interface LLMProvider {
+    readonly id: string;
+    readonly model?: string;
+    readonly capabilities?: LLMProviderCapabilities;
+    complete(model: string, messages: LLMProviderMessage[], tools: ToolDefinition[], onText?: (text: string) => void, signal?: AbortSignal, context?: LLMProviderRequestContext): Promise<LLMCompletionResult>;
+    completeLocal?(model: string, messages: LLMProviderMessage[], tools: ToolDefinition[], onText?: (text: string) => void, signal?: AbortSignal, context?: LLMProviderRequestContext): Promise<LLMCompletionResult>;
+}
+type DualLLMMode = "auto" | "local" | "cloud";
+interface ChatParams {
+    messages: Array<{
+        role: "system" | "user" | "assistant";
+        content: string;
+    }>;
+    model?: string;
+    maxTokens?: number;
+    temperature?: number;
+    systemPrompt?: string;
+    jsonMode?: boolean;
+    stop?: string[];
+}
+interface ChatResponse {
+    success: boolean;
+    content: string;
+    endpoint: "local" | "cloud";
+    model: string;
+    usage: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+    error?: string;
+}
+interface DualLLMStatus {
+    mode: DualLLMMode;
+    localAvailable: boolean;
+    activeEndpoint: "local" | "cloud";
+    localModel?: string;
+    localUrl: string;
+    cloudUrl: string;
+}
+interface DualLLMProviderConfig {
+    localUrl?: string;
+    cloudUrl?: string;
+    cloudApiKey?: string;
+    mode?: DualLLMMode;
+    localModel?: string;
+    cloudModel?: string;
+}
+declare class DualLLMProvider {
+    private localUrl;
+    private cloudUrl;
+    private cloudApiKey;
+    private mode;
+    private defaultLocalModel;
+    private defaultCloudModel;
+    private localAvailable;
+    private localModelName;
+    private lastHealthCheck;
+    constructor(config?: DualLLMProviderConfig);
+    chat(params: ChatParams): Promise<ChatResponse>;
+    chatStream(params: ChatParams): AsyncGenerator<string>;
+    isLocalAvailable(forceRefresh?: boolean): Promise<boolean>;
+    setMode(mode: DualLLMMode): void;
+    getMode(): DualLLMMode;
+    setLocalUrl(url: string): void;
+    setCloudApiKey(apiKey: string): void;
+    getStatus(): Promise<DualLLMStatus>;
+    asLLMProvider(options?: {
+        id?: string;
+        model?: string;
+    }): LLMProvider;
+    private shouldUseLocal;
+    private chatLocal;
+    private chatCloud;
+}
+type DirectEndpointProfile = "public-https" | "local-network";
+interface DirectEndpointPolicy {
+    profile?: DirectEndpointProfile;
+    allowedHosts?: string[];
+    resolveHostname?: (hostname: string) => Promise<string[]>;
+}
+declare function validateDirectEndpoint(raw: string, policy?: DirectEndpointPolicy): URL;
+declare function assertDirectEndpointResolution(url: URL, policy?: DirectEndpointPolicy): Promise<void>;
+interface ProviderTransportLimits {
+    connectTimeoutMs?: number;
+    totalTimeoutMs?: number;
+    idleTimeoutMs?: number;
+    maxResponseBytes?: number;
+    maxHeaderBytes?: number;
+    maxEventBytes?: number;
+}
+type DirectProviderKind = "anthropic" | "openai-responses" | "google" | "openai-compatible";
+type DirectProviderCapabilityProfile = Pick<LLMProviderCapabilities, "streaming" | "textInput" | "imageInput" | "tools" | "parallelToolCalls" | "structuredOutput" | "reasoningMetadata" | "usageAccounting" | "cancellation" | "retryAfter" | "promptCaching">;
+interface DirectProviderConfig {
+    kind: DirectProviderKind;
+    apiKey: string;
+    baseURL?: string;
+    anthropicVersion?: string;
+    maxTokens?: number;
+    streaming?: boolean;
+    capabilityProfile?: DirectProviderCapabilityProfile;
+    endpointProfile?: DirectEndpointProfile;
+    allowedHosts?: string[];
+    resolveHostname?: (hostname: string) => Promise<string[]>;
+    transportLimits?: ProviderTransportLimits;
+    chatCompletionsPath?: string;
+    authentication?: {
+        type: "bearer";
+    } | {
+        type: "header";
+        header: string;
+        prefix?: string;
+    } | {
+        type: "none";
+    };
+}
+declare function createDirectProvider(config: DirectProviderConfig): LLMProvider;
+type ProviderErrorCategory = "authentication" | "authorization" | "unsupported_model" | "unsupported_capability" | "rate_limit" | "context_overflow" | "safety_refusal" | "timeout" | "disconnect" | "malformed_response" | "server" | "transport" | "endpoint_policy" | "cancelled";
+type ProviderErrorCode = "PROVIDER_AUTHENTICATION_FAILED" | "PROVIDER_AUTHORIZATION_FAILED" | "PROVIDER_MODEL_UNSUPPORTED" | "PROVIDER_CAPABILITY_UNSUPPORTED" | "PROVIDER_RATE_LIMITED" | "PROVIDER_CONTEXT_OVERFLOW" | "PROVIDER_SAFETY_REFUSAL" | "PROVIDER_TIMEOUT" | "PROVIDER_DISCONNECTED" | "PROVIDER_MALFORMED_RESPONSE" | "PROVIDER_SERVER_ERROR" | "PROVIDER_TRANSPORT_ERROR" | "PROVIDER_ENDPOINT_REJECTED" | "PROVIDER_CANCELLED";
+interface ProviderErrorOptions {
+    category: ProviderErrorCategory;
+    code: ProviderErrorCode;
+    retryable?: boolean;
+    providerId?: string;
+    statusCode?: number;
+    retryAfterMs?: number;
+    requestId?: string;
+    cause?: unknown;
+}
+declare class ProviderError extends Error {
+    readonly category: ProviderErrorCategory;
+    readonly code: ProviderErrorCode;
+    readonly retryable: boolean;
+    readonly providerId?: string;
+    readonly statusCode?: number;
+    readonly retryAfterMs?: number;
+    readonly requestId?: string;
+    constructor(message: string, options: ProviderErrorOptions);
+}
+declare function parseRetryAfter(value: string | null, now?: number): number | undefined;
+declare function classifyProviderHttpError(input: {
+    providerId: string;
+    statusCode: number;
+    body: unknown;
+    retryAfterMs?: number;
+    requestId?: string;
+}): ProviderError;
+declare function providerProtocolError(providerId: string, message: string, cause?: unknown): ProviderError;
+declare function providerCapabilityError(providerId: string, capability: string): ProviderError;
+type ToolSchemaProviderDialect = "xeno" | "anthropic" | "openai-responses" | "openai-chat" | "google";
+interface ToolSchemaProjectionChange {
+    path: string;
+    keyword: string;
+    action: "omitted" | "transformed";
+    reason: string;
+}
+interface ToolSchemaProjectionResult {
+    schema: ToolDefinition["input_schema"];
+    dialect: ToolSchemaProviderDialect;
+    canonicalSha256: string;
+    projectedSha256: string;
+    changes: ToolSchemaProjectionChange[];
+}
+declare class ToolSchemaProjectionError extends Error {
+    readonly dialect: ToolSchemaProviderDialect;
+    readonly path: string;
+    constructor(dialect: ToolSchemaProviderDialect, path: string, message: string);
+}
+declare function projectToolSchemaForProvider(schema: ToolDefinition["input_schema"], providerDialect: ToolSchemaProviderDialect): ToolSchemaProjectionResult;
+declare function projectToolDefinitionsForProvider(tools: ToolDefinition[], providerDialect: ToolSchemaProviderDialect): Array<{
+    definition: ToolDefinition;
+    projection: ToolSchemaProjectionResult;
+}>;
+declare const XENO_PROVIDER_CATALOG_SCHEMA_VERSION: 1;
+type XenoProviderAdapterKind = DirectProviderKind | "aws-bedrock" | "vertex-ai";
+type XenoProviderCredentialMode = "bearer-env" | "header-env" | "cloud-chain" | "none";
+type XenoProviderReadiness = "ready" | "missing-credential" | "needs-configuration" | "requires-host-adapter" | "blocked";
+interface XenoProviderCapabilities {
+    streaming: boolean;
+    textInput: boolean;
+    imageInput: boolean;
+    tools: boolean;
+    parallelToolCalls: boolean;
+    structuredOutput: boolean;
+    reasoningMetadata: boolean;
+    usageAccounting: boolean;
+    promptCaching: boolean;
+    modelDiscovery: boolean;
+}
+interface XenoProviderAuthPreset {
+    mode: XenoProviderCredentialMode;
+    defaultSecretRef?: string;
+    header?: string;
+    prefix?: string;
+    description: string;
+}
+interface XenoProviderPreset {
+    schemaVersion: typeof XENO_PROVIDER_CATALOG_SCHEMA_VERSION;
+    id: string;
+    displayName: string;
+    family: "xeno" | "direct" | "gateway" | "cloud" | "local";
+    adapterKind: XenoProviderAdapterKind;
+    defaultBaseUrl?: string;
+    endpointProfile: DirectEndpointProfile;
+    allowedHosts?: string[];
+    auth: XenoProviderAuthPreset;
+    capabilities: XenoProviderCapabilities;
+    discoveryPath?: string;
+    requires: string[];
+    documentationUrl?: string;
+}
+interface XenoProviderConnection {
+    id: string;
+    providerId: string;
+    baseUrl?: string;
+    secretRef?: string;
+    model?: string;
+    enabled?: boolean;
+    metadata?: {
+        organizationId?: string;
+        projectId?: string;
+        region?: string;
+        deployment?: string;
+    };
+}
+interface XenoProviderConnectionView {
+    connection: XenoProviderConnection;
+    preset: XenoProviderPreset;
+    endpoint?: string;
+    secretRef?: string;
+    readiness: XenoProviderReadiness;
+    blockers: string[];
+}
+interface XenoProviderModelDescriptor {
+    id: string;
+    displayName?: string;
+    ownedBy?: string;
+    contextTokens?: number;
+    inputCostPerMillion?: number;
+    outputCostPerMillion?: number;
+    capabilities?: Partial<XenoProviderCapabilities>;
+    metadataSource: "provider" | "configuration" | "catalog";
+}
+interface XenoProviderProbeResult {
+    schemaVersion: 1;
+    connectionId: string;
+    providerId: string;
+    endpoint?: string;
+    readiness: XenoProviderReadiness;
+    credentialState: "present" | "missing" | "not-required" | "external";
+    reachable: boolean;
+    authenticated: boolean | null;
+    latencyMs?: number;
+    models: XenoProviderModelDescriptor[];
+    capabilities: XenoProviderCapabilities;
+    errors: string[];
+}
+interface XenoProviderRoutingPolicy {
+    allowedProviderIds?: string[];
+    deniedProviderIds?: string[];
+    fallbackOrder?: string[];
+    preferLocal?: boolean;
+    require?: Partial<XenoProviderCapabilities>;
+    maxInputCostPerMillion?: number;
+    maxOutputCostPerMillion?: number;
+}
+interface XenoProviderRouteCandidate {
+    connection: XenoProviderConnectionView;
+    model: XenoProviderModelDescriptor;
+}
+interface ProbeXenoProviderOptions {
+    connection: XenoProviderConnection;
+    catalog?: XenoProviderCatalog;
+    resolveSecretRef?: (reference: string) => string | undefined | Promise<string | undefined>;
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+    maxResponseBytes?: number;
+    resolveHostname?: (hostname: string) => Promise<string[]>;
+}
+declare const BUILT_IN_XENO_PROVIDER_PRESETS: readonly XenoProviderPreset[];
+declare class XenoProviderCatalog {
+    private readonly presets;
+    constructor(presets?: readonly XenoProviderPreset[]);
+    add(value: XenoProviderPreset): void;
+    get(id: string): XenoProviderPreset | undefined;
+    list(): XenoProviderPreset[];
+    resolve(connection: XenoProviderConnection, secretAvailable?: (reference: string) => boolean): XenoProviderConnectionView;
+}
+declare function probeXenoProvider(options: ProbeXenoProviderOptions): Promise<XenoProviderProbeResult>;
+declare function selectXenoProviderRoute(candidates: XenoProviderRouteCandidate[], policy?: XenoProviderRoutingPolicy): XenoProviderRouteCandidate[];
+declare function directProviderConfigFromConnection(view: XenoProviderConnectionView, secret: string | undefined): DirectProviderConfig;
+declare const XENO_PROVIDER_CONNECTION_STORE_SCHEMA_VERSION: 1;
+interface XenoProviderConnectionSnapshot {
+    schemaVersion: typeof XENO_PROVIDER_CONNECTION_STORE_SCHEMA_VERSION;
+    generation: number;
+    updatedAt: string;
+    connections: XenoProviderConnection[];
+    routingPolicy: XenoProviderRoutingPolicy;
+    checksum: {
+        algorithm: "sha256";
+        value: string;
+    };
+}
+interface FileXenoProviderConnectionStoreOptions {
+    directory: string;
+    catalog?: XenoProviderCatalog;
+    now?: () => Date;
+}
+declare class FileXenoProviderConnectionStore {
+    readonly directory: string;
+    readonly snapshotPath: string;
+    readonly lockPath: string;
+    private readonly catalog;
+    private readonly now;
+    constructor(options: FileXenoProviderConnectionStoreOptions);
+    upsert(connection: XenoProviderConnection): Promise<XenoProviderConnection>;
+    remove(id: string): Promise<boolean>;
+    setRoutingPolicy(policy: XenoProviderRoutingPolicy): Promise<XenoProviderRoutingPolicy>;
+    get(id: string): Promise<XenoProviderConnection | null>;
+    list(): Promise<XenoProviderConnection[]>;
+    load(): Promise<XenoProviderConnectionSnapshot>;
+    private mutate;
+}
+export { BUILT_IN_XENO_PROVIDER_PRESETS, type ChatParams, type ChatResponse, type DirectEndpointPolicy, type DirectEndpointProfile, type DirectProviderCapabilityProfile, type DirectProviderConfig, type DirectProviderKind, type DualLLMMode, DualLLMProvider, type DualLLMProviderConfig, type DualLLMStatus, FileXenoProviderConnectionStore, type FileXenoProviderConnectionStoreOptions, type ProbeXenoProviderOptions, ProviderError, type ProviderErrorCategory, type ProviderErrorCode, type ProviderErrorOptions, type ProviderTransportLimits, type ToolSchemaProjectionChange, ToolSchemaProjectionError, type ToolSchemaProjectionResult, type ToolSchemaProviderDialect, XENO_PROVIDER_CATALOG_SCHEMA_VERSION, XENO_PROVIDER_CONNECTION_STORE_SCHEMA_VERSION, type XenoProviderAdapterKind, type XenoProviderAuthPreset, type XenoProviderCapabilities, XenoProviderCatalog, type XenoProviderConnection, type XenoProviderConnectionSnapshot, type XenoProviderConnectionView, type XenoProviderCredentialMode, type XenoProviderModelDescriptor, type XenoProviderPreset, type XenoProviderProbeResult, type XenoProviderReadiness, type XenoProviderRouteCandidate, type XenoProviderRoutingPolicy, assertDirectEndpointResolution, classifyProviderHttpError, createDirectProvider, directProviderConfigFromConnection, parseRetryAfter, probeXenoProvider, projectToolDefinitionsForProvider, projectToolSchemaForProvider, providerCapabilityError, providerProtocolError, selectXenoProviderRoute, validateDirectEndpoint };