@blade-hq/agent-client 2612.0.0-beta.53 → 2612.0.0-beta.55

package/README.md

@@ -113,6 +113,8 @@ const configured = await client.sessions.create({ intent: "数据分析", model:
 
 SDK 创建的会话默认归接入应用（`initiator: "sdk"`），运行事件仍由 SDK 交付，提醒展示和点击导航由接入应用自行处理，BA 内置 Web 不弹出这些会话的完成或等待回复提醒。内置 Web 创建入口显式使用 `initiator: "ui"`；此字段表示应用归属，与 headless 执行模式无关。
 
+创建请求省略默认的 `sdk` 值，由服务端采用默认归属；显式 `ui` 仍会发送。这样默认创建不会因旧服务端尚未定义 `initiator` 而返回 422。接入时仍须按服务端 `/api/version` 返回的 `version` 安装配套 SDK，其他新功能参数不保证适用于旧服务端。
+
 ### 声明完整会话
 
 自定义 Solution、Skill 和模型无需手写上传步骤：
@@ -153,6 +155,7 @@ await client.sessions.getSession(id)                  // 会话详情
 await client.sessions.updateSession(id, { intent: "新标题" })
 await client.sessions.deleteSession(id)
 await client.sessions.getSessionTurns(id)             // 历史消息（投影格式，与实时流同构）
+await client.sessions.getRunResult(id, executionId)    // 所有者查询持久执行结果；尚无结束记录返回 null
 const page = await client.sessions.getSessionTurnsPage(id) // 聊天首屏 recent page
 await client.sessions.getSessionTurnsPage(id, { before: page.nextBefore! })
 // 从某条用户发言定位到最新（消息导航点窗口外的发言）：调用参数是 SessionTurnsQuery
@@ -769,7 +772,15 @@ chat.renderers = {
 
 ## 账号连接器
 
-`client.connectors.list()` 列出当前用户沙盒中创建的连接器及随项目发布的内置连接器，来源分别为 `personal`、`builtin`，无需商店安装；`listForSession(sessionId)` 同时返回当前对话的启用状态。`read(name)` 获取认证表单与连接状态；`connect(name, update)` 保存个人配置并执行真实认证；`verify(name)` 验证已有连接；`disconnect(name)` 清除该连接和个人配置。每用户每连接器只有一个连接，修改账号更新原连接；密码与私有状态不通过读取接口返回。认证通过后，用 `sessions.setSessionPluginActivation(sessionId, name, true)` 在沙盒对话中启用；包内容变化后需要重新连接。
+内置飞书返回 `authorization.type="device"` 时，使用 `connectors.authorization(name)` 读取 `ConnectorAuthorization`，以 `connectors.authorize(name, action, pushUrl?, options?)` 推进授权。`ConnectorAuthorizationAction` 的 `authorize` 由 SW 按当前状态推进应用注册、核验与本人授权，`poll` 继续当前步骤，客户端只展示 `current_step` 的当前操作；应用注册、本人读取、取消和核验入口仍保留。`activation_pending=true` 表示新连接待首次完成，刷新后仍应保留默认启用意图；成功 finish 或明确停用后变为 false，已有记录缺字段不推断为新连接。空槽位返回 false，实际创建连接后的响应再变为 true。显式 `finish` 提交 BA 可执行能力，`ConnectorAuthorizationOptions.enable=false` 可在增加能力时保持 BA 已停用；`bind`、`pause`、`resume` 独立管理 PA 接收订阅，不改变 BA 启用状态。SW 保存并刷新全部飞书凭据，BA 服务端以当前用户 PAT 访问 SW HTTP MCP；浏览器只读取展示链接和脱敏状态。详情见 [飞书 SW 接入设计](../../../docs/specs/261026-feishu-sw-mcp/design.md)。
+
+`ConnectorDomain` 与 `ConnectorCapability.category/category_name` 提供业务分类；`operations` 对每个 `tool_name` 分别给出有效权限 `status`、实现状态 `executable` 和实际动作 `effect`，`capability_id` 对应授权选择。`ConnectorApprovalStatus` 区分 `exempt`、`review_required` 与 `unknown`，必须结合 `approval_evidence` 展示，未知不能当作免审核。`ConnectorPermission.approval_status` 提供同样的结构化判断，原 `approval` 保留平台说明。`catalog_revision` 是业务目录内容版本；新增工具采用 SW 的实际 MCP schema，BA 服务端固定连接身份，平台权限和资源范围仍逐次校验。`ConnectorAuthorizationStep` 和 `ConnectorAuthorizationFailure` 提供当前步骤、可重试性、下一步与排查编号；部分失败不会清除已有授权。`connectors.authorizationPlan(name, capabilities)` 返回 `ConnectorAuthorizationPlan`，仅预览本次权限差异，并分别返回已就绪、需要本人授权、管理员审核、审批未知和不支持的能力集合；`connectors.diagnostics(name)` 返回 `ConnectorDiagnostics`，其中 `ConnectorAuditEvent` 是脱敏审计记录，`ConnectorRuntimeDiagnostics` 描述消息通道和 PA 投递的实际记录。`subscription_state` 分别表示未绑定、启用、暂停或失效，不能只用扫码成功判断收消息链路。
+
+`ConnectorArtifact` 描述 SW 按用户、连接和应用隔离的临时文件，包含 SHA256、大小、来源与到期时间。`connectors.uploadFile(name, blob, fileName, requestId)` 把明确选择的附件经 BA 同源代理上传，重试复用原编号；`downloadFile(name, artifactId)` 返回经过 BA 鉴权的 Blob，不能把私有 `download_path` 当作公开分享链接。用户 PAT 只在 BA→SW 传输，不进入文件工具参数或浏览器响应。智能体可沿现有 `lazy_tool_run` 的 `files.read` 传一个当前会话相对文件，由平台安全暂存并注入 `artifact_id`；下载工具可用 `files.write` 把经过大小、SHA256 校验的产物保存到会话 `plugin-output`。不接受任意主机路径或远程下载地址，失败不发布输出文件。
+
+飞书的 `disconnect(name)` 仅停用 BA 绑定，保留 SW 账号与 PA 订阅。重新启用通过显式 `finish` 动作完成；停止推送可用 `pause`；移除连接并重新关联使用 `authorize(name, "remove", undefined, { expected_connection_id: view.connection_id })`。仅 SW 确认移除后清空旧绑定和目录，保留当前用户 PAT；不会删除飞书后台应用或自动发起新关联。成功后的目录暂不可读仍返回 disconnected 与 `catalog_unavailable=true`，不恢复旧应用。
+
+`client.connectors.list()` 列出当前用户沙盒中创建的连接器及随项目发布的内置连接器，来源分别为 `personal`、`builtin`，无需商店安装；`listForSession(sessionId)` 同时返回当前对话的启用状态。`read(name)` 获取认证表单与连接状态；`connect(name, update)` 保存个人配置并执行真实认证；`verify(name)` 验证已有连接；`disconnect(name)` 清除普通连接器的连接和个人配置（飞书仅停用 BA）。每用户每连接器只有一个连接，修改账号更新原连接；密码与私有状态不通过读取接口返回。认证通过后，用 `sessions.setSessionPluginActivation(sessionId, name, true)` 在沙盒对话中启用；包内容变化后需要重新连接。
 
 相关类型：`ConnectorsResource`、`AccountConnector`、`ConnectorConnection`、`ConnectorConnectionView`。
 
@@ -789,7 +800,7 @@ chat.renderers = {
 - **声明式会话**：`SessionDefinition`、`SolutionDefinition`、`SkillDefinition`、`SkillFile`、`SessionConfig`、`TextFile`、`SessionSetupError`、`SessionSetupStage`
 - **会话消息队列**：`SessionQueueSnapshot`、`QueuedMessage`、`QueuedMessageStatus`、`QueueOperationResult`
 - **页面协作**：`CommandHandler`、`BladeChatMountRenderers`、`MountRenderer`、`MountRendererObject`、`MountResult`、`MountHandle`
-- **会话资源（REST）**：`SessionsResource`、`CreateSessionRequest`、`McpSourceConfig`、`PaginatedSessionsResult`、`SessionInfo`、`SessionStatus`、`SessionDetail`、`DEFAULT_REPLAY_SPEED`、`ReplaySpeed`、`ReplayState`、`SessionTurnsPage`、`SessionTurnsQuery`、`FileEntry`、`UploadFileEntry`、`UploadFilesOptions`、`AppCliDefinition`、`AppCliAttachment`
+- **会话资源（REST）**：`SessionsResource`、`CreateSessionRequest`、`McpSourceConfig`、`PaginatedSessionsResult`、`SessionInfo`、`SessionStatus`、`SessionDetail`、`DEFAULT_REPLAY_SPEED`、`ReplaySpeed`、`ReplayState`、`SessionTurnsPage`、`SessionTurnsQuery`、`SessionRunResult`、`FileEntry`、`UploadFileEntry`、`UploadFilesOptions`、`AppCliDefinition`、`AppCliAttachment`
 - **模型目录**：`ModelsResource`、`ModelCatalog`、`ModelOption`
 - **沙盒脚本**：`SandboxResource`、`SandboxScriptRequest`、`SandboxScriptResult`。`client.sandbox.execute({ script, cwd, timeout })` 在当前登录用户的沙盒执行脚本，无需创建智能体会话；`cwd` 使用绝对路径，`timeout` 单位为秒，默认及最大值为 120。结果包含合并诊断输出 `output`、独立标准输出 `stdout` 及其截断标志 `stdout_truncated`、可为空的退出码、超时标志和错误信息；无法启动或无法确认停止时应检查 `error`，不能仅凭退出码判断成功。
 - **远程电脑**：`ComputersResource`、`SessionComputer`、`AccountComputer`

package/dist/{chunk-CF6ROLBQ.js → chunk-ZKTKJZNT.js}

@@ -201,7 +201,7 @@ var ToolProvider = class {
         const params = message.params;
         const tool = this.options.tools.find((t) => t.name === params?.name);
         if (!tool || typeof params?.sessionId !== "string" || !params.sessionId || !params.arguments || typeof params.arguments !== "object" || Array.isArray(params.arguments)) throw new Error("Invalid or unauthorized tool call");
-        response.result = await tool.handler(params.arguments, { sessionId: params.sessionId, signal: controller.signal });
+        response.result = await tool.handler(params.arguments, { sessionId: params.sessionId, signal: controller.signal, ...Object.fromEntries(["executionId", "requestId", "toolCallId"].flatMap((key) => typeof params[key] === "string" && params[key] ? [[key, params[key]]] : [])) });
       } else {
         response.error = { code: -32601, message: "Method not found" };
       }
@@ -224,7 +224,7 @@ var ToolProvider = class {
 
 // src/version.ts
 var SDK_NAME = "agent-client";
-var SDK_VERSION = true ? "2612.0.0-beta.53" : "1.1.1";
+var SDK_VERSION = true ? "2612.0.0-beta.55" : "1.1.1";
 
 // src/auth-login.ts
 function isAuthCallbackMessage(value) {
@@ -3368,6 +3368,34 @@ var ConnectorsResource = class {
     this.client = client;
   }
   client;
+  /** Stage an explicit attachment in the current user's SW connection. Reuse requestId on retry. */
+  async uploadFile(name, file, fileName, requestId) {
+    const form = new FormData();
+    form.append("file", file, fileName);
+    form.append("request_id", requestId);
+    const response = await this.client.formData("POST", `/api/connectors/${encodeURIComponent(name)}/files`, form);
+    return response.json();
+  }
+  /** Fetch a private artifact through BA authentication; no SW PAT or public URL is exposed. */
+  downloadFile(name, artifactId) {
+    return this.client.blob("GET", `/api/connectors/${encodeURIComponent(name)}/files/${encodeURIComponent(artifactId)}`);
+  }
+  authorization(name, init) {
+    return this.client.jsonFromInit(`/api/connectors/${encodeURIComponent(name)}/authorization`, init);
+  }
+  authorize(name, action, pushUrl, options) {
+    return this.client.json("POST", `/api/connectors/${encodeURIComponent(name)}/authorization`, {
+      action,
+      ...options,
+      ...pushUrl ? { push_url: pushUrl } : {}
+    });
+  }
+  authorizationPlan(name, capabilities) {
+    return this.client.json("POST", `/api/connectors/${encodeURIComponent(name)}/authorization`, { action: "plan", capabilities });
+  }
+  diagnostics(name, init) {
+    return this.client.jsonFromInit(`/api/connectors/${encodeURIComponent(name)}/diagnostics`, init);
+  }
   create(draft) {
     return this.client.json("POST", "/api/connectors", draft);
   }
@@ -3525,7 +3553,8 @@ function toCreateSessionPayload(request) {
   const solutionRef = request.solution_ref ?? externalSolutionRef(request.solution_id);
   return {
     intent: request.intent ?? "",
-    initiator: request.initiator ?? "sdk",
+    // The server defaults to sdk; older APIs reject even this redundant field.
+    initiator: request.initiator === "sdk" ? void 0 : request.initiator,
     anonymous: request.anonymous,
     solution_id: solutionRef ? void 0 : request.solution_id,
     solution_ref: solutionRef,
@@ -3877,6 +3906,10 @@ var SessionsResource = class {
   getSessionTasks(sessionId) {
     return this.client.json("GET", `/api/sessions/${sessionId}/tasks`);
   }
+  /** Durable result for this execution; null until its run_end is committed. Owner only. */
+  getRunResult(sessionId, runId) {
+    return this.client.json("GET", `/api/sessions/${encodeURIComponent(sessionId)}/runs/${encodeURIComponent(runId)}`);
+  }
   async getSessionTurns(sessionId) {
     const entries = await this.client.json(
       "GET",
@@ -6502,9 +6535,9 @@ var AgentSession = class _AgentSession {
     }
   }
   /** 停止当前回复。 */
-  async stop() {
+  async stop(executionId) {
     const request = this.manualCompactionRequest;
-    if (request) {
+    if (request && !executionId) {
       const ack = await request.ack;
       if (ack.status !== "accepted") return ack;
       if (this.manualCompactionRequest !== request) return { status: "idle" };
@@ -6513,7 +6546,7 @@ var AgentSession = class _AgentSession {
         chat_run_id: request.runId
       }, 35e3) ?? {};
     }
-    const response = await this.runtime.emitWithAck("chat:stop", { session_id: this.sessionId }, 35e3) ?? {};
+    const response = await this.runtime.emitWithAck("chat:stop", { session_id: this.sessionId, ...executionId ? { chat_run_id: executionId } : {} }, 35e3) ?? {};
     const cancelled = response.cancelled_client_request_ids;
     if (response.status === "stopped" && Array.isArray(cancelled) && this.pendingChatRequestId !== null && cancelled.includes(this.pendingChatRequestId)) {
       this.pendingChatRequestId = null;
@@ -9303,4 +9336,4 @@ export {
   parseAskUserQuestion,
   formatAskUserAnswer
 };
-//# sourceMappingURL=chunk-CF6ROLBQ.js.map
+//# sourceMappingURL=chunk-ZKTKJZNT.js.map