@blade-hq/agent-client 2612.0.0-beta.19 → 2612.0.0-beta.20

package/README.md

@@ -111,6 +111,8 @@ const configured = await client.sessions.create({ intent: "数据分析", model:
 
 两者都返回 [`AgentSession`](#agentsession)。
 
+SDK 创建的会话默认归接入应用（`initiator: "sdk"`），运行事件仍由 SDK 交付，提醒展示和点击导航由接入应用自行处理，BA 内置 Web 不弹出这些会话的完成或等待回复提醒。内置 Web 创建入口显式使用 `initiator: "ui"`；此字段表示应用归属，与 headless 执行模式无关。
+
 ### 声明完整会话
 
 自定义 Solution、Skill 和模型无需手写上传步骤：
@@ -838,3 +840,23 @@ const delivery = await session.getDelivery(request.requestId)
 匿名客户端不能读取 owner-only `configuration`，详情不返回 `env`。持链接者可以在共享沙盒执行代码，因此显式提供的环境变量会对该会话参与者可见；不要用它保存创建者的私人凭据。第一版不支持匿名 `app-dev`（软件工厂），也不提供同源 HTML 应用展示；文件可以下载查看。
 
 匿名子客户端保留 `commandTransport`，并为匿名命令额外提供第四个可选参数 `{ anonymousSessionId }`。中间件应使用本次调用的 `send()` 保持匿名凭证，或按该范围使用专属通道；不能把命令转发到另一个账号连接。普通命令仍提供原来的三个参数。
+
+### 消息附加资料
+
+应用可通过 `SendOptions.contextAttachments` 或 `PreparedSendOptions.contextAttachments` 提供消息级资料。`ContextAttachment` 的 `id`、`label`、可读纯文本 `content` 与可选 `data`、`files` 都绑定到该条消息，完整资料通过 Context 提供给模型，正文保持原文。资料不是系统指令。
+
+```ts
+const request = session.prepareSend('任务已完成', {
+  mode: 'executing',
+  contextAttachments: [{
+    id: 'receipt-1', label: '市场周报', content: '状态：已完成\n已验证交付。',
+    data: { status: 'succeeded' },
+    files: [{ name: '周报.html', session_id: workerSessionId, path: '周报.html' }],
+  }],
+})
+// 在网络提交前持久化完整 request，重试时复用同一快照和 requestId。
+await persist(request)
+await session.sendPrepared(request)
+```
+
+每条消息最多 20 份资料，ID 不重复，每份正文最多 64000 个 Unicode 字符，整个资料 JSON 最多 256 KiB，超限拒绝。文件沿用指定会话的鉴权与路径解析，不接受外部 URL；仅有 `name` 的文件显示不可用。带资料的可靠消息作为独立一轮排队，不能走只传正文的「立即补充」。原生智能体目前不支持此通道。

package/dist/{chunk-XKAHFAEI.js → chunk-2VIJBVAC.js}

@@ -213,7 +213,7 @@ var ToolProvider = class {
 
 // src/version.ts
 var SDK_NAME = "agent-client";
-var SDK_VERSION = true ? "2612.0.0-beta.19" : "1.1.1";
+var SDK_VERSION = true ? "2612.0.0-beta.20" : "1.1.1";
 
 // src/auth-login.ts
 function isAuthCallbackMessage(value) {
@@ -445,6 +445,30 @@ var LogCursor = class {
   }
 };
 
+// src/schemas/context-attachments.ts
+function snapshotContextAttachments(value) {
+  const snapshot2 = JSON.parse(JSON.stringify(value));
+  if (!Array.isArray(snapshot2) || snapshot2.length > 20) throw new Error("\u6BCF\u6761\u6D88\u606F\u6700\u591A\u63D0\u4F9B 20 \u4EFD\u8D44\u6599");
+  const ids = /* @__PURE__ */ new Set();
+  const validText = (text, limit) => typeof text === "string" && [...text].length > 0 && [...text].length <= limit;
+  for (const item of snapshot2) {
+    if (!item || !validText(item.id, 128) || !validText(item.label, 512) || !validText(item.content, 64e3) || ids.has(item.id)) throw new Error("\u9644\u52A0\u8D44\u6599\u683C\u5F0F\u9519\u8BEF\u6216 ID \u91CD\u590D");
+    ids.add(item.id);
+    if (item.data != null && (typeof item.data !== "object" || Array.isArray(item.data))) throw new Error("\u8D44\u6599\u6570\u636E\u5FC5\u987B\u662F JSON \u5BF9\u8C61");
+    if (item.files != null && (!Array.isArray(item.files) || item.files.length > 20)) throw new Error("\u8D44\u6599\u6587\u4EF6\u683C\u5F0F\u9519\u8BEF");
+    for (const file of item.files ?? []) {
+      if (!validText(file.name, 512)) throw new Error("\u8D44\u6599\u6587\u4EF6\u540D\u683C\u5F0F\u9519\u8BEF");
+      if (file.session_id == null && file.path == null) continue;
+      if (!validText(file.session_id, 128) || !validText(file.path, 2048) || /[\\:]/.test(file.path) || file.path.replace(/^\//, "").split("/").some((part) => !part || part === "." || part === "..")) throw new Error("\u8D44\u6599\u6587\u4EF6\u5FC5\u987B\u4F7F\u7528\u6709\u6548\u7684\u4F1A\u8BDD\u6587\u4EF6\u8DEF\u5F84");
+    }
+  }
+  if (new TextEncoder().encode(JSON.stringify(snapshot2)).length > 256 * 1024) throw new Error("\u6D88\u606F\u9644\u52A0\u8D44\u6599\u4E0D\u80FD\u8D85\u8FC7 256 KiB");
+  return snapshot2;
+}
+function normalizeContextAttachments(value) {
+  return Array.isArray(value) ? value : [];
+}
+
 // src/schemas/plugin-refs.ts
 function normalizePluginRefs(value) {
   if (!Array.isArray(value)) return [];
@@ -1734,6 +1758,7 @@ var ClientProjectionBuilder = class {
       status: "completed",
       blocks: [{ type: "text", content: displayContent }],
       ...refs.length ? { refs } : {},
+      context_attachments: normalizeContextAttachments(payload.context_attachments),
       topic_asset_refs: normalizeTopicAssetRefs(payload.topic_asset_refs),
       tool_calls: [],
       model: null,
@@ -2439,6 +2464,7 @@ function projectHistory(entries) {
       if (role === "user") {
         const refs = normalizeMessageRefs(message.refs);
         if (refs.length) turn.refs = refs;
+        turn.context_attachments = normalizeContextAttachments(message.context_attachments);
       }
       const isNativeToolEntry = role === "assistant" && Array.isArray(message.tool_calls) && message.tool_calls.some(
         (toolCall) => isRecord(toolCall) && typeof toolCall.provider === "string"
@@ -3344,6 +3370,7 @@ function toCreateSessionPayload(request) {
   const solutionRef = request.solution_ref ?? externalSolutionRef(request.solution_id);
   return {
     intent: request.intent ?? "",
+    initiator: request.initiator ?? "sdk",
     anonymous: request.anonymous,
     solution_id: solutionRef ? void 0 : request.solution_id,
     solution_ref: solutionRef,
@@ -5154,6 +5181,7 @@ function projectionToMessage(turn) {
     ...turn.started_at ? { timestamp: turn.started_at } : {},
     ...turn.memory_refs?.length ? { memory_refs: turn.memory_refs } : {},
     ...turn.refs?.length ? { refs: turn.refs } : {},
+    ...turn.context_attachments?.length ? { context_attachments: turn.context_attachments } : {},
     ...turn.topic_asset_refs?.length ? { topic_asset_refs: turn.topic_asset_refs } : {}
   };
 }
@@ -5391,7 +5419,7 @@ function withQueue(state, snapshot2) {
   return { ...state, queue: snapshot2 };
 }
 var localTurnCounter = 0;
-function addUserMessage(state, content, clientRequestId, topicAssetRefs, refs) {
+function addUserMessage(state, content, clientRequestId, topicAssetRefs, refs, contextAttachments) {
   localTurnCounter += 1;
   const turnId = `local-user-${clientRequestId ?? `${Date.now()}-${localTurnCounter}`}`;
   const optimisticTurn = {
@@ -5403,6 +5431,7 @@ function addUserMessage(state, content, clientRequestId, topicAssetRefs, refs) {
     // 消费方才能拿它当"确认前后不变"的稳定标识使用。
     client_render_id: turnId,
     ...refs ? { refs } : {},
+    ...contextAttachments?.length ? { context_attachments: contextAttachments } : {},
     ...topicAssetRefs?.length ? { topic_asset_refs: topicAssetRefs } : {},
     loop_id: "root",
     role: "user",
@@ -5652,6 +5681,8 @@ var AgentSession = class _AgentSession {
   bufferedCommandDeliveries = null;
   pendingReplayMessage = null;
   pendingReplayMode;
+  pendingReplayRequestId;
+  pendingReplayAttachments;
   pendingReplayRefs;
   pendingReplayTopicAssetRefs;
   recentChatEndAt = 0;
@@ -5956,10 +5987,12 @@ var AgentSession = class _AgentSession {
   /** Prepare a durable text input without sending any network request. */
   prepareSend(content, options = {}) {
     if (!content.trim()) throw new Error("\u6D88\u606F\u4E0D\u80FD\u4E3A\u7A7A");
-    if (Object.keys(options).some((key) => !["mode", "model", "thinkingOverride", "reasoningLevel"].includes(key))) {
+    if (Object.keys(options).some((key) => !["mode", "model", "thinkingOverride", "reasoningLevel", "contextAttachments"].includes(key))) {
       throw new Error("\u53EF\u9760\u6587\u672C\u53D1\u9001\u4E0D\u652F\u6301\u8FD9\u4E9B\u53C2\u6570\uFF0C\u8BF7\u4F7F\u7528 send()");
     }
-    return { sessionId: this.sessionId, requestId: createClientRequestId(), content, options: JSON.parse(JSON.stringify(options)) };
+    const snapshot2 = JSON.parse(JSON.stringify(options));
+    if (snapshot2.contextAttachments) snapshot2.contextAttachments = snapshotContextAttachments(snapshot2.contextAttachments);
+    return { sessionId: this.sessionId, requestId: createClientRequestId(), content, options: snapshot2 };
   }
   /** Durably enqueue an ordinary text input. Retries must reuse the saved request. */
   async sendPrepared(request) {
@@ -5974,7 +6007,8 @@ var AgentSession = class _AgentSession {
           mode: request.options.mode,
           model: request.options.model,
           thinking_override: request.options.thinkingOverride,
-          reasoning_level: request.options.reasoningLevel
+          reasoning_level: request.options.reasoningLevel,
+          ...request.options.contextAttachments ? { context_attachments: request.options.contextAttachments } : {}
         }
       }, QUEUE_ACK_TIMEOUT_MS);
       const result = parseQueueAck(response, this.sessionId);
@@ -6151,6 +6185,7 @@ var AgentSession = class _AgentSession {
     }
   }
   async sendUnlocked(content, options) {
+    const contextAttachments = options.contextAttachments ? snapshotContextAttachments(options.contextAttachments) : void 0;
     await this.ensureIdleBeforeSend();
     if (this.state.isStreaming && options.queueWhenRunning !== true || this.state.activeCompaction || this.manualCompactionRequest) {
       this.update(
@@ -6187,7 +6222,7 @@ var AgentSession = class _AgentSession {
     let optimisticAskAnswer;
     let previousAskAnswer;
     this.update((state) => {
-      const next = addUserMessage(state, content, clientRequestId, options.topicAssetRefs, options.refs);
+      const next = addUserMessage(state, content, clientRequestId, options.topicAssetRefs, options.refs, contextAttachments);
       optimisticTurnId = next.turns.at(-1)?.turn_id ?? null;
       return next;
     });
@@ -6205,6 +6240,8 @@ var AgentSession = class _AgentSession {
     if (!options.replayDecision) {
       this.pendingReplayMessage = content;
       this.pendingReplayMode = options.mode;
+      this.pendingReplayRequestId = clientRequestId;
+      this.pendingReplayAttachments = contextAttachments;
       this.pendingReplayRefs = options.refs;
       this.pendingReplayTopicAssetRefs = options.topicAssetRefs;
     }
@@ -6221,6 +6258,7 @@ var AgentSession = class _AgentSession {
       whatif: options.whatif,
       replay_decision: options.replayDecision,
       app_context: appContext,
+      context_attachments: contextAttachments,
       refs: options.refs,
       topic_asset_refs: options.topicAssetRefs,
       // 运行中提交不必由客户端挑命令：服务端按会话运行状态决定直接执行还是入队。
@@ -6306,6 +6344,8 @@ var AgentSession = class _AgentSession {
     }
     this.pendingReplayMessage = null;
     this.pendingReplayMode = void 0;
+    this.pendingReplayRequestId = void 0;
+    this.pendingReplayAttachments = void 0;
     this.pendingReplayRefs = void 0;
     this.pendingReplayTopicAssetRefs = void 0;
     this.update((current) => {
@@ -6838,10 +6878,14 @@ var AgentSession = class _AgentSession {
   _handleReplayMismatch(data) {
     const message = this.pendingReplayMessage ?? data.actual_message ?? "";
     const mode = this.pendingReplayMode;
+    const requestId = this.pendingReplayRequestId ?? createClientRequestId();
+    const contextAttachments = this.pendingReplayAttachments;
     const refs = this.pendingReplayRefs;
     const topicAssetRefs = this.pendingReplayTopicAssetRefs;
     this.pendingReplayMessage = null;
     this.pendingReplayMode = void 0;
+    this.pendingReplayRequestId = void 0;
+    this.pendingReplayAttachments = void 0;
     this.pendingReplayRefs = void 0;
     this.pendingReplayTopicAssetRefs = void 0;
     const respond = (decision) => {
@@ -6852,8 +6896,10 @@ var AgentSession = class _AgentSession {
           message,
           mode,
           replay_decision: decision,
+          client_request_id: requestId,
           refs,
-          topic_asset_refs: topicAssetRefs
+          topic_asset_refs: topicAssetRefs,
+          context_attachments: contextAttachments
         },
         3e4
       ).then((response) => {
@@ -8554,4 +8600,4 @@ export {
   createSocket,
   BladeClient
 };
-//# sourceMappingURL=chunk-XKAHFAEI.js.map
+//# sourceMappingURL=chunk-2VIJBVAC.js.map