@downcity/agent 1.1.287 → 1.1.310

package/src/types/session/SessionPort.ts

@@ -11,10 +11,7 @@ import type {
   SessionMetadataV1,
   SessionRecordV1,
 } from "@/executor/types/SessionRecords.js";
-import type {
-  SessionRunInput,
-  SessionRunResult,
-} from "@/executor/types/SessionRun.js";
+import type { SessionExecutor } from "@/types/session/SessionExecution.js";
 import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
 import type { AgentSessionStopResult } from "@/types/sdk/AgentSessionStop.js";
 import type { AgentSessionTurnHandle } from "@/types/sdk/AgentSessionTurn.js";
@@ -24,33 +21,18 @@ import type {
 } from "@/types/session/SessionMutation.js";
 import type { SessionContextSnapshot } from "@/types/session/SessionSegment.js";
 
-/**
- * 单个 Session 执行端口。
- */
-export interface SessionExecutorPort {
-  /** 执行一次 Session run。 */
-  run(params: SessionRunInput): Promise<SessionRunResult>;
-
-  /**
-   * 请求取消当前正在执行的 turn。
-   *
-   * @returns `true` 表示已发出取消请求；`false` 表示当前没有可取消的执行。
-   */
-  stop(): boolean;
-}
-
 /**
  * 单个 Session 实例端口。
  */
 export interface SessionPort {
   /** 当前 Session 稳定标识。 */
-  readonly sessionId: string;
+  readonly session_id: string;
 
   /** 获取当前 Session 优先解析后的运行时模型实例。 */
-  getModel(): LanguageModel | undefined;
+  get_model(): LanguageModel | undefined;
 
   /** 获取当前 Session 的执行端口。 */
-  getExecutor(): SessionExecutorPort;
+  get_executor(): SessionExecutor;
 
   /** 读取当前 Session 的累计 Summary 与 Active Message 快照。 */
   context(): Promise<SessionContextSnapshot>;
@@ -86,12 +68,12 @@ export interface SessionPort {
     message?: SessionRecordV1 | null;
 
     /** 未传入完整消息时使用的兜底文本。 */
-    fallbackText?: string;
+    fallback_text?: string;
 
     /** 当前消息附加元数据。 */
     extra?: SessionMetadataV1["extra"];
   }): Promise<void>;
 
   /** 返回当前 Session 是否正在执行。 */
-  isExecuting(): boolean;
+  is_executing(): boolean;
 }

package/src/types/session/SessionState.ts

@@ -6,20 +6,19 @@
 
 import type { LanguageModel } from "ai";
 import type { SessionMessages } from "@/session/SessionMessages.js";
-import type { AgentSessionConfigSnapshot } from "@/types/agent/SessionTypes.js";
 import type { SessionLocalState } from "@/types/session/SessionLocalState.js";
 import type { SessionMutation } from "@/types/session/SessionMutation.js";
-import type { SessionQueueCommand } from "@/types/session/SessionQueue.js";
 import type { Logger } from "@/utils/logger/Logger.js";
