@downcity/agent 1.1.287 → 1.1.310

package/src/workspace/search/SearchToolError.ts

@@ -0,0 +1,94 @@
+/**
+ * 搜索工具内部错误。
+ *
+ * 关键点（中文）
+ * - 搜索运行时使用类型化错误中断，tool 边界统一转换为结构化失败结果。
+ * - 文件路径策略产生的错误会映射为搜索工具自己的稳定错误码。
+ */
+
+import { FileToolRuntimeError } from "@/workspace/file/FileToolError.js";
+import type {
+  SearchToolErrorCode,
+  SearchToolFailure,
+} from "@/types/workspace/SearchTool.js";
+
+/** 搜索工具可识别的内部错误。 */
+export class SearchToolRuntimeError extends Error {
+  /** 稳定的公共错误码。 */
+  readonly error_code: SearchToolErrorCode;
+  /** 已完成解析时的搜索绝对路径。 */
+  readonly search_path?: string;
+
+  constructor(params: {
+    /** 稳定的公共错误码。 */
+    error_code: SearchToolErrorCode;
+    /** 人类可读错误信息。 */
+    message: string;
+    /** 已完成解析时的搜索绝对路径。 */
+    search_path?: string;
+  }) {
+    super(params.message);
+    this.name = "SearchToolRuntimeError";
+    this.error_code = params.error_code;
+    this.search_path = params.search_path;
+  }
+}
+
+/** 把内部、文件路径或 Node.js 错误转换为稳定失败结果。 */
+export function to_search_tool_failure(
+  error: unknown,
+  fallback_search_path?: string,
+): SearchToolFailure {
+  if (error instanceof SearchToolRuntimeError) {
+    return {
+      success: false,
+      error_code: error.error_code,
+      message: error.message,
+      ...(error.search_path || fallback_search_path
+        ? { search_path: error.search_path || fallback_search_path }
+        : {}),
+    };
+  }
+  if (error instanceof FileToolRuntimeError) {
+    const error_code: SearchToolErrorCode = error.error_code === "file_not_found"
+      ? "path_not_found"
+      : error.error_code === "sandbox_denied"
+        ? "sandbox_denied"
+        : error.error_code === "invalid_path"
+          ? "invalid_path"
+          : "search_failed";
+    return {
+      success: false,
+      error_code,
+      message: error.message,
+      ...(error.file_path || fallback_search_path
+        ? { search_path: error.file_path || fallback_search_path }
+        : {}),
+    };
+  }
+
+  const node_error = error as NodeJS.ErrnoException;
+  const code = String(node_error?.code || "");
+  if (code === "ENOENT") {
+    return {
+      success: false,
+      error_code: "path_not_found",
+      message: `Search path not found: ${fallback_search_path || "unknown path"}`,
+      ...(fallback_search_path ? { search_path: fallback_search_path } : {}),
+    };
+  }
+  if (code === "EACCES" || code === "EPERM") {
+    return {
+      success: false,
+      error_code: "search_failed",
+      message: `Permission denied: ${fallback_search_path || "unknown path"}`,
+      ...(fallback_search_path ? { search_path: fallback_search_path } : {}),
+    };
+  }
+  return {
+    success: false,
+    error_code: "internal_error",
+    message: error instanceof Error ? error.message : String(error),
+    ...(fallback_search_path ? { search_path: fallback_search_path } : {}),
+  };
+}

package/src/{session/messages → workspace/store}/JsonlSessionMessageStore.ts

@@ -1,14 +1,11 @@
 /**
- * Session Message 的 Active + Segment JSONL 存储。
+ * Workspace Session Message 的 Active + Segment JSONL 存储。
  *
  * Active 保存上次 Compact 后产生的真实 Message；Compact 把 Active 前缀写入按
  * sequence 范围命名的不可变 Segment，并在 Segment 末尾追加累计 Summary footer。
  */
 
