@yushaw/sanqian-ai-sdk 0.1.1 → 0.1.2

package/dist/index.d.mts

@@ -120,6 +120,20 @@ interface RuntimeConnectionSnapshot {
     errorCode?: RuntimeConnectionErrorCode;
     lastChangedAt: number;
 }
+/**
+ * Per-request tool-choice constraint (mirrors Vercel AI SDK / OpenAI semantics).
+ * - 'auto' (default): the model decides whether to call tools.
+ * - 'none': the model must not call tools.
+ * - 'required': the model MUST call at least one tool this turn.
+ * - { type: 'tool', toolName }: the model MUST call the named tool.
+ * Providers that cannot honor a constraining value MUST throw instead of silently
+ * degrading to 'auto' — callers rely on this for command-style requests where a
+ * hallucinated "done" without a tool call is a correctness bug.
+ */
+type RuntimeToolChoice = 'auto' | 'none' | 'required' | {
+    type: 'tool';
+    toolName: string;
+};
 interface RuntimeChatRequest {
     agentId: string;
     messages: RuntimeMessage[];
@@ -127,6 +141,7 @@ interface RuntimeChatRequest {
     providerInstanceId?: string;
     operationId?: string;
     tools?: RuntimeToolDefinition[];
+    toolChoice?: RuntimeToolChoice;
     contexts?: RuntimeContext[];
     resources?: RuntimeResourceRef[];
     sessionResources?: RuntimeResource[];
@@ -145,6 +160,7 @@ interface RuntimeChatStreamRequest {
     providerInstanceId?: string;
     operationId?: string;
     tools?: RuntimeToolDefinition[];
+    toolChoice?: RuntimeToolChoice;
     contexts?: RuntimeContext[];
     resources?: RuntimeResourceRef[];
     sessionResources?: RuntimeResource[];
@@ -1390,4 +1406,4 @@ declare class VercelEmbeddingProvider implements EmbeddingProvider {
     private redact;
 }
 
-export { type ActiveRuntimeWork, type ActiveRuntimeWorkKind, type ActiveStream, type ActiveWorkTracker, type AgentExecutionMode, type AgentIdResolver, type AiFeatureRuntimeState, type AuthMode, type BillingMode, type BridgeSessionResource, type ChatRuntimeBridge, type ChatRuntimeBridgeConfig, type ConversationDetail, type ConversationInfo, type ConversationPage, type ConversationPatch, type ConversationStore, type CreateConversationInput, EMPTY_CAPABILITIES, type EditorOutputContext, type EmbeddingModelChangeEvent, type EmbeddingProvider, type EmbeddingProviderConfig, type EmbeddingSession, type ExecutionTarget, type GetConversationInput, type HistoryLocation, type InsertOutputData, type ListConversationsInput, MockSanqianSdk, type MockScenario, type MockSdkConfig, type OutputOperation, type OutputOperationType, type OutputOperationsManager, type PendingOutputOps, type PendingPermission, type PermissionDecision, type PermissionGate, type PermissionPolicy, type ProviderChangedEvent, type ProviderInstanceConfig, type RerankInput, type RerankProvider, type RerankResult, type RerankResultItem, type ResourceListPage, type ResourceListRequest, type ResourceProviderInfo, type RuntimeAgentConfig, type RuntimeAgentId, type RuntimeAgentRegistry, type RuntimeChatRequest, type RuntimeChatResponse, type RuntimeChatStreamRequest, type RuntimeConnectionErrorCode, type RuntimeConnectionSnapshot, type RuntimeConnectionStatus, type RuntimeContext, type RuntimeConversationMessage, type RuntimeHitlResponse, type RuntimeInterrupt, type RuntimeMessage, type RuntimePermissionResponse, type RuntimeProfile, type RuntimeProvider, type RuntimeProviderCapabilities, type RuntimeProviderDescriptor, type RuntimeProviderKind, type RuntimeResource, type RuntimeResourceRef, type RuntimeSecretStore, type RuntimeSessionManager, type RuntimeSessionResourceEvent, type RuntimeStreamEvent, type RuntimeTaskPipeline, type RuntimeTaskPipelineInput, type RuntimeToolCall, type RuntimeToolDefinition, type RuntimeToolExecutionContext, type RuntimeToolExecutionInput, type RuntimeToolExecutionMetadata, type RuntimeToolExecutionResult, type RuntimeToolHandler, type RuntimeToolMetadata, type RuntimeToolRegistration, type RuntimeToolRegistry, type RuntimeUsage, type SanqianEmbeddingConfig, SanqianEmbeddingProvider, SanqianProvider, type SanqianProviderConfig, type SanqianRerankConfig, SanqianRerankProvider, type SanqianSdkPort, type SecretDescriptor, type SecretRef, type StoreSecretInput, type SwitchOptions, type SwitchResult, type ToolCategory, type VercelEmbeddingConfig, VercelEmbeddingProvider, VercelProvider, type VercelProviderConfig, convertSdkStreamEvent, convertToolsForVercel, createActiveWorkTracker, createCategoryPermissionPolicy, createChatRuntimeBridge, createDefaultPermissionPolicy, createDisabledState, createEmbeddingSession, createMemoryConversationStore, createMemorySecretStore, createOutputOperationsManager, createPermissionGate, createSanqianAgentIdResolver, createSessionManager, createTaskPipeline, createToolRegistry, redactToolError, resolveAiFeaturesFromRuntime, validateOutputContent };
+export { type ActiveRuntimeWork, type ActiveRuntimeWorkKind, type ActiveStream, type ActiveWorkTracker, type AgentExecutionMode, type AgentIdResolver, type AiFeatureRuntimeState, type AuthMode, type BillingMode, type BridgeSessionResource, type ChatRuntimeBridge, type ChatRuntimeBridgeConfig, type ConversationDetail, type ConversationInfo, type ConversationPage, type ConversationPatch, type ConversationStore, type CreateConversationInput, EMPTY_CAPABILITIES, type EditorOutputContext, type EmbeddingModelChangeEvent, type EmbeddingProvider, type EmbeddingProviderConfig, type EmbeddingSession, type ExecutionTarget, type GetConversationInput, type HistoryLocation, type InsertOutputData, type ListConversationsInput, MockSanqianSdk, type MockScenario, type MockSdkConfig, type OutputOperation, type OutputOperationType, type OutputOperationsManager, type PendingOutputOps, type PendingPermission, type PermissionDecision, type PermissionGate, type PermissionPolicy, type ProviderChangedEvent, type ProviderInstanceConfig, type RerankInput, type RerankProvider, type RerankResult, type RerankResultItem, type ResourceListPage, type ResourceListRequest, type ResourceProviderInfo, type RuntimeAgentConfig, type RuntimeAgentId, type RuntimeAgentRegistry, type RuntimeChatRequest, type RuntimeChatResponse, type RuntimeChatStreamRequest, type RuntimeConnectionErrorCode, type RuntimeConnectionSnapshot, type RuntimeConnectionStatus, type RuntimeContext, type RuntimeConversationMessage, type RuntimeHitlResponse, type RuntimeInterrupt, type RuntimeMessage, type RuntimePermissionResponse, type RuntimeProfile, type RuntimeProvider, type RuntimeProviderCapabilities, type RuntimeProviderDescriptor, type RuntimeProviderKind, type RuntimeResource, type RuntimeResourceRef, type RuntimeSecretStore, type RuntimeSessionManager, type RuntimeSessionResourceEvent, type RuntimeStreamEvent, type RuntimeTaskPipeline, type RuntimeTaskPipelineInput, type RuntimeToolCall, type RuntimeToolChoice, type RuntimeToolDefinition, type RuntimeToolExecutionContext, type RuntimeToolExecutionInput, type RuntimeToolExecutionMetadata, type RuntimeToolExecutionResult, type RuntimeToolHandler, type RuntimeToolMetadata, type RuntimeToolRegistration, type RuntimeToolRegistry, type RuntimeUsage, type SanqianEmbeddingConfig, SanqianEmbeddingProvider, SanqianProvider, type SanqianProviderConfig, type SanqianRerankConfig, SanqianRerankProvider, type SanqianSdkPort, type SecretDescriptor, type SecretRef, type StoreSecretInput, type SwitchOptions, type SwitchResult, type ToolCategory, type VercelEmbeddingConfig, VercelEmbeddingProvider, VercelProvider, type VercelProviderConfig, convertSdkStreamEvent, convertToolsForVercel, createActiveWorkTracker, createCategoryPermissionPolicy, createChatRuntimeBridge, createDefaultPermissionPolicy, createDisabledState, createEmbeddingSession, createMemoryConversationStore, createMemorySecretStore, createOutputOperationsManager, createPermissionGate, createSanqianAgentIdResolver, createSessionManager, createTaskPipeline, createToolRegistry, redactToolError, resolveAiFeaturesFromRuntime, validateOutputContent };

package/dist/index.d.ts

@@ -120,6 +120,20 @@ interface RuntimeConnectionSnapshot {
     errorCode?: RuntimeConnectionErrorCode;
     lastChangedAt: number;
 }
+/**
+ * Per-request tool-choice constraint (mirrors Vercel AI SDK / OpenAI semantics).
+ * - 'auto' (default): the model decides whether to call tools.
+ * - 'none': the model must not call tools.
+ * - 'required': the model MUST call at least one tool this turn.
+ * - { type: 'tool', toolName }: the model MUST call the named tool.
+ * Providers that cannot honor a constraining value MUST throw instead of silently
+ * degrading to 'auto' — callers rely on this for command-style requests where a
+ * hallucinated "done" without a tool call is a correctness bug.
+ */
+type RuntimeToolChoice = 'auto' | 'none' | 'required' | {
+    type: 'tool';
+    toolName: string;
+};
 interface RuntimeChatRequest {
     agentId: string;
     messages: RuntimeMessage[];
@@ -127,6 +141,7 @@ interface RuntimeChatRequest {
     providerInstanceId?: string;
     operationId?: string;
     tools?: RuntimeToolDefinition[];
+    toolChoice?: RuntimeToolChoice;
     contexts?: RuntimeContext[];
     resources?: RuntimeResourceRef[];
     sessionResources?: RuntimeResource[];
@@ -145,6 +160,7 @@ interface RuntimeChatStreamRequest {
     providerInstanceId?: string;
     operationId?: string;
     tools?: RuntimeToolDefinition[];
+    toolChoice?: RuntimeToolChoice;
     contexts?: RuntimeContext[];
     resources?: RuntimeResourceRef[];
     sessionResources?: RuntimeResource[];
@@ -1390,4 +1406,4 @@ declare class VercelEmbeddingProvider implements EmbeddingProvider {
     private redact;
 }
 
-export { type ActiveRuntimeWork, type ActiveRuntimeWorkKind, type ActiveStream, type ActiveWorkTracker, type AgentExecutionMode, type AgentIdResolver, type AiFeatureRuntimeState, type AuthMode, type BillingMode, type BridgeSessionResource, type ChatRuntimeBridge, type ChatRuntimeBridgeConfig, type ConversationDetail, type ConversationInfo, type ConversationPage, type ConversationPatch, type ConversationStore, type CreateConversationInput, EMPTY_CAPABILITIES, type EditorOutputContext, type EmbeddingModelChangeEvent, type EmbeddingProvider, type EmbeddingProviderConfig, type EmbeddingSession, type ExecutionTarget, type GetConversationInput, type HistoryLocation, type InsertOutputData, type ListConversationsInput, MockSanqianSdk, type MockScenario, type MockSdkConfig, type OutputOperation, type OutputOperationType, type OutputOperationsManager, type PendingOutputOps, type PendingPermission, type PermissionDecision, type PermissionGate, type PermissionPolicy, type ProviderChangedEvent, type ProviderInstanceConfig, type RerankInput, type RerankProvider, type RerankResult, type RerankResultItem, type ResourceListPage, type ResourceListRequest, type ResourceProviderInfo, type RuntimeAgentConfig, type RuntimeAgentId, type RuntimeAgentRegistry, type RuntimeChatRequest, type RuntimeChatResponse, type RuntimeChatStreamRequest, type RuntimeConnectionErrorCode, type RuntimeConnectionSnapshot, type RuntimeConnectionStatus, type RuntimeContext, type RuntimeConversationMessage, type RuntimeHitlResponse, type RuntimeInterrupt, type RuntimeMessage, type RuntimePermissionResponse, type RuntimeProfile, type RuntimeProvider, type RuntimeProviderCapabilities, type RuntimeProviderDescriptor, type RuntimeProviderKind, type RuntimeResource, type RuntimeResourceRef, type RuntimeSecretStore, type RuntimeSessionManager, type RuntimeSessionResourceEvent, type RuntimeStreamEvent, type RuntimeTaskPipeline, type RuntimeTaskPipelineInput, type RuntimeToolCall, type RuntimeToolDefinition, type RuntimeToolExecutionContext, type RuntimeToolExecutionInput, type RuntimeToolExecutionMetadata, type RuntimeToolExecutionResult, type RuntimeToolHandler, type RuntimeToolMetadata, type RuntimeToolRegistration, type RuntimeToolRegistry, type RuntimeUsage, type SanqianEmbeddingConfig, SanqianEmbeddingProvider, SanqianProvider, type SanqianProviderConfig, type SanqianRerankConfig, SanqianRerankProvider, type SanqianSdkPort, type SecretDescriptor, type SecretRef, type StoreSecretInput, type SwitchOptions, type SwitchResult, type ToolCategory, type VercelEmbeddingConfig, VercelEmbeddingProvider, VercelProvider, type VercelProviderConfig, convertSdkStreamEvent, convertToolsForVercel, createActiveWorkTracker, createCategoryPermissionPolicy, createChatRuntimeBridge, createDefaultPermissionPolicy, createDisabledState, createEmbeddingSession, createMemoryConversationStore, createMemorySecretStore, createOutputOperationsManager, createPermissionGate, createSanqianAgentIdResolver, createSessionManager, createTaskPipeline, createToolRegistry, redactToolError, resolveAiFeaturesFromRuntime, validateOutputContent };
+export { type ActiveRuntimeWork, type ActiveRuntimeWorkKind, type ActiveStream, type ActiveWorkTracker, type AgentExecutionMode, type AgentIdResolver, type AiFeatureRuntimeState, type AuthMode, type BillingMode, type BridgeSessionResource, type ChatRuntimeBridge, type ChatRuntimeBridgeConfig, type ConversationDetail, type ConversationInfo, type ConversationPage, type ConversationPatch, type ConversationStore, type CreateConversationInput, EMPTY_CAPABILITIES, type EditorOutputContext, type EmbeddingModelChangeEvent, type EmbeddingProvider, type EmbeddingProviderConfig, type EmbeddingSession, type ExecutionTarget, type GetConversationInput, type HistoryLocation, type InsertOutputData, type ListConversationsInput, MockSanqianSdk, type MockScenario, type MockSdkConfig, type OutputOperation, type OutputOperationType, type OutputOperationsManager, type PendingOutputOps, type PendingPermission, type PermissionDecision, type PermissionGate, type PermissionPolicy, type ProviderChangedEvent, type ProviderInstanceConfig, type RerankInput, type RerankProvider, type RerankResult, type RerankResultItem, type ResourceListPage, type ResourceListRequest, type ResourceProviderInfo, type RuntimeAgentConfig, type RuntimeAgentId, type RuntimeAgentRegistry, type RuntimeChatRequest, type RuntimeChatResponse, type RuntimeChatStreamRequest, type RuntimeConnectionErrorCode, type RuntimeConnectionSnapshot, type RuntimeConnectionStatus, type RuntimeContext, type RuntimeConversationMessage, type RuntimeHitlResponse, type RuntimeInterrupt, type RuntimeMessage, type RuntimePermissionResponse, type RuntimeProfile, type RuntimeProvider, type RuntimeProviderCapabilities, type RuntimeProviderDescriptor, type RuntimeProviderKind, type RuntimeResource, type RuntimeResourceRef, type RuntimeSecretStore, type RuntimeSessionManager, type RuntimeSessionResourceEvent, type RuntimeStreamEvent, type RuntimeTaskPipeline, type RuntimeTaskPipelineInput, type RuntimeToolCall, type RuntimeToolChoice, type RuntimeToolDefinition, type RuntimeToolExecutionContext, type RuntimeToolExecutionInput, type RuntimeToolExecutionMetadata, type RuntimeToolExecutionResult, type RuntimeToolHandler, type RuntimeToolMetadata, type RuntimeToolRegistration, type RuntimeToolRegistry, type RuntimeUsage, type SanqianEmbeddingConfig, SanqianEmbeddingProvider, SanqianProvider, type SanqianProviderConfig, type SanqianRerankConfig, SanqianRerankProvider, type SanqianSdkPort, type SecretDescriptor, type SecretRef, type StoreSecretInput, type SwitchOptions, type SwitchResult, type ToolCategory, type VercelEmbeddingConfig, VercelEmbeddingProvider, VercelProvider, type VercelProviderConfig, convertSdkStreamEvent, convertToolsForVercel, createActiveWorkTracker, createCategoryPermissionPolicy, createChatRuntimeBridge, createDefaultPermissionPolicy, createDisabledState, createEmbeddingSession, createMemoryConversationStore, createMemorySecretStore, createOutputOperationsManager, createPermissionGate, createSanqianAgentIdResolver, createSessionManager, createTaskPipeline, createToolRegistry, redactToolError, resolveAiFeaturesFromRuntime, validateOutputContent };

package/dist/index.js

@@ -958,6 +958,11 @@ function createSanqianAgentIdResolver(appName) {
 }
 
 // src/providers/sanqian/provider.ts
+var SANQIAN_TOOL_CHOICE_UNSUPPORTED_ERROR = "SanqianProvider does not support constraining toolChoice yet: the runtime wire protocol has no tool_choice field. Fail-fast by contract - do not silently degrade to auto.";
+function assertSupportedToolChoice(toolChoice) {
+  if (toolChoice === void 0 || toolChoice === "auto") return;
+  throw new Error(SANQIAN_TOOL_CHOICE_UNSUPPORTED_ERROR);
+}
 var SANQIAN_CAPABILITIES = {
   streamingText: true,
   reasoning: true,
@@ -1073,6 +1078,7 @@ var SanqianProvider = class {
   // --- Chat ---
   async chat(input) {
     this.ensureNotDisposed();
+    assertSupportedToolChoice(input.toolChoice);
     const agentId = await this.resolveAgentId(input.agentId);
     const messages = input.messages.map((m) => ({ role: m.role, content: m.content }));
     const response = await this.sdk.chat(agentId, messages, {
@@ -1090,6 +1096,7 @@ var SanqianProvider = class {
   }
   async *chatStream(input) {
     this.ensureNotDisposed();
+    assertSupportedToolChoice(input.toolChoice);
     const agentId = await this.resolveAgentId(input.agentId);
     const messages = input.messages.map((m) => ({ role: m.role, content: m.content }));
     const stream = this.sdk.chatStream(agentId, messages, {
@@ -1719,6 +1726,16 @@ function convertToolsForVercel(tools, registry, options) {
 }
 
 // src/providers/vercel/provider.ts
+function isConstrainingToolChoice(toolChoice) {
+  return toolChoice === "required" || typeof toolChoice === "object" && toolChoice !== null;
+}
+function resolveToolChoiceOption(toolChoice, hasTools) {
+  if (toolChoice === void 0) return {};
+  if (!hasTools && isConstrainingToolChoice(toolChoice)) {
+    throw new Error("toolChoice requires at least one resolved tool for this agent");
+  }
+  return { toolChoice };
+}
 var VERCEL_CAPABILITIES = {
   streamingText: true,
   reasoning: true,
@@ -1810,6 +1827,7 @@ var VercelProvider = class {
       system,
       messages: userMessages,
       tools,
+      ...resolveToolChoiceOption(input.toolChoice, !!tools),
       stopWhen: (0, import_ai.stepCountIs)(maxSteps),
       abortSignal: input.signal
     });
@@ -1846,6 +1864,7 @@ var VercelProvider = class {
         system,
         messages: userMessages,
         tools,
+        ...resolveToolChoiceOption(input.toolChoice, !!tools),
         stopWhen: (0, import_ai.stepCountIs)(maxSteps),
         abortSignal: input.signal
       });