@yushaw/sanqian-sdk 0.3.26 → 0.3.28

package/README.md

@@ -341,6 +341,25 @@ const response = await sdk.chat('agent', messages, {
 })
 ```
 
+### Local file ingest
+
+For same-machine deployments where the Sanqian backend can read a local path directly, use `uploadFile()` first, then pass the returned `file.path` into `chat()`:
+
+```typescript
+const uploaded = await sdk.uploadFile('/absolute/path/report.pdf', {
+  conversationId,
+  autoIndex: true,
+  asyncProcess: true,
+})
+
+const response = await sdk.chat('agent', messages, {
+  conversationId: uploaded.conversationId,
+  filePaths: [uploaded.file.path],
+})
+```
+
+`uploadFile(localPath)` is not a remote file transfer protocol. For remote/backend-on-another-machine cases, continue using explicit byte upload APIs.
+
 ---
 
 ## Human-in-the-Loop (HITL)
@@ -1328,6 +1347,25 @@ const response = await sdk.chat('agent', messages, {
 })
 ```
 
+### 本地文件导入
+
+对于 Sanqian 后端与调用方在同一台机器、且后端能直接读取本地路径的场景，先调用 `uploadFile()`，再把返回的 `file.path` 传给 `chat()`：
+
+```typescript
+const uploaded = await sdk.uploadFile('/absolute/path/report.pdf', {
+  conversationId,
+  autoIndex: true,
+  asyncProcess: true,
+})
+
+const response = await sdk.chat('agent', messages, {
+  conversationId: uploaded.conversationId,
+  filePaths: [uploaded.file.path],
+})
+```
+
+`uploadFile(localPath)` 不是远程文件传输协议。对于远程 backend 或不同机器场景，仍应使用显式字节上传能力。
+
 ---
 
 ## 人机协作 (HITL)

package/dist/index.browser.d.mts

