@downcity/agent 1.1.217 → 1.1.224

package/src/types/runtime/agent/AgentContext.ts

@@ -29,10 +29,10 @@ import type { SessionHistoryStore } from "@/executor/store/history/SessionHistor
 import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
 import type { AgentSessionStopResult } from "@/types/sdk/AgentSessionStop.js";
 import type {
-  AgentSessionEvent,
-  AgentSessionSubscriber,
-  AgentSessionUnsubscribe,
-} from "@/types/sdk/AgentSessionEvent.js";
+  SessionMutationSubscriber,
+  SessionMutationUnsubscribe,
+} from "@/types/session/SessionMutation.js";
+import type { SessionApprovalRuntimeEvent } from "@/types/session/SessionApproval.js";
 import type { AgentSessionTurnHandle } from "@/types/sdk/AgentSessionTurn.js";
 
 /**
@@ -133,9 +133,11 @@ export interface SessionPort {
    *
    * 关键点（中文）
    * - 只广播订阅之后产生的事件。
-   * - session records 仍通过 `getHistoryStore()` / SDK `records()` 读取。
+   * - 当前 Message snapshot 通过公开 SDK `session.messages()` 读取。
    */
-  subscribe(subscriber: AgentSessionSubscriber): AgentSessionUnsubscribe;
+  subscribe(
+    subscriber: SessionMutationSubscriber,
+  ): SessionMutationUnsubscribe;
   /**
    * 发布一条 session runtime 事件。
    *
@@ -143,7 +145,7 @@ export interface SessionPort {
    * - plugin runtime 用它把审批、外部进度等非模型 chunk 事件推送给订阅方。
    * - 历史消息持久化仍由 append_user_message / append_assistant_message 负责。
    */
-  publishEvent(event: AgentSessionEvent): void;
+  publishEvent(event: SessionApprovalRuntimeEvent): Promise<void>;
   /**
    * 追加一条 user 消息。
    */

package/src/types/session/SessionApproval.ts

