@yushaw/sanqian-ai-sdk 0.1.0

package/dist/testing.d.mts

@@ -0,0 +1,363 @@
+/**
+ * Runtime Profile - separates provider, auth, billing, and history concerns.
+ */
+type RuntimeProviderKind = 'sanqian-sdk' | 'vercel-ai-sdk' | 'fake' | 'replay';
+
+/**
+ * Runtime Stream Events - normalized event protocol for all providers.
+ */
+interface RuntimeToolCall {
+    id: string;
+    name: string;
+    arguments: string;
+}
+interface RuntimeInterrupt {
+    type: string;
+    payload: unknown;
+}
+interface RuntimeToolExecutionMetadata {
+    status?: 'pending' | 'running' | 'completed' | 'error' | 'cancelled' | string;
+    actionRequired?: string;
+    settingsTab?: string;
+    settingsSubTab?: string;
+    commandExitCode?: number;
+    durationMs?: number;
+    sandboxed?: boolean;
+    timedOut?: boolean;
+    truncated?: boolean;
+    stdoutPath?: string;
+    stderrPath?: string;
+    presentation?: string;
+}
+type RuntimeStreamEvent = {
+    type: 'start';
+    runId?: string;
+    conversationId?: string;
+} | {
+    type: 'text';
+    content: string;
+} | {
+    type: 'thinking';
+    content: string;
+} | {
+    type: 'tool_call';
+    toolCall: RuntimeToolCall;
+} | {
+    type: 'tool_args_chunk';
+    toolCallId: string;
+    toolName: string;
+    chunk: string;
+} | {
+    type: 'tool_args';
+    toolCallId: string;
+    toolName: string;
+    args: Record<string, unknown>;
+} | ({
+    type: 'tool_result';
+    toolCallId: string;
+    result?: unknown;
+    success?: boolean;
+    error?: string;
+} & RuntimeToolExecutionMetadata) | {
+    type: 'interrupt';
+    runId?: string;
+    interrupt: RuntimeInterrupt;
+} | {
+    type: 'cancelled';
+    runId?: string;
+} | {
+    type: 'done';
+    conversationId: string;
+    title?: string;
+} | {
+    type: 'error';
+    error: string;
+    code?: string;
+};
+interface RuntimeUsage {
+    promptTokens?: number;
+    completionTokens?: number;
+    totalTokens?: number;
+}
+
+/**
+ * Runtime Provider - the core abstraction that all providers implement.
+ */
+
+interface RuntimeProviderCapabilities {
+    streamingText: boolean;
+    reasoning: boolean;
+    toolCalling: boolean;
+    parallelToolCalls: boolean;
+    toolArgsStreaming: boolean;
+    abort: boolean;
+    hitl: boolean;
+    conversations: boolean;
+    sessionResources: boolean;
+    resourcePicker: boolean;
+    embeddings: boolean;
+    rerank: boolean;
+}
+type RuntimeConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'reconnecting' | 'error';
+type RuntimeConnectionErrorCode = 'NOT_FOUND' | 'CONNECTION_FAILED' | 'WEBSOCKET_ERROR' | 'AUTH_ERROR' | 'TIMEOUT' | 'UNKNOWN' | (string & {});
+interface RuntimeConnectionSnapshot {
+    status: RuntimeConnectionStatus;
+    isConnected: boolean;
+    error?: string;
+    errorCode?: RuntimeConnectionErrorCode;
+    lastChangedAt: number;
+}
+interface RuntimeChatRequest {
+    agentId: string;
+    messages: RuntimeMessage[];
+    conversationId?: string | null;
+    providerInstanceId?: string;
+    operationId?: string;
+    tools?: RuntimeToolDefinition[];
+    contexts?: RuntimeContext[];
+    resources?: RuntimeResourceRef[];
+    sessionResources?: RuntimeResource[];
+    signal?: AbortSignal;
+}
+interface RuntimeChatResponse {
+    content: string;
+    conversationId?: string;
+    usage?: RuntimeUsage;
+    toolResults?: RuntimeToolExecutionResult[];
+}
+interface RuntimeChatStreamRequest {
+    agentId: string;
+    messages: RuntimeMessage[];
+    conversationId?: string | null;
+    providerInstanceId?: string;
+    operationId?: string;
+    tools?: RuntimeToolDefinition[];
+    contexts?: RuntimeContext[];
+    resources?: RuntimeResourceRef[];
+    sessionResources?: RuntimeResource[];
+    signal?: AbortSignal;
+}
+interface RuntimeMessage {
+    role: 'user' | 'assistant' | 'system';
+    content: string;
+}
+interface RuntimeContext {
+    id: string;
+    content: string;
+}
+interface RuntimeResourceRef {
+    providerId: string;
+    resourceId: string;
+}
+interface RuntimeResource {
+    id: string;
+    title: string;
+    content: string;
+    summary?: string;
+}
+interface RuntimeToolDefinition {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+}
+interface RuntimeToolExecutionResult {
+    toolCallId: string;
+    result?: unknown;
+    success: boolean;
+    error?: string;
+}
+interface RuntimeProvider {
+    readonly id: string;
+    readonly kind: RuntimeProviderKind;
+    readonly displayName: string;
+    readonly capabilities: RuntimeProviderCapabilities;
+    ensureReady(): Promise<void>;
+    dispose?(): Promise<void>;
+    isConnected?(): boolean;
+    getConnectionSnapshot?(): RuntimeConnectionSnapshot;
+    onConnectionChange?(callback: (snapshot: RuntimeConnectionSnapshot) => void): () => void;
+    chat(input: RuntimeChatRequest): Promise<RuntimeChatResponse>;
+    chatStream(input: RuntimeChatStreamRequest): AsyncIterable<RuntimeStreamEvent>;
+    cancel?(runId: string): Promise<void>;
+    sendPermissionResponse?(input: RuntimePermissionResponse): Promise<void>;
+}
+interface RuntimePermissionResponse {
+    runId: string;
+    toolCallId: string;
+    decision: 'approve' | 'deny' | 'cancel';
+    reason?: string;
+    response?: RuntimeHitlResponse;
+}
+interface RuntimeHitlResponse {
+    approved?: boolean;
+    remember?: boolean;
+    answer?: string;
+    selected_indices?: number[];
+    cancelled?: boolean;
+    timed_out?: boolean;
+}
+
+interface EmbeddingProvider {
+    readonly id: string;
+    readonly model: string;
+    readonly dimensions: number;
+    ensureReady(): Promise<void>;
+    dispose?(): Promise<void>;
+    /** Embed multiple texts in a single batch. */
+    embedMany(texts: string[], options?: {
+        signal?: AbortSignal;
+    }): Promise<number[][]>;
+    /** Embed a single text. */
+    embed(text: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<number[]>;
+    /** Test the embedding API connection. */
+    test?(): Promise<{
+        success: boolean;
+        dimensions?: number;
+        error?: string;
+    }>;
+}
+interface RerankInput {
+    query: string;
+    documents: Array<{
+        id: string;
+        text: string;
+    }>;
+    topN?: number;
+}
+interface RerankResultItem {
+    id: string;
+    score: number;
+    index: number;
+}
+interface RerankResult {
+    results: RerankResultItem[];
+}
+interface RerankProvider {
+    readonly id: string;
+    readonly model: string;
+    ensureReady(): Promise<void>;
+    dispose?(): Promise<void>;
+    rerank(input: RerankInput, options?: {
+        signal?: AbortSignal;
+    }): Promise<RerankResult>;
+    /** Test the rerank API connection. */
+    test?(): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+}
+
+/**
+ * Fake Provider - deterministic provider for testing runtime contracts.
+ *
+ * Supports scripted responses, tool calls, cancellation, and error scenarios.
+ */
+
+interface FakeStreamStep {
+    delay?: number;
+    event: RuntimeStreamEvent;
+}
+interface FakeScenario {
+    /** Match by agentId (undefined = match all) */
+    agentId?: string;
+    /** Non-streaming response */
+    response?: string;
+    /** Streaming steps */
+    stream?: FakeStreamStep[];
+    /** Throw error on call */
+    error?: string;
+}
+interface FakeProviderConfig {
+    id?: string;
+    displayName?: string;
+    capabilities?: Partial<RuntimeProviderCapabilities>;
+    scenarios?: FakeScenario[];
+    /** Default stream for unmatched calls */
+    defaultResponse?: string;
+    /** Whether ensureReady() should fail */
+    readinessError?: string;
+}
+declare class FakeProvider implements RuntimeProvider {
+    readonly id: string;
+    readonly kind: RuntimeProviderKind;
+    readonly displayName: string;
+    readonly capabilities: RuntimeProviderCapabilities;
+    private scenarios;
+    private defaultResponse;
+    private readinessError;
+    private disposed;
+    /** Track calls for assertions */
+    readonly chatCalls: RuntimeChatRequest[];
+    readonly chatStreamCalls: RuntimeChatStreamRequest[];
+    readonly cancelCalls: string[];
+    readonly permissionResponses: RuntimePermissionResponse[];
+    constructor(config?: FakeProviderConfig);
+    ensureReady(): Promise<void>;
+    dispose(): Promise<void>;
+    isDisposed(): boolean;
+    chat(input: RuntimeChatRequest): Promise<RuntimeChatResponse>;
+    chatStream(input: RuntimeChatStreamRequest): AsyncIterable<RuntimeStreamEvent>;
+    cancel(runId: string): Promise<void>;
+    sendPermissionResponse(input: RuntimePermissionResponse): Promise<void>;
+    private findScenario;
+}
+
+/**
+ * Fake Embedding/Rerank providers for testing.
+ */
+
+interface FakeEmbeddingConfig {
+    id?: string;
+    model?: string;
+    dimensions?: number;
+    readinessError?: string;
+}
+declare class FakeEmbeddingProvider implements EmbeddingProvider {
+    readonly id: string;
+    readonly model: string;
+    readonly dimensions: number;
+    private readinessError;
+    private disposed;
+    readonly embedCalls: string[][];
+    constructor(config?: FakeEmbeddingConfig);
+    ensureReady(): Promise<void>;
+    dispose(): Promise<void>;
+    isDisposed(): boolean;
+    embedMany(texts: string[], _opts?: {
+        signal?: AbortSignal;
+    }): Promise<number[][]>;
+    embed(text: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<number[]>;
+    test(): Promise<{
+        success: boolean;
+        dimensions?: number;
+        error?: string;
+    }>;
+    private deterministicVector;
+}
+interface FakeRerankConfig {
+    id?: string;
+    model?: string;
+    readinessError?: string;
+}
+declare class FakeRerankProvider implements RerankProvider {
+    readonly id: string;
+    readonly model: string;
+    private readinessError;
+    private disposed;
+    readonly rerankCalls: RerankInput[];
+    constructor(config?: FakeRerankConfig);
+    ensureReady(): Promise<void>;
+    dispose(): Promise<void>;
+    isDisposed(): boolean;
+    rerank(input: RerankInput): Promise<RerankResult>;
+    test(): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+}
+
+export { type FakeEmbeddingConfig, FakeEmbeddingProvider, FakeProvider, type FakeProviderConfig, type FakeRerankConfig, FakeRerankProvider, type FakeScenario, type FakeStreamStep };

package/dist/testing.d.ts

@@ -0,0 +1,363 @@
+/**
+ * Runtime Profile - separates provider, auth, billing, and history concerns.
+ */
+type RuntimeProviderKind = 'sanqian-sdk' | 'vercel-ai-sdk' | 'fake' | 'replay';
+
+/**
+ * Runtime Stream Events - normalized event protocol for all providers.
+ */
+interface RuntimeToolCall {
+    id: string;
+    name: string;
+    arguments: string;
+}
+interface RuntimeInterrupt {
+    type: string;
+    payload: unknown;
+}
+interface RuntimeToolExecutionMetadata {
+    status?: 'pending' | 'running' | 'completed' | 'error' | 'cancelled' | string;
+    actionRequired?: string;
+    settingsTab?: string;
+    settingsSubTab?: string;
+    commandExitCode?: number;
+    durationMs?: number;
+    sandboxed?: boolean;
+    timedOut?: boolean;
+    truncated?: boolean;
+    stdoutPath?: string;
+    stderrPath?: string;
+    presentation?: string;
+}
+type RuntimeStreamEvent = {
+    type: 'start';
+    runId?: string;
+    conversationId?: string;
+} | {
+    type: 'text';
+    content: string;
+} | {
+    type: 'thinking';
+    content: string;
+} | {
+    type: 'tool_call';
+    toolCall: RuntimeToolCall;
+} | {
+    type: 'tool_args_chunk';
+    toolCallId: string;
+    toolName: string;
+    chunk: string;
+} | {
+    type: 'tool_args';
+    toolCallId: string;
+    toolName: string;
+    args: Record<string, unknown>;
+} | ({
+    type: 'tool_result';
+    toolCallId: string;
+    result?: unknown;
+    success?: boolean;
+    error?: string;
+} & RuntimeToolExecutionMetadata) | {
+    type: 'interrupt';
+    runId?: string;
+    interrupt: RuntimeInterrupt;
+} | {
+    type: 'cancelled';
+    runId?: string;
+} | {
+    type: 'done';
+    conversationId: string;
+    title?: string;
+} | {
+    type: 'error';
+    error: string;
+    code?: string;
+};
+interface RuntimeUsage {
+    promptTokens?: number;
+    completionTokens?: number;
+    totalTokens?: number;
+}
+
+/**
+ * Runtime Provider - the core abstraction that all providers implement.
+ */
+
+interface RuntimeProviderCapabilities {
+    streamingText: boolean;
+    reasoning: boolean;
+    toolCalling: boolean;
+    parallelToolCalls: boolean;
+    toolArgsStreaming: boolean;
+    abort: boolean;
+    hitl: boolean;
+    conversations: boolean;
+    sessionResources: boolean;
+    resourcePicker: boolean;
+    embeddings: boolean;
+    rerank: boolean;
+}
+type RuntimeConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'reconnecting' | 'error';
+type RuntimeConnectionErrorCode = 'NOT_FOUND' | 'CONNECTION_FAILED' | 'WEBSOCKET_ERROR' | 'AUTH_ERROR' | 'TIMEOUT' | 'UNKNOWN' | (string & {});
+interface RuntimeConnectionSnapshot {
+    status: RuntimeConnectionStatus;
+    isConnected: boolean;
+    error?: string;
+    errorCode?: RuntimeConnectionErrorCode;
+    lastChangedAt: number;
+}
+interface RuntimeChatRequest {
+    agentId: string;
+    messages: RuntimeMessage[];
+    conversationId?: string | null;
+    providerInstanceId?: string;
+    operationId?: string;
+    tools?: RuntimeToolDefinition[];
+    contexts?: RuntimeContext[];
+    resources?: RuntimeResourceRef[];
+    sessionResources?: RuntimeResource[];
+    signal?: AbortSignal;
+}
+interface RuntimeChatResponse {
+    content: string;
+    conversationId?: string;
+    usage?: RuntimeUsage;
+    toolResults?: RuntimeToolExecutionResult[];
+}
+interface RuntimeChatStreamRequest {
+    agentId: string;
+    messages: RuntimeMessage[];
+    conversationId?: string | null;
+    providerInstanceId?: string;
+    operationId?: string;
+    tools?: RuntimeToolDefinition[];
+    contexts?: RuntimeContext[];
+    resources?: RuntimeResourceRef[];
+    sessionResources?: RuntimeResource[];
+    signal?: AbortSignal;
+}
+interface RuntimeMessage {
+    role: 'user' | 'assistant' | 'system';
+    content: string;
+}
+interface RuntimeContext {
+    id: string;
+    content: string;
+}
+interface RuntimeResourceRef {
+    providerId: string;
+    resourceId: string;
+}
+interface RuntimeResource {
+    id: string;
+    title: string;
+    content: string;
+    summary?: string;
+}
+interface RuntimeToolDefinition {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+}
+interface RuntimeToolExecutionResult {
+    toolCallId: string;
+    result?: unknown;
+    success: boolean;
+    error?: string;
+}
+interface RuntimeProvider {
+    readonly id: string;
+    readonly kind: RuntimeProviderKind;
+    readonly displayName: string;
+    readonly capabilities: RuntimeProviderCapabilities;
+    ensureReady(): Promise<void>;
+    dispose?(): Promise<void>;
+    isConnected?(): boolean;
+    getConnectionSnapshot?(): RuntimeConnectionSnapshot;
+    onConnectionChange?(callback: (snapshot: RuntimeConnectionSnapshot) => void): () => void;
+    chat(input: RuntimeChatRequest): Promise<RuntimeChatResponse>;
+    chatStream(input: RuntimeChatStreamRequest): AsyncIterable<RuntimeStreamEvent>;
+    cancel?(runId: string): Promise<void>;
+    sendPermissionResponse?(input: RuntimePermissionResponse): Promise<void>;
+}
+interface RuntimePermissionResponse {
+    runId: string;
+    toolCallId: string;
+    decision: 'approve' | 'deny' | 'cancel';
+    reason?: string;
+    response?: RuntimeHitlResponse;
+}
+interface RuntimeHitlResponse {
+    approved?: boolean;
+    remember?: boolean;
+    answer?: string;
+    selected_indices?: number[];
+    cancelled?: boolean;
+    timed_out?: boolean;
+}
+
+interface EmbeddingProvider {
+    readonly id: string;
+    readonly model: string;
+    readonly dimensions: number;
+    ensureReady(): Promise<void>;
+    dispose?(): Promise<void>;
+    /** Embed multiple texts in a single batch. */
+    embedMany(texts: string[], options?: {
+        signal?: AbortSignal;
+    }): Promise<number[][]>;
+    /** Embed a single text. */
+    embed(text: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<number[]>;
+    /** Test the embedding API connection. */
+    test?(): Promise<{
+        success: boolean;
+        dimensions?: number;
+        error?: string;
+    }>;
+}
+interface RerankInput {
+    query: string;
+    documents: Array<{
+        id: string;
+        text: string;
+    }>;
+    topN?: number;
+}
+interface RerankResultItem {
+    id: string;
+    score: number;
+    index: number;
+}
+interface RerankResult {
+    results: RerankResultItem[];
+}
+interface RerankProvider {
+    readonly id: string;
+    readonly model: string;
+    ensureReady(): Promise<void>;
+    dispose?(): Promise<void>;
+    rerank(input: RerankInput, options?: {
+        signal?: AbortSignal;
+    }): Promise<RerankResult>;
+    /** Test the rerank API connection. */
+    test?(): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+}
+
+/**
+ * Fake Provider - deterministic provider for testing runtime contracts.
+ *
+ * Supports scripted responses, tool calls, cancellation, and error scenarios.
+ */
+
+interface FakeStreamStep {
+    delay?: number;
+    event: RuntimeStreamEvent;
+}
+interface FakeScenario {
+    /** Match by agentId (undefined = match all) */
+    agentId?: string;
+    /** Non-streaming response */
+    response?: string;
+    /** Streaming steps */
+    stream?: FakeStreamStep[];
+    /** Throw error on call */
+    error?: string;
+}
+interface FakeProviderConfig {
+    id?: string;
+    displayName?: string;
+    capabilities?: Partial<RuntimeProviderCapabilities>;
+    scenarios?: FakeScenario[];
+    /** Default stream for unmatched calls */
+    defaultResponse?: string;
+    /** Whether ensureReady() should fail */
+    readinessError?: string;
+}
+declare class FakeProvider implements RuntimeProvider {
+    readonly id: string;
+    readonly kind: RuntimeProviderKind;
+    readonly displayName: string;
+    readonly capabilities: RuntimeProviderCapabilities;
+    private scenarios;
+    private defaultResponse;
+    private readinessError;
+    private disposed;
+    /** Track calls for assertions */
+    readonly chatCalls: RuntimeChatRequest[];
+    readonly chatStreamCalls: RuntimeChatStreamRequest[];
+    readonly cancelCalls: string[];
+    readonly permissionResponses: RuntimePermissionResponse[];
+    constructor(config?: FakeProviderConfig);
+    ensureReady(): Promise<void>;
+    dispose(): Promise<void>;
+    isDisposed(): boolean;
+    chat(input: RuntimeChatRequest): Promise<RuntimeChatResponse>;
+    chatStream(input: RuntimeChatStreamRequest): AsyncIterable<RuntimeStreamEvent>;
+    cancel(runId: string): Promise<void>;
+    sendPermissionResponse(input: RuntimePermissionResponse): Promise<void>;
+    private findScenario;
+}
+
+/**
+ * Fake Embedding/Rerank providers for testing.
+ */
+
+interface FakeEmbeddingConfig {
+    id?: string;
+    model?: string;
+    dimensions?: number;
+    readinessError?: string;
+}
+declare class FakeEmbeddingProvider implements EmbeddingProvider {
+    readonly id: string;
+    readonly model: string;
+    readonly dimensions: number;
+    private readinessError;
+    private disposed;
+    readonly embedCalls: string[][];
+    constructor(config?: FakeEmbeddingConfig);
+    ensureReady(): Promise<void>;
+    dispose(): Promise<void>;
+    isDisposed(): boolean;
+    embedMany(texts: string[], _opts?: {
+        signal?: AbortSignal;
+    }): Promise<number[][]>;
+    embed(text: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<number[]>;
+    test(): Promise<{
+        success: boolean;
+        dimensions?: number;
+        error?: string;
+    }>;
+    private deterministicVector;
+}
+interface FakeRerankConfig {
+    id?: string;
+    model?: string;
+    readinessError?: string;
+}
+declare class FakeRerankProvider implements RerankProvider {
+    readonly id: string;
+    readonly model: string;
+    private readinessError;
+    private disposed;
+    readonly rerankCalls: RerankInput[];
+    constructor(config?: FakeRerankConfig);
+    ensureReady(): Promise<void>;
+    dispose(): Promise<void>;
+    isDisposed(): boolean;
+    rerank(input: RerankInput): Promise<RerankResult>;
+    test(): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+}
+
+export { type FakeEmbeddingConfig, FakeEmbeddingProvider, FakeProvider, type FakeProviderConfig, type FakeRerankConfig, FakeRerankProvider, type FakeScenario, type FakeStreamStep };