@downcity/agent 1.1.237 → 1.1.258

package/src/session/approval/SessionApprovalBroker.ts

@@ -0,0 +1,164 @@
+/**
+ * Session 级 Tool 审批 Broker。
+ *
+ * 关键点（中文）
+ * - pending approval、审批模式、超时与用户决定只归当前 Session 所有。
+ * - Shell 通过强类型 Gateway 等待结果，不保存或反向发布 Session 状态。
+ */
+
+import { generateId } from "@/utils/Id.js";
+import type {
+  ShellApprovalGateway,
+  ShellApprovalHandle,
+  ShellApprovalRequest,
+  ShellApprovalStatus,
+} from "@downcity/shell";
+import type {
+  SessionApproval,
+  SessionApprovalDecision,
+  SessionApprovalMode,
+  SessionApprovalModeSnapshot,
+  SessionApprovalResult,
+} from "@/types/session/SessionApproval.js";
+import type { SessionPendingApproval } from "@/types/session/SessionApprovalBroker.js";
+import type { SessionMessages } from "@/session/SessionMessages.js";
+
+/** 单个 Session 的审批状态与决定入口。 */
+export class SessionApprovalBroker implements ShellApprovalGateway {
+  private readonly session_id: string;
+  private readonly messages: SessionMessages;
+  private readonly pending_by_id = new Map<string, SessionPendingApproval>();
+  private mode: SessionApprovalMode = "ask";
+
+  /**
+   * @param options Broker 所属 Session 与 Tool Runtime。
+   */
+  constructor(options: {
+    /** 当前 Broker 所属 Session。 */
+    session_id: string;
+    /** 当前 Session 的 Message 领域入口。 */
+    messages: SessionMessages;
+  }) {
+    this.session_id = options.session_id;
+    this.messages = options.messages;
+  }
+
+  /** Shell 调用的强类型审批网关入口。 */
+  async request(input: ShellApprovalRequest): Promise<ShellApprovalHandle> {
+    if (input.session_id !== this.session_id) {
+      throw new Error(`Approval Session mismatch: ${input.session_id}`);
+    }
+    const approval_id = `ap_${generateId()}`;
+    if (this.mode === "always-allow") {
+      return {
+        approval_id,
+        requires_user_decision: false,
+        decision: Promise.resolve("approved"),
+      };
+    }
+
+    const created_at = Date.now();
+    const approval: SessionApproval = {
+      approval_id,
+      session_id: this.session_id,
+      turn_id: input.turn_id,
+      tool_call_id: input.tool_call_id,
+      tool_name: input.tool_name,
+      command: input.command,
+      cwd: input.cwd,
+      reason: input.reason,
+      operation: input.operation,
+      created_at,
+      expires_at: created_at + input.timeout_ms,
+    };
+    let resolve_decision!: (decision: ShellApprovalStatus) => void;
+    const decision = new Promise<ShellApprovalStatus>((resolve) => {
+      resolve_decision = resolve;
+    });
+    const timer = setTimeout(() => {
+      void this.expire(approval_id);
+    }, input.timeout_ms);
+    if (typeof timer.unref === "function") timer.unref();
+    this.pending_by_id.set(approval_id, {
+      approval,
+      resolve: resolve_decision,
+      timer,
+    });
+
+    try {
+      await this.messages.request_tool_approval(approval);
+    } catch (error) {
+      clearTimeout(timer);
+      this.pending_by_id.delete(approval_id);
+      resolve_decision("denied");
+      throw error;
+    }
+    return {
+      approval_id,
+      requires_user_decision: true,
+      decision,
+    };
+  }
+
+  /** 返回当前 Session 的全部 pending approval 快照。 */
+  list(): SessionApproval[] {
+    return [...this.pending_by_id.values()].map((item) => structuredClone(item.approval));
+  }
+
+  /** 返回当前 Session 的审批模式。 */
+  get_mode(): SessionApprovalModeSnapshot {
+    return { session_id: this.session_id, mode: this.mode };
+  }
+
+  /** 更新当前 Session 的审批模式。 */
+  set_mode(mode: SessionApprovalMode): SessionApprovalModeSnapshot {
+    this.mode = mode === "always-allow" ? "always-allow" : "ask";
+    return this.get_mode();
+  }
+
+  /** 处理用户提交的审批决定。 */
+  async resolve(input: {
+    /** 当前审批请求标识。 */
+    approval_id: string;
+    /** 用户提交的审批决定。 */
+    decision: SessionApprovalDecision;
+  }): Promise<SessionApprovalResult> {
+    const success = await this.settle(input.approval_id, input.decision, false);
+    return { success, approval_id: input.approval_id, decision: input.decision };
+  }
+
+  /** 让当前 Session 的全部 pending 请求过期，用于停止或销毁执行。 */
+  async expire_all(): Promise<void> {
+    await Promise.all([...this.pending_by_id.keys()].map((approval_id) =>
+      this.settle(approval_id, "expired", true)
+    ));
+  }
+
+  /** 处理单个自动过期请求。 */
+  private async expire(approval_id: string): Promise<void> {
+    await this.settle(approval_id, "expired", true);
+  }
+
+  /** 先提交 Tool 状态，再兑现 Shell 等待 Promise，保证执行顺序稳定。 */
+  private async settle(
+    approval_id: string,
+    decision: ShellApprovalStatus,
+    force: boolean,
+  ): Promise<boolean> {
+    const pending = this.pending_by_id.get(approval_id);
+    if (!pending) return false;
+    try {
+      await this.messages.resolve_tool_approval({
+        approval_id,
+        decision,
+        tool_call_id: pending.approval.tool_call_id,
+      });
+    } catch (error) {
+      if (!force) throw error;
+    }
+    clearTimeout(pending.timer);
+    this.pending_by_id.delete(approval_id);
+    pending.resolve(decision);
+    return true;
+  }
+}