+import type { SessionStore } from "@/types/store/SessionStore.js";
 
 /** SessionState 构造参数。 */
 export interface SessionStateOptions {
   /** 当前 Agent 的稳定标识。 */
   agent_id: string;
-  /** 当前项目的绝对根目录。 */
-  project_root: string;
   /** 当前 Session 的稳定标识。 */
   session_id: string;
+  /** 当前 Session 独享的领域持久化视图。 */
+  store: SessionStore;
   /** 当前 Session 的 canonical Message 入口。 */
   messages: SessionMessages;
   /** 当前 Session 的可变内存状态。 */
@@ -33,15 +32,3 @@ export interface SessionStateOptions {
   /** 发布 Session Mutation 的函数。 */
   publish_event: (mutation: SessionMutation) => void;
 }
-
-/** Session 配置写入选项。 */
-export interface SessionSetOptions {
-  /** 是否为本次配置变化生成 Model Switching Action。 */
-  emit_action?: boolean;
-}
-
-/** Session 配置成功写入后的队列提交结果。 */
-export interface SessionConfiguredCommandResult {
-  /** 等待在下一 Session Step 检查点执行的 Command。 */
-  command?: SessionQueueCommand;
-}

package/src/types/store/AgentStore.ts

@@ -0,0 +1,52 @@
+/**
+ * Agent Store 类型。
+ *
+ * 关键点（中文）
+ * - AgentSessions 只通过该接口管理 Session 生命周期和索引。
+ * - 接口不暴露物理目录，避免 Session 领域重新依赖路径约定。
+ */
+
+import type {
+  AgentArchiveSessionResult,
+  AgentArchiveSessionsInput,
+  AgentArchiveSessionsResult,
+  AgentCleanArchiveResult,
+  AgentListSessionsInput,
+  AgentSessionSummaryPage,
+} from "@/types/agent/SessionTypes.js";
+import type { SessionStore } from "@/types/store/SessionStore.js";
+
+/** Agent 领域持久化入口。 */
+export interface AgentStore {
+  /** 返回指定 Session 的稳定持久化视图。 */
+  session(session_id: string): SessionStore;
+
+  /** 判断活动 Session 是否存在。 */
+  has_session(session_id: string): Promise<boolean>;
+
+  /** 永久删除活动 Session 的全部领域数据。 */
+  remove_session(session_id: string): Promise<boolean>;
+
+  /** 清空活动 Session 的 Message 数据。 */
+  clear_session_messages(session_id: string): Promise<boolean>;
+
+  /** 返回活动 Session 摘要页。 */
+  list_sessions(
+    input: AgentListSessionsInput | undefined,
+    executing_session_ids: ReadonlySet<string>,
+  ): Promise<AgentSessionSummaryPage>;
+
+  /** 将活动 Session 原子迁入归档区。 */
+  archive_session(session_id: string): Promise<AgentArchiveSessionResult>;
+
+  /** 返回已归档 Session 摘要页。 */
+  list_archived_sessions(
+    input?: AgentArchiveSessionsInput,
+  ): Promise<AgentArchiveSessionsResult>;
+
+  /** 永久删除全部归档 Session。 */
+  clean_archive(): Promise<AgentCleanArchiveResult>;
+
+  /** 刷新并释放当前 Store 持有的资源。 */
+  dispose(): Promise<void>;
+}

package/src/types/store/LocalStore.ts

@@ -0,0 +1,39 @@
+/**
+ * 本地 Workspace Store 实现的构造类型。
+ *
+ * 关键点（中文）
+ * - 本地 Store 只接收 Workspace 已创建的 FileSystem，不单独接收存储根目录。
+ * - AgentStore 与 SessionStore 因而始终和 WorkspaceTools 使用同一资源容器。
+ */
+
+import type { FileSystem } from "@/types/workspace/FileSystem.js";
+
+/** LocalAgentStore 构造参数。 */
+export interface LocalAgentStoreOptions {
+  /** 当前 Store 与 WorkspaceTools 共用的 Workspace 文件能力。 */
+  files: FileSystem;
+  /** 当前 Agent 的稳定标识，用于划分 `.downcity/agents` 子目录。 */
+  agent_id: string;
+}
+
+/** LocalSessionStore 构造参数。 */
+export interface LocalSessionStoreOptions {
+  /** 当前 Store 与 WorkspaceTools 共用的 Workspace 文件能力。 */
+  files: FileSystem;
+  /** 当前 Session 所属 Agent 的稳定标识。 */
+  agent_id: string;
+  /** 当前 Session 的稳定标识。 */
+  session_id: string;
+}
+
+/** JsonlSessionMessageStore 构造参数。 */
+export interface JsonlSessionMessageStoreOptions {
+  /** 当前 Message Store 与 Session 共用的 Workspace 文件能力。 */
+  files: FileSystem;
+  /** 当前 Session 的稳定标识。 */
+  session_id: string;
+  /** Active JSONL 文件的绝对路径。 */
+  file_path: string;
+  /** Assistant 运行中快照的可选绝对路径。 */
+  assistant_message_file_path?: string;
+}

package/src/types/store/SessionStore.ts

@@ -0,0 +1,105 @@
+/**
+ * Session Store 类型。
+ *
+ * 关键点（中文）
+ * - Session 领域只依赖这些持久化能力，不感知 JSONL、目录或文件名。
+ * - Message、Metadata 与 Instruction 共享同一个 Session 生命周期边界。
+ */
+
+import type { SessionHistoryMetaV1 } from "@/executor/types/SessionHistoryMeta.js";
+import type {
+  SessionAssistantMessage,
+  SessionMessage,
+} from "@/types/session/SessionMessage.js";
+import type {
+  SessionMessageStorageStats,
+  SessionSegmentRange,
+  SessionSegmentSnapshot,
+  SessionSegmentSummary,
+} from "@/types/session/SessionSegment.js";
+
+/** 在 Message Store 写事务中创建新消息所需的稳定状态。 */
+export interface SessionMessageCommitState {
+  /** 下一条真实 Message 应使用的全局线性顺序。 */
+  message_sequence: number;
+  /** 当前 Active 与 Assistant 草稿组成的运行态 Message。 */
+  messages: SessionMessage[];
+}
+
+/** Active Message 压缩提交参数。 */
+export interface CompactActiveMessagesInput {
+  /** 移入新 Segment 的最后一条真实 Message sequence。 */
+  through_sequence: number;
+  /** 写入新 Segment 末尾的累计上下文摘要。 */
+  summary: SessionSegmentSummary;
+}
+
+/** Active Message 压缩提交结果。 */
+export interface CompactActiveMessagesResult {
+  /** 本次创建的不可变历史分段。 */
+  segment: SessionSegmentSnapshot;
+  /** 压缩后继续保留在 Active 区域的 Message。 */
+  active_messages: SessionMessage[];
+}
+
+/** Session Message 持久化能力。 */
+export interface SessionMessageStore {
+  /** 初始化消息存储，并修复可恢复的中断状态。 */
+  initialize(): Promise<void>;
+  /** 读取当前 Active Message 与运行中的 Assistant 草稿。 */
+  list_messages(): Promise<SessionMessage[]>;
+  /** 读取指定 sequence 之前最近的完整历史分段。 */
+  read_segment_before(before_sequence: number): Promise<SessionSegmentSnapshot | null>;
+  /** 读取最新历史分段的累计摘要。 */
+  read_latest_summary(): Promise<SessionSegmentSummary | null>;
+  /** 读取当前 Session 的全部真实历史消息。 */
+  list_history_messages(): Promise<SessionMessage[]>;
+  /** 读取消息数量、存储大小与最新消息统计。 */
+  stats(): Promise<SessionMessageStorageStats>;
+  /** 判断指定 sequence 之前是否存在历史分段。 */
+  has_segment_before(before_sequence: number): Promise<boolean>;
+  /** 计算当前 Active Message 之前的读取边界。 */
+  active_before_sequence(messages: SessionMessage[]): Promise<number | undefined>;
+  /** 读取当前运行中的 Assistant 草稿。 */
+  read_assistant_message(): Promise<SessionAssistantMessage | null>;
+  /** 原子覆盖当前运行中的 Assistant 草稿。 */
+  write_assistant_message(message: SessionAssistantMessage): Promise<void>;
+  /** 在存储事务中创建唯一 Assistant 草稿。 */
+  create_assistant_message(
+    build_message: (state: SessionMessageCommitState) => SessionAssistantMessage,
+  ): Promise<SessionAssistantMessage>;
+  /** 在存储事务中追加一条 Message。 */
+  append_message(
+    build_message: (state: SessionMessageCommitState) => SessionMessage,
+  ): Promise<SessionMessage>;
+  /** 提交最终 Assistant Message 并删除运行中草稿。 */
+  finalize_assistant_message(message: SessionAssistantMessage): Promise<void>;
+  /** 将 Active 前缀压缩为不可变历史分段。 */
+  compact_active(input: CompactActiveMessagesInput): Promise<CompactActiveMessagesResult>;
+  /** 读取全部历史分段的 sequence 索引。 */
+  list_segment_ranges(): Promise<SessionSegmentRange[]>;
+}
+
+/** 单个 Session 的领域持久化视图。 */
+export interface SessionStore {
+  /** 当前 Session 的稳定标识。 */
+  readonly session_id: string;
+
+  /** 当前 Session 的 Message 持久化能力。 */
+  readonly messages: SessionMessageStore;
+
+  /** 读取 Session Metadata；不存在时返回规范化的初始值。 */
+  read_metadata(): Promise<SessionHistoryMetaV1>;
+
+  /** 原子写入完整 Session Metadata。 */
+  write_metadata(metadata: SessionHistoryMetaV1): Promise<void>;
+
+  /** 判断 Session 是否存在显式固化的完整 system。 */
+  has_instruction(): Promise<boolean>;
+
+  /** 读取显式固化的完整 system；不存在时返回 null。 */
+  read_instruction(): Promise<string | null>;
+
+  /** 原子写入显式固化的完整 system。 */
+  write_instruction(instruction: string): Promise<void>;
+}

package/src/types/tools/ask/AskQuestionsTool.ts

@@ -0,0 +1,27 @@
+/**
+ * ask_question Tool 的输入与输出协议。
+ *
+ * 该协议只描述模型发起问题和收到回答时可见的数据；Interaction 标识、Turn 标识与
+ * 生命周期状态由 Session 运行时维护，不交给模型生成。
+ */
+
+import type {
+  SessionInteractionAnswer,
+  SessionInteractionQuestion,
+} from "@/types/session/SessionInteraction.js";
+
+/** 模型调用 ask_question 时提交的结构化输入。 */
+export interface AskQuestionsToolInput {
+  /** 问题卡片向用户展示的简短标题。 */
+  title: string;
+  /** 本次需要用户完整回答的一到多条问题。 */
+  questions: SessionInteractionQuestion[];
+}
+
+/** 用户完成回答后返回给模型的结构化 Tool Result。 */
+export interface AskQuestionsToolOutput {
+  /** 当前提问已由用户完整回答。 */
+  status: "resolved";
+  /** 按 question_id 关联的完整回答集合。 */
+  answers: SessionInteractionAnswer[];
+}

package/src/types/workspace/FileSystem.ts

@@ -0,0 +1,76 @@
+/**
+ * Workspace 文件系统类型。
+ *
+ * 关键点（中文）
+ * - 文件与搜索共享同一个已解析项目根目录。
+ * - WorkspaceTools 与 AgentStore 共用这一文件能力，不建立额外存储根目录。
+ */
+
+import type {
+  FileToolActionRequest,
+  FileToolActionResult,
+} from "@/types/workspace/FileTool.js";
+import type {
+  SearchToolActionRequest,
+  SearchToolActionResult,
+} from "@/types/workspace/SearchTool.js";
+
+/** Workspace 目录中的稳定条目摘要。 */
+export interface WorkspaceDirectoryEntry {
+  /** 当前条目的原始文件名。 */
+  name: string;
+  /** 当前条目是否为普通目录。 */
+  is_directory: boolean;
+  /** 当前条目是否为普通文件。 */
+  is_file: boolean;
+}
+
+/** Workspace 内统一的文件与搜索能力。 */
+export interface FileSystem {
+  /** 已解析且不可变的项目根目录。 */
+  readonly root_path: string;
+
+  /** 将 Workspace 内的相对路径片段解析为本地绝对路径。 */
+  resolve_path(...segments: string[]): string;
+
+  /** 判断 Workspace 内的文件或目录是否存在。 */
+  path_exists(file_path: string): Promise<boolean>;
+
+  /** 读取 Workspace 内文件的完整字节内容。 */
+  read_file(file_path: string): Promise<Buffer>;
+
+  /** 读取 Workspace 内普通文件的字节大小。 */
+  file_size(file_path: string): Promise<number>;
+
+  /** 创建 Workspace 内目录及缺失的父目录。 */
+  ensure_directory(directory_path: string): Promise<void>;
+
+  /** 删除 Workspace 内文件或目录；目标不存在时视为成功。 */
+  remove_path(target_path: string): Promise<void>;
+
+  /** 原子移动 Workspace 内的文件或目录，不覆盖已有目标。 */
+  move_path(source_path: string, target_path: string): Promise<void>;
+
+  /** 读取 Workspace 内目录的直接子条目。 */
+  read_directory(directory_path: string): Promise<WorkspaceDirectoryEntry[]>;
+
+  /** 原子创建或覆盖 Workspace 内的完整文件内容。 */
+  write_file_atomically(file_path: string, content: string | Buffer): Promise<void>;
+
+  /** 向 Workspace 文件末尾追加完整字节内容。 */
+  append_file(file_path: string, content: string | Buffer): Promise<void>;
+
+  /**
+   * 使用 Workspace 内的独占锁串行执行文件事务。
+   *
+   * @param lock_path 锁文件路径；调用完成后由 FileSystem 自动释放。
+   * @param action 获得锁后执行的事务；异常会原样向调用方抛出。
+   */
+  with_file_lock<T>(lock_path: string, action: () => Promise<T>): Promise<T>;
+
+  /** 执行一次受项目根目录限制的结构化文件操作。 */
+  run_file_action(request: FileToolActionRequest): Promise<FileToolActionResult>;
+
+  /** 执行一次受项目根目录限制的结构化搜索操作。 */
+  run_search_action(request: SearchToolActionRequest): Promise<SearchToolActionResult>;
+}

package/src/types/workspace/FileTool.ts

@@ -0,0 +1,225 @@
+/**
+ * 文件工具公开类型。
+ *
+ * 关键点（中文）
+ * - 文件工具由 Workspace 持有，与 Shell/PTY action 分离。
+ * - 所有模型可见字段统一使用 snake_case。
+ * - 成功与失败均返回结构化结果，避免依赖异常文本判断执行状态。
+ */
+
+import type { Tool } from "ai";
+
+/** 文件工具支持的结构化错误码。 */
+export type FileToolErrorCode =
+  | "invalid_path"
+  | "sandbox_denied"
+  | "file_not_found"
+  | "not_a_file"
+  | "permission_denied"
+  | "file_exists"
+  | "file_too_large"
+  | "content_too_large"
+  | "line_too_large"
+  | "encoding_error"
+  | "binary_file"
+  | "no_edits"
+  | "too_many_edits"
+  | "duplicate_match"
+  | "not_found"
+  | "overlapping_edits"
+  | "edit_too_large"
+  | "file_changed"
+  | "internal_error";
+
+/** 文件读取工具输入。 */
+export interface ReadFileToolInput {
+  /** 要读取的项目内相对路径或绝对路径。 */
+  file_path: string;
+  /** 从第几行开始读取，使用 0-based 行号。 */
+  offset?: number;
+  /** 本次最多返回的行数。 */
+  limit?: number;
+}
+
+/** 文件写入工具输入。 */
+export interface WriteFileToolInput {
+  /** 要创建或覆盖的项目内相对路径或绝对路径。 */
+  file_path: string;
+  /** 要写入的 UTF-8 文本内容。 */
+  content: string;
+  /** 文件存在时是否允许覆盖，默认不允许。 */
+  overwrite?: boolean;
+}
+
+/** 单项精确文本编辑。 */
+export interface FileEditOperation {
+  /** 必须在原文件中唯一匹配的原始文本。 */
+  old_text: string;
+  /** 用于替换唯一匹配区域的新文本。 */
+  new_text: string;
+}
+
+/** 文件编辑工具输入。 */
+export interface EditFileToolInput {
+  /** 要编辑的项目内相对路径或绝对路径。 */
+  file_path: string;
+  /** 一次原子应用的精确文本编辑列表。 */
+  edits: FileEditOperation[];
+  /** 可选的读取时 SHA-256；文件变化后拒绝编辑。 */
+  expected_sha256?: string;
+}
+
+/** 文件工具统一失败结果。 */
+export interface FileToolFailure {
+  /** 表示本次文件操作失败。 */
+  success: false;
+  /** 供模型和调用方稳定解析的错误码。 */
+  error_code: FileToolErrorCode;
+  /** 面向模型和日志的人类可读错误信息。 */
+  message: string;
+  /** 已完成解析时的目标绝对路径。 */
+  file_path?: string;
+  /** 编辑失败时每项匹配的详细结果。 */
+  details?: FileEditDetail[];
+}
+
+/** 文件读取成功结果。 */
+export interface ReadFileToolSuccess {
+  /** 表示本次文件读取成功。 */
+  success: true;
+  /** 解析并校验后的目标绝对路径。 */
+  file_path: string;
+  /** 原始文件总字节数。 */
+  total_bytes: number;
+  /** 文本文件总行数；图片和其他二进制文件固定为 0。 */
+  total_lines: number;
+  /** 本次返回内容的 0-based 起始行。 */
+  start_line: number;
+  /** 本次返回内容的 0-based 结束行；没有返回行时小于 start_line。 */
+  end_line: number;
+  /** 返回给模型的文本内容；图片和其他二进制文件为空字符串。 */
+  content: string;
+  /** 是否还有后续文本行未返回。 */
+  truncated: boolean;
+  /** 有后续文本时建议下一次使用的 offset。 */
+  next_offset?: number;
+  /** 当前文件被识别为文本、图片还是其他二进制文件。 */
+  type: "text" | "image" | "binary";
+  /** 当前文件的 MIME 类型。 */
+  mime_type?: string;
+  /** 文本文件实际采用的解码格式。 */
+  encoding?: "utf-8" | "utf-16le" | "utf-16be";
+  /** 原始文件内容的 SHA-256，可传给 edit 防止并发覆盖。 */
+  sha256: string;
+}
+
+/** 文件写入成功结果。 */
+export interface WriteFileToolSuccess {
+  /** 表示本次文件写入成功。 */
+  success: true;
+  /** 解析并校验后的目标绝对路径。 */
+  file_path: string;
+  /** 实际写入的 UTF-8 字节数。 */
+  bytes_written: number;
+  /** 实际写入的文本行数。 */
+  lines_written: number;
+  /** 本次操作是否覆盖了已有文件。 */
+  overwritten: boolean;
+  /** 写入完成后的 ISO 时间戳。 */
+  timestamp: string;
+  /** 写入后文件内容的 SHA-256。 */
+  sha256: string;
+}
+
+/** 单项编辑匹配详情。 */
+export interface FileEditDetail {
+  /** 当前编辑项的原始索引。 */
+  index: number;
+  /** 当前编辑项的匹配与应用状态。 */
+  status: "applied" | "not_found" | "duplicate";
+  /** 当前 old_text 在原文件中的匹配次数。 */
+  match_count: number;
+  /** 唯一匹配成功时的 0-based 起始行。 */
+  line_start?: number;
+}
+
+/** 文件编辑成功结果。 */
+export interface EditFileToolSuccess {
+  /** 表示全部编辑已原子应用。 */
+  success: true;
+  /** 解析并校验后的目标绝对路径。 */
+  file_path: string;
+  /** 成功应用的编辑数量。 */
+  applied: number;
+  /** 每项编辑的匹配与应用详情。 */
+  details: FileEditDetail[];
+  /** 编辑后文件的总行数。 */
+  new_total_lines: number;
+  /** 编辑前文件内容的 SHA-256。 */
+  previous_sha256: string;
+  /** 编辑后文件内容的 SHA-256。 */
+  sha256: string;
+}
+
+/** 文件读取工具结果。 */
+export type ReadFileToolResult = ReadFileToolSuccess | FileToolFailure;
+
+/** 文件写入工具结果。 */
+export type WriteFileToolResult = WriteFileToolSuccess | FileToolFailure;
+
+/** 文件编辑工具结果。 */
+export type EditFileToolResult = EditFileToolSuccess | FileToolFailure;
+
+/** 文件工具内部 action 名称。 */
+export type FileToolAction = "read" | "write" | "edit";
+
+/** 文件 action 的判别式请求。 */
+export type FileToolActionRequest =
+  | {
+      /** 指定执行文件读取。 */
+      action: "read";
+      /** 文件读取输入。 */
+      input: ReadFileToolInput;
+    }
+  | {
+      /** 指定执行文件写入。 */
+      action: "write";
+      /** 文件写入输入。 */
+      input: WriteFileToolInput;
+    }
+  | {
+      /** 指定执行文件编辑。 */
+      action: "edit";
+      /** 文件编辑输入。 */
+      input: EditFileToolInput;
+    };
+
+/** 文件 action 的统一结果。 */
+export type FileToolActionResult =
+  | ReadFileToolResult
+  | WriteFileToolResult
+  | EditFileToolResult;
+
+/** 文件工具运行器协议。 */
+export interface FileToolRunner {
+  /** 执行一个独立文件 action。 */
+  run_file_action(request: FileToolActionRequest): Promise<FileToolActionResult>;
+}
+
+/** `@downcity/shell` 对模型暴露的文件工具集合。 */
+export interface FileToolSet {
+  /** 分页读取文本并识别二进制文件。 */
+  read: Tool;
+  /** 创建或显式覆盖 UTF-8 文本文件。 */
+  write: Tool;
+  /** 通过唯一文本匹配原子编辑单个文件。 */
+  edit: Tool;
+}
+
+/** 已通过项目根目录约束的文件工具路径。 */
+export interface ResolvedFileToolPath {
+  /** 解析后的目标绝对路径。 */
+  file_path: string;
+  /** 解析后的项目根目录绝对路径。 */
+  root_path: string;
+}