@downcity/agent 1.1.338 → 1.1.400

package/src/workspace/search/SearchToolError.ts

@@ -1,94 +0,0 @@
-/**
- * 搜索工具内部错误。
- *
- * 关键点（中文）
- * - 搜索运行时使用类型化错误中断，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/workspace/store/LocalAgentStore.ts

@@ -1,191 +0,0 @@
-/**
- * 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/tool/FileToolSchemas.ts

@@ -1,77 +0,0 @@
-/**
- * 文件工具输入 schema。
- *
- * 关键点（中文）
- * - schema 只描述模型可调用协议，不混入路径与文件系统逻辑。
- * - 参数名统一采用 snake_case，与现有 Shell tools 保持一致。
- */
-
-import { z } from "zod";
-
-/** read 工具输入 schema。 */
-export const read_file_tool_input_schema = z.object({
-  file_path: z
-    .string()
-    .min(1)
-    .describe("Project-relative or absolute file path. Paths outside the project root are rejected."),
-  offset: z
-    .number()
-    .int()
-    .min(0)
-    .optional()
-    .default(0)
-    .describe("Zero-based line offset. Defaults to 0."),
-  limit: z
-    .number()
-    .int()
-    .min(1)
-    .max(2000)
-    .optional()
-    .default(500)
-    .describe("Maximum lines to return. Defaults to 500 and cannot exceed 2000."),
-});
-
-/** write 工具输入 schema。 */
-export const write_file_tool_input_schema = z.object({
-  file_path: z
-    .string()
-    .min(1)
-    .describe("Project-relative or absolute file path. Paths outside the project root are rejected."),
-  content: z.string().describe("Complete UTF-8 text content to write."),
-  overwrite: z
-    .boolean()
-    .optional()
-    .default(false)
-    .describe("Whether an existing file may be atomically replaced. Defaults to false."),
-});
-
-/** 单项 edit 输入 schema。 */
-export const file_edit_operation_schema = z.object({
-  old_text: z
-    .string()
-    .min(1)
-    .max(10000)
-    .describe("Exact text that must occur exactly once in the original file."),
-  new_text: z
-    .string()
-    .max(50000)
-    .describe("Replacement text for the unique old_text match."),
-});
-
-/** edit 工具输入 schema。 */
-export const edit_file_tool_input_schema = z.object({
-  file_path: z
-    .string()
-    .min(1)
-    .describe("Project-relative or absolute file path. Paths outside the project root are rejected."),
-  edits: z
-    .array(file_edit_operation_schema)
-    .min(1)
-    .max(10)
-    .describe("One to ten non-overlapping exact replacements applied atomically."),
-  expected_sha256: z
-    .string()
-    .regex(/^[a-fA-F0-9]{64}$/)
-    .optional()
-    .describe("Optional SHA-256 returned by read. The edit is rejected if the file changed."),
-});

package/src/workspace/tool/FileTools.ts