package/src/session/browse/Browse.ts

@@ -45,7 +45,7 @@ import { getSdkAgentArchivedSessionsDirPath } from "@/session/storage/Paths.js";
 import { getSdkAgentArchivedSessionMessagesPath } from "@/session/storage/Paths.js";
 import { getSdkAgentArchivedSessionMetaPath } from "@/session/storage/Paths.js";
 import { readSessionMetadataFromPath } from "@/session/storage/Metadata.js";
-import { to_executor_ui_message } from "@/session/recorder/SessionMessageCodec.js";
+import { to_executor_ui_message } from "@/session/messages/SessionMessageCodec.js";
 import type { SessionMessage } from "@/types/session/SessionMessage.js";
 
 type AnyUiPart = UIMessagePart<Record<string, never>, Record<string, never>>;
@@ -432,7 +432,6 @@ export function buildSessionInfo(
     ...(input.metadata.modelLabel
       ? { modelLabel: input.metadata.modelLabel }
       : {}),
-    ...(input.metadata.modelId ? { modelId: input.metadata.modelId } : {}),
     ...(typeof input.metadata.timezone === "string" && input.metadata.timezone.trim()
       ? { timezone: input.metadata.timezone.trim() }
       : {}),
@@ -666,7 +665,6 @@ export async function listAgentSessionSummaryPage(params: {
       ...(typeof info.createdAt === "number" ? { createdAt: info.createdAt } : {}),
       ...(typeof info.updatedAt === "number" ? { updatedAt: info.updatedAt } : {}),
       ...(info.modelLabel ? { modelLabel: info.modelLabel } : {}),
-      ...(info.modelId ? { modelId: info.modelId } : {}),
       ...(info.executing ? { executing: true } : {}),
     };
 
@@ -767,7 +765,6 @@ export async function listArchivedAgentSessionSummaryPage(params: {
       ...(typeof info.createdAt === "number" ? { createdAt: info.createdAt } : {}),
       ...(typeof info.updatedAt === "number" ? { updatedAt: info.updatedAt } : {}),
       ...(info.modelLabel ? { modelLabel: info.modelLabel } : {}),
-      ...(info.modelId ? { modelId: info.modelId } : {}),
     };
 
     if (query) {

package/src/session/messages/SessionAssistantMessageWriter.ts

@@ -0,0 +1,345 @@
+/**
+ * 单个 Assistant Message 的流式写入器。
+ *
+ * Writer 把 AI SDK chunk、Executor Tool 输入屏障和最终关闭操作收口到同一条
+ * 单写者队列，保证并发回调不会产生 revision 冲突。
+ */
+
+import type { UIMessageChunk } from "ai";
+import type { SessionMessages } from "@/session/SessionMessages.js";
+import { to_session_json_value } from "@/session/messages/SessionJsonValue.js";
+import type {
+  SessionAssistantFilePart,
+  SessionAssistantMessage,
+  SessionAssistantMessagePart,
+  SessionAssistantToolPart,
+} from "@/types/session/SessionMessage.js";
+import type { SessionToolInputReady } from "@/types/session/SessionTool.js";
+import { generateId } from "@/utils/Id.js";
+
+/** 单个 Assistant segment 的流式 writer。 */
+export class SessionAssistantMessageWriter {
+  readonly message_id: string;
+  private readonly recorder: SessionMessages;
+  private readonly pending_text_parts = new Map<string, "text" | "reasoning">();
+  private readonly active_text_part_ids = new Map<string, string>();
+  private write_chain: Promise<void> = Promise.resolve();
+  private closed = false;
+
+  constructor(recorder: SessionMessages, message_id: string) {
+    this.recorder = recorder;
+    this.message_id = message_id;
+  }
+
+  /** 应用一个原始 AI SDK UI chunk。 */
+  async apply_chunk(chunk: UIMessageChunk): Promise<void> {
+    await this.enqueue_write(async () => {
+      await this.apply_chunk_serialized(chunk);
+    });
+  }
+
+  /** 在当前 Assistant writer 的单写者队列中应用原始 chunk。 */
+  private async apply_chunk_serialized(chunk: UIMessageChunk): Promise<void> {
+    if (this.closed) throw new Error("Assistant Message writer is closed");
+    const current = this.current_message();
+    switch (chunk.type) {
+      case "text-start":
+      case "reasoning-start": {
+        const type = chunk.type === "text-start" ? "text" : "reasoning";
+        const part_id = this.resolve_text_part_id(type, chunk.id);
+        if (!current.parts.some((part) => part.part_id === part_id)) {
+          this.pending_text_parts.set(part_id, type);
+        }
+        return;
+      }
+      case "text-delta":
+      case "reasoning-delta": {
+        const type = chunk.type === "text-delta" ? "text" : "reasoning";
+        const part_id = this.resolve_text_part_id(type, chunk.id);
+        await this.ensure_text_part(part_id, type);
+        await this.recorder.append_assistant_delta(
+          this.message_id,
+          part_id,
+          type,
+          chunk.delta,
+        );
+        return;
+      }
+      case "text-end":
+      case "reasoning-end": {
+        const type = chunk.type === "text-end" ? "text" : "reasoning";
+        const source_part_id = this.source_text_part_id(type, chunk.id);
+        const part_id = this.active_text_part_ids.get(source_part_id);
+        if (!part_id) return;
+        const part = current.parts.find((item) => item.part_id === part_id);
+        if (part?.type === "text" || part?.type === "reasoning") {
+          await this.upsert_part({ ...part, state: "done" });
+        } else {
+          this.pending_text_parts.delete(part_id);
+        }
+        this.active_text_part_ids.delete(source_part_id);
+        return;
+      }
+      case "tool-input-start":
+        if (this.find_tool(chunk.toolCallId)) return;
+        await this.upsert_tool(chunk.toolCallId, {
+          tool_name: chunk.toolName,
+          state: "input-streaming",
+          input_text: "",
+        });
+        return;
+      case "tool-input-delta": {
+        const tool = this.find_tool(chunk.toolCallId);
+        if (tool && tool.state !== "input-streaming") return;
+        await this.upsert_tool(chunk.toolCallId, {
+          tool_name: tool?.tool_name || "unknown",
+          state: "input-streaming",
+          input_text: `${tool?.input_text || ""}${chunk.inputTextDelta}`,
+        });
+        return;
+      }
+      case "tool-input-available": {
+        const tool = this.find_tool(chunk.toolCallId);
+        if (tool && tool.state !== "input-streaming") return;
+        await this.upsert_tool(chunk.toolCallId, {
+          tool_name: chunk.toolName,
+          state: "ready",
+          input: to_session_json_value(chunk.input),
+        });
+        return;
+      }
+      case "tool-input-error":
+        await this.upsert_tool(chunk.toolCallId, {
+          tool_name: chunk.toolName,
+          state: "failed",
+          input: to_session_json_value(chunk.input),
+          error: chunk.errorText,
+        });
+        return;
+      case "tool-output-available": {
+        const tool = this.find_tool(chunk.toolCallId);
+        if (
+          tool?.state === "failed" &&
+          (tool.error === "Approval denied" || tool.error === "Approval expired")
+        ) return;
+        await this.upsert_tool(chunk.toolCallId, {
+          tool_name: tool?.tool_name || "unknown",
+          state: "completed",
+          output: to_session_json_value(chunk.output),
+        });
+        return;
+      }
+      case "tool-output-error":
+      case "tool-output-denied": {
+        const tool = this.find_tool(chunk.toolCallId);
+        await this.upsert_tool(chunk.toolCallId, {
+          tool_name: tool?.tool_name || "unknown",
+          state: "failed",
+          error:
+            chunk.type === "tool-output-error"
+              ? chunk.errorText
+              : "Tool output denied",
+        });
+        return;
+      }
+      case "file":
+        await this.append_file_part({
+          media_type: chunk.mediaType,
+          url: chunk.url,
+        });
+        return;
+      default:
+        return;
+    }
+  }
+
+  /** 写入一个完整 Assistant part。 */
+  async upsert_part(part: SessionAssistantMessagePart): Promise<void> {
+    await this.recorder.update_assistant_part(this.message_id, part);
+  }
+
+  /** Executor 在调用 Tool 实现前写入完整输入。 */
+  async prepare_tool_input(input: SessionToolInputReady): Promise<void> {
+    await this.enqueue_write(async () => {
+      const current = this.find_tool(input.tool_call_id);
+      if (current && current.state !== "input-streaming" && current.state !== "ready") {
+        throw new Error(
+          `Tool input cannot be prepared from ${current.state}: ${input.tool_call_id}`,
+        );
+      }
+      await this.upsert_tool(input.tool_call_id, {
+        tool_name: input.tool_name,
+        state: "ready",
+        input: to_session_json_value(input.input),
+      });
+    });
+  }
+
+  /** 把最终结果中的文件补入当前 Assistant，并对流式已写入文件去重。 */
+  async append_file_part(
+    input: Pick<SessionAssistantFilePart, "filename" | "media_type" | "url">,
+  ): Promise<void> {
+    const filename = String(input.filename || "").trim();
+    const current = this.current_message();
+    const existing = current.parts.find(
+      (part) =>
+        part.type === "file" &&
+        part.url === input.url &&
+        part.media_type === input.media_type,
+    );
+    if (existing?.type === "file") {
+      if (filename && String(existing.filename || "").trim() !== filename) {
+        await this.upsert_part({ ...existing, filename });
+      }
+      return;
+    }
+    await this.upsert_part({
+      part_id: `file:${generateId()}`,
+      sequence: this.next_part_sequence(),
+      type: "file",
+      media_type: input.media_type,
+      url: input.url,
+      ...(filename ? { filename } : {}),
+    });
+  }
+
+  /** 等待当前 Assistant writer 已入队的全部写操作完成。 */
+  async flush(): Promise<void> {
+    await this.write_chain;
+  }
+
+  /** 正常完成当前 assistant segment。 */
+  async complete(): Promise<void> {
+    await this.enqueue_write(async () => {
+      await this.close_serialized("completed");
+    });
+  }
+
+  /** 停止当前 assistant segment，并保留已有 parts。 */
+  async stop(): Promise<void> {
+    await this.enqueue_write(async () => {
+      await this.close_serialized("stopped");
+    });
+  }
+
+  /** 以失败状态关闭当前 assistant segment。 */
+  async fail(_error: unknown): Promise<void> {
+    await this.enqueue_write(async () => {
+      await this.close_serialized("failed");
+    });
+  }
+
+  /** 读取当前 Assistant Message 快照。 */
+  private current_message(): SessionAssistantMessage {
+    const message = this.recorder.get_message(this.message_id);
+    if (!message || message.type !== "assistant") {
+      throw new Error(`Assistant Message not found: ${this.message_id}`);
+    }
+    return message;
+  }
+
+  /** 读取当前 Assistant 中的指定 Tool Part。 */
+  private find_tool(tool_call_id: string): SessionAssistantToolPart | undefined {
+    return this.current_message().parts.find(
+      (part): part is SessionAssistantToolPart =>
+        part.type === "tool" && part.tool_call_id === tool_call_id,
+    );
+  }
+
+  /** 计算下一个不可变 Part 顺序号。 */
+  private next_part_sequence(): number {
+    return this.current_message().parts.reduce(
+      (value, part) => Math.max(value, part.sequence + 1),
+      1,
+    );
+  }
+
+  /**
+   * 把 AI SDK 当前 stream 内的临时 chunk ID 映射为 Message 内唯一 Part ID。
+   *
+   * AI SDK 会在不同 `streamText()` 调用中重复使用 `txt-0`、`reasoning-0`
+   * 等 ID，因此这些 ID 只能用于关联当前尚未结束的文本片段。
+   */
+  private resolve_text_part_id(
+    type: "text" | "reasoning",
+    chunk_id: string,
+  ): string {
+    const source_part_id = this.source_text_part_id(type, chunk_id);
+    const active_part_id = this.active_text_part_ids.get(source_part_id);
+    if (active_part_id) return active_part_id;
+    const part_id = `${type}:${generateId()}`;
+    this.active_text_part_ids.set(source_part_id, part_id);
+    return part_id;
+  }
+
+  /** 构造当前流片段使用的临时关联键。 */
+  private source_text_part_id(
+    type: "text" | "reasoning",
+    chunk_id: string,
+  ): string {
+    return `${type}:${chunk_id}`;
+  }
+
+  /** 在首个有效 Delta 到达时才固定文本 Part 的真实顺序。 */
+  private async ensure_text_part(
+    part_id: string,
+    type: "text" | "reasoning",
+  ): Promise<void> {
+    const existing = this.current_message().parts.find(
+      (part) => part.part_id === part_id,
+    );
+    if (existing) {
+      if (existing.type !== type) {
+        throw new Error(`Assistant Part type changed: ${part_id}`);
+      }
+      return;
+    }
+    const pending_type = this.pending_text_parts.get(part_id);
+    if (pending_type && pending_type !== type) {
+      throw new Error(`Assistant pending Part type changed: ${part_id}`);
+    }
+    await this.upsert_part({
+      part_id,
+      sequence: this.next_part_sequence(),
+      type,
+      text: "",
+      state: "streaming",
+    });
+    this.pending_text_parts.delete(part_id);
+  }
+
+  /** 创建或更新 Tool Part 完整快照。 */
+  private async upsert_tool(
+    tool_call_id: string,
+    changes: Pick<SessionAssistantToolPart, "tool_name" | "state"> &
+      Partial<Omit<SessionAssistantToolPart, "part_id" | "type" | "tool_call_id" | "tool_name" | "state">>,
+  ): Promise<void> {
+    const current = this.find_tool(tool_call_id);
+    await this.upsert_part({
+      ...(current || {}),
+      part_id: `tool:${tool_call_id}`,
+      sequence: current?.sequence || this.next_part_sequence(),
+      type: "tool",
+      tool_call_id,
+      ...changes,
+    });
+  }
+
+  /** 串行执行对当前 Assistant Message 的全部写操作。 */
+  private async enqueue_write(operation: () => Promise<void>): Promise<void> {
+    const current = this.write_chain.then(operation, operation);
+    this.write_chain = current.catch(() => undefined);
+    await current;
+  }
+
+  /** 在队列内关闭当前 Assistant Message。 */
+  private async close_serialized(
+    status: "completed" | "stopped" | "failed",
+  ): Promise<void> {
+    if (this.closed) return;
+    this.pending_text_parts.clear();
+    this.active_text_part_ids.clear();
+    await this.recorder.complete_assistant_message(this.message_id, status);
+    this.closed = true;
+  }
+}

package/src/session/messages/SessionJsonValue.ts

@@ -0,0 +1,25 @@
+/**
+ * Session JSON 值归一化工具。
+ *
+ * Session 持久化边界只接受 JSON 值；无法直接序列化的输入降级为字符串，
+ * 避免 Tool、User Data 等外部输入污染 canonical Message。
+ */
+
+import type { JsonValue } from "@/types/common/Json.js";
+
+/** 把任意运行时输入转换为可持久化的 JSON 值。 */
+export function to_session_json_value(input: unknown): JsonValue {
+  if (input === undefined || input === null) return null;
+  if (
+    typeof input === "string" ||
+    typeof input === "number" ||
+    typeof input === "boolean"
+  ) {
+    return input;
+  }
+  try {
+    return JSON.parse(JSON.stringify(input)) as JsonValue;
+  } catch {
+    return String(input);
+  }
+}

package/src/session/{recorder → messages}/SessionMessageCodec.ts

@@ -8,6 +8,7 @@
  */
 
 import type { UIMessage } from "ai";
+import { to_session_json_value } from "@/session/messages/SessionJsonValue.js";
 import type {
   SessionAssistantMessage,
   SessionAssistantMessagePart,
@@ -18,7 +19,40 @@ import type {
 import type {
   SessionMessageRecordV1,
   SessionMetadataV1,
+  SessionRecordV1,
 } from "@/executor/types/SessionRecords.js";
+import type { SessionContextSnapshot } from "@/types/session/SessionSegment.js";
+
+/** 把 canonical Session 历史快照投影为内部 UIMessage records。 */
+export function to_executor_history(
+  session_id: string,
+  snapshot: Readonly<SessionContextSnapshot>,
+): SessionRecordV1[] {
+  const records: SessionRecordV1[] = [];
+  if (snapshot.summary) {
+    records.push({
+      id: snapshot.summary.summary_id,
+      role: "assistant",
+      metadata: {
+        v: 1,
+        ts: snapshot.summary.created_at,
+        sessionId: session_id,
+        source: "compact",
+        kind: "summary",
+        extra: {
+          visibility: "internal",
+          summaryThroughSequence: snapshot.summary.through_sequence,
+        },
+      },
+      parts: [{ type: "text", text: snapshot.summary.text }],
+    });
+  }
+  for (const message of snapshot.messages) {
+    const record = to_executor_ui_message(message);
+    if (record) records.push(record);
+  }
+  return records;
+}
 
 /** 把 Session Message 投影成 Executor 可消费的 UIMessage。 */
 export function to_executor_ui_message(
@@ -90,7 +124,7 @@ export function from_ui_user_parts(
         part_id: `user-data:${index + 1}`,
         type: "data" as const,
         data_type: String(candidate.type),
-        data: to_json_value(candidate.data),
+        data: to_session_json_value(candidate.data),
       }];
     }
     return [];
@@ -149,10 +183,10 @@ export function from_ui_assistant_parts(
                     ? "ready" as const
                     : "running" as const,
         ...(candidate.input !== undefined
-          ? { input: to_json_value(candidate.input) }
+          ? { input: to_session_json_value(candidate.input) }
           : {}),
         ...(candidate.output !== undefined
-          ? { output: to_json_value(candidate.output) }
+          ? { output: to_session_json_value(candidate.output) }
           : {}),
         ...(candidate.errorText ? { error: String(candidate.errorText) } : {}),
       }];
@@ -244,7 +278,7 @@ function to_ui_assistant_parts(
         toolCallId: part.tool_call_id,
         state: "approval-requested",
         input,
-        approval: { id: part.approval_id || `approval:${part.tool_call_id}` },
+        approval: { id: part.approval?.approval_id || `approval:${part.tool_call_id}` },
       };
     }
     return {
@@ -266,19 +300,3 @@ function parse_json(input: string | undefined): unknown {
     return value;
   }
 }
-
-function to_json_value(input: unknown) {
-  if (input === undefined || input === null) return null;
-  if (
-    typeof input === "string" ||
-    typeof input === "number" ||
-    typeof input === "boolean"
-  ) {
-    return input;
-  }
-  try {
-    return JSON.parse(JSON.stringify(input));
-  } catch {
-    return String(input);
-  }
-}