@downcity/agent 1.1.287 → 1.1.310

package/src/session/browse/SessionMessageTimeline.ts

@@ -0,0 +1,135 @@
+/**
+ * Canonical Session Message 时间线投影。
+ *
+ * 关键点（中文）
+ * - 只接收公开的 SessionMessage，不暴露 JSONL 或内部 Executor Record。
+ * - 为 CLI、控制台与其他宿主提供同一套用户可见时间线语义。
+ * - 纯数据转换，不读取文件，也不持有 Session 运行态。
+ */
+
+import type {
+  AgentSessionTimelineEvent,
+} from "@/types/agent/SessionTypes.js";
+import type {
+  SessionAssistantToolPart,
+  SessionMessage,
+} from "@/types/session/SessionMessage.js";
+
+/** 将未知数据转换为有界展示文本。 */
+function stringify_for_display(input: unknown, max_chars = 2400): string {
+  if (input === undefined) return "";
+  if (input === null) return "null";
+  const value = typeof input === "string"
+    ? input.trim()
+    : JSON.stringify(input, null, 2);
+  if (!value) return "";
+  return value.length <= max_chars
+    ? value
+    : `${value.slice(0, Math.max(0, max_chars - 1)).trimEnd()}…`;
+}
+
+/** 创建一个带稳定 Message 内序号的时间线事件。 */
+function create_timeline_event(input: {
+  /** 来源 Message。 */
+  message: SessionMessage;
+  /** 事件角色。 */
+  role: AgentSessionTimelineEvent["role"];
+  /** 展示文本。 */
+  text: string;
+  /** Message 内事件序号。 */
+  index: number;
+  /** 可选工具名称。 */
+  tool_name?: string;
+}): AgentSessionTimelineEvent {
+  return {
+    id: `${input.message.message_id}:${input.index}`,
+    role: input.role,
+    ts: input.message.updated_at,
+    text: input.text,
+    ...(input.tool_name ? { tool_name: input.tool_name } : {}),
+  };
+}
+
+/** 将单个 Tool Part 展开为调用与可选结果事件。 */
+function project_tool_part(
+  message: SessionMessage,
+  part: SessionAssistantToolPart,
+  start_index: number,
+): AgentSessionTimelineEvent[] {
+  const events = [create_timeline_event({
+    message,
+    role: "tool-call",
+    text: stringify_for_display(part.input ?? part.input_text) || "(empty)",
+    index: start_index,
+    tool_name: part.tool_name,
+  })];
+  const output = part.state === "completed"
+    ? part.output
+    : part.state === "failed"
+      ? { error: part.error || "tool_error" }
+      : undefined;
+  if (output !== undefined) {
+    events.push(create_timeline_event({
+      message,
+      role: "tool-result",
+      text: stringify_for_display(output) || "(empty)",
+      index: start_index + 1,
+      tool_name: part.tool_name,
+    }));
+  }
+  return events;
+}
+
+/** 把一条 canonical Session Message 投影为 UI 时间线事件。 */
+export function to_session_message_timeline_events(
+  message: SessionMessage,
+): AgentSessionTimelineEvent[] {
+  if (message.type === "action") {
+    return [{
+      id: `${message.message_id}:0`,
+      role: "action",
+      ts: message.updated_at,
+      text: message.description
+        ? `${message.title}\n${message.description}`
+        : message.title,
+      action_title: message.title,
+      ...(message.description ? { action_description: message.description } : {}),
+      action_state: message.status,
+    }];
+  }
+  if (message.type === "error") {
+    return [create_timeline_event({
+      message,
+      role: "assistant",
+      text: message.message,
+      index: 0,
+    })];
+  }
+  if (message.type === "user") {
+    const text = message.parts
+      .filter((part) => part.type === "text")
+      .map((part) => part.text.trim())
+      .filter(Boolean)
+      .join("\n");
+    return [create_timeline_event({ message, role: "user", text, index: 0 })];
+  }
+
+  const events: AgentSessionTimelineEvent[] = [];
+  for (const part of [...message.parts].sort((left, right) => left.sequence - right.sequence)) {
+    if (part.type === "text") {
+      const text = part.text.trim();
+      if (text) {
+        events.push(create_timeline_event({
+          message,
+          role: "assistant",
+          text,
+          index: events.length,
+        }));
+      }
+      continue;
+    }
+    if (part.type !== "tool") continue;
+    events.push(...project_tool_part(message, part, events.length));
+  }
+  return events;
+}