-import fs from "fs-extra";
-import { open, readFile, stat } from "node:fs/promises";
 import path from "node:path";
-import { generateId } from "@/utils/Id.js";
 import type { SessionAssistantMessage, SessionMessage } from "@/types/session/SessionMessage.js";
 import type {
   SessionMessageStorageStats,
@@ -16,40 +13,13 @@ import type {
   SessionSegmentSnapshot,
   SessionSegmentSummary,
 } from "@/types/session/SessionSegment.js";
-
-/** Active JSONL 存储构造参数。 */
-export interface JsonlSessionMessageStoreOptions {
-  /** 当前 Session 标识。 */
-  session_id: string;
-  /** active.jsonl 的绝对或相对路径。 */
-  file_path: string;
-  /** Assistant 运行中快照路径，默认与 active.jsonl 同目录。 */
-  assistant_message_file_path?: string;
-}
-
-/** 在写锁内计算新 Message 所需的状态。 */
-export interface SessionMessageCommitState {
-  /** 下一条真实 Message 的全局线性顺序。 */
-  message_sequence: number;
-  /** 当前 Active 与 Assistant 草稿组成的运行态 Message。 */
-  messages: SessionMessage[];
-}
-
-/** Compact 提交参数。 */
-export interface CompactActiveMessagesInput {
-  /** 移入新 Segment 的最后一条真实 Message sequence。 */
-  through_sequence: number;
-  /** 写在新 Segment 文件末尾的累计 Summary。 */
-  summary: SessionSegmentSummary;
-}
-
-/** Compact 提交结果。 */
-export interface CompactActiveMessagesResult {
-  /** 新创建的不可变 Segment。 */
-  segment: SessionSegmentSnapshot;
-  /** Compact 后继续留在 Active 的真实 Message。 */
-  active_messages: SessionMessage[];
-}
+import type {
+  CompactActiveMessagesInput,
+  CompactActiveMessagesResult,
+  SessionMessageCommitState,
+} from "@/types/store/SessionStore.js";
+import type { JsonlSessionMessageStoreOptions } from "@/types/store/LocalStore.js";
+import type { FileSystem } from "@/types/workspace/FileSystem.js";
 
 const SEGMENT_FILE_PATTERN = /^(\d+)-(\d+)\.jsonl$/;
 const SEQUENCE_FILE_WIDTH = 12;
@@ -62,8 +32,10 @@ export class JsonlSessionMessageStore {
   readonly segments_dir_path: string;
 
   private readonly lock_file_path: string;
+  private readonly files: FileSystem;
 
   constructor(options: JsonlSessionMessageStoreOptions) {
+    this.files = options.files;
     this.session_id = String(options.session_id || "").trim();
     this.active_file_path = path.resolve(options.file_path);
     this.assistant_message_file_path = path.resolve(
@@ -113,7 +85,7 @@ export class JsonlSessionMessageStore {
         finalized.revision >= draft.revision &&
         finalized.status !== "streaming"
       ) {
-        await fs.remove(this.assistant_message_file_path);
+        await this.files.remove_path(this.assistant_message_file_path);
       }
     });
   }
@@ -172,7 +144,7 @@ export class JsonlSessionMessageStore {
       null;
     const paths = [this.active_file_path, ...ranges.map((range) => range.file_path)];
     const sizes = await Promise.all(
-      paths.map(async (file_path) => await stat(file_path).then((value) => value.size).catch(() => 0)),
+      paths.map(async (file_path) => await this.files.file_size(file_path).catch(() => 0)),
     );
     const latest_sequence = Math.max(
       latest_range?.end_sequence || 0,
@@ -204,7 +176,9 @@ export class JsonlSessionMessageStore {
   /** 读取当前运行中的 Assistant 草稿。 */
   async read_assistant_message(): Promise<SessionAssistantMessage | null> {
     try {
-      const value = await fs.readJson(this.assistant_message_file_path) as SessionAssistantMessage;
+      const value = JSON.parse(
+        (await this.files.read_file(this.assistant_message_file_path)).toString("utf8"),
+      ) as SessionAssistantMessage;
       this.validate_message(value);
       return value.type === "assistant" && value.status === "streaming" ? value : null;
     } catch (error) {
@@ -270,7 +244,7 @@ export class JsonlSessionMessageStore {
         messages: current_messages,
       });
       this.validate_message(message);
-      await fs.appendFile(this.active_file_path, `${JSON.stringify(message)}\n`, "utf8");
+      await this.files.append_file(this.active_file_path, `${JSON.stringify(message)}\n`);
       return message;
     });
   }
@@ -287,8 +261,8 @@ export class JsonlSessionMessageStore {
       if (message.revision !== current.revision + 1) {
         throw new Error(`Invalid final Assistant revision: ${message.message_id}`);
       }
-      await fs.appendFile(this.active_file_path, `${JSON.stringify(message)}\n`, "utf8");
-      await fs.remove(this.assistant_message_file_path);
+      await this.files.append_file(this.active_file_path, `${JSON.stringify(message)}\n`);
+      await this.files.remove_path(this.assistant_message_file_path);
     });
   }
 