@@ -297,6 +297,30 @@ interface ChatStreamEvent {
     result?: unknown;
     /** Whether tool execution succeeded (for "tool_result" event) */
     success?: boolean;
+    /** Normalized tool execution status (for "tool_result" event) */
+    status?: "running" | "completed" | "error" | "cancelled";
+    /** Structured action required hint (for "tool_result" event) */
+    action_required?: string;
+    /** Optional settings deep link target (for "tool_result" event) */
+    settings_tab?: string;
+    /** Optional settings deep link sub-target (for "tool_result" event) */
+    settings_sub_tab?: string;
+    /** Structured SDK tool failure marker (for "tool_result" event) */
+    sdk_tool_error?: boolean;
+    /** App name that emitted the SDK tool failure (for "tool_result" event) */
+    sdk_tool_app?: string;
+    /** Failure domain for structured tool errors (for "tool_result" event) */
+    tool_failure_domain?: string;
+    /** App identifier for structured tool errors (for "tool_result" event) */
+    tool_failure_app?: string;
+    /** Failure kind for structured tool errors (for "tool_result" event) */
+    tool_failure_kind?: string;
+    /** Whether the tool reported a rollback during failure handling (for "tool_result" event) */
+    tool_failure_rolled_back?: boolean;
+    /** Human-readable failure message for structured tool errors (for "tool_result" event) */
+    tool_failure_error?: string;
+    /** Stable target key for structured tool errors (for "tool_result" event) */
+    tool_failure_target_key?: string;
     /** Conversation ID (for "done" event) */
     conversationId?: string;
     /** Conversation title (for "done" event) */
@@ -519,6 +543,27 @@ interface ConversationHistoryResult {
     user_loaded_tools?: string[];
     user_loaded_subagents?: string[];
 }
+interface UploadFileOptions {
+    conversationId?: string;
+    autoIndex?: boolean;
+    asyncProcess?: boolean;
+}
+interface UploadedFileInfo {
+    id?: number | null;
+    path: string;
+    name: string;
+    size: number;
+    mimeType?: string | null;
+    extension?: string | null;
+    source?: string | null;
+    processStatus?: string | null;
+    resourceUri?: string | null;
+    resourceStatus?: string | null;
+}
+interface UploadFileResult {
+    conversationId: string;
+    file: UploadedFileInfo;
+}
 /** Agent update configuration (all fields optional except agent_id) */
 interface AgentUpdateConfig {
     /** Agent ID to update */
@@ -998,7 +1043,9 @@ declare abstract class SanqianSDKBase {
     private resolvePendingStartIndex;
     private getActiveConnectionInfo;
     private getHttpBaseUrl;
-    getHttpAuthHeaders(): Record<string, string>;
+    getHttpAuthHeaders(options?: {
+        includeAppIdentity?: boolean;
+    }): Record<string, string>;
     /**
      * Centralized HTTP request method.
      * Automatically injects X-App-Token auth header and standardizes error handling.
@@ -1156,6 +1203,11 @@ declare abstract class SanqianSDKBase {
      * Delete a conversation
      */
     deleteConversation(conversationId: string): Promise<void>;
+    /**
+     * Prepare a local file for chat attachment via the backend ingest-local route.
+     * This is intended for same-machine deployments where the backend can read localPath directly.
+     */
+    uploadFile(localPath: string, options?: UploadFileOptions): Promise<UploadFileResult>;
     /**
      * Send a chat message to an agent (non-streaming)
      */

package/dist/index.browser.d.ts

@@ -297,6 +297,30 @@ interface ChatStreamEvent {
     result?: unknown;
     /** Whether tool execution succeeded (for "tool_result" event) */
     success?: boolean;
+    /** Normalized tool execution status (for "tool_result" event) */
+    status?: "running" | "completed" | "error" | "cancelled";
+    /** Structured action required hint (for "tool_result" event) */
+    action_required?: string;
+    /** Optional settings deep link target (for "tool_result" event) */
+    settings_tab?: string;
+    /** Optional settings deep link sub-target (for "tool_result" event) */
+    settings_sub_tab?: string;
+    /** Structured SDK tool failure marker (for "tool_result" event) */
+    sdk_tool_error?: boolean;
+    /** App name that emitted the SDK tool failure (for "tool_result" event) */
+    sdk_tool_app?: string;
+    /** Failure domain for structured tool errors (for "tool_result" event) */
+    tool_failure_domain?: string;
+    /** App identifier for structured tool errors (for "tool_result" event) */
+    tool_failure_app?: string;
+    /** Failure kind for structured tool errors (for "tool_result" event) */
+    tool_failure_kind?: string;
+    /** Whether the tool reported a rollback during failure handling (for "tool_result" event) */
+    tool_failure_rolled_back?: boolean;
+    /** Human-readable failure message for structured tool errors (for "tool_result" event) */
+    tool_failure_error?: string;
+    /** Stable target key for structured tool errors (for "tool_result" event) */
+    tool_failure_target_key?: string;
     /** Conversation ID (for "done" event) */
     conversationId?: string;
     /** Conversation title (for "done" event) */
@@ -519,6 +543,27 @@ interface ConversationHistoryResult {
     user_loaded_tools?: string[];
     user_loaded_subagents?: string[];
 }
+interface UploadFileOptions {
+    conversationId?: string;
+    autoIndex?: boolean;
+    asyncProcess?: boolean;
+}
+interface UploadedFileInfo {
+    id?: number | null;
+    path: string;
+    name: string;
+    size: number;
+    mimeType?: string | null;
+    extension?: string | null;
+    source?: string | null;
+    processStatus?: string | null;
+    resourceUri?: string | null;
+    resourceStatus?: string | null;
+}
+interface UploadFileResult {
+    conversationId: string;
+    file: UploadedFileInfo;
+}
 /** Agent update configuration (all fields optional except agent_id) */
 interface AgentUpdateConfig {
     /** Agent ID to update */
@@ -998,7 +1043,9 @@ declare abstract class SanqianSDKBase {
     private resolvePendingStartIndex;
     private getActiveConnectionInfo;
     private getHttpBaseUrl;
-    getHttpAuthHeaders(): Record<string, string>;
+    getHttpAuthHeaders(options?: {
+        includeAppIdentity?: boolean;
+    }): Record<string, string>;
     /**
      * Centralized HTTP request method.
      * Automatically injects X-App-Token auth header and standardizes error handling.
@@ -1156,6 +1203,11 @@ declare abstract class SanqianSDKBase {
      * Delete a conversation
      */
     deleteConversation(conversationId: string): Promise<void>;
+    /**
+     * Prepare a local file for chat attachment via the backend ingest-local route.
+     * This is intended for same-machine deployments where the backend can read localPath directly.
+     */
+    uploadFile(localPath: string, options?: UploadFileOptions): Promise<UploadFileResult>;
     /**
      * Send a chat message to an agent (non-streaming)
      */

package/dist/index.browser.js

@@ -368,10 +368,20 @@ var SanqianSDKBase = class _SanqianSDKBase {
     const host = info.ws_host || "127.0.0.1";
     return `${protocol}://${host}:${info.port}`;
   }
-  getHttpAuthHeaders() {
+  getHttpAuthHeaders(options) {
     const info = this.getActiveConnectionInfo();
     const token = info?.token;
-    return token ? { "X-App-Token": token } : {};
+    const headers = token ? { "X-App-Token": token } : {};
+    if (options?.includeAppIdentity) {
+      headers["X-App-Name"] = this.config.appName;
+      if (this.config.appVersion) {
+        headers["X-App-Version"] = this.config.appVersion;
+      }
+      if (this.config.displayName) {
+        headers["X-App-Display-Name"] = this.config.displayName;
+      }
+    }
+    return headers;
   }
   /**
    * Centralized HTTP request method.
@@ -384,11 +394,18 @@ var SanqianSDKBase = class _SanqianSDKBase {
     if (qs) {
       url += `?${qs}`;
     }
-    const headers = { ...this.getHttpAuthHeaders() };
+    const headers = {
+      ...this.getHttpAuthHeaders({ includeAppIdentity: options?.includeAppIdentity })
+    };
     const init = { method, headers };
     if (options?.body !== void 0) {
       headers["Content-Type"] = "application/json";
       init.body = JSON.stringify(options.body);
+    } else if (options?.rawBody !== void 0) {
+      if (options.contentType) {
+        headers["Content-Type"] = options.contentType;
+      }
+      init.body = options.rawBody;
     }
     const response = await fetch(url, init);
     if (!response.ok) {
@@ -784,7 +801,19 @@ var SanqianSDKBase = class _SanqianSDKBase {
             tool_call_id: tool_result.call_id,
             result: tool_result.result,
             success: tool_result.success,
-            error: tool_result.error
+            error: tool_result.error,
+            status: tool_result.status,
+            action_required: tool_result.action_required,
+            settings_tab: tool_result.settings_tab,
+            settings_sub_tab: tool_result.settings_sub_tab,
+            sdk_tool_error: tool_result.sdk_tool_error,
+            sdk_tool_app: tool_result.sdk_tool_app,
+            tool_failure_domain: tool_result.tool_failure_domain,
+            tool_failure_app: tool_result.tool_failure_app,
+            tool_failure_kind: tool_result.tool_failure_kind,
+            tool_failure_rolled_back: tool_result.tool_failure_rolled_back,
+            tool_failure_error: tool_result.tool_failure_error,
+            tool_failure_target_key: tool_result.tool_failure_target_key
           });
         } else {
           this.log("Received tool_result event without tool_result data");
@@ -896,10 +925,22 @@ var SanqianSDKBase = class _SanqianSDKBase {
     if (handler) {
       handler.onEvent({
         type: "tool_result",
-        tool_call_id: message.tool_call_id,
+        tool_call_id: message.tool_call_id || message.tool_id,
         result: message.result,
         success: message.success,
-        error: message.error
+        error: message.error,
+        status: message.status,
+        action_required: message.action_required,
+        settings_tab: message.settings_tab,
+        settings_sub_tab: message.settings_sub_tab,
+        sdk_tool_error: message.sdk_tool_error,
+        sdk_tool_app: message.sdk_tool_app,
+        tool_failure_domain: message.tool_failure_domain,
+        tool_failure_app: message.tool_failure_app,
+        tool_failure_kind: message.tool_failure_kind,
+        tool_failure_rolled_back: message.tool_failure_rolled_back,
+        tool_failure_error: message.tool_failure_error,
+        tool_failure_target_key: message.tool_failure_target_key
       });
     }
   }
@@ -970,11 +1011,12 @@ var SanqianSDKBase = class _SanqianSDKBase {
     } catch (e) {
       const errorMessage = e instanceof Error ? e.message : String(e);
       const errorStack = e instanceof Error ? e.stack : void 0;
+      const structuredToolResult = e && typeof e === "object" && "toolResult" in e ? e.toolResult : void 0;
       this.log(`Tool '${toolName}' failed:`, errorMessage);
       if (errorStack) {
         this.log(`Tool error stack:`, errorStack);
       }
-      await this.sendToolResult(msgId, call_id, false, void 0, errorMessage);
+      await this.sendToolResult(msgId, call_id, false, structuredToolResult, errorMessage);
     }
   }
   async sendToolResult(id, callId, success, result, error) {
@@ -1518,6 +1560,46 @@ var SanqianSDKBase = class _SanqianSDKBase {
       throw createSDKError("CONVERSATION_NOT_FOUND" /* CONVERSATION_NOT_FOUND */, response.error);
     }
   }
+  /**
+   * Prepare a local file for chat attachment via the backend ingest-local route.
+   * This is intended for same-machine deployments where the backend can read localPath directly.
+   */
+  async uploadFile(localPath, options) {
+    await this.ensureHttpReady();
+    const form = new URLSearchParams();
+    form.append("local_path", localPath);
+    if (options?.conversationId) {
+      form.append("conversation_id", options.conversationId);
+    }
+    form.append("auto_index", String(options?.autoIndex ?? true));
+    form.append("async_process", String(options?.asyncProcess ?? true));
+    const response = await this.httpRequest("POST", "/api/files/ingest-local", {
+      rawBody: form.toString(),
+      contentType: "application/x-www-form-urlencoded",
+      includeAppIdentity: true
+    });
+    if (!response.success || !response.conversation_id || !response.file?.path) {
+      throw createSDKError(
+        "REQUEST_FAILED" /* REQUEST_FAILED */,
+        response.error || "POST /api/files/ingest-local returned an invalid response"
+      );
+    }
+    return {
+      conversationId: response.conversation_id,
+      file: {
+        id: response.file.id,
+        path: response.file.path,
+        name: response.file.name || "",
+        size: response.file.size ?? 0,
+        mimeType: response.file.mime_type,
+        extension: response.file.extension,
+        source: response.file.source,
+        processStatus: response.file.process_status,
+        resourceUri: response.file.resource_uri,
+        resourceStatus: response.file.resource_status
+      }
+    };
+  }
   // ============================================
   // Chat API
   // ============================================