package/src/session/control/SessionInteractions.ts

@@ -0,0 +1,290 @@
+/**
+ * Session 用户异步交互运行时。
+ *
+ * 本模块只拥有 pending waiter、超时与恢复执行；Interaction 的权威状态由
+ * SessionMessages 持久化。任何终态都必须先提交 canonical Message，再兑现等待 Promise。
+ */
+
+import type { SessionMessages } from "@/session/SessionMessages.js";
+import type {
+  RespondSessionInteractionInput,
+  SessionInteractionHandle,
+  SessionInteractionLifecycle,
+  SessionInteractionPort,
+  SessionInteractionRequest,
+  SessionInteractionResponse,
+  SessionInteractionResult,
+  SessionPendingInteraction,
+} from "@/types/session/SessionInteraction.js";
+import type { SessionPendingInteractionRuntime } from "@/types/session/SessionInteractions.js";
+
+/** 单个 Session 的异步用户交互入口。 */
+export class SessionInteractions implements SessionInteractionPort, SessionInteractionLifecycle {
+  private readonly session_id: string;
+  private readonly messages: SessionMessages;
+  private readonly pending_by_id = new Map<
+    string,
+    SessionPendingInteractionRuntime
+  >();
+
+  constructor(options: {
+    /** 当前 Interaction 运行时所属 Session 标识。 */
+    session_id: string;
+    /** 当前 Session 的 canonical Message 入口。 */
+    messages: SessionMessages;
+  }) {
+    this.session_id = String(options.session_id || "").trim();
+    this.messages = options.messages;
+    if (!this.session_id) {
+      throw new Error("SessionInteractions requires a non-empty session_id");
+    }
+  }
+
+  /** 创建并持久化一次 Interaction，返回等待终态结果的句柄。 */
+  async request(
+    request: SessionInteractionRequest,
+  ): Promise<SessionInteractionHandle> {
+    this.validate_request(request);
+    if (this.pending_by_id.has(request.interaction_id)) {
+      throw new Error(`Session Interaction is already pending: ${request.interaction_id}`);
+    }
+
+    let resolve_result!: (result: SessionInteractionResult) => void;
+    const result = new Promise<SessionInteractionResult>((resolve) => {
+      resolve_result = resolve;
+    });
+    const pending: SessionPendingInteractionRuntime = {
+      request: structuredClone(request),
+      resolve: resolve_result,
+    };
+    this.pending_by_id.set(request.interaction_id, pending);
+
+    try {
+      await this.messages.request_interaction(request);
+    } catch (error) {
+      this.pending_by_id.delete(request.interaction_id);
+      throw error;
+    }
+
+    if (request.expires_at !== undefined) {
+      const delay_ms = Math.max(0, request.expires_at - Date.now());
+      const timer = setTimeout(() => {
+        void this.expire(request.interaction_id);
+      }, delay_ms);
+      if (typeof timer.unref === "function") timer.unref();
+      pending.timer = timer;
+    }
+
+    return {
+      interaction_id: request.interaction_id,
+      result,
+    };
+  }
+
+  /** 返回当前 Session 全部 pending Interaction 请求快照。 */
+  list(): SessionPendingInteraction[] {
+    return this.messages.list_pending_interactions().map((interaction) => ({
+      request: structuredClone(interaction.request),
+    }));
+  }
+
+  /** 保存用户响应，并在提交成功后恢复原执行。 */
+  async respond(
+    input: RespondSessionInteractionInput,
+  ): Promise<SessionInteractionResult> {
+    const pending = this.require_pending(input.interaction_id);
+    this.validate_response(pending.request, input.response);
+    await this.messages.resolve_interaction(
+      input.interaction_id,
+      input.response,
+    );
+    const result: SessionInteractionResult = {
+      status: "resolved",
+      interaction_id: input.interaction_id,
+      response: structuredClone(input.response),
+    };
+    this.finish_pending(input.interaction_id, result);
+    return result;
+  }
+
+  /** 取消当前 Session 的全部 pending Interaction。 */
+  async cancel_all(
+    reason: "turn_stopped" | "session_disposed" | "runtime_interrupted",
+  ): Promise<void> {
+    let first_error: unknown;
+    for (const interaction_id of [...this.pending_by_id.keys()]) {
+      const result: SessionInteractionResult = {
+        status: "cancelled",
+        interaction_id,
+        reason,
+      };
+      try {
+        await this.messages.close_interaction(interaction_id, {
+          status: "cancelled",
+          reason,
+        });
+        this.finish_pending(interaction_id, result);
+      } catch (error) {
+        first_error ??= error;
+      }
+    }
+    if (first_error) throw first_error;
+  }
+
+  /** 处理单个 Interaction 自动过期。 */
+  private async expire(interaction_id: string): Promise<void> {
+    if (!this.pending_by_id.has(interaction_id)) return;
+    const result: SessionInteractionResult = {
+      status: "expired",
+      interaction_id,
+    };
+    try {
+      await this.messages.close_interaction(interaction_id, {
+        status: "expired",
+      });
+    } catch {
+      return;
+    }
+    this.finish_pending(interaction_id, result);
+  }
+
+  /** 校验执行面提交的 Interaction 请求。 */
+  private validate_request(request: SessionInteractionRequest): void {
+    if (!String(request.interaction_id || "").trim()) {
+      throw new Error("Session Interaction requires interaction_id");
+    }
+    if (!String(request.turn_id || "").trim()) {
+      throw new Error("Session Interaction requires turn_id");
+    }
+    if (
+      request.expires_at !== undefined &&
+      (!Number.isFinite(request.expires_at) || request.expires_at < request.created_at)
+    ) {
+      throw new Error("Session Interaction expires_at must not precede created_at");
+    }
+    if (request.kind === "question") {
+      if (request.questions.length === 0) {
+        throw new Error("Question Interaction requires at least one question");
+      }
+      const question_ids = new Set<string>();
+      for (const question of request.questions) {
+        if (!String(question.question_id || "").trim()) {
+          throw new Error("Interaction question requires question_id");
+        }
+        if (question_ids.has(question.question_id)) {
+          throw new Error(
+            `Duplicate Interaction question_id: ${question.question_id}`,
+          );
+        }
+        question_ids.add(question.question_id);
+        if (!String(question.prompt || "").trim()) {
+          throw new Error(
+            `Interaction question requires prompt: ${question.question_id}`,
+          );
+        }
+        if (
+          question.response_type !== "text" &&
+          (!question.options || question.options.length === 0)
+        ) {
+          throw new Error(
+            `Select Interaction question requires options: ${question.question_id}`,
+          );
+        }
+        if (question.options) {
+          const option_values = new Set<string>();
+          for (const option of question.options) {
+            if (!String(option.value || "").trim()) {
+              throw new Error(
+                `Interaction option requires value: ${question.question_id}`,
+              );
+            }
+            if (option_values.has(option.value)) {
+              throw new Error(
+                `Duplicate Interaction option value: ${question.question_id}/${option.value}`,
+              );
+            }
+            option_values.add(option.value);
+          }
+        }
+      }
+    }
+  }
+
+  /** 校验响应 kind、问题集合与回答值。 */
+  private validate_response(
+    request: SessionInteractionRequest,
+    response: SessionInteractionResponse,
+  ): void {
+    if (request.kind !== response.kind) {
+      throw new Error(
+        `Session Interaction response kind mismatch: ${request.interaction_id}`,
+      );
+    }
+    if (request.kind !== "question" || response.kind !== "question") return;
+    const answers = new Map<string, string | string[]>();
+    for (const answer of response.answers) {
+      if (answers.has(answer.question_id)) {
+        throw new Error(
+          `Duplicate Session Interaction answer: ${answer.question_id}`,
+        );
+      }
+      answers.set(answer.question_id, answer.value);
+    }
+    if (answers.size !== request.questions.length) {
+      throw new Error(
+        `Session Interaction answer count mismatch: ${request.interaction_id}`,
+      );
+    }
+    for (const question of request.questions) {
+      const value = answers.get(question.question_id);
+      if (value === undefined) {
+        throw new Error(
+          `Session Interaction answer is missing: ${question.question_id}`,
+        );
+      }
+      if (question.response_type === "multi_select") {
+        if (!Array.isArray(value)) {
+          throw new Error(
+            `Session Interaction answer must be an array: ${question.question_id}`,
+          );
+        }
+      } else if (typeof value !== "string") {
+        throw new Error(
+          `Session Interaction answer must be a string: ${question.question_id}`,
+        );
+      }
+      if (question.response_type !== "text") {
+        const allowed = new Set(
+          (question.options || []).map((option) => option.value),
+        );
+        const selected = Array.isArray(value) ? value : [value];
+        if (selected.some((item) => !allowed.has(item))) {
+          throw new Error(
+            `Session Interaction answer contains an invalid option: ${question.question_id}`,
+          );
+        }
+      }
+    }
+  }
+
+  /** 读取当前 pending Interaction 运行态。 */
+  private require_pending(
+    interaction_id: string,
+  ): SessionPendingInteractionRuntime {
+    const pending = this.pending_by_id.get(interaction_id);
+    if (pending) return pending;
+    throw new Error(`Pending Session Interaction not found: ${interaction_id}`);
+  }
+
+  /** 清理运行态并兑现执行方等待 Promise。 */
+  private finish_pending(
+    interaction_id: string,
+    result: SessionInteractionResult,
+  ): void {
+    const pending = this.pending_by_id.get(interaction_id);
+    if (!pending) return;
+    if (pending.timer) clearTimeout(pending.timer);
+    this.pending_by_id.delete(interaction_id);
+    pending.resolve(result);
+  }
+}