@@ -1,91 +0,0 @@
-/**
- * 文件 AI SDK tools。
- *
- * 关键点（中文）
- * - 模型看到独立的 read/write/edit 工具，不需要构造 shell 命令。
- * - 工具只负责 schema 与 action 转发，文件语义由 FileActionRuntime 统一实现。
- */
-
-import path from "node:path";
-import { tool } from "ai";
-import type { ActionResult } from "@/types/action/ActionResult.js";
-import type {
-  EditFileToolInput,
-  EditFileToolResult,
-  FileToolRunner,
-  FileToolSet,
-  ReadFileToolInput,
-  ReadFileToolResult,
-  WriteFileToolInput,
-  WriteFileToolResult,
-} from "@/types/workspace/FileTool.js";
-import {
-  edit_file_tool_input_schema,
-  read_file_tool_input_schema,
-  write_file_tool_input_schema,
-} from "@/workspace/tool/FileToolSchemas.js";
-
-/** 创建 Workspace 持有的结构化文件工具。 */
-export function create_file_tools(runner: FileToolRunner): FileToolSet {
-  const read = tool({
-    description:
-      "Read a project file instead of using cat or sed. For a chat attachment, use the file part's url (the .downcity/... storage path) as path; filename is only the user's display name and is not a project path. Images and PDFs are attached to the next model step as local file parts. Text output is limited to 500 lines and 256KB by default; use offset and limit to continue. Other binary files return metadata only.",
-    inputSchema: read_file_tool_input_schema,
-    execute: async (
-      input: ReadFileToolInput,
-    ): Promise<ActionResult<ReadFileToolResult>> => {
-      const output = await runner.run_file_action({
-        action: "read",
-        input,
-      }) as ReadFileToolResult;
-      const messages: ActionResult<ReadFileToolResult>["messages"] = [];
-      if (
-        output.success &&
-        (output.type === "image" || output.mime_type === "application/pdf")
-      ) {
-        messages.push({
-          role: "user",
-          parts: [{
-            type: "file",
-            url: output.file_path,
-            mediaType: output.mime_type || "application/octet-stream",
-            filename: path.basename(output.file_path),
-          }],
-        });
-      }
-      return { output, messages };
-    },
-  });
-
-  const write = tool({
-    description:
-      "Create a new UTF-8 text file or atomically replace an existing file when overwrite=true. Parent directories are created automatically. Use edit for partial changes.",
-    inputSchema: write_file_tool_input_schema,
-    execute: async (
-      input: WriteFileToolInput,
-    ): Promise<ActionResult<WriteFileToolResult>> => {
-      const output = await runner.run_file_action({
-        action: "write",
-        input,
-      }) as WriteFileToolResult;
-      return { output, messages: [] };
-    },
-  });
-
-  const edit = tool({
-    description:
-      "Atomically edit one text file using exact replacements. Every edits[].old_text must match exactly once in the original file, and edit regions must not overlap. Combine separate changes to one file in a single call.",
-    inputSchema: edit_file_tool_input_schema,
-    execute: async (
-      input: EditFileToolInput,
-    ): Promise<ActionResult<EditFileToolResult>> => {
-      const output = await runner.run_file_action({
-        action: "edit",
-        input,
-      }) as EditFileToolResult;
-      return { output, messages: [] };
-    },
-  });
-
-  return { read, write, edit };
-}

package/src/workspace/tool/SearchToolSchemas.ts

@@ -1,62 +0,0 @@
-/**
- * 搜索工具输入 schema。
- *
- * 关键点（中文）
- * - schema 只描述模型可调用协议，路径校验与搜索逻辑由运行时负责。
- * - 参数名统一采用 snake_case，与其他 Shell tools 保持一致。
- */
-
-import { z } from "zod";
-
-/** grep 工具输入 schema。 */
-export const grep_tool_input_schema = z.object({
-  query: z.string().min(1).describe("Literal text or ripgrep regular expression to search for."),
-  path: z
-    .string()
-    .min(1)
-    .optional()
-    .default(".")
-    .describe("Project-relative or absolute file/directory path. Defaults to the project root."),
-  glob: z
-    .array(z.string().min(1))
-    .max(20)
-    .optional()
-    .describe("Optional ripgrep glob patterns used to include or exclude candidate files."),
-  case_sensitive: z
-    .boolean()
-    .optional()
-    .default(false)
-    .describe("Whether matching is case-sensitive. Defaults to false."),
-  literal: z
-    .boolean()
-    .optional()
-    .default(true)
-    .describe("Treat query as literal text. Set false to use ripgrep regular expressions."),
-  max_results: z
-    .number()
-    .int()
-    .min(1)
-    .max(2000)
-    .optional()
-    .default(200)
-    .describe("Maximum matches to return. Defaults to 200 and cannot exceed 2000."),
-});
-
-/** find 工具输入 schema。 */
-export const find_tool_input_schema = z.object({
-  pattern: z.string().min(1).describe("POSIX glob pattern used to discover files."),
-  path: z
-    .string()
-    .min(1)
-    .optional()
-    .default(".")
-    .describe("Project-relative or absolute directory to search. Defaults to the project root."),
-  max_results: z
-    .number()
-    .int()
-    .min(1)
-    .max(2000)
-    .optional()
-    .default(200)
-    .describe("Maximum files to return. Defaults to 200 and cannot exceed 2000."),
-});

