@downcity/agent 1.1.113 → 1.1.119

package/src/executor/tools/shell/types/Shell.ts

@@ -1,123 +0,0 @@
-/**
- * Shell 工具类型定义。
- *
- * 关键点（中文）
- * - 统一沉淀 `shell_start/shell_status/shell_read/shell_write/shell_wait/shell_close` 类型。
- * - `shell_id` 与 chat `sessionId` 严格分离，避免语义混淆。
- */
-
-/**
- * shell 执行 sandbox 模式。
- */
-export type ShellSandboxMode = "safe" | "unrestricted";
-
-/**
- * shell unrestricted sandbox 申请原因。
- */
-export type ShellUnrestrictedReason = string;
-
-/**
- * 启动一个交互式 shell session 的输入。
- */
-export type ShellStartInput = {
-  /** 要启动的命令文本。 */
-  cmd: string;
-  /** shell 进程的工作目录。 */
-  workdir?: string;
-  /** 显式指定 shell 可执行文件。 */
-  shell?: string;
-  /** 是否使用 login shell 语义启动。 */
-  login?: boolean;
-  /** 启动后内联等待输出的毫秒数。 */
-  inline_wait_ms?: number;
-  /** 最多返回多少输出 token。 */
-  max_output_tokens?: number;
-  /** 进程退出时是否自动通知调用方。 */
-  auto_notify_on_exit?: boolean;
-  /** 命令执行 sandbox 模式；默认 safe。 */
-  sandbox?: ShellSandboxMode;
-  /** 请求 unrestricted sandbox 时展示给用户的原因。 */
-  reason?: string;
-};
-
-/**
- * 执行一次非持久 shell 命令的输入。
- */
-export type ShellExecInput = {
-  /** 要执行的命令文本。 */
-  cmd: string;
-  /** 命令执行工作目录。 */
-  workdir?: string;
-  /** 显式指定 shell 可执行文件。 */
-  shell?: string;
-  /** 是否使用 login shell 语义启动。 */
-  login?: boolean;
-  /** 本次命令执行超时时间。 */
-  timeout_ms?: number;
-  /** 最多返回多少输出 token。 */
-  max_output_tokens?: number;
-  /** 命令执行 sandbox 模式；默认 safe。 */
-  sandbox?: ShellSandboxMode;
-  /** 请求 unrestricted sandbox 时展示给用户的原因。 */
-  reason?: string;
-};
-
-/**
- * 查询 shell 运行状态的输入。
- */
-export type ShellStatusInput = {
-  /** 要查询的 shell session ID。 */
-  shell_id?: string;
-  /** 可选的原始命令文本，用于宽松筛选。 */
-  cmd?: string;
-};
-
-/**
- * 读取 shell 输出流的输入。
- */
-export type ShellReadInput = {
-  /** 要读取的 shell session ID。 */
-  shell_id: string;
-  /** 从哪个游标开始增量读取。 */
-  from_cursor?: number;
-  /** 最多返回多少输出 token。 */
-  max_output_tokens?: number;
-};
-
-/**
- * 向 shell session 写入输入字符。
- */
-export type ShellWriteInput = {
-  /** 要写入的 shell session ID。 */
-  shell_id: string;
-  /** 要发送到 stdin 的字符内容。 */
-  chars: string;
-  /** 向 unrestricted shell session 写入 stdin 时展示给用户的原因。 */
-  reason?: ShellUnrestrictedReason;
-};
-
-/**
- * 等待 shell 新输出的输入。
- */
-export type ShellWaitInput = {
-  /** 要等待的 shell session ID。 */
-  shell_id: string;
-  /** 从哪个版本号之后开始等待变更。 */
-  after_version?: number;
-  /** 从哪个输出游标开始读取。 */
-  from_cursor?: number;
-  /** 最长等待时间。 */
-  timeout_ms?: number;
-  /** 最多返回多少输出 token。 */
-  max_output_tokens?: number;
-};
-
-/**
- * 关闭 shell session 的输入。
- */
-export type ShellCloseInput = {
-  /** 要关闭的 shell session ID。 */
-  shell_id: string;
-  /** 是否强制结束子进程。 */
-  force?: boolean;
-};

package/src/executor/tools/shell/types/ShellPlugin.ts

