@downcity/agent 1.1.287 → 1.1.310

package/src/session/browse/Browse.ts

@@ -8,73 +8,48 @@
  * - 这里不持有运行态状态；执行状态等动态信息通过调用参数显式注入。
  */
 
-import fs from "fs-extra";
 import path from "node:path";
-import {
-  getToolName,
-  isTextUIPart,
-  isToolUIPart,
-  type UIMessagePart,
-} from "ai";
 import type {
   AgentListSessionsInput,
-  AgentSessionRecordsInput,
-  AgentSessionRecordsPage,
-  AgentSessionRecordsView,
   AgentSessionInfo,
   AgentSessionSummary,
   AgentSessionSummaryPage,
-  AgentSessionTimelineEvent,
 } from "@/types/agent/SessionTypes.js";
 import type {
-  SessionActionRecordV1,
   SessionRecordV1,
   SessionMetadataV1,
-  SessionMessageRecordV1,
-} from "@/executor/types/SessionRecords.js";
-import {
-  is_session_action_record,
-  is_session_message_record,
 } from "@/executor/types/SessionRecords.js";
+import { is_session_message_record } from "@/executor/types/SessionRecords.js";
 import type { SessionHistoryMetaV1 } from "@/executor/types/SessionHistoryMeta.js";
 import { resolve_session_message_preview } from "@/session/preview/SessionMessagePreview.js";
