@downcity/agent 1.1.222 → 1.1.226

package/src/types/session/SessionMessage.ts

@@ -30,7 +30,7 @@ export interface SessionMessageBase {
   turn_id?: string;
   /** Message 的线性位置；创建后永远不变。 */
   sequence: number;
-  /** Message 版本号；每次 Mutation 后递增。 */
+  /** Message 版本号；每次对外发布的消息变化后递增。 */
   revision: number;
   /** 当前 Message 是否默认对用户可见。 */
   visibility: SessionMessageVisibility;
@@ -100,6 +100,8 @@ export interface SessionUserMessage extends SessionMessageBase {
 export interface SessionAssistantTextPart {
   /** Assistant Message 内稳定的 part 标识。 */
   part_id: string;
+  /** Assistant Part 在当前 Message 中的不可变线性顺序，从 1 开始。 */
+  sequence: number;
   /** part 是可见文本或推理文本。 */
   type: "text" | "reasoning";
   /** 当前已经累计的完整文本。 */
@@ -112,6 +114,8 @@ export interface SessionAssistantTextPart {
 export interface SessionAssistantToolPart {
   /** Assistant Message 内稳定的 part 标识。 */
   part_id: string;
+  /** Assistant Part 在当前 Message 中的不可变线性顺序，从 1 开始。 */
+  sequence: number;
   /** part 类型固定为 tool。 */
   type: "tool";
   /** 模型工具调用稳定标识。 */
@@ -119,7 +123,7 @@ export interface SessionAssistantToolPart {
   /** 工具注册名称。 */
   tool_name: string;
   /** 工具当前生命周期状态。 */
-  state: "input-streaming" | "approval-required" | "running" | "completed" | "failed";
+  state: "input-streaming" | "ready" | "approval-required" | "running" | "completed" | "failed";
   /** 流式接收中的参数原文。 */
   input_text?: string;
   /** 收敛后的结构化输入。 */
@@ -136,6 +140,8 @@ export interface SessionAssistantToolPart {
 export interface SessionAssistantFilePart {
   /** Assistant Message 内稳定的 part 标识。 */
   part_id: string;
+  /** Assistant Part 在当前 Message 中的不可变线性顺序，从 1 开始。 */
+  sequence: number;
   /** part 类型固定为 file。 */
   type: "file";
   /** 文件 MIME 类型。 */
@@ -150,6 +156,8 @@ export interface SessionAssistantFilePart {
 export interface SessionAssistantDataPart {
   /** Assistant Message 内稳定的 part 标识。 */
   part_id: string;
+  /** Assistant Part 在当前 Message 中的不可变线性顺序，从 1 开始。 */
+  sequence: number;
   /** part 类型固定为 data。 */
   type: "data";
   /** 对应 AI SDK 的 data-* 类型名称。 */
@@ -242,6 +250,4 @@ export interface SessionMessagePage {
   next_cursor?: string;
   /** 是否仍有更多 Message。 */
   has_more: boolean;
-  /** 当前 snapshot 已包含的最大 commit_sequence。 */
-  latest_commit_sequence: number;
 }

package/src/types/session/SessionMutation.ts

@@ -0,0 +1,141 @@
+/**
+ * Session 的统一实时 Mutation 协议。
+ *
+ * Mutation 描述订阅之后发生的状态变化，不等同于 messages.jsonl 持久化格式。
+ */
+
+import type { SessionAssistantMessagePart, SessionMessage } from "@/types/session/SessionMessage.js";
+import type { ResolveSessionApprovalInput, SessionApprovalResult } from "@/types/session/SessionApproval.js";
+
+/** 所有 Session Mutation 的公共字段。 */
+export interface SessionMutationBase {
+  /** 当前 Mutation 的稳定唯一标识。 */
+  mutation_id: string;
+  /** 当前 Mutation 所属 Session 标识。 */
+  session_id: string;
+  /** 当前 Mutation 创建时间戳（ms）。 */
+  created_at: number;
+}
+/** Message 创建或完整快照更新 Mutation。 */
+export type SessionMessageMutation = {
+  [TType in SessionMessage["type"]]: SessionMutationBase & {
+    /** Mutation 层级固定为 message。 */
+    variant: "message";
+    /** 当前完整 Message 类型。 */
+    type: TType;
+    /** 当前 Mutation 目标 Message 标识。 */
+    message_id: string;
+    /** 当前 Mutation 所属 Turn 标识。 */
+    turn_id?: string;
+    /** 当前 Message 在线性 Session 中的不可变顺序。 */
+    sequence: number;
+    /** 应用当前 Mutation 后的 Message revision。 */
+    revision: number;
+    /** 创建或更新后的完整 Message 快照。 */
+    message: Extract<SessionMessage, { type: TType }>;
+  };
+}[SessionMessage["type"]];
+
+/** Assistant Part 创建或完整快照更新 Mutation。 */
+export type SessionPartMutation = {
+  [TType in SessionAssistantMessagePart["type"]]: SessionMutationBase & {
+    /** Mutation 层级固定为 part。 */
+    variant: "part";
+    /** 当前完整 Part 类型。 */
+    type: TType;
+    /** 当前 Part 所属 Message 标识。 */
+    message_id: string;
+    /** 当前 Mutation 所属 Turn 标识。 */
+    turn_id?: string;
+    /** 应用当前 Mutation 后的 Message revision。 */
+    revision: number;
+    /** 当前被创建或更新的 Part 标识。 */
+    part_id: string;
+    /** 创建或更新后的完整 Part 快照。 */
+    part: SessionAssistantMessagePart & { type: TType };
+  };
+}[SessionAssistantMessagePart["type"]];
+
+/** Assistant 文本或推理的原始增量 Mutation。 */
+export interface SessionDeltaMutation extends SessionMutationBase {
+  /** Mutation 层级固定为 delta。 */
+  variant: "delta";
+  /** Delta 只允许可见文本或推理文本。 */
+  type: "text" | "reasoning";
+  /** 当前 Delta 所属 Message 标识。 */
+  message_id: string;
+  /** 当前 Mutation 所属 Turn 标识。 */
+  turn_id?: string;
+  /** 应用当前 Mutation 后的 Message revision。 */
+  revision: number;
+  /** 当前 Delta 所属 Part 标识。 */
+  part_id: string;
+  /** 本次新增的原始文本，不是累计全文。 */
+  delta: string;
+}
+
+/** Turn 生命周期 Mutation。 */
+export type SessionTurnMutation = SessionMutationBase & {
+  /** Mutation 层级固定为 turn。 */
+  variant: "turn";
+  /** 当前 Turn 是开始还是完成。 */
+  type: "start" | "finish";
+  /** 当前 Turn 的稳定唯一标识。 */
+  turn_id: string;
+  /** 当前 Turn 的执行状态。 */
+  status: "running" | "completed" | "failed" | "stopped";
+  /** Turn 完成时的最终可见文本。 */
+  text?: string;
+  /** Turn 失败或停止时的错误文本。 */
+  error?: string;
+};
+
+/** Session 自身属性变化 Mutation。 */
+export type SessionStateMutation = SessionMutationBase & {
+  /** Mutation 层级固定为 session。 */
+  variant: "session";
+  /** 当前 Session 属性变化类型。 */
+  type: "title";
+  /** 当前 Session 最新标题。 */
+  title: string;
+};
+
+/** Session 对外唯一实时 Mutation 联合类型。 */
+export type SessionMutation =
+  | SessionMessageMutation
+  | SessionPartMutation
+  | SessionDeltaMutation
+  | SessionTurnMutation
+  | SessionStateMutation;
+
+/** 当前 Mutation 可用的命令回复入口。 */
+export interface SessionMutationReply {
+  /**
+   * 回复当前 Tool Part 的审批请求。
+   * 只有 approval-required Tool Part Mutation 可以成功调用。
+   */
+  approval(input: Pick<ResolveSessionApprovalInput, "decision">): Promise<SessionApprovalResult>;
+}
+
+/** Session Mutation 订阅回调。 */
+export type SessionMutationSubscriber = (
+  mutation: SessionMutation,
+  reply: SessionMutationReply,
+) => void | Promise<void>;
+
+/** 取消 Session Mutation 订阅的函数。 */
+export type SessionMutationUnsubscribe = () => void;
+
+/** 判断未知事件是否为 Session Mutation。 */
+export function is_session_mutation(input: unknown): input is SessionMutation {
+  if (!input || typeof input !== "object") return false;
+  const candidate = input as { mutation_id?: unknown; variant?: unknown; type?: unknown };
+  if (typeof candidate.mutation_id !== "string" || typeof candidate.type !== "string") return false;
+  return (
+    candidate.variant === "message" ||
+    candidate.variant === "part" ||
+    candidate.variant === "delta" ||
+    candidate.variant === "turn" ||
+    candidate.variant === "session"
+  );
+}

package/src/types/session/SessionOptions.ts

@@ -14,6 +14,13 @@ import type { AgentSessionSystemBlock } from "@/types/agent/SessionTypes.js";
 import type { SessionComposerOptions } from "@/types/session/SessionComposerOptions.js";
 import type { Logger } from "@/utils/logger/Logger.js";
 import type { AgentModel } from "@/model/CityModelAdapter.js";
+import type {
+  ResolveSessionApprovalInput,
+  SessionApproval,
+  SessionApprovalModeSnapshot,
+  SessionApprovalResult,
+  SetSessionApprovalModeInput,
+} from "@/types/session/SessionApproval.js";
 
 /**
  * Agent 可管理的本地 Session 实例。
@@ -87,6 +94,24 @@ export interface SessionOptions {
   /** 按稳定模型 ID 解析当前 Session 的运行时模型。 */
   resolve_model?: (model_id: string) => Promise<AgentModel>;
 
+  /** 列出当前 Session 的 pending 工具审批。 */
+  list_approvals: (session_id: string) => Promise<SessionApproval[]>;
+
+  /** 读取当前 Session 的工具审批模式。 */
+  get_approval_mode: (session_id: string) => Promise<SessionApprovalModeSnapshot>;
+
+  /** 更新当前 Session 的工具审批模式。 */
+  set_approval_mode: (
+    session_id: string,
+    input: SetSessionApprovalModeInput,
+  ) => Promise<SessionApprovalModeSnapshot>;
+
+  /** 处理当前 Session 的 pending 工具审批。 */
+  resolve_approval: (
+    session_id: string,
+    input: ResolveSessionApprovalInput,
+  ) => Promise<SessionApprovalResult>;
+
   /**
    * 当前 session 的 Composer 覆盖项。
    */