@@ -1,278 +0,0 @@
-/**
- * Shell plugin runtime 类型定义。
- *
- * 关键点（中文）
- * - `shell_id` 是 shell 会话的唯一标识，与 chat `sessionId` 严格区分。
- * - 这些类型同时服务于 shell runtime 状态管理与 agent tool 协议。
- */
-
-export type ShellSessionStatus =
-  | "starting"
-  | "running"
-  | "completed"
-  | "failed"
-  | "killed"
-  | "expired";
-
-/**
- * shell 执行 sandbox 模式。
- */
-export type ShellSandboxMode = "safe" | "unrestricted";
-
-/**
- * unrestricted sandbox 审批状态。
- */
-export type ShellApprovalStatus = "approved" | "denied" | "expired";
-
-/**
- * shell unrestricted sandbox 审批来源工具。
- */
-export type ShellApprovalToolName = "shell_exec" | "shell_start" | "shell_write";
-
-/**
- * shell 会话关联的外部引用。
- *
- * 说明（中文）
- * - 用于记录诸如第三方平台 `thread_id`、任务链接等弱结构化引用。
- * - 不要求所有 shell 都存在该信息；仅在可识别时附加。
- */
-export type ShellExternalRef = {
-  /** 引用类别，例如 `thread_id`。 */
-  kind: string;
-  /** 引用的原始值。 */
-  value: string;
-  /** 可选的人类可读标签。 */
-  label?: string;
-};
-
-/**
- * shell 会话快照。
- *
- * 说明（中文）
- * - 该对象是 shell plugin runtime 对外暴露的统一状态视图。
- * - 内部运行态（child process / waiter 集合）不会暴露给上层。
- */
-export type ShellSessionSnapshot = {
-  /** shell 唯一标识。 */
-  shellId: string;
-  /** 发起该 shell 的 chat/context 标识；不存在时表示非聊天上下文触发。 */
-  ownerContextId?: string;
-  /** 原始命令字符串。 */
-  cmd: string;
-  /** 命令执行工作目录（绝对路径）。 */
-  cwd: string;
-  /** 实际使用的 shell 可执行文件路径。 */
-  shellPath: string;
-  /** 当前 shell 是否运行在 sandbox 中。 */
-  sandboxed?: boolean;
-  /** 当前 shell 的 Downcity sandbox 模式。 */
-  sandboxMode?: ShellSandboxMode;
-  /** unrestricted sandbox 审批状态。 */
-  approvalStatus?: ShellApprovalStatus;
-  /** unrestricted sandbox 审批请求 ID。 */
-  approvalId?: string;
-  /** unrestricted sandbox 申请原因。 */
-  approvalReason?: string;
-  /** 当前 shell 是否允许继续写入 stdin。 */
-  stdinWritable?: boolean;
-  /** 当前 shell 使用的 sandbox backend。 */
-  sandboxBackend?: string;
-  /** 当前 shell 采用的 sandbox 网络模式。 */
-  sandboxNetworkMode?: "off" | "restricted" | "full";
-  /** 当前 agent 级 sandbox 的持久目录。 */
-  sandboxDir?: string;
-  /** 当前 shell 在 sandbox 中使用的 HOME。 */
-  sandboxHomeDir?: string;
-  /** 当前 shell 在 sandbox 中使用的临时目录。 */
-  sandboxTmpDir?: string;
-  /** 当前 shell 在 sandbox 中使用的 XDG cache 目录。 */
-  sandboxCacheDir?: string;
-  /** 当前 shell 状态。 */
-  status: ShellSessionStatus;
-  /** 子进程 pid；若尚未创建成功则为空。 */
-  pid?: number;
-  /** shell 创建时间戳（毫秒）。 */
-  startedAt: number;
-  /** 最近一次状态或输出变更时间戳（毫秒）。 */
-  updatedAt: number;
-  /** shell 结束时间戳（毫秒）；运行中为空。 */
-  endedAt?: number;
-  /** 进程退出码；运行中为空。 */
-  exitCode?: number;
-  /** 最近一次收到输出的时间戳（毫秒）。 */
-  lastOutputAt?: number;
-  /** 最近一小段输出预览，供状态查询快速展示。 */
-  lastOutputPreview?: string;
-  /** 当前累计输出字符数。 */
-  outputChars: number;
-  /** 因内存缓存裁剪而丢弃的字符数。 */
-  droppedChars: number;
-  /** 状态版本号；任意输出/状态变化都递增。 */
-  version: number;
-  /** 是否在 shell 结束后自动回投到所属 chat，让主 agent 自己回复。 */
-  autoNotifyOnExit: boolean;
-  /** 自动回投是否已经发送，避免重复通知。 */
-  notificationSent: boolean;
-  /** 从输出中识别到的外部引用集合。 */
-  externalRefs: ShellExternalRef[];
-};
-
-/**
- * shell 启动请求。
- */
-export type ShellStartRequest = {
-  /** 要执行的完整 shell 命令。 */
-  cmd: string;
-  /** 可选工作目录；为空时回退项目根目录。 */
-  cwd?: string;
-  /** 可选 shell 路径，例如 `/bin/zsh`。 */
-  shell?: string;
-  /** 是否以 login shell 方式启动；默认 `true`。 */
-  login?: boolean;
-  /** 启动后内联等待多久再返回首批状态/输出。 */
-  inlineWaitMs?: number;
-  /** 单次读取输出返回给模型的 token 上限。 */
-  maxOutputTokens?: number;
-  /** 显式指定 owner sessionId；为空时优先从 SessionRunScope 推断。 */
-  ownerContextId?: string;
-  /** 是否在 shell 结束后自动回投主 chat agent。 */
-  autoNotifyOnExit?: boolean;
-  /** 命令执行 sandbox 模式；默认 safe。 */
-  sandbox?: ShellSandboxMode;
-  /** 请求 unrestricted sandbox 时展示给用户的原因。 */
-  reason?: string;
-  /** 内部审批来源工具名；普通调用方不需要传。 */
-  approvalToolName?: ShellApprovalToolName;
-};
-
-/**
- * shell 一次性执行请求。
- *
- * 说明（中文）
- * - 适合短命令与无需中途查询状态的场景。
- * - 底层仍复用 shell session 引擎，但调用方不需要管理 `shell_id`。
- */
-export type ShellExecRequest = {
-  /** 要执行的完整 shell 命令。 */
-  cmd: string;
-  /** 可选工作目录；为空时回退项目根目录。 */
-  cwd?: string;
-  /** 可选 shell 路径，例如 `/bin/zsh`。 */
-  shell?: string;
-  /** 是否以 login shell 方式启动；默认 `true`。 */
-  login?: boolean;
-  /** 整个一次性执行的总超时时间（毫秒）。 */
-  timeoutMs?: number;
-  /** 单次读取输出返回给模型的 token 上限。 */
-  maxOutputTokens?: number;
-  /** 命令执行 sandbox 模式；默认 safe。 */
-  sandbox?: ShellSandboxMode;
-  /** 请求 unrestricted sandbox 时展示给用户的原因。 */
-  reason?: string;
-};
-
-/**
- * shell 查询请求。
- *
- * 说明（中文）
- * - `shellId` 优先级最高。
- * - 若未提供 `shellId`，允许在同一 owner context 下按 `cmd` 模糊匹配最近一个会话。
- */
-export type ShellQueryRequest = {
-  /** 目标 shell_id。 */
-  shellId?: string;
-  /** 命令关键字；用于在当前 context 下查找最近匹配会话。 */
-  cmd?: string;
-  /** 指定 owner sessionId；为空时优先从 SessionRunScope 推断。 */
-  ownerContextId?: string;
-  /** 是否允许匹配已结束会话。 */
-  includeCompleted?: boolean;
-};
-
-/**
- * shell 输出读取请求。
- */
-export type ShellReadRequest = ShellQueryRequest & {
-  /** 从哪个字符偏移开始读取；默认从头或从最新游标外部自行维护。 */
-  fromCursor?: number;
-  /** 单次读取输出返回给模型的 token 上限。 */
-  maxOutputTokens?: number;
-};
-
-/**
- * shell stdin 写入请求。
- */
-export type ShellWriteRequest = {
-  /** 目标 shell_id。 */
-  shellId: string;
-  /** 要写入 stdin 的原始文本。 */
-  chars: string;
-  /** 向 unrestricted shell session 写入 stdin 时展示给用户的原因。 */
-  reason?: string;
-};
-
-/**
- * shell 等待请求。
- *
- * 说明（中文）
- * - `afterVersion` 用于等待“状态变化”而非模型侧空轮询。
- * - 可同时附带 `fromCursor`，一旦变化就顺便取回新的输出增量。
- */
-export type ShellWaitRequest = {
-  /** 目标 shell_id。 */
-  shellId: string;
-  /** 仅当版本号大于该值时才立即返回。 */
-  afterVersion?: number;
-  /** 读取输出的起始字符游标。 */
-  fromCursor?: number;
-  /** 最大等待时间（毫秒）。 */
-  timeoutMs?: number;
-  /** 单次读取输出返回给模型的 token 上限。 */
-  maxOutputTokens?: number;
-};
-
-/**
- * shell 关闭请求。
- */
-export type ShellCloseRequest = {
-  /** 目标 shell_id。 */
-  shellId: string;
-  /** 是否强制 kill（SIGKILL）；默认优雅终止。 */
-  force?: boolean;
-};
-
-/**
- * shell 输出块。
- *
- * 说明（中文）
- * - 统一用于 `start/read/wait` 的输出增量返回。
- * - `startCursor/endCursor` 采用字符偏移，便于上层自行维护断点。
- */
-export type ShellOutputChunk = {
-  /** 本次输出块对应的 shell_id。 */
-  shellId: string;
-  /** 本次读取返回的文本。 */
-  output: string;
-  /** 本次读取的起始字符游标。 */
-  startCursor: number;
-  /** 本次读取结束后的字符游标。 */
-  endCursor: number;
-  /** 原始待读取文本字符数。 */
-  originalChars: number;
-  /** 原始待读取文本行数。 */
-  originalLines: number;
-  /** 是否仍有未读输出。 */
-  hasMoreOutput: boolean;
-};
-
-/**
- * shell plugin runtime 对 agent tool 返回的统一数据结构。
- */
-export type ShellActionResponse = {
-  /** shell 当前快照。 */
-  shell: ShellSessionSnapshot;
-  /** 可选输出块；仅在 start/read/wait 中返回。 */
-  chunk?: ShellOutputChunk;
-  /** 操作说明或附加提示。 */
-  note?: string;
-};

