@downcity/agent 1.1.21 → 1.1.23

package/src/types/sdk/AgentSessionTurn.ts

@@ -0,0 +1,65 @@
+/**
+ * Agent Session turn 句柄与结果类型定义。
+ *
+ * 关键点（中文）
+ * - `session.prompt()` 返回的是“已绑定到某个 turn”的句柄，而不是一次性文本结果。
+ * - 同一个 turn 可以吸收多条 prompt，因此多个 prompt 可能返回相同 `id` 的 turn handle。
+ * - 增量过程继续通过 `session.subscribe()` 观察；turn handle 只负责等待最终完成结果。
+ */
+
+/**
+ * 单个 Session turn 的最终结果。
+ */
+export interface AgentSessionTurnResult {
+  /**
+   * 当前已完成 turn 的稳定标识。
+   */
+  turnId: string;
+
+  /**
+   * 当前 turn 最终可见文本。
+   */
+  text: string;
+
+  /**
+   * 当前 turn 是否成功结束。
+   */
+  success: boolean;
+
+  /**
+   * 当前 turn 失败时的错误文本。
+   */
+  error?: string;
+}
+
+/**
+ * 单个 Session turn 的等待句柄。
+ */
+export interface AgentSessionTurnHandle {
+  /**
+   * 当前句柄绑定到的 turnId。
+   *
+   * 说明（中文）
+   * - `prompt()` 只有在确定当前输入被并入哪个 turn 后才会返回。
+   * - 因此这里总是最终可用的 turnId，而不是临时 receipt id。
+   */
+  id: string;
+
+  /**
+   * 当前 turn 已完成后的最终结果快照。
+   *
+   * 说明（中文）
+   * - 在 `finished` 兑现之前这里为 `null`。
+   * - 兑现之后会变成与 `finished` 相同的最终结果对象。
+   */
+  result: AgentSessionTurnResult | null;
+
+  /**
+   * 等待当前 turn 完成的 Promise。
+   *
+   * 关键点（中文）
+   * - 这里无论 turn 成功还是失败都会 resolve。
+   * - 调用方应读取返回结果中的 `success` / `error` 判断最终状态。
+   */
+  finished: Promise<AgentSessionTurnResult>;
+}

package/src/types/sdk/AgentUiChunkEvent.ts

@@ -0,0 +1,108 @@
+/**
+ * Agent UI chunk 事件类型定义。
+ *
+ * 关键点（中文）
+ * - 这是内部传输/映射层事件，不是 Session 的公开订阅事件。
+ * - 它用于把底层 AI SDK `UIMessageChunk` 归一化，再按不同宿主场景转成最终输出。
+ */
+
+import type { JsonValue } from "@/types/common/Json.js";
+
+/**
+ * 内部 UI chunk 事件。
+ */
+export type AgentUiChunkEvent =
+  | {
+      /**
+       * 文本增量事件。
+       */
+      type: "text-delta";
+      /**
+       * 当前追加的文本片段。
+       */
+      text: string;
+    }
+  | {
+      /**
+       * reasoning 增量事件。
+       */
+      type: "reasoning-delta";
+      /**
+       * 当前追加的 reasoning 文本片段。
+       */
+      text: string;
+    }
+  | {
+      /**
+       * 工具调用可用事件。
+       */
+      type: "tool-call";
+      /**
+       * 当前工具调用唯一标识。
+       */
+      toolCallId: string;
+      /**
+       * 工具名称。
+       */
+      toolName: string;
+      /**
+       * 工具输入参数。
+       */
+      args: JsonValue;
+    }
+  | {
+      /**
+       * 工具调用结果事件。
+       */
+      type: "tool-result";
+      /**
+       * 当前工具调用唯一标识。
+       */
+      toolCallId: string;
+      /**
+       * 工具名称。
+       */
+      toolName: string;
+      /**
+       * 工具输出结果。
+       */
+      result: JsonValue;
+    }
+  | {
+      /**
+       * 工具调用失败事件。
+       */
+      type: "tool-error";
+      /**
+       * 当前工具调用唯一标识。
+       */
+      toolCallId: string;
+      /**
+       * 工具名称。
+       */
+      toolName: string;
+      /**
+       * 错误文本。
+       */
+      error: string;
+    }
+  | {
+      /**
+       * 运行结束事件。
+       */
+      type: "finish";
+      /**
+       * 最终完成原因（若底层可提供）。
+       */
+      finishReason?: string;
+    }
+  | {
+      /**
+       * 运行错误事件。
+       */
+      type: "error";
+      /**
+       * 错误文本。
+       */
+      error: string;
+    };