@@ -0,0 +1,108 @@
+/**
+ * Session 级工具审批类型。
+ *
+ * 审批由具体工具运行时执行，但归属、查询和决策能力统一通过 Session 暴露。
+ */
+
+/** Session 工具审批的最终人工决策。 */
+export type SessionApprovalDecision = "approved" | "denied";
+
+/** Session 工具审批模式。 */
+export type SessionApprovalMode = "ask" | "always-allow";
+
+/** 当前 Session 的待审批工具请求。 */
+export interface SessionApproval {
+  /** 当前审批请求的稳定唯一标识。 */
+  approval_id: string;
+  /** 当前审批所属 Session 标识。 */
+  session_id: string;
+  /** 当前审批所属 Turn 标识。 */
+  turn_id?: string;
+  /** 当前审批对应的工具调用标识。 */
+  tool_call_id?: string;
+  /** 当前审批对应的工具注册名称。 */
+  tool_name: string;
+  /** 请求执行的命令或输入文本。 */
+  command: string;
+  /** 当前工具执行工作目录。 */
+  cwd: string;
+  /** 工具申请 unrestricted 权限的原因。 */
+  reason: string;
+  /** 当前审批对应的工具操作类型。 */
+  operation: "exec" | "start" | "write";
+  /** 当前审批创建时间戳（ms）。 */
+  created_at: number;
+}
+
+/** 提交 Session 工具审批决策的参数。 */
+export interface ResolveSessionApprovalInput {
+  /** 需要处理的审批请求标识。 */
+  approval_id: string;
+  /** 对当前审批请求作出的最终决定。 */
+  decision: SessionApprovalDecision;
+}
+
+/** Session 工具审批决策结果。 */
+export interface SessionApprovalResult {
+  /** 是否成功命中并处理 pending 审批。 */
+  success: boolean;
+  /** 已尝试处理的审批请求标识。 */
+  approval_id: string;
+  /** 已提交的最终审批决定。 */
+  decision: SessionApprovalDecision;
+}
+
+/** 当前 Session 的审批模式快照。 */
+export interface SessionApprovalModeSnapshot {
+  /** 当前审批模式所属 Session 标识。 */
+  session_id: string;
+  /** 当前 Session 生效的审批模式。 */
+  mode: SessionApprovalMode;
+}
+
+/** 更新当前 Session 审批模式的参数。 */
+export interface SetSessionApprovalModeInput {
+  /** 需要设置的新审批模式。 */
+  mode: SessionApprovalMode;
+}
+
+/** Shell Runtime 发给 Session 的工具审批请求。 */
+export interface SessionToolApprovalRequest {
+  /** Runtime 事件类型固定为工具审批请求。 */
+  type: "tool-approval-request";
+  /** 当前审批所属 Turn 标识。 */
+  turn_id: string;
+  /** 当前审批对应的工具调用标识。 */
+  tool_call_id: string;
+  /** 当前审批对应的工具注册名称。 */
+  tool_name: string;
+  /** 当前审批请求的稳定唯一标识。 */
+  approval_id: string;
+  /** 请求执行的命令或输入文本。 */
+  command: string;
+  /** 当前工具执行工作目录。 */
+  cwd: string;
+  /** 工具申请 unrestricted 权限的原因。 */
+  reason: string;
+  /** 当前审批对应的工具操作类型。 */
+  operation: "exec" | "start" | "write";
+}
+
+/** Shell Runtime 发给 Session 的工具审批结果。 */
+export interface SessionToolApprovalResult {
+  /** Runtime 事件类型固定为工具审批结果。 */
+  type: "tool-approval-result";
+  /** 当前审批所属 Turn 标识。 */
+  turn_id: string;
+  /** 当前审批对应的工具调用标识。 */
+  tool_call_id: string;
+  /** 当前审批请求的稳定唯一标识。 */
+  approval_id: string;
+  /** 当前审批的最终结果，超时由 Runtime 标记为 expired。 */
+  decision: SessionApprovalDecision | "expired";
+}
+
+/** Session 内部接收的工具审批 Runtime 事件。 */
+export type SessionApprovalRuntimeEvent =
+  | SessionToolApprovalRequest
+  | SessionToolApprovalResult;

package/src/types/session/SessionMessage.ts