package/src/sandbox/LinuxBubblewrapSandbox.ts

@@ -1,222 +0,0 @@
-/**
- * Linux Bubblewrap sandbox backend。
- *
- * 关键点（中文）
- * - 基于 `bwrap` 提供 Linux 本机 shell sandbox。
- * - 继续保持“shell 命令必须进入 sandbox”的安全语义，不提供宿主机裸跑回退。
- * - 边界与 macOS backend 对齐：路径、环境变量、网络、agent 级共享 HOME/TMPDIR/cache。
- */
-
-import { spawn } from "node:child_process";
-import path from "node:path";
-import fs from "fs-extra";
-import type {
-  SandboxSpawnParams,
-  SandboxSpawnResult,
-} from "@/sandbox/types/SandboxRuntime.js";
-
-const DEFAULT_PATH_VALUE =
-  "/usr/local/bin:/usr/bin:/bin:/usr/local/sbin:/usr/sbin:/sbin";
-
-function dedupeExistingPaths(values: string[]): string[] {
-  const seen = new Set<string>();
-  const result: string[] = [];
-  for (const value of values) {
-    const normalized = path.resolve(String(value || "").trim());
-    if (!normalized || seen.has(normalized)) continue;
-    if (!fs.existsSync(normalized)) continue;
-    seen.add(normalized);
-    result.push(normalized);
-  }
-  return result;
-}
-
-function buildReadablePaths(params: {
-  rootPath: string;
-  shellPath: string;
-  sandboxDir: string;
-  tmpDir: string;
-  cacheDir: string;
-}): string[] {
-  return dedupeExistingPaths([
-    "/usr",
-    "/bin",
-    "/sbin",
-    "/lib",
-    "/lib64",
-    "/etc",
-    params.rootPath,
-    params.sandboxDir,
-    params.tmpDir,
-    params.cacheDir,
-    path.dirname(params.shellPath),
-  ]);
-}
-
-function buildWritablePaths(params: SandboxSpawnParams): string[] {
-  return dedupeExistingPaths([
-    ...params.config.writablePaths,
-    params.executionDir,
-    params.config.sandboxDir,
-    params.config.tmpDir,
-    params.config.cacheDir,
-  ]);
-}
-
-function isPathCoveredBy(paths: string[], targetPath: string): boolean {
-  const normalizedTarget = path.resolve(targetPath);
-  return paths.some((value) => {
-    const normalizedValue = path.resolve(value);
-    if (normalizedValue === normalizedTarget) return true;
-    const relative = path.relative(normalizedValue, normalizedTarget);
-    return Boolean(relative) && !relative.startsWith("..") && !path.isAbsolute(relative);
-  });
-}
-
-function buildSandboxEnv(params: SandboxSpawnParams): NodeJS.ProcessEnv {
-  const env: NodeJS.ProcessEnv = {};
-  for (const key of params.config.envAllowlist) {
-    const value = params.baseEnv[key];
-    if (typeof value !== "string" || !value.trim()) continue;
-    env[key] = value;
-  }
-
-  for (const [key, value] of Object.entries(params.baseEnv)) {
-    if (!key.startsWith("DC_")) continue;
-    if (typeof value !== "string" || !value.trim()) continue;
-    env[key] = value;
-  }
-
-  env.PATH = String(env.PATH || params.baseEnv.PATH || DEFAULT_PATH_VALUE);
-  env.HOME = params.config.homeDir;
-  env.TMPDIR = params.config.tmpDir;
-  env.XDG_CACHE_HOME = params.config.cacheDir;
-  env.DC_SANDBOX = "1";
-  env.DC_SANDBOX_DIR = params.config.sandboxDir;
-  env.DC_SANDBOX_HOME = params.config.homeDir;
-  env.DC_SANDBOX_CACHE = params.config.cacheDir;
-  env.SHELL = params.shellPath;
-
-  return env;
-}
-
-function addReadOnlyBind(args: string[], sourcePath: string): void {
-  args.push("--ro-bind", sourcePath, sourcePath);
-}
-
-function addWritableBind(args: string[], sourcePath: string): void {
-  args.push("--bind", sourcePath, sourcePath);
-}
-
-function addParentDirs(args: string[], targetPath: string, createdDirs: Set<string>): void {
-  const parts = path.resolve(targetPath).split(path.sep).filter(Boolean);
-  let current = "";
-  for (let index = 0; index < parts.length - 1; index += 1) {
-    current = `${current}/${parts[index]}`;
-    if (createdDirs.has(current)) continue;
-    createdDirs.add(current);
-    args.push("--dir", current);
-  }
-}
-
-export function buildLinuxBubblewrapArgs(params: SandboxSpawnParams & {
-  actualCwd: string;
-}): string[] {
-  const readablePaths = buildReadablePaths({
-    rootPath: params.config.rootPath,
-    shellPath: params.shellPath,
-    sandboxDir: params.config.sandboxDir,
-    tmpDir: params.config.tmpDir,
-    cacheDir: params.config.cacheDir,
-  });
-  const writablePaths = buildWritablePaths(params);
-  const writableSet = new Set(writablePaths);
-  const createdDirs = new Set<string>();
-  const mountedPaths: string[] = [];
-  const args = [
-    "--die-with-parent",
-    "--unshare-pid",
-    "--proc",
-    "/proc",
-    "--dev",
-    "/dev",
-  ];
-
-  if (params.config.networkMode === "off") {
-    args.push("--unshare-net");
-  }
-
-  for (const readablePath of readablePaths) {
-    if (writableSet.has(readablePath)) continue;
-    if (!isPathCoveredBy(mountedPaths, readablePath)) {
-      addParentDirs(args, readablePath, createdDirs);
-    }
-    addReadOnlyBind(args, readablePath);
-    mountedPaths.push(readablePath);
-  }
-
-  for (const writablePath of writablePaths) {
-    if (isPathCoveredBy(mountedPaths, writablePath)) continue;
-    addParentDirs(args, writablePath, createdDirs);
-    addWritableBind(args, writablePath);
-    mountedPaths.push(writablePath);
-  }
-
-  if (
-    !isPathCoveredBy(readablePaths, params.actualCwd) &&
-    !isPathCoveredBy(writablePaths, params.actualCwd)
-  ) {
-    if (!isPathCoveredBy(mountedPaths, params.actualCwd)) {
-      addParentDirs(args, params.actualCwd, createdDirs);
-    }
-    addReadOnlyBind(args, params.actualCwd);
-  }
-
-  args.push(
-    "--chdir",
-    params.actualCwd,
-    params.shellPath,
-    params.login ? "-lc" : "-c",
-    params.cmd,
-  );
-  return args;
-}
-
-/**
- * 在 Linux bubblewrap sandbox 中启动 shell 子进程。
- */
-export async function spawnLinuxBubblewrapSandbox(
-  params: SandboxSpawnParams & { actualCwd: string },
-): Promise<SandboxSpawnResult> {
-  await fs.ensureDir(params.config.sandboxDir);
-  await fs.ensureDir(params.config.tmpDir);
-  await fs.ensureDir(params.config.cacheDir);
-  await fs.ensureDir(params.executionDir);
-  for (const writablePath of params.config.writablePaths) {
-    await fs.ensureDir(writablePath);
-  }
-
-  const child = spawn("bwrap", buildLinuxBubblewrapArgs({
-    ...params,
-  }), {
-    cwd: params.actualCwd,
-    stdio: "pipe",
-    env: buildSandboxEnv(params),
-  });
-
-  child.stdout.setEncoding("utf8");
-  child.stderr.setEncoding("utf8");
-
-  return {
-    child,
-    cwd: params.actualCwd,
-    sandboxed: true,
-    sandboxMode: "safe",
-    backend: "linux-bubblewrap",
-    networkMode: params.config.networkMode,
-    sandboxDir: params.config.sandboxDir,
-    homeDir: params.config.homeDir,
-    tmpDir: params.config.tmpDir,
-    cacheDir: params.config.cacheDir,
-  };
-}