@blade-hq/agent-client 2612.0.0-beta.5 → 2612.0.0-beta.7

package/README.md

@@ -12,6 +12,8 @@ Blade Agent 的框架无关客户端。浏览器和 Node.js 都能用；用 Vue
 npm install @blade-hq/agent-client
 ```
 
+TypeScript 消费者需要开发依赖 `@types/node`：底层 arktype 的声明使用 Node `buffer.File` 类型。若显式配置 `compilerOptions.types`，需包含 `node`；这是类型检查环境要求，浏览器运行时不因此依赖 Node。React 使用者还需对应版本的 `@types/react` / `@types/react-dom`。
+
 默认装到的是当前长期支持版（LTS），厂内离线交付按它开发。要跟两周一发的公网版本，改用 `@next`。
 
 最稳妥的做法是先读目标 Server 的 `GET /api/version`，按返回的版本号在 `package.json` 里钉死——NPM 的 `latest` 不一定和目标环境跑的版本一致。
@@ -709,7 +711,15 @@ chat.renderers = {
 - `session.send(text, { topicAssetRefs: [{ topic_id, path }] })` 为本条消息选择资产；省略时不继承上一条选择。服务端重新解析元数据，通过 Context 提供拉取指引，不自动读取正文。
 - `ChatMessage.topic_asset_refs` 是实时与历史一致的展示引用，不能当作访问许可。主题成员不会因此获得其他成员的会话读取权；任务的 `session_id` 只返回给该会话所有者。
 
-资产引用目前是专用字段，不依赖通用 `context_refs` 注册机制。知识库的 `kbIds` 选择行为保持不变。
+资产引用目前是专用字段，不依赖通用 `context_refs` 注册机制。
 
 
 主题类型：`ChatGroup`、`ChatGroupRole`、`ChatGroupMember`、`ChatGroupTask`、`CreateChatGroupTask`、`UpdateChatGroupTask`、`ChatGroupAsset`、`ChatGroupAssetList`、`TopicAssetRef`。`normalizeTopicAssetRefs` 仅规范化展示引用并去重，不代替服务端鉴权。
+
+### 插件条目选择
+
+`PluginRef` 保存 `{ provider: "plugin", plugin, server, id, label }`，`normalizePluginRefs(value)` 按插件、服务和条目 id 去重。label 只用于展示，条目权限和全文由服务端按当前账号重新读取。
+
+`session.send(text, { refs })` 选择本轮条目；不传 refs 继承上一轮选择，`refs: []` 清除，新的数组替换。AskUser 和暂停续跑沿用本轮冻结内容，下一条新消息才重新读取。流式消息和历史消息都保留 `message.refs`。
+
+`ToolEvidence` 是工具调用的原文快照类型。`ToolCallInfo.evidence` 保存引用编号、原文、插件包摘要及具体调用身份；历史查看直接使用该字段，插件停用或卸载后仍可核查当时内容。

package/dist/{chunk-Q337O3AM.js → chunk-E7J2JBML.js}

@@ -1,6 +1,6 @@
 // src/version.ts
 var SDK_NAME = "agent-client";
-var SDK_VERSION = true ? "2612.0.0-beta.5" : "1.1.1";
+var SDK_VERSION = true ? "2612.0.0-beta.7" : "1.1.1";
 
 // src/auth-login.ts
 function isAuthCallbackMessage(value) {
@@ -280,6 +280,19 @@ var LogCursor = class {
   }
 };
 
+// src/schemas/plugin-refs.ts
+function normalizePluginRefs(value) {
+  if (!Array.isArray(value)) return [];
+  const seen = /* @__PURE__ */ new Set();
+  return value.flatMap((item) => {
+    if (!item || typeof item !== "object" || item.provider !== "plugin" || ![item.plugin, item.server, item.id, item.label].every((part) => typeof part === "string" && part)) return [];
+    const key = JSON.stringify([item.plugin, item.server, item.id]);
+    if (seen.has(key)) return [];
+    seen.add(key);
+    return [{ provider: "plugin", plugin: item.plugin, server: item.server, id: item.id, label: item.label }];
+  });
+}
+
 // src/schemas/topic-assets.ts
 function normalizeTopicAssetRefs(value) {
   if (!Array.isArray(value)) return [];
@@ -828,6 +841,10 @@ function normalizeChildPause(pausePayload) {
   }
   return { pauseToolData, childLoopName, childToolCallId, description };
 }
+function attachToolEvidence(call, evidence) {
+  if (!call) return;
+  call.evidence = call.status === "done" && Array.isArray(evidence) ? evidence : void 0;
+}
 
 // src/schemas/message.ts
 function inferToolStatus(resultStr) {
@@ -1528,6 +1545,7 @@ var ClientProjectionBuilder = class {
   onUserMessage(_loopId, payload) {
     const entryId = String(payload.entry_id ?? this.nextTurnId("user"));
     const displayContent = payload.display_content ?? payload.content ?? "";
+    const refs = normalizePluginRefs(payload.refs);
     const turn = {
       id: entryId,
       sequence: this.nextSeq(),
@@ -1537,6 +1555,7 @@ var ClientProjectionBuilder = class {
       role: "user",
       status: "completed",
       blocks: [{ type: "text", content: displayContent }],
+      ...refs.length ? { refs } : {},
       topic_asset_refs: normalizeTopicAssetRefs(payload.topic_asset_refs),
       tool_calls: [],
       model: null,
@@ -1672,6 +1691,7 @@ var ClientProjectionBuilder = class {
     const sl = sourceLoopFor(state.loopId, this.loopDescriptions);
     const startedAt = typeof payload.started_at === "string" && payload.started_at ? payload.started_at : null;
     applyToolResult(state, toolCallId, content, status, durationMs, ranInParallel, sl, startedAt);
+    attachToolEvidence(state.toolCalls.find((call) => call.id === toolCallId), payload.evidence);
     const pendingChild = [...this.pendingChildPauses.values()].find(
       (pause) => pause.parentLoopName === loopId && pause.parentToolCallId === toolCallId
     );
@@ -2193,6 +2213,7 @@ function projectHistory(entries) {
         if (owner && toolCall) {
           toolCall.status = message._error ? "error" : inferToolStatus(String(message.content ?? ""));
           toolCall.result = message.content ?? "";
+          attachToolEvidence(toolCall, message._evidence);
           const duration = numberOrNull(message._duration_ms);
           if (duration !== null) toolCall.duration_ms = duration;
           if (typeof message._started_at === "string") {
@@ -2602,6 +2623,7 @@ var HeadlessResource = class {
     return this.runTracked(session_id, prompt, options, true);
   }
   async runTracked(sessionId, prompt, options, returnEnvelope) {
+    if ((options.refs?.length ?? 0) > 20) throw new HeadlessError("\u6BCF\u6761\u6D88\u606F\u6700\u591A\u9009\u62E9 20 \u4E2A\u63D2\u4EF6\u6761\u76EE");
     if ((options.topicAssetRefs?.length ?? 0) > 20) throw new HeadlessError("\u6BCF\u6761\u6D88\u606F\u6700\u591A\u5F15\u7528 20 \u4E2A\u4E3B\u9898\u8D44\u4EA7");
     const timeoutMs = options.timeoutMs ?? 3e5;
     const session_id = sessionId;
@@ -2829,6 +2851,7 @@ var HeadlessResource = class {
           headless: true,
           output_schema: options.schema ?? null,
           model: options.model ?? null,
+          refs: options.refs,
           topic_asset_refs: options.topicAssetRefs
         },
         (response) => {
@@ -3225,18 +3248,21 @@ var SessionsResource = class {
    *
    * Secrets are never returned: `write_only` lists the pointers that hold one.
    */
-  getSessionPluginConfig(sessionId, name, init) {
-    return this.client.jsonFromInit(`/api/sessions/${encodeURIComponent(sessionId)}/plugins/${encodeURIComponent(name)}/config`, init);
+  getSessionPluginConfig(sessionId, name, init, scope = "personal") {
+    return this.client.jsonFromInit(`/api/sessions/${encodeURIComponent(sessionId)}/plugins/${encodeURIComponent(name)}/config?scope=${scope}`, init);
   }
   /**
-   * Publish explicit set/remove operations to the user's keychain file.
+   * Save explicit set/remove operations to encrypted server storage.
    *
    * Fields absent from both lists keep their stored value, so a form never has
-   * to round-trip a secret. Rejections leave the previous file untouched; the
-   * call never restarts MCP servers.
+   * to round-trip a secret. Rejections preserve the previous values; the
+   * shared settings restart only the affected hosted plugin.
    */
-  updateSessionPluginConfig(sessionId, name, update, init) {
-    return this.client.jsonFromInit(`/api/sessions/${encodeURIComponent(sessionId)}/plugins/${encodeURIComponent(name)}/config`, { method: "PUT", body: JSON.stringify(update), ...init });
+  updateSessionPluginConfig(sessionId, name, update, init, scope = "personal") {
+    return this.client.jsonFromInit(`/api/sessions/${encodeURIComponent(sessionId)}/plugins/${encodeURIComponent(name)}/config?scope=${scope}`, { method: "PUT", body: JSON.stringify(update), ...init });
+  }
+  restartSessionPluginHost(sessionId, name) {
+    return this.client.jsonFromInit(`/api/sessions/${encodeURIComponent(sessionId)}/plugins/${encodeURIComponent(name)}/host`, { method: "POST" });
   }
   /** 创建新会话并直接连接，返回可收发消息的 AgentSession。 */
   async create(request = {}) {
@@ -4851,6 +4877,7 @@ function projectionToMessage(turn) {
     display_name: toolCall.display_name,
     arguments: toolCall.arguments,
     result: toolCall.result ?? void 0,
+    ...toolCall.evidence ? { evidence: toolCall.evidence } : {},
     pending_question_ref: toolCall.pending_question_ref ?? void 0,
     status: toolCall.status === "pending" || toolCall.status === "awaiting_answer" || toolCall.status === "done" || toolCall.status === "error" || toolCall.status === "cancelled" ? toolCall.status : "pending",
     ...typeof toolCall.duration_ms === "number" ? { duration_ms: toolCall.duration_ms } : {}
@@ -4870,6 +4897,7 @@ function projectionToMessage(turn) {
     ...typeof turn.duration_ms === "number" ? { duration_ms: turn.duration_ms } : {},
     ...turn.started_at ? { timestamp: turn.started_at } : {},
     ...turn.memory_refs?.length ? { memory_refs: turn.memory_refs } : {},
+    ...turn.refs?.length ? { refs: turn.refs } : {},
     ...turn.topic_asset_refs?.length ? { topic_asset_refs: turn.topic_asset_refs } : {}
   };
 }
@@ -5107,7 +5135,7 @@ function withQueue(state, snapshot2) {
   return { ...state, queue: snapshot2 };
 }
 var localTurnCounter = 0;
-function addUserMessage(state, content, clientRequestId, topicAssetRefs) {
+function addUserMessage(state, content, clientRequestId, topicAssetRefs, refs) {
   localTurnCounter += 1;
   const turnId = `local-user-${clientRequestId ?? `${Date.now()}-${localTurnCounter}`}`;
   const optimisticTurn = {
@@ -5118,6 +5146,7 @@ function addUserMessage(state, content, clientRequestId, topicAssetRefs) {
     // client_render_id（= 乐观 turn 自己的 turn_id）保持同一个值，
     // 消费方才能拿它当"确认前后不变"的稳定标识使用。
     client_render_id: turnId,
+    ...refs ? { refs } : {},
     ...topicAssetRefs?.length ? { topic_asset_refs: topicAssetRefs } : {},
     loop_id: "root",
     role: "user",
@@ -5367,7 +5396,7 @@ var AgentSession = class _AgentSession {
   bufferedCommandDeliveries = null;
   pendingReplayMessage = null;
   pendingReplayMode;
-  pendingReplayKbIds;
+  pendingReplayRefs;
   pendingReplayTopicAssetRefs;
   recentChatEndAt = 0;
   /**
@@ -5837,7 +5866,7 @@ var AgentSession = class _AgentSession {
     let optimisticAskAnswer;
     let previousAskAnswer;
     this.update((state) => {
-      const next = addUserMessage(state, content, clientRequestId, options.topicAssetRefs);
+      const next = addUserMessage(state, content, clientRequestId, options.topicAssetRefs, options.refs);
       optimisticTurnId = next.turns.at(-1)?.turn_id ?? null;
       return next;
     });
@@ -5855,7 +5884,7 @@ var AgentSession = class _AgentSession {
     if (!options.replayDecision) {
       this.pendingReplayMessage = content;
       this.pendingReplayMode = options.mode;
-      this.pendingReplayKbIds = options.kbIds;
+      this.pendingReplayRefs = options.refs;
       this.pendingReplayTopicAssetRefs = options.topicAssetRefs;
     }
     this.pendingChatRequestId = clientRequestId;
@@ -5871,7 +5900,7 @@ var AgentSession = class _AgentSession {
       whatif: options.whatif,
       replay_decision: options.replayDecision,
       app_context: appContext,
-      kb_ids: options.kbIds,
+      refs: options.refs,
       topic_asset_refs: options.topicAssetRefs,
       // 运行中提交不必由客户端挑命令：服务端按会话运行状态决定直接执行还是入队。
       queue_when_running: options.queueWhenRunning === true
@@ -5956,7 +5985,7 @@ var AgentSession = class _AgentSession {
     }
     this.pendingReplayMessage = null;
     this.pendingReplayMode = void 0;
-    this.pendingReplayKbIds = void 0;
+    this.pendingReplayRefs = void 0;
     this.pendingReplayTopicAssetRefs = void 0;
     this.update((current) => {
       const filtered = optimisticTurnId ? current.turns.filter((turn) => turn.turn_id !== optimisticTurnId) : current.turns;
@@ -6489,11 +6518,11 @@ var AgentSession = class _AgentSession {
   _handleReplayMismatch(data) {
     const message = this.pendingReplayMessage ?? data.actual_message ?? "";
     const mode = this.pendingReplayMode;
-    const kbIds = this.pendingReplayKbIds;
+    const refs = this.pendingReplayRefs;
     const topicAssetRefs = this.pendingReplayTopicAssetRefs;
     this.pendingReplayMessage = null;
     this.pendingReplayMode = void 0;
-    this.pendingReplayKbIds = void 0;
+    this.pendingReplayRefs = void 0;
     this.pendingReplayTopicAssetRefs = void 0;
     const respond = (decision) => {
       void this.runtime.emitWithAck(
@@ -6503,7 +6532,7 @@ var AgentSession = class _AgentSession {
           message,
           mode,
           replay_decision: decision,
-          kb_ids: kbIds,
+          refs,
           topic_asset_refs: topicAssetRefs
         },
         3e4
@@ -6780,6 +6809,7 @@ var AgentSession = class _AgentSession {
         display_name: toolCall.display_name,
         arguments: toolCall.arguments,
         result: toolCall.result ?? void 0,
+        ...toolCall.evidence ? { evidence: toolCall.evidence } : {},
         status: toolCall.status === "pending" || toolCall.status === "awaiting_answer" || toolCall.status === "done" || toolCall.status === "error" || toolCall.status === "cancelled" ? toolCall.status : "pending"
       };
       if (!this.seenToolCallIds.has(toolCall.id)) {
@@ -8084,6 +8114,7 @@ export {
   SDK_VERSION,
   BladeApiError,
   isRecord,
+  normalizePluginRefs,
   normalizeTopicAssetRefs,
   inferToolStatus,
   contextProjectionData,
@@ -8163,4 +8194,4 @@ export {
   createSocket,
   BladeClient
 };
-//# sourceMappingURL=chunk-Q337O3AM.js.map
+//# sourceMappingURL=chunk-E7J2JBML.js.map