@@ -324,7 +298,7 @@ export class JsonlSessionMessageStore {
         end_sequence,
         file_path: this.segment_file_path(start_sequence, end_sequence),
       };
-      if (await fs.pathExists(range.file_path)) {
+      if (await this.files.path_exists(range.file_path)) {
         throw new Error(`Session Segment already exists: ${range.file_path}`);
       }
       await this.write_segment_unsafe(range, segment_messages, input.summary);
@@ -339,10 +313,10 @@ export class JsonlSessionMessageStore {
   /** 扫描 Segment 文件名并返回 sequence 升序索引。 */
   async list_segment_ranges(): Promise<SessionSegmentRange[]> {
     await this.ensure_layout();
-    const entries = await fs.readdir(this.segments_dir_path, { withFileTypes: true });
+    const entries = await this.files.read_directory(this.segments_dir_path);
     const ranges = entries
       .flatMap<SessionSegmentRange>((entry) => {
-        if (!entry.isFile()) return [];
+        if (!entry.is_file) return [];
         const match = SEGMENT_FILE_PATTERN.exec(entry.name);
         if (!match) return [];
         const start_sequence = Number(match[1]);
@@ -373,7 +347,7 @@ export class JsonlSessionMessageStore {
 
   /** 读取并验证一个不可变 Segment。 */
   private async read_segment(range: SessionSegmentRange): Promise<SessionSegmentSnapshot> {
-    const raw = await fs.readFile(range.file_path, "utf8");
+    const raw = (await this.files.read_file(range.file_path)).toString("utf8");
     const lines = raw.split("\n").map((line) => line.trim()).filter(Boolean);
     const summary_value = JSON.parse(lines.pop() || "null") as SessionSegmentSummary | null;
     this.validate_summary(summary_value, range.end_sequence);
@@ -408,7 +382,9 @@ export class JsonlSessionMessageStore {
 
   /** 读取 Active 原始行，并按 Message ID 保留最高 revision。 */
   private async read_folded_active_messages_unsafe(): Promise<SessionMessage[]> {
-    const raw = await fs.readFile(this.active_file_path, "utf8").catch(() => "");
+    const raw = await this.files.read_file(this.active_file_path)
+      .then((value) => value.toString("utf8"))
+      .catch(() => "");
     const by_id = new Map<string, SessionMessage>();
     for (const line of raw.split("\n")) {
       if (!line.trim()) continue;
@@ -431,19 +407,18 @@ export class JsonlSessionMessageStore {
 
   /** 原子覆盖 Assistant 草稿。 */
   private async write_assistant_message_unsafe(message: SessionAssistantMessage): Promise<void> {
-    const temporary_path = `${this.assistant_message_file_path}.${process.pid}.${Date.now()}.tmp`;
-    await fs.writeJson(temporary_path, message, { spaces: 2 });
-    await fs.move(temporary_path, this.assistant_message_file_path, { overwrite: true });
+    await this.files.write_file_atomically(
+      this.assistant_message_file_path,
+      `${JSON.stringify(message, null, 2)}\n`,
+    );
   }
 
   /** 原子覆盖 Active，只写入每个 Message 的最终 revision。 */
   private async write_active_messages_unsafe(messages: SessionMessage[]): Promise<void> {
-    const temporary_path = `${this.active_file_path}.${process.pid}.${Date.now()}.tmp`;
     const content = messages.length > 0
       ? `${messages.map((message) => JSON.stringify(message)).join("\n")}\n`
       : "";
-    await fs.writeFile(temporary_path, content, "utf8");
-    await fs.move(temporary_path, this.active_file_path, { overwrite: true });
+    await this.files.write_file_atomically(this.active_file_path, content);
   }
 
   /** 原子创建一个带累计 Summary footer 的 Segment。 */
@@ -452,13 +427,14 @@ export class JsonlSessionMessageStore {
     messages: SessionMessage[],
     summary: SessionSegmentSummary,
   ): Promise<void> {
-    const temporary_path = `${range.file_path}.${process.pid}.${Date.now()}.tmp`;
     const content = `${[
       ...messages.map((message) => JSON.stringify(message)),
       JSON.stringify(summary),
     ].join("\n")}\n`;
-    await fs.writeFile(temporary_path, content, "utf8");
-    await fs.move(temporary_path, range.file_path, { overwrite: false });
+    if (await this.files.path_exists(range.file_path)) {
+      throw new Error(`Session Segment already exists: ${range.file_path}`);
+    }
+    await this.files.write_file_atomically(range.file_path, content);
   }
 
   /** 生成稳定的 Segment sequence 范围文件名。 */
@@ -517,44 +493,17 @@ export class JsonlSessionMessageStore {
 
   /** 创建 Active、Segment 与锁所需目录。 */
   private async ensure_layout(): Promise<void> {
-    await fs.ensureDir(path.dirname(this.active_file_path));
-    await fs.ensureDir(this.segments_dir_path);
-    await fs.ensureFile(this.active_file_path);
+    await this.files.ensure_directory(path.dirname(this.active_file_path));
+    await this.files.ensure_directory(this.segments_dir_path);
+    if (!(await this.files.path_exists(this.active_file_path))) {
+      await this.files.write_file_atomically(this.active_file_path, "");
+    }
   }
 
   /** 使用同目录锁串行化 Active、草稿与 Segment 写入。 */
   private async with_write_lock<T>(callback: () => Promise<T>): Promise<T> {
     await this.ensure_layout();
-    const token = `${process.pid}:${Date.now()}:${generateId()}`;
-    const stale_ms = 30_000;
-    const started_at = Date.now();
-    while (true) {
-      try {
-        const file = await open(this.lock_file_path, "wx");
-        await file.writeFile(token, "utf8");
-        await file.close();
-        break;
-      } catch (error) {
-        if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
-        try {
-          const lock_stat = await stat(this.lock_file_path);
-          if (Date.now() - lock_stat.mtimeMs > stale_ms) await fs.remove(this.lock_file_path);
-        } catch { /* 锁文件可能刚被释放。 */ }
-        if (Date.now() - started_at > stale_ms * 2) {
-          throw new Error(`Session message lock timeout: ${this.lock_file_path}`);
-        }
-        await new Promise((resolve) => setTimeout(resolve, 40));
-      }
-    }
-    try {
-      return await callback();
-    } finally {
-      try {
-        if ((await readFile(this.lock_file_path, "utf8")).trim() === token) {
-          await fs.remove(this.lock_file_path);
-        }
-      } catch { /* 锁已被清理。 */ }
-    }
+    return await this.files.with_file_lock(this.lock_file_path, callback);
   }
 }
 

package/src/workspace/store/LocalAgentStore.ts

@@ -0,0 +1,191 @@
+/**
+ * LocalAgentStore：Workspace 内本地 Agent 领域数据入口。
+ *
+ * 职责说明（中文）
+ * - 统一管理 Session 创建判断、删除、列表、归档与清理。
+ * - 缓存稳定的 LocalSessionStore，避免同一 Session 重复创建 Message Store。
+ * - 当前阶段沿用既有本地目录布局；调用方和 Session 不感知该约定。
+ */
+
+import type {
+  AgentArchiveSessionResult,
+  AgentArchiveSessionsInput,
+  AgentArchiveSessionsResult,
+  AgentCleanArchiveResult,
+  AgentListSessionsInput,
+  AgentSessionSummaryPage,
+} from "@/types/agent/SessionTypes.js";
+import type { AgentStore } from "@/types/store/AgentStore.js";
+import type { SessionStore } from "@/types/store/SessionStore.js";
+import { LocalSessionStore } from "@/workspace/store/LocalSessionStore.js";
+import {
+  get_sdk_agent_archived_session_dir_path,
+  get_sdk_agent_archived_sessions_dir_path,
+  get_sdk_agent_session_dir_path,
+  get_sdk_agent_session_messages_dir_path,
+} from "@/workspace/store/LocalStorePaths.js";
+import {
+  list_archived_agent_session_summary_page,
+  list_agent_session_summary_page,
+} from "@/session/browse/Browse.js";
+import type { FileSystem } from "@/types/workspace/FileSystem.js";
+import type { LocalAgentStoreOptions } from "@/types/store/LocalStore.js";
+
+/** 解码目录中经过 URL 编码的 Session 标识。 */
+function decode_session_id(input: string): string {
+  try {
+    return decodeURIComponent(input);
+  } catch {
+    return input;
+  }
+}
+
+/** 默认本地 Agent Store。 */
+export class LocalAgentStore implements AgentStore {
+  /** 当前 Store 与 WorkspaceTools 共用的 Workspace 文件能力。 */
+  private readonly files: FileSystem;
+
+  /** 当前 Agent 的稳定标识。 */
+  private readonly agent_id: string;
+
+  /** 已创建的 Session Store 缓存。 */
+  private readonly sessions = new Map<string, LocalSessionStore>();
+
+  constructor(options: LocalAgentStoreOptions) {
+    this.files = options.files;
+    this.agent_id = options.agent_id;
+  }
+
+  /** 返回指定 Session 的稳定持久化视图。 */
+  session(session_id: string): SessionStore {
+    const resolved_session_id = String(session_id || "").trim();
+    if (!resolved_session_id) {
+      throw new Error("AgentStore.session requires a non-empty session_id");
+    }
+    const cached = this.sessions.get(resolved_session_id);
+    if (cached) return cached;
+    const created = new LocalSessionStore({
+      files: this.files,
+      agent_id: this.agent_id,
+      session_id: resolved_session_id,
+    });
+    this.sessions.set(resolved_session_id, created);
+    return created;
+  }
+
+  /** 判断活动 Session 是否存在。 */
+  async has_session(session_id: string): Promise<boolean> {
+    return await this.files.path_exists(this.session_path(session_id));
+  }
+
+  /** 永久删除活动 Session。 */
+  async remove_session(session_id: string): Promise<boolean> {
+    const session_path = this.session_path(session_id);
+    const existed = await this.files.path_exists(session_path);
+    if (existed) await this.files.remove_path(session_path);
+    this.sessions.delete(session_id);
+    return existed;
+  }
+
+  /** 清空活动 Session Message 数据。 */
+  async clear_session_messages(session_id: string): Promise<boolean> {
+    const messages_path = get_sdk_agent_session_messages_dir_path(
+      this.files.root_path,
+      this.agent_id,
+      session_id,
+    );
+    const existed = await this.files.path_exists(messages_path);
+    if (existed) await this.files.remove_path(messages_path);
+    this.sessions.delete(session_id);
+    return existed;
+  }
+
+  /** 返回活动 Session 摘要页。 */
+  async list_sessions(
+    input: AgentListSessionsInput | undefined,
+    executing_session_ids: ReadonlySet<string>,
+  ): Promise<AgentSessionSummaryPage> {
+    return await list_agent_session_summary_page({
+      project_root: this.files.root_path,
+      agent_id: this.agent_id,
+      input,
+      executingSessionIds: new Set(executing_session_ids),
+      files: this.files,
+    });
+  }
+
+  /** 将活动 Session 迁入归档区。 */
+  async archive_session(session_id: string): Promise<AgentArchiveSessionResult> {
+    const source_path = this.session_path(session_id);
+    if (!(await this.files.path_exists(source_path))) {
+      throw new Error(`Session "${session_id}" not found`);
+    }
+    const target_path = get_sdk_agent_archived_session_dir_path(
+      this.files.root_path,
+      this.agent_id,
+      session_id,
+    );
+    if (await this.files.path_exists(target_path)) {
+      throw new Error(`Archived session "${session_id}" already exists`);
+    }
+    await this.files.ensure_directory(get_sdk_agent_archived_sessions_dir_path(
+      this.files.root_path,
+      this.agent_id,
+    ));
+    await this.files.move_path(source_path, target_path);
+    this.sessions.delete(session_id);
+    return {
+      session_id: session_id,
+      archived_at: Date.now(),
+    };
+  }
+
+  /** 返回归档 Session 摘要页。 */
+  async list_archived_sessions(
+    input?: AgentArchiveSessionsInput,
+  ): Promise<AgentArchiveSessionsResult> {
+    return await list_archived_agent_session_summary_page({
+      project_root: this.files.root_path,
+      agent_id: this.agent_id,
+      input,
+      files: this.files,
+    });
+  }
+
+  /** 永久删除全部归档 Session。 */
+  async clean_archive(): Promise<AgentCleanArchiveResult> {
+    const archive_path = get_sdk_agent_archived_sessions_dir_path(
+      this.files.root_path,
+      this.agent_id,
+    );
+    if (!(await this.files.path_exists(archive_path))) {
+      return { removed_session_ids: [] };
+    }
+    const entries = await this.files.read_directory(archive_path);
+    const removed_session_ids: string[] = [];
+    for (const entry of entries) {
+      if (!entry.is_directory) continue;
+      const session_id = decode_session_id(entry.name);
+      if (!session_id) continue;
+      await this.files.remove_path(get_sdk_agent_archived_session_dir_path(
+        this.files.root_path,
+        this.agent_id,
+        session_id,
+      ));
+      removed_session_ids.push(session_id);
+    }
+    return { removed_session_ids: removed_session_ids };
+  }
+
+  /** 本地 JSONL Store 当前没有常驻句柄。 */
+  async dispose(): Promise<void> {}
+
+  /** 返回活动 Session 物理目录，仅供本地实现内部使用。 */
+  private session_path(session_id: string): string {
+    return get_sdk_agent_session_dir_path(
+      this.files.root_path,
+      this.agent_id,
+      session_id,
+    );
+  }
+}

package/src/workspace/store/LocalSessionStore.ts

@@ -0,0 +1,114 @@
+/**
+ * LocalSessionStore：Workspace 内单个 Session 的 JSONL 持久化视图。
+ *
+ * 职责说明（中文）
+ * - 集中创建 Message Store，并封装 Metadata 与 Instruction 的物理路径。
+ * - Session 领域只持有本对象，不再自行拼接任何存储路径。
+ */
+
+import { JsonlSessionMessageStore } from "@/workspace/store/JsonlSessionMessageStore.js";
+import {
+  get_sdk_agent_session_instruction_path,
+  get_sdk_agent_session_meta_path,
+  get_sdk_agent_session_assistant_message_path,
+  get_sdk_agent_session_messages_path,
+} from "@/workspace/store/LocalStorePaths.js";
+import { normalize_session_metadata } from "@/session/storage/Metadata.js";
+import type { SessionHistoryMetaV1 } from "@/executor/types/SessionHistoryMeta.js";
+import type { SessionStore } from "@/types/store/SessionStore.js";
+import type { FileSystem } from "@/types/workspace/FileSystem.js";
+import type { LocalSessionStoreOptions } from "@/types/store/LocalStore.js";
+
+/** 本地 Session Store。 */
+export class LocalSessionStore implements SessionStore {
+  /** 当前 Session 的稳定标识。 */
+  readonly session_id: string;
+
+  /** 当前 Session 的 JSONL Message Store。 */
+  readonly messages: JsonlSessionMessageStore;
+
+  /** 当前 Store 与 WorkspaceTools 共用的 Workspace 文件能力。 */
+  private readonly files: FileSystem;
+
+  /** 当前 Agent 的稳定标识。 */
+  private readonly agent_id: string;
+
+  constructor(options: LocalSessionStoreOptions) {
+    this.files = options.files;
+    this.agent_id = options.agent_id;
+    this.session_id = options.session_id;
+    this.messages = new JsonlSessionMessageStore({
+      files: this.files,
+      session_id: this.session_id,
+      file_path: get_sdk_agent_session_messages_path(
+        this.files.root_path,
+        this.agent_id,
+        this.session_id,
+      ),
+      assistant_message_file_path: get_sdk_agent_session_assistant_message_path(
+        this.files.root_path,
+        this.agent_id,
+        this.session_id,
+      ),
+    });
+  }
+
+  /** 读取规范化 Session Metadata。 */
+  async read_metadata(): Promise<SessionHistoryMetaV1> {
+    try {
+      const raw = JSON.parse(
+        (await this.files.read_file(this.metadata_path())).toString("utf8"),
+      ) as Partial<SessionHistoryMetaV1>;
+      return normalize_session_metadata(raw, this.session_id, this.agent_id);
+    } catch {
+      return normalize_session_metadata({}, this.session_id, this.agent_id);
+    }
+  }
+
+  /** 写入完整 Session Metadata。 */
+  async write_metadata(metadata: SessionHistoryMetaV1): Promise<void> {
+    await this.files.write_file_atomically(
+      this.metadata_path(),
+      `${JSON.stringify(metadata, null, 2)}\n`,
+    );
+  }
+
+  /** 判断显式 system 快照是否存在。 */
+  async has_instruction(): Promise<boolean> {
+    return await this.files.path_exists(this.instruction_path());
+  }
+
+  /** 读取显式 system 快照。 */
+  async read_instruction(): Promise<string | null> {
+    if (!(await this.has_instruction())) return null;
+    return (await this.files.read_file(this.instruction_path())).toString("utf8");
+  }
+
+  /** 写入显式 system 快照。 */
+  async write_instruction(instruction: string): Promise<void> {
+    const instruction_path = get_sdk_agent_session_instruction_path(
+      this.files.root_path,
+      this.agent_id,
+      this.session_id,
+    );
+    await this.files.write_file_atomically(instruction_path, instruction);
+  }
+
+  /** 返回当前 Session instruction.md 的 Workspace 路径。 */
+  private instruction_path(): string {
+    return get_sdk_agent_session_instruction_path(
+      this.files.root_path,
+      this.agent_id,
+      this.session_id,
+    );
+  }
+
+  /** 返回当前 Session meta.json 的 Workspace 路径。 */
+  private metadata_path(): string {
+    return get_sdk_agent_session_meta_path(
+      this.files.root_path,
+      this.agent_id,
+      this.session_id,
+    );
+  }
+}