package/src/session/execution/SessionAssistantOutputAdapter.ts

@@ -0,0 +1,144 @@
+/**
+ * AI SDK Assistant 输出到 Session canonical Message 的协议 Adapter。
+ *
+ * 本模块是 AI SDK 临时 ID、空 Part 与最终 UIMessage 快照能进入的最外层边界。
+ * 它只通过 SessionMessages 打开 Writer，不持有第二份 Assistant Message 状态。
+ */
+
+import type { SessionMessageRecordV1 } from "@/executor/types/SessionRecords.js";
+import { from_ui_assistant_parts } from "@/session/messages/SessionMessageCodec.js";
+import {
+  SessionAssistantMessageWriter,
+  SessionMessages,
+} from "@/session/SessionMessages.js";
+import type { SessionAssistantOutput } from "@/types/executor/SessionAssistantOutput.js";
+import type { SessionToolInputReady } from "@/types/session/SessionTool.js";
+import type { UIMessage, UIMessageChunk } from "ai";
+
+/** 单个 Turn 使用的 Assistant 输出 Adapter。 */
+export class SessionAssistantOutputAdapter implements SessionAssistantOutput {
+  private readonly turn_id: string;
+  private readonly messages: SessionMessages;
+  private writer: SessionAssistantMessageWriter | null = null;
+  private writer_task: Promise<SessionAssistantMessageWriter> | null = null;
+  private step_pending = false;
+
+  constructor(options: {
+    /** 当前输出所属 Turn 标识。 */
+    turn_id: string;
+    /** canonical Message 写入入口。 */
+    messages: SessionMessages;
+  }) {
+    this.turn_id = String(options.turn_id || "").trim();
+    this.messages = options.messages;
+    if (!this.turn_id) {
+      throw new Error("SessionAssistantOutputAdapter requires a non-empty turn_id");
+    }
+  }
+
+  /** 开始当前 Provider Step。 */
+  async begin_step(): Promise<void> {
+    if (this.writer) {
+      await this.writer.begin_step();
+      return;
+    }
+    this.step_pending = true;
+  }
+
+  /** 把可持久化 AI SDK Chunk 写入当前 canonical Message。 */
+  async write_chunk(chunk: UIMessageChunk): Promise<void> {
+    if (!is_assistant_content_chunk(chunk.type)) return;
+    await (await this.ensure_writer()).apply_chunk(chunk);
+  }
+
+  /** 使用最终快照校验当前 Step Part 顺序并补齐 metadata。 */
+  async finish_step(message: SessionMessageRecordV1): Promise<void> {
+    await (await this.ensure_writer()).finish_step(
+      from_ui_assistant_parts(message.parts),
+    );
+  }
+
+  /** 清理异常结束的 Step 作用域。 */
+  async abort_step(): Promise<void> {
+    if (this.writer) await this.writer.abort_step();
+    this.step_pending = false;
+  }
+
+  /** 在 Tool 实现开始前提交完整输入。 */
+  async prepare_tool_input(input: SessionToolInputReady): Promise<void> {
+    await (await this.ensure_writer()).prepare_tool_input(input);
+  }
+
+  /** User steer 已持久化后关闭当前 Assistant Message；没有输出时保持为空。 */
+  async close_current_message(): Promise<void> {
+    if (!this.writer) {
+      this.step_pending = false;
+      return;
+    }
+    await this.writer.complete();
+    this.writer = null;
+  }
+
+  /** 把 Action 产生的完整 UI Parts 追加到当前 canonical Assistant Message。 */
+  async append_parts(parts: UIMessage["parts"]): Promise<void> {
+    if (!Array.isArray(parts) || parts.length === 0) return;
+    await (await this.ensure_writer()).append_parts(
+      from_ui_assistant_parts(parts),
+    );
+  }
+
+  /** 按 Turn 结果收口最后一个 canonical Message。 */
+  async finish(input: {
+    /** Assistant 最终状态。 */
+    status: "completed" | "failed" | "stopped";
+    /** 失败信息。 */
+    error?: string;
+  }): Promise<void> {
+    if (!this.writer) {
+      this.step_pending = false;
+      return;
+    }
+    const writer = await this.ensure_writer();
+    if (input.status === "stopped") await writer.stop();
+    else if (input.status === "completed") await writer.complete();
+    else await writer.fail(input.error);
+    this.writer = null;
+  }
+
+  /** 惰性打开当前连续 Assistant 回复的唯一 Writer。 */
+  private async ensure_writer(): Promise<SessionAssistantMessageWriter> {
+    if (this.writer) return this.writer;
+    if (this.writer_task) return await this.writer_task;
+    this.writer_task = this.messages.open_assistant_message({
+      turn_id: this.turn_id,
+    });
+    try {
+      this.writer = await this.writer_task;
+      if (this.step_pending) {
+        await this.writer.begin_step();
+        this.step_pending = false;
+      }
+      return this.writer;
+    } finally {
+      this.writer_task = null;
+    }
+  }
+}
+
+/** 判断 AI SDK Chunk 是否属于 canonical Assistant 内容。 */
+function is_assistant_content_chunk(type: string): boolean {
+  return (
+    type === "text-start" ||
+    type === "text-delta" ||
+    type === "text-end" ||
+    type === "reasoning-start" ||
+    type === "reasoning-delta" ||
+    type === "reasoning-end" ||
+    type.startsWith("tool-") ||
+    type === "file" ||
+    type === "source-url" ||
+    type === "source-document" ||
+    type === "start-step" ||
+    type.startsWith("data-")
+  );
+}