@@ -0,0 +1,253 @@
+/**
+ * Session canonical 消息类型。
+ *
+ * Session 只维护一条由 sequence 排序的消息序列；assistant 的 text、reasoning、tool、file
+ * 均为内部 part，不提升为顶层消息。
+ */
+
+import type { JsonObject, JsonValue } from "@/types/common/Json.js";
+
+/** Message 默认展示范围。 */
+export type SessionMessageVisibility = "visible" | "internal";
+
+/** 从其他 Session 导入时保留的来源身份。 */
+export interface SessionMessageOrigin {
+  /** 来源 Session 标识。 */
+  session_id: string;
+  /** 来源 Message 标识。 */
+  message_id: string;
+  /** 来源 turn 标识。 */
+  turn_id?: string;
+}
+
+/** Session Message 公共字段。 */
+export interface SessionMessageBase {
+  /** 当前 Message 在 Session 内的稳定唯一标识。 */
+  message_id: string;
+  /** 当前 Message 所属 Session 标识。 */
+  session_id: string;
+  /** 当前 Message 所属 turn；独立 action 可以省略。 */
+  turn_id?: string;
+  /** Message 的线性位置；创建后永远不变。 */
+  sequence: number;
+  /** Message 版本号；每次对外发布的消息变化后递增。 */
+  revision: number;
+  /** 当前 Message 是否默认对用户可见。 */
+  visibility: SessionMessageVisibility;
+  /** Message 首次创建时间戳（ms）。 */
+  created_at: number;
+  /** Message 最近更新时间戳（ms）。 */
+  updated_at: number;
+  /** 从其他 Session 导入时的来源信息。 */
+  origin?: SessionMessageOrigin;
+}
+
+/** User 文本 part。 */
+export interface SessionUserTextPart {
+  /** User Message 内稳定的 part 标识。 */
+  part_id: string;
+  /** part 类型固定为 text。 */
+  type: "text";
+  /** 用户输入文本。 */
+  text: string;
+  /** User 文本已经完整，不参与流式更新。 */
+  state: "done";
+}
+
+/** User 文件 part。 */
+export interface SessionUserFilePart {
+  /** User Message 内稳定的 part 标识。 */
+  part_id: string;
+  /** part 类型固定为 file。 */
+  type: "file";
+  /** 文件可读取地址或 data URL。 */
+  url: string;
+  /** 文件 MIME 类型。 */
+  media_type: string;
+  /** 可选原始文件名。 */
+  filename?: string;
+}
+
+/** User 结构化数据 part。 */
+export interface SessionUserDataPart {
+  /** User Message 内稳定的 part 标识。 */
+  part_id: string;
+  /** part 类型固定为 data。 */
+  type: "data";
+  /** 对应 AI SDK 的 data-* 类型名称。 */
+  data_type: `data-${string}` | string;
+  /** 可 JSON 序列化的数据。 */
+  data: JsonValue;
+}
+
+/** User Message part。 */
+export type SessionUserMessagePart =
+  | SessionUserTextPart
+  | SessionUserFilePart
+  | SessionUserDataPart;
+
+/** User 顶层 Message。 */
+export interface SessionUserMessage extends SessionMessageBase {
+  /** Message 类型固定为 user。 */
+  type: "user";
+  /** 普通 prompt 或当前 turn 中的 steering 输入。 */
+  input_type: "prompt" | "steer";
+  /** 用户消息的结构化 parts。 */
+  parts: SessionUserMessagePart[];
+}
+
+/** Assistant 文本或推理 part。 */
+export interface SessionAssistantTextPart {
+  /** Assistant Message 内稳定的 part 标识。 */
+  part_id: string;
+  /** Assistant Part 在当前 Message 中的不可变线性顺序，从 1 开始。 */
+  sequence: number;
+  /** part 是可见文本或推理文本。 */
+  type: "text" | "reasoning";
+  /** 当前已经累计的完整文本。 */
+  text: string;
+  /** 文本 part 是否已经结束。 */
+  state: "streaming" | "done";
+}
+
+/** Assistant 工具 part。 */
+export interface SessionAssistantToolPart {
+  /** Assistant Message 内稳定的 part 标识。 */
+  part_id: string;
+  /** Assistant Part 在当前 Message 中的不可变线性顺序，从 1 开始。 */
+  sequence: number;
+  /** part 类型固定为 tool。 */
+  type: "tool";
+  /** 模型工具调用稳定标识。 */
+  tool_call_id: string;
+  /** 工具注册名称。 */
+  tool_name: string;
+  /** 工具当前生命周期状态。 */
+  state: "input-streaming" | "ready" | "approval-required" | "running" | "completed" | "failed";
+  /** 流式接收中的参数原文。 */
+  input_text?: string;
+  /** 收敛后的结构化输入。 */
+  input?: JsonValue;
+  /** 工具成功输出。 */
+  output?: JsonValue;
+  /** 工具失败信息。 */
+  error?: string;
+  /** 工具审批请求标识。 */
+  approval_id?: string;
+}
+
+/** Assistant 文件 part。 */
+export interface SessionAssistantFilePart {
+  /** Assistant Message 内稳定的 part 标识。 */
+  part_id: string;
+  /** Assistant Part 在当前 Message 中的不可变线性顺序，从 1 开始。 */
+  sequence: number;
+  /** part 类型固定为 file。 */
+  type: "file";
+  /** 文件 MIME 类型。 */
+  media_type: string;
+  /** 文件可读取地址或 data URL。 */
+  url: string;
+  /** 可选原始文件名。 */
+  filename?: string;
+}
+
+/** Assistant 结构化数据 part。 */
+export interface SessionAssistantDataPart {
+  /** Assistant Message 内稳定的 part 标识。 */
+  part_id: string;
+  /** Assistant Part 在当前 Message 中的不可变线性顺序，从 1 开始。 */
+  sequence: number;
+  /** part 类型固定为 data。 */
+  type: "data";
+  /** 对应 AI SDK 的 data-* 类型名称。 */
+  data_type: `data-${string}` | string;
+  /** 可 JSON 序列化的数据。 */
+  data: JsonValue;
+}
+
+/** Assistant Message part。 */
+export type SessionAssistantMessagePart =
+  | SessionAssistantTextPart
+  | SessionAssistantToolPart
+  | SessionAssistantFilePart
+  | SessionAssistantDataPart;
+
+/** Assistant 顶层 Message。 */
+export interface SessionAssistantMessage extends SessionMessageBase {
+  /** Message 类型固定为 assistant。 */
+  type: "assistant";
+  /** 普通 assistant segment 或内部 compact summary。 */
+  kind: "normal" | "summary";
+  /** Assistant 在所属 turn 内的 segment 序号，从一开始。 */
+  segment_index: number;
+  /** Assistant 当前执行状态。 */
+  status: "streaming" | "completed" | "stopped" | "failed";
+  /** Assistant 内按真实生成顺序保存的 parts。 */
+  parts: SessionAssistantMessagePart[];
+  /** Summary 已覆盖到的来源 Message 标识。 */
+  summary_through_message_id?: string;
+}
+
+/** Action 顶层 Message。 */
+export interface SessionActionMessage extends SessionMessageBase {
+  /** Message 类型固定为 action。 */
+  type: "action";
+  /** Action 业务类型。 */
+  action_type: string;
+  /** Action 当前状态。 */
+  status: "running" | "completed" | "failed";
+  /** Action 展示标题。 */
+  title: string;
+  /** Action 展示描述。 */
+  description?: string;
+  /** Action 附加结构化信息。 */
+  data?: JsonObject;
+}
+
+/** Error 顶层 Message。 */
+export interface SessionErrorMessage extends SessionMessageBase {
+  /** Message 类型固定为 error。 */
+  type: "error";
+  /** 错误影响范围。 */
+  scope: "session" | "turn";
+  /** 稳定错误码。 */
+  code: string;
+  /** 用户可见错误信息。 */
+  message: string;
+  /** 当前错误是否允许重试恢复。 */
+  recoverable: boolean;
+}
+
+/** Session 唯一顶层 Message 联合类型。 */
+export type SessionMessage =
+  | SessionUserMessage
+  | SessionAssistantMessage
+  | SessionActionMessage
+  | SessionErrorMessage;
+
+/** 读取 Session Message snapshot 的分页输入。 */
+export interface ListSessionMessagesInput {
+  /** 单页数量上限。 */
+  limit?: number;
+  /** 上一页返回的透明游标。 */
+  cursor?: string;
+  /** 只返回 sequence 严格小于该值的 Message，供向前翻页。 */
+  before_sequence?: number;
+  /** 是否包含 internal Message。 */
+  include_internal?: boolean;
+  /** 只返回不大于该 sequence 的 Message。 */
+  through_sequence?: number;
+}
+
+/** Session Message snapshot 分页结果。 */
+export interface SessionMessagePage {
+  /** 当前页按 sequence 升序排列的 Message。 */
+  items: SessionMessage[];
+  /** 当前过滤条件下的 Message 总数。 */
+  total: number;
+  /** 下一页透明游标。 */
+  next_cursor?: string;
+  /** 是否仍有更多 Message。 */
+  has_more: boolean;
+}

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 覆盖项。
    */