package/src/workspace/tool/SearchTools.ts

@@ -1,61 +0,0 @@
-/**
- * 项目搜索 AI SDK tools。
- *
- * 关键点（中文）
- * - 模型通过独立的 `grep` / `find` 工具搜索内容和发现文件。
- * - 工具只负责 schema、abort signal 与 action 转发，搜索语义由运行时实现。
- */
-
-import { tool, type ToolExecutionOptions } from "ai";
-import type { ActionResult } from "@/types/action/ActionResult.js";
-import type {
-  FindToolInput,
-  FindToolResult,
-  GrepToolInput,
-  GrepToolResult,
-  SearchToolRunner,
-  SearchToolSet,
-} from "@/types/workspace/SearchTool.js";
-import {
-  find_tool_input_schema,
-  grep_tool_input_schema,
-} from "@/workspace/tool/SearchToolSchemas.js";
-
-/** 创建 Workspace 持有的结构化搜索工具。 */
-export function create_search_tools(runner: SearchToolRunner): SearchToolSet {
-  const grep = tool({
-    description:
-      "Search project file contents with ripgrep instead of running rg through the shell. Returns structured file, line, column, and matched text data; respects ignore files by default.",
-    inputSchema: grep_tool_input_schema,
-    execute: async (
-      input: GrepToolInput,
-      options: ToolExecutionOptions,
-    ): Promise<ActionResult<GrepToolResult>> => {
-      const output = await runner.run_search_action({
-        action: "grep",
-        input,
-        abort_signal: options.abortSignal,
-      }) as GrepToolResult;
-      return { output, messages: [] };
-    },
-  });
-
-  const find = tool({
-    description:
-      "Find project files with a POSIX glob pattern instead of running shell find. Respects .gitignore, includes dotfiles, and does not follow symbolic links.",
-    inputSchema: find_tool_input_schema,
-    execute: async (
-      input: FindToolInput,
-      options: ToolExecutionOptions,
-    ): Promise<ActionResult<FindToolResult>> => {
-      const output = await runner.run_search_action({
-        action: "find",
-        input,
-        abort_signal: options.abortSignal,
-      }) as FindToolResult;
-      return { output, messages: [] };
-    },
-  });
-
-  return { grep, find };
-}

package/src/workspace/tool/WorkspaceTools.ts

@@ -1,31 +0,0 @@
-/**
- * Workspace Tools 组合模块。
- *
- * 职责说明（中文）
- * - 统一创建当前 Workspace 的文件、搜索与可选 Shell 工具。
- * - 这里只组合 Workspace 资源，不注册 Plugin Tool 或调用方自定义 Tool。
- */
-
-import { create_file_tools } from "@/workspace/tool/FileTools.js";
-import { create_search_tools } from "@/workspace/tool/SearchTools.js";
-import type {
-  CreateWorkspaceToolsOptions,
-  WorkspaceTools,
-} from "@/types/workspace/WorkspaceTools.js";
-
-/** 创建当前 Workspace 的完整模型工具集合。 */
-export function create_workspace_tools(
-  options: CreateWorkspaceToolsOptions,
-): WorkspaceTools {
-  return {
-    ...create_file_tools({
-      run_file_action: async (request) =>
-        await options.files.run_file_action(request),
-    }),
-    ...create_search_tools({
-      run_search_action: async (request) =>
-        await options.files.run_search_action(request),
-    }),
-    ...(options.shell?.tools || {}),
-  };
-}