-import { getSdkAgentSessionMessagesPath } from "@/session/storage/Paths.js";
-import { getSdkAgentSessionMetaPath } from "@/session/storage/Paths.js";
-import { getSdkAgentSessionsRootDirPath } from "@/session/storage/Paths.js";
-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 {
+  get_sdk_agent_archived_session_messages_path,
+  get_sdk_agent_archived_session_meta_path,
+  get_sdk_agent_archived_sessions_dir_path,
+  get_sdk_agent_session_messages_path,
+  get_sdk_agent_session_meta_path,
+  get_sdk_agent_sessions_root_dir_path,
+} from "@/workspace/store/LocalStorePaths.js";
+import { read_session_metadata_from_path } from "@/session/storage/Metadata.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>>;
-
-type ToolPartCompatShape = {
-  type?: unknown;
-  state?: unknown;
-  input?: unknown;
-  output?: unknown;
-  errorText?: unknown;
-  error?: unknown;
-  approval?: { reason?: unknown } | null;
-};
+import type { FileSystem } from "@/types/workspace/FileSystem.js";
 
 type SessionBrowseBaseInput = {
   /**
    * 当前项目根目录。
    */
-  projectRoot: string;
+  project_root: string;
 
   /**
-   * 当前 agentId。
+   * 当前 agent_id。
    */
-  agentId: string;
+  agent_id: string;
 
   /**
-   * 当前 sessionId。
+   * 当前 session_id。
    */
-  sessionId: string;
+  session_id: string;
 
   /**
    * 当前 session 已读取到的 metadata。
@@ -133,190 +108,16 @@ function encodeCursor(offset: number): string | undefined {
   return String(Math.floor(offset));
 }
 
-function stringifyForDisplay(input: unknown, maxChars = 2400): string {
-  if (input === undefined) return "";
-  if (input === null) return "null";
-  if (typeof input === "string") {
-    const value = input.trim();
-    if (!value) return "";
-    try {
-      const parsed = JSON.parse(value);
-      return truncateText(JSON.stringify(parsed, null, 2), maxChars);
-    } catch {
-      return truncateText(value, maxChars);
-    }
-  }
-  if (typeof input === "number" || typeof input === "boolean") {
-    return truncateText(String(input), maxChars);
-  }
-  try {
-    return truncateText(JSON.stringify(input, null, 2), maxChars);
-  } catch {
-    return truncateText(String(input), maxChars);
-  }
-}
-
-function resolveToolName(part: ToolPartCompatShape, aiToolName?: string): string {
-  const fromAi = String(aiToolName || "").trim();
-  if (fromAi) return fromAi;
-  const rawType = typeof part.type === "string" ? part.type.trim() : "";
-  if (rawType.startsWith("tool-")) return rawType.slice("tool-".length);
-  return "unknown_tool";
-}
-
-function extractToolCallInput(part: ToolPartCompatShape): unknown {
-  return part.input ?? undefined;
-}
-
-function extractToolResultOutput(part: ToolPartCompatShape): unknown {
-  const state = typeof part.state === "string" ? part.state.trim() : "";
-  if (state === "output-available") return part.output;
-  if (state === "output-error") {
-    return { error: part.errorText ?? part.error ?? "tool_error" };
-  }
-  if (state === "output-denied") {
-    return {
-      error: "tool_denied",
-      reason: part.approval?.reason ?? "",
-    };
-  }
-  return undefined;
-}
-
-function toTimelineEvent(params: {
-  message: SessionMessageRecordV1;
-  role: AgentSessionTimelineEvent["role"];
-  text: string;
-  sequence: number;
-  toolName?: string;
-}): AgentSessionTimelineEvent {
-  const metadata = (params.message.metadata || null) as SessionMetadataV1 | null;
-  return {
-    id: `${String(params.message.id || "")}:${params.sequence}`,
-    role: params.role,
-    ...(typeof metadata?.ts === "number" ? { ts: metadata.ts } : {}),
-    ...(typeof metadata?.kind === "string" ? { kind: metadata.kind } : {}),
-    ...(typeof metadata?.source === "string" ? { source: metadata.source } : {}),
-    text: params.text,
-    ...(params.toolName ? { toolName: params.toolName } : {}),
-  };
-}
-
-function toActionTimelineEvent(
-  message: SessionActionRecordV1,
-): AgentSessionTimelineEvent {
-  const metadata = message.metadata || null;
-  return {
-    id: `${String(message.id || "")}:0`,
-    role: "action",
-    ...(typeof metadata?.ts === "number" ? { ts: metadata.ts } : {}),
-    text: resolve_session_message_preview(message),
-    actionTitle: message.title,
-    ...(message.description ? { actionDescription: message.description } : {}),
-    actionState: message.state,
-  };
-}
-
-/**
- * 把单条 session message 展平成时间线事件。
- */
-export function toSessionTimelineEvents(
-  message: SessionRecordV1,
-): AgentSessionTimelineEvent[] {
-  if (is_session_action_record(message)) {
-    return [toActionTimelineEvent(message)];
-  }
-
-  if (!is_session_message_record(message)) return [];
-  if (message.role !== "assistant") {
-    return [
-      toTimelineEvent({
-        message,
-        role: message.role === "user" ? "user" : "assistant",
-        text: resolve_session_message_preview(message),
-        sequence: 0,
-      }),
-    ];
-  }
-
-  const parts = Array.isArray(message.parts)
-    ? (message.parts as AnyUiPart[])
-    : [];
-  const events: AgentSessionTimelineEvent[] = [];
-  let sequence = 0;
-
-  for (const part of parts) {
-    if (!part || typeof part !== "object") continue;
-    const partObject = part as ToolPartCompatShape;
-
-    if (isTextUIPart(part)) {
-      const text = String(part.text || "").trim();
-      if (!text) continue;
-      events.push(
-        toTimelineEvent({
-          message,
-          role: "assistant",
-          text,
-          sequence,
-        }),
-      );
-      sequence += 1;
-      continue;
-    }
-
-    if (isToolUIPart(part)) {
-      const toolName = resolveToolName(partObject, String(getToolName(part) || ""));
-      const inputText = stringifyForDisplay(extractToolCallInput(partObject));
-      events.push(
-        toTimelineEvent({
-          message,
-          role: "tool-call",
-          text: inputText || "(empty)",
-          sequence,
-          toolName,
-        }),
-      );
-      sequence += 1;
-
-      const output = extractToolResultOutput(partObject);
-      if (output !== undefined) {
-        events.push(
-          toTimelineEvent({
-            message,
-            role: "tool-result",
-            text: stringifyForDisplay(output) || "(empty)",
-            sequence,
-            toolName,
-          }),
-        );
-        sequence += 1;
-      }
-    }
-  }
-
-  if (events.length === 0) {
-    events.push(
-      toTimelineEvent({
-        message,
-        role: "assistant",
-        text: resolve_session_message_preview(message),
-        sequence: 0,
-      }),
-    );
-  }
-
-  return events;
-}
-
 /**
  * 读取指定 JSONL 消息文件。
  */
-export async function loadSessionMessagesFromPath(
+export async function load_session_messages_from_path(
   filePath: string,
+  files: FileSystem,
 ): Promise<SessionRecordV1[]> {
   const messages_by_id = new Map<string, SessionMessage>();
-  if (await fs.pathExists(filePath)) {
-    const raw = await fs.readFile(filePath, "utf-8");
+  if (await files.path_exists(filePath)) {
+    const raw = (await files.read_file(filePath)).toString("utf8");
     const lines = raw.split("\n").filter(Boolean);
     for (const line of lines) {
       try {
@@ -333,9 +134,11 @@ export async function loadSessionMessagesFromPath(
   }
 
   const inflight_path = path.join(path.dirname(filePath), "assistant_message.json");
-  if (await fs.pathExists(inflight_path)) {
+  if (await files.path_exists(inflight_path)) {
     try {
-      const message = (await fs.readJson(inflight_path)) as SessionMessage;
+      const message = JSON.parse(
+        (await files.read_file(inflight_path)).toString("utf8"),
+      ) as SessionMessage;
       if (is_canonical_session_message(message) && message.type === "assistant") {
         messages_by_id.set(message.message_id, message);
       }
@@ -377,8 +180,8 @@ function project_canonical_message_record(message: SessionMessage): SessionRecor
     metadata: {
       v: 1,
       ts: message.updated_at,
-      sessionId: message.session_id,
-      ...(message.turn_id ? { turnId: message.turn_id } : {}),
+      session_id: message.session_id,
+      ...(message.turn_id ? { turn_id: message.turn_id } : {}),
     },
   }];
 }
@@ -398,18 +201,18 @@ function filterUserVisibleHistoryMessages(
 /**
  * 基于 metadata + messages 构建 SDK session 详情。
  */
-export function buildSessionInfo(
+export function build_session_info(
   input: SessionBrowseBaseInput,
 ): AgentSessionInfo {
   const messages = input.messages;
-  const previewText = messages && messages.length > 0
+  const preview_text = messages && messages.length > 0
     ? truncateText(
         resolve_session_message_preview(messages[messages.length - 1]),
         180,
       )
-    : input.metadata.previewText;
-  const message_count = typeof input.metadata.messageCount === "number"
-    ? input.metadata.messageCount
+    : input.metadata.preview_text;
+  const message_count = typeof input.metadata.message_count === "number"
+    ? input.metadata.message_count
     : messages
       ? filterUserVisibleHistoryMessages(messages).length
       : 0;
@@ -418,19 +221,19 @@ export function buildSessionInfo(
       ? input.metadata.title.trim()
       : undefined;
   return {
-    agentId: input.agentId,
-    sessionId: input.sessionId,
+    agent_id: input.agent_id,
+    session_id: input.session_id,
     ...(title ? { title } : {}),
-    ...(previewText ? { previewText } : {}),
-    messageCount: message_count,
-    ...(typeof input.metadata.createdAt === "number"
-      ? { createdAt: input.metadata.createdAt }
+    ...(preview_text ? { preview_text } : {}),
+    message_count: message_count,
+    ...(typeof input.metadata.created_at === "number"
+      ? { created_at: input.metadata.created_at }
       : {}),
-    ...(typeof input.metadata.updatedAt === "number"
-      ? { updatedAt: input.metadata.updatedAt }
+    ...(typeof input.metadata.updated_at === "number"
+      ? { updated_at: input.metadata.updated_at }
       : {}),
-    ...(input.metadata.modelLabel
-      ? { modelLabel: input.metadata.modelLabel }
+    ...(input.metadata.model_label
+      ? { model_label: input.metadata.model_label }
       : {}),
     ...(typeof input.metadata.timezone === "string" && input.metadata.timezone.trim()
       ? { timezone: input.metadata.timezone.trim() }
@@ -455,38 +258,46 @@ async function resolve_session_summary_metadata(input: {
   metaPath: string;
   /** 是否强制刷新摘要。 */
   refresh: boolean;
+  /** 当前 Workspace 的统一文件能力。 */
+  files: FileSystem;
 }): Promise<SessionHistoryMetaV1> {
-  const storage_stats = await resolve_session_disk_stats(input.messagesPath);
+  const storage_stats = await resolve_session_disk_stats(
+    input.messagesPath,
+    input.files,
+  );
   const history_bytes = storage_stats.history_bytes;
   const inflight_path = path.join(path.dirname(input.messagesPath), "assistant_message.json");
-  const has_inflight = await fs.pathExists(inflight_path);
+  const has_inflight = await input.files.path_exists(inflight_path);
   if (
     !input.refresh &&
     !has_inflight &&
-    typeof input.metadata.messageCount === "number" &&
+    typeof input.metadata.message_count === "number" &&
     input.metadata.historyBytes === history_bytes
   ) {
     return input.metadata;
   }
-  const messages = await loadSessionMessagesFromPath(input.messagesPath);
+  const messages = await load_session_messages_from_path(
+    input.messagesPath,
+    input.files,
+  );
   const last_message = messages[messages.length - 1];
   const preview_text = last_message
     ? truncateText(resolve_session_message_preview(last_message), 180)
     : "";
-  const { previewText: _previous_preview, ...metadata_without_preview } = input.metadata;
+  const { preview_text: _previous_preview, ...metadata_without_preview } = input.metadata;
   void _previous_preview;
   const next_metadata: SessionHistoryMetaV1 = {
     ...metadata_without_preview,
-    messageCount: storage_stats.message_count,
+    message_count: storage_stats.message_count,
     historyBytes: history_bytes,
-    ...(preview_text || input.metadata.previewText
-      ? { previewText: preview_text || input.metadata.previewText }
+    ...(preview_text || input.metadata.preview_text
+      ? { preview_text: preview_text || input.metadata.preview_text }
       : {}),
   };
-  const temp_path = `${input.metaPath}.${process.pid}.${Date.now()}.tmp`;
-  await fs.ensureDir(path.dirname(input.metaPath));
-  await fs.writeJson(temp_path, next_metadata, { spaces: 2 });
-  await fs.move(temp_path, input.metaPath, { overwrite: true });
+  await input.files.write_file_atomically(
+    input.metaPath,
+    `${JSON.stringify(next_metadata, null, 2)}\n`,
+  );
   return next_metadata;
 }
 
@@ -497,13 +308,16 @@ async function resolve_session_summary_metadata(input: {
  * - Segment 的结束 sequence 直接来自文件名，不解析历史正文。
  * - Active 需要逐行读取，以同时覆盖 revision 行与运行中 Assistant sequence。
  */
-async function resolve_session_disk_stats(messages_path: string) {
+async function resolve_session_disk_stats(
+  messages_path: string,
+  files: FileSystem,
+) {
   const messages_dir_path = path.dirname(messages_path);
   const segments_dir_path = path.join(messages_dir_path, "segments");
-  const segment_entries = await fs.readdir(segments_dir_path, { withFileTypes: true })
+  const segment_entries = await files.read_directory(segments_dir_path)
     .catch(() => []);
   const segment_files = segment_entries.flatMap((entry) => {
-    if (!entry.isFile()) return [];
+    if (!entry.is_file) return [];
     const match = /^(\d+)-(\d+)\.jsonl$/.exec(entry.name);
     if (!match) return [];
     return [{
@@ -511,7 +325,9 @@ async function resolve_session_disk_stats(messages_path: string) {
       end_sequence: Number(match[2]),
     }];
   });
-  const active_raw = await fs.readFile(messages_path, "utf8").catch(() => "");
+  const active_raw = await files.read_file(messages_path)
+    .then((value) => value.toString("utf8"))
+    .catch(() => "");
   let latest_active_sequence = 0;
   for (const line of active_raw.split("\n")) {
     if (!line.trim()) continue;
@@ -526,7 +342,9 @@ async function resolve_session_disk_stats(messages_path: string) {
   }
   const inflight_path = path.join(messages_dir_path, "assistant_message.json");
   try {
-    const inflight = await fs.readJson(inflight_path) as Partial<SessionMessage>;
+    const inflight = JSON.parse(
+      (await files.read_file(inflight_path)).toString("utf8"),
+    ) as Partial<SessionMessage>;
     if (Number.isInteger(inflight.sequence)) {
       latest_active_sequence = Math.max(latest_active_sequence, Number(inflight.sequence));
     }
@@ -534,8 +352,7 @@ async function resolve_session_disk_stats(messages_path: string) {
     // 草稿不存在或损坏时只统计已完成历史。
   }
   const segment_sizes = await Promise.all(
-    segment_files.map(({ file_path }) => fs.stat(file_path)
-      .then((file_stat) => file_stat.size)
+    segment_files.map(({ file_path }) => files.file_size(file_path)
       .catch(() => 0)),
   );
   const latest_segment_sequence = segment_files.reduce(
@@ -549,130 +366,86 @@ async function resolve_session_disk_stats(messages_path: string) {
   };
 }
 
-/**
- * 基于完整消息列表构建 session records 分页结果。
- */
-export function buildSessionRecordsPage(params: {
-  session: AgentSessionInfo;
-  messages: SessionRecordV1[];
-  input?: AgentSessionRecordsInput;
-}): AgentSessionRecordsPage {
-  const view: AgentSessionRecordsView = params.input?.view || "message";
-  const order = params.input?.order || "asc";
-  const limit = normalizeLimit(params.input?.limit, 50, 500);
-  const cursor = normalizeCursor(params.input?.cursor);
-  const visibleMessages = filterUserVisibleHistoryMessages(params.messages);
-
-  if (view === "timeline") {
-    const allEvents = visibleMessages.flatMap((message) => toSessionTimelineEvents(message));
-    const orderedEvents = order === "desc" ? [...allEvents].reverse() : allEvents;
-    const pageItems = orderedEvents.slice(cursor, cursor + limit);
-    const nextOffset = cursor + pageItems.length;
-    return {
-      session: params.session,
-      view,
-      items: pageItems,
-      total: orderedEvents.length,
-      ...(nextOffset < orderedEvents.length
-        ? { next_cursor: encodeCursor(nextOffset) }
-        : {}),
-      has_more: nextOffset < orderedEvents.length,
-    };
-  }
-
-  const orderedMessages =
-    order === "desc" ? [...visibleMessages].reverse() : [...visibleMessages];
-  const pageItems = orderedMessages.slice(cursor, cursor + limit);
-  const nextOffset = cursor + pageItems.length;
-  return {
-    session: params.session,
-    view,
-    items: pageItems,
-    total: orderedMessages.length,
-    ...(nextOffset < orderedMessages.length
-      ? { next_cursor: encodeCursor(nextOffset) }
-      : {}),
-    has_more: nextOffset < orderedMessages.length,
-  };
-}
-
 /**
  * 列出指定 agent 的 session 摘要页。
  */
-export async function listAgentSessionSummaryPage(params: {
-  projectRoot: string;
-  agentId: string;
+export async function list_agent_session_summary_page(params: {
+  project_root: string;
+  agent_id: string;
   input?: AgentListSessionsInput;
   executingSessionIds?: Set<string>;
+  files: FileSystem;
 }): Promise<AgentSessionSummaryPage> {
   const limit = normalizeLimit(params.input?.limit, 50, 500);
   const cursor = normalizeCursor(params.input?.cursor);
   const query = String(params.input?.query || "").trim().toLowerCase();
-  const sessionsRoot = getSdkAgentSessionsRootDirPath(
-    params.projectRoot,
-    params.agentId,
+  const sessionsRoot = get_sdk_agent_sessions_root_dir_path(
+    params.project_root,
+    params.agent_id,
   );
 
-  if (!(await fs.pathExists(sessionsRoot))) {
+  if (!(await params.files.path_exists(sessionsRoot))) {
     return {
       items: [],
       total: 0,
-      hasMore: false,
+      has_more: false,
     };
   }
 
-  const entries = await fs.readdir(sessionsRoot, { withFileTypes: true });
+  const entries = await params.files.read_directory(sessionsRoot);
   const summaries: AgentSessionSummary[] = [];
 
   for (const entry of entries) {
-    if (!entry.isDirectory()) continue;
-    const sessionId = decodeMaybe(entry.name);
-    if (!sessionId) continue;
-    const meta_path = getSdkAgentSessionMetaPath(
-      params.projectRoot,
-      params.agentId,
-      sessionId,
+    if (!entry.is_directory) continue;
+    const session_id = decodeMaybe(entry.name);
+    if (!session_id) continue;
+    const meta_path = get_sdk_agent_session_meta_path(
+      params.project_root,
+      params.agent_id,
+      session_id,
     );
-    const messages_path = getSdkAgentSessionMessagesPath(
-      params.projectRoot,
-      params.agentId,
-      sessionId,
+    const messages_path = get_sdk_agent_session_messages_path(
+      params.project_root,
+      params.agent_id,
+      session_id,
     );
-    const persisted_metadata = await readSessionMetadataFromPath({
+    const persisted_metadata = await read_session_metadata_from_path({
       filePath: meta_path,
-      sessionId,
-      agentId: params.agentId,
+      session_id,
+      agent_id: params.agent_id,
+      files: params.files,
     });
     const metadata = await resolve_session_summary_metadata({
       metadata: persisted_metadata,
       messagesPath: messages_path,
       metaPath: meta_path,
-      refresh: params.executingSessionIds?.has(sessionId) === true,
+      refresh: params.executingSessionIds?.has(session_id) === true,
+      files: params.files,
     });
-    const info = buildSessionInfo({
-      projectRoot: params.projectRoot,
-      agentId: params.agentId,
-      sessionId,
+    const info = build_session_info({
+      project_root: params.project_root,
+      agent_id: params.agent_id,
+      session_id,
       metadata,
-      executing: params.executingSessionIds?.has(sessionId),
+      executing: params.executingSessionIds?.has(session_id),
     });
     const summary: AgentSessionSummary = {
-      agentId: info.agentId,
-      sessionId: info.sessionId,
+      agent_id: info.agent_id,
+      session_id: info.session_id,
       ...(info.title ? { title: info.title } : {}),
-      ...(info.previewText ? { previewText: info.previewText } : {}),
-      messageCount: info.messageCount,
-      ...(typeof info.createdAt === "number" ? { createdAt: info.createdAt } : {}),
-      ...(typeof info.updatedAt === "number" ? { updatedAt: info.updatedAt } : {}),
-      ...(info.modelLabel ? { modelLabel: info.modelLabel } : {}),
+      ...(info.preview_text ? { preview_text: info.preview_text } : {}),
+      message_count: info.message_count,
+      ...(typeof info.created_at === "number" ? { created_at: info.created_at } : {}),
+      ...(typeof info.updated_at === "number" ? { updated_at: info.updated_at } : {}),
+      ...(info.model_label ? { model_label: info.model_label } : {}),
       ...(info.executing ? { executing: true } : {}),
     };
 
     if (query) {
       const haystack = [
-        summary.sessionId,
+        summary.session_id,
         summary.title || "",
-        summary.previewText || "",
+        summary.preview_text || "",
       ]
         .join("\n")
         .toLowerCase();
@@ -682,7 +455,7 @@ export async function listAgentSessionSummaryPage(params: {
     summaries.push(summary);
   }
 
-  summaries.sort((left, right) => (right.updatedAt || 0) - (left.updatedAt || 0));
+  summaries.sort((left, right) => (right.updated_at || 0) - (left.updated_at || 0));
 
   const items = summaries.slice(cursor, cursor + limit);
   const nextOffset = cursor + items.length;
@@ -690,88 +463,91 @@ export async function listAgentSessionSummaryPage(params: {
     items,
     total: summaries.length,
     ...(nextOffset < summaries.length
-      ? { nextCursor: encodeCursor(nextOffset) }
+      ? { next_cursor: encodeCursor(nextOffset) }
       : {}),
-    hasMore: nextOffset < summaries.length,
+    has_more: nextOffset < summaries.length,
   };
 }
 
 /**
  * 列出指定 agent 的已归档 session 摘要页。
  */
-export async function listArchivedAgentSessionSummaryPage(params: {
-  projectRoot: string;
-  agentId: string;
+export async function list_archived_agent_session_summary_page(params: {
+  project_root: string;
+  agent_id: string;
   input?: AgentListSessionsInput;
+  files: FileSystem;
 }): Promise<AgentSessionSummaryPage> {
   const limit = normalizeLimit(params.input?.limit, 50, 500);
   const cursor = normalizeCursor(params.input?.cursor);
   const query = String(params.input?.query || "").trim().toLowerCase();
-  const archivedRoot = getSdkAgentArchivedSessionsDirPath(
-    params.projectRoot,
-    params.agentId,
+  const archivedRoot = get_sdk_agent_archived_sessions_dir_path(
+    params.project_root,
+    params.agent_id,
   );
 
-  if (!(await fs.pathExists(archivedRoot))) {
+  if (!(await params.files.path_exists(archivedRoot))) {
     return {
       items: [],
       total: 0,
-      hasMore: false,
+      has_more: false,
     };
   }
 
-  const entries = await fs.readdir(archivedRoot, { withFileTypes: true });
+  const entries = await params.files.read_directory(archivedRoot);
   const summaries: AgentSessionSummary[] = [];
 
   for (const entry of entries) {
-    if (!entry.isDirectory()) continue;
-    const sessionId = decodeMaybe(entry.name);
-    if (!sessionId) continue;
-    const meta_path = getSdkAgentArchivedSessionMetaPath(
-      params.projectRoot,
-      params.agentId,
-      sessionId,
+    if (!entry.is_directory) continue;
+    const session_id = decodeMaybe(entry.name);
+    if (!session_id) continue;
+    const meta_path = get_sdk_agent_archived_session_meta_path(
+      params.project_root,
+      params.agent_id,
+      session_id,
     );
-    const messages_path = getSdkAgentArchivedSessionMessagesPath(
-      params.projectRoot,
-      params.agentId,
-      sessionId,
+    const messages_path = get_sdk_agent_archived_session_messages_path(
+      params.project_root,
+      params.agent_id,
+      session_id,
     );
-    const persisted_metadata = await readSessionMetadataFromPath({
+    const persisted_metadata = await read_session_metadata_from_path({
       filePath: meta_path,
-      sessionId,
-      agentId: params.agentId,
+      session_id,
+      agent_id: params.agent_id,
+      files: params.files,
     });
     const metadata = await resolve_session_summary_metadata({
       metadata: persisted_metadata,
       messagesPath: messages_path,
       metaPath: meta_path,
       refresh: false,
+      files: params.files,
     });
     // 关键点（中文）：归档 session 不再生成新 title，仅读取归档目录内已有 meta。
-    const info = buildSessionInfo({
-      projectRoot: params.projectRoot,
-      agentId: params.agentId,
-      sessionId,
+    const info = build_session_info({
+      project_root: params.project_root,
+      agent_id: params.agent_id,
+      session_id,
       metadata,
       executing: false,
     });
     const summary: AgentSessionSummary = {
-      agentId: info.agentId,
-      sessionId: info.sessionId,
+      agent_id: info.agent_id,
+      session_id: info.session_id,
       ...(info.title ? { title: info.title } : {}),
-      ...(info.previewText ? { previewText: info.previewText } : {}),
-      messageCount: info.messageCount,
-      ...(typeof info.createdAt === "number" ? { createdAt: info.createdAt } : {}),
-      ...(typeof info.updatedAt === "number" ? { updatedAt: info.updatedAt } : {}),
-      ...(info.modelLabel ? { modelLabel: info.modelLabel } : {}),
+      ...(info.preview_text ? { preview_text: info.preview_text } : {}),
+      message_count: info.message_count,
+      ...(typeof info.created_at === "number" ? { created_at: info.created_at } : {}),
+      ...(typeof info.updated_at === "number" ? { updated_at: info.updated_at } : {}),
+      ...(info.model_label ? { model_label: info.model_label } : {}),
     };
 
     if (query) {
       const haystack = [
-        summary.sessionId,
+        summary.session_id,
         summary.title || "",
-        summary.previewText || "",
+        summary.preview_text || "",
       ]
         .join("\n")
         .toLowerCase();
@@ -781,7 +557,7 @@ export async function listArchivedAgentSessionSummaryPage(params: {
     summaries.push(summary);
   }
 
-  summaries.sort((left, right) => (right.updatedAt || 0) - (left.updatedAt || 0));
+  summaries.sort((left, right) => (right.updated_at || 0) - (left.updated_at || 0));
 
   const items = summaries.slice(cursor, cursor + limit);
   const nextOffset = cursor + items.length;
@@ -789,8 +565,8 @@ export async function listArchivedAgentSessionSummaryPage(params: {
     items,
     total: summaries.length,
     ...(nextOffset < summaries.length
-      ? { nextCursor: encodeCursor(nextOffset) }
+      ? { next_cursor: encodeCursor(nextOffset) }
       : {}),
-    hasMore: nextOffset < summaries.length,
+    has_more: nextOffset < summaries.length,
   };
 }