package/src/session/execution/tools/SessionShellApprovalAdapter.ts

@@ -0,0 +1,94 @@
+/**
+ * Shell 审批到 Session Interaction 的执行边界 Adapter。
+ *
+ * Shell 只理解高风险命令审批协议；本 Adapter 把它转换成 Session 的通用
+ * approval Interaction，并把 Interaction 终态映射回 Shell 决策。
+ */
+
+import type {
+  ShellApprovalGateway,
+  ShellApprovalHandle,
+  ShellApprovalRequest,
+  ShellApprovalStatus,
+} from "@downcity/shell";
+import type { SessionInteractions } from "@/session/control/SessionInteractions.js";
+import type { SessionApprovalMode } from "@/types/session/SessionInteraction.js";
+import { generate_id } from "@/utils/Id.js";
+
+/** 单个 Session 的 Shell 高风险操作审批 Adapter。 */
+export class SessionShellApprovalAdapter implements ShellApprovalGateway {
+  private readonly session_id: string;
+  private readonly interactions: SessionInteractions;
+  private mode: SessionApprovalMode = "ask";
+
+  constructor(options: {
+    /** 当前 Adapter 所属 Session 标识。 */
+    session_id: string;
+    /** 当前 Session 的异步用户交互入口。 */
+    interactions: SessionInteractions;
+  }) {
+    this.session_id = String(options.session_id || "").trim();
+    this.interactions = options.interactions;
+    if (!this.session_id) {
+      throw new Error(
+        "SessionShellApprovalAdapter requires a non-empty session_id",
+      );
+    }
+  }
+
+  /** 把 Shell 高风险操作请求转换成 approval Interaction。 */
+  async request(input: ShellApprovalRequest): Promise<ShellApprovalHandle> {
+    if (input.session_id !== this.session_id) {
+      throw new Error(`Approval Session mismatch: ${input.session_id}`);
+    }
+    const interaction_id = `interaction:${generate_id()}`;
+    if (this.mode === "always-allow") {
+      return {
+        approval_id: interaction_id,
+        requires_user_decision: false,
+        decision: Promise.resolve("approved"),
+      };
+    }
+
+    const created_at = Date.now();
+    const handle = await this.interactions.request({
+      interaction_id,
+      turn_id: input.turn_id,
+      kind: "approval",
+      source: {
+        type: "tool",
+        tool_call_id: input.tool_call_id,
+        tool_name: input.tool_name,
+      },
+      title: `Approve ${input.tool_name}`,
+      description: input.reason,
+      command: input.command,
+      cwd: input.cwd,
+      reason: input.reason,
+      operation: input.operation,
+      created_at,
+      expires_at: created_at + input.timeout_ms,
+    });
+
+    return {
+      approval_id: interaction_id,
+      requires_user_decision: true,
+      decision: handle.result.then((result): ShellApprovalStatus => {
+        if (result.status === "expired") return "expired";
+        if (result.status !== "resolved") return "denied";
+        if (result.response.kind !== "approval") return "denied";
+        return result.response.decision;
+      }),
+    };
+  }
+
+  /** 读取当前 Session 执行面使用的高风险操作审批模式。 */
+  get_effective_mode(): SessionApprovalMode {
+    return this.mode;
+  }
+
+  /** 在 Session Step 检查点提交后续高风险操作请求使用的审批模式。 */
+  set_effective_mode(mode: SessionApprovalMode): void {
+    this.mode = mode === "always-allow" ? "always-allow" : "ask";
+  }
+}