@downcity/agent 1.1.86 → 1.1.92

package/src/sandbox/LinuxBubblewrapSandbox.ts

@@ -0,0 +1,229 @@
+/**
+ * Linux Bubblewrap sandbox backend。
+ *
+ * 关键点（中文）
+ * - 基于 `bwrap` 提供 Linux 本机 shell sandbox。
+ * - 继续保持“shell 命令必须进入 sandbox”的安全语义，不提供宿主机裸跑回退。
+ * - 边界与 macOS backend 对齐：路径、环境变量、网络、隔离 HOME/TMPDIR。
+ */
+
+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;
+  shellHomeDir: string;
+  shellTmpDir: string;
+}): string[] {
+  return dedupeExistingPaths([
+    "/usr",
+    "/bin",
+    "/sbin",
+    "/lib",
+    "/lib64",
+    "/etc",
+    params.rootPath,
+    params.shellHomeDir,
+    params.shellTmpDir,
+    path.dirname(params.shellPath),
+  ]);
+}
+
+function buildWritablePaths(params: SandboxSpawnParams & {
+  shellHomeDir: string;
+  shellTmpDir: string;
+}): string[] {
+  return dedupeExistingPaths([
+    ...params.config.writablePaths,
+    params.shellDir,
+    params.shellHomeDir,
+    params.shellTmpDir,
+  ]);
+}
+
+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 & {
+  shellHomeDir: string;
+  shellTmpDir: string;
+}): 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.shellHomeDir;
+  env.TMPDIR = params.shellTmpDir;
+  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;
+  shellHomeDir: string;
+  shellTmpDir: string;
+}): string[] {
+  const readablePaths = buildReadablePaths({
+    rootPath: params.config.rootPath,
+    shellPath: params.shellPath,
+    shellHomeDir: params.shellHomeDir,
+    shellTmpDir: params.shellTmpDir,
+  });
+  const writablePaths = buildWritablePaths({
+    ...params,
+    shellHomeDir: params.shellHomeDir,
+    shellTmpDir: params.shellTmpDir,
+  });
+  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)) {
+      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> {
+  const sandboxRootDir = path.join(params.shellDir, "sandbox");
+  const shellHomeDir = path.join(sandboxRootDir, "home");
+  const shellTmpDir = path.join(sandboxRootDir, "tmp");
+
+  await fs.ensureDir(shellHomeDir);
+  await fs.ensureDir(shellTmpDir);
+  for (const writablePath of params.config.writablePaths) {
+    await fs.ensureDir(writablePath);
+  }
+
+  const child = spawn("bwrap", buildLinuxBubblewrapArgs({
+    ...params,
+    shellHomeDir,
+    shellTmpDir,
+  }), {
+    cwd: params.actualCwd,
+    stdio: "pipe",
+    env: buildSandboxEnv({
+      ...params,
+      shellHomeDir,
+      shellTmpDir,
+    }),
+  });
+
+  child.stdout.setEncoding("utf8");
+  child.stderr.setEncoding("utf8");
+
+  return {
+    child,
+    cwd: params.actualCwd,
+    sandboxed: true,
+    backend: "linux-bubblewrap",
+    networkMode: params.config.networkMode,
+  };
+}

package/src/sandbox/SandboxConfigResolver.ts

@@ -9,6 +9,7 @@
 
 import path from "node:path";
 import type { AgentContext } from "@/types/runtime/agent/AgentContext.js";
+import type { SandboxBackend } from "@/sandbox/types/SandboxRuntime.js";
 import type { ResolvedSandboxConfig } from "@/sandbox/types/SandboxRuntime.js";
 
 const DEFAULT_ENV_ALLOWLIST = [
@@ -84,6 +85,17 @@ function normalizeWritablePaths(params: {
   return result;
 }
 
+/**
+ * 根据宿主平台解析当前 sandbox backend。
+ */
+export function resolveSandboxBackend(): SandboxBackend {
+  if (process.platform === "darwin") return "macos-seatbelt";
+  if (process.platform === "linux") return "linux-bubblewrap";
+  throw new Error(
+    `sandbox backend is required for shell execution, but current platform is unsupported: ${process.platform}`,
+  );
+}
+
 /**
  * 解析当前请求最终使用的 sandbox 配置。
  */
@@ -91,14 +103,8 @@ export function resolveSandboxConfig(context: AgentContext): ResolvedSandboxConf
   const rootPath = path.resolve(context.rootPath);
   const projectConfig = context.config?.sandbox;
 
-  if (process.platform !== "darwin") {
-    throw new Error(
-      `sandbox backend is required for shell execution, but current platform is unsupported: ${process.platform}`,
-    );
-  }
-
   return {
-    backend: "macos-seatbelt",
+    backend: resolveSandboxBackend(),
     rootPath,
     envAllowlist: normalizeEnvAllowlist(projectConfig?.envAllowlist),
     writablePaths: normalizeWritablePaths({

package/src/sandbox/SandboxPreflight.ts

@@ -0,0 +1,205 @@
+/**
+ * SandboxPreflight：本机 shell sandbox 依赖预检。
+ *
+ * 关键点（中文）
+ * - shell 命令必须进入 sandbox；这里提前检查 backend 依赖，避免启动后首次 shell 执行才失败。
+ * - Linux backend 基于 bubblewrap，本质使用 Linux namespaces / bind mount 等内核能力。
+ * - 本模块只诊断并给出修复建议，不自动安装软件，也不修改宿主机 sysctl。
+ */
+
+import { access, readFile } from "node:fs/promises";
+import path from "node:path";
+import { delimiter } from "node:path";
+import type { SandboxBackend } from "@/sandbox/types/SandboxRuntime.js";
+
+/**
+ * sandbox 预检失败原因。
+ */
+export type SandboxPreflightIssueCode =
+  | "unsupported-platform"
+  | "missing-command"
+  | "userns-disabled";
+
+/**
+ * 单条 sandbox 预检失败。
+ */
+export interface SandboxPreflightIssue {
+  /**
+   * 机器可读的失败原因。
+   */
+  code: SandboxPreflightIssueCode;
+
+  /**
+   * 人类可读的失败说明。
+   */
+  message: string;
+
+  /**
+   * 可复制的修复建议列表。
+   */
+  fixes: string[];
+}
+
+/**
+ * sandbox 预检结果。
+ */
+export interface SandboxPreflightResult {
+  /**
+   * 当前平台是否满足 shell sandbox 启动要求。
+   */
+  ok: boolean;
+
+  /**
+   * 当前宿主平台。
+   */
+  platform: NodeJS.Platform;
+
+  /**
+   * 当前平台对应的 sandbox backend。
+   */
+  backend?: SandboxBackend;
+
+  /**
+   * 失败原因集合。
+   */
+  issues: SandboxPreflightIssue[];
+}
+
+/**
+ * sandbox 预检宿主探测依赖。
+ */
+export interface ShellSandboxPreflightProbe {
+  /**
+   * 判断命令是否存在于 PATH 中。
+   */
+  commandExists(command: string): Promise<boolean>;
+
+  /**
+   * 读取 `/proc` 下整数配置。
+   */
+  readProcInt(filePath: string): Promise<number | null>;
+}
+
+async function commandExists(command: string): Promise<boolean> {
+  const pathValue = String(process.env.PATH || "").trim();
+  const dirs = pathValue ? pathValue.split(delimiter) : [];
+  for (const dir of dirs) {
+    const candidate = path.join(dir, command);
+    try {
+      await access(candidate);
+      return true;
+    } catch {
+      // continue
+    }
+  }
+  return false;
+}
+
+async function readProcInt(filePath: string): Promise<number | null> {
+  try {
+    const raw = await readFile(filePath, "utf-8");
+    const value = Number.parseInt(raw.trim(), 10);
+    return Number.isFinite(value) && !Number.isNaN(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+async function isLinuxUserNamespaceEnabled(
+  probe: ShellSandboxPreflightProbe,
+): Promise<boolean> {
+  const unprivilegedUsernsClone = await probe.readProcInt(
+    "/proc/sys/kernel/unprivileged_userns_clone",
+  );
+  if (unprivilegedUsernsClone === 0) return false;
+
+  const maxUserNamespaces = await probe.readProcInt("/proc/sys/user/max_user_namespaces");
+  if (maxUserNamespaces === 0) return false;
+
+  return true;
+}
+
+/**
+ * 检查当前宿主是否满足 shell sandbox 运行要求。
+ */
+export async function checkShellSandboxPreflight(): Promise<SandboxPreflightResult> {
+  return await checkShellSandboxPreflightWithProbe({
+    commandExists,
+    readProcInt,
+  });
+}
+
+/**
+ * 使用注入探针检查当前宿主是否满足 shell sandbox 运行要求。
+ */
+export async function checkShellSandboxPreflightWithProbe(
+  probe: ShellSandboxPreflightProbe,
+): Promise<SandboxPreflightResult> {
+  const platform = process.platform;
+  const issues: SandboxPreflightIssue[] = [];
+
+  if (platform === "darwin") {
+    if (!(await probe.commandExists("sandbox-exec"))) {
+      issues.push({
+        code: "missing-command",
+        message: "macOS shell sandbox requires sandbox-exec, but it was not found.",
+        fixes: [
+          "Use a macOS system that includes /usr/bin/sandbox-exec.",
+        ],
+      });
+    }
+    return {
+      ok: issues.length === 0,
+      platform,
+      backend: "macos-seatbelt",
+      issues,
+    };
+  }
+
+  if (platform === "linux") {
+    if (!(await probe.commandExists("bwrap"))) {
+      issues.push({
+        code: "missing-command",
+        message: "Linux shell sandbox requires bubblewrap (bwrap), but it was not found.",
+        fixes: [
+          "Debian / Ubuntu: sudo apt install bubblewrap",
+          "Fedora: sudo dnf install bubblewrap",
+          "Arch: sudo pacman -S bubblewrap",
+        ],
+      });
+    }
+
+    if (!(await isLinuxUserNamespaceEnabled(probe))) {
+      issues.push({
+        code: "userns-disabled",
+        message: "Linux user namespaces are disabled, so bubblewrap cannot create the sandbox.",
+        fixes: [
+          "Check: cat /proc/sys/kernel/unprivileged_userns_clone",
+          "Check: cat /proc/sys/user/max_user_namespaces",
+          "Debian / Ubuntu: sudo sysctl kernel.unprivileged_userns_clone=1",
+        ],
+      });
+    }
+
+    return {
+      ok: issues.length === 0,
+      platform,
+      backend: "linux-bubblewrap",
+      issues,
+    };
+  }
+
+  return {
+    ok: false,
+    platform,
+    issues: [
+      {
+        code: "unsupported-platform",
+        message: `Shell sandbox is not supported on this platform: ${platform}.`,
+        fixes: [
+          "Use macOS or Linux for local shell execution.",
+        ],
+      },
+    ],
+  };
+}

package/src/sandbox/SandboxRunner.ts

@@ -3,7 +3,7 @@
  *
  * 关键点（中文）
  * - 这里不实现完整的 session/read/write 协议，只负责 shell 子进程创建时统一进入 sandbox backend。
- * - 当前版本只接入 macOS seatbelt backend。
+ * - 当前版本接入 macOS seatbelt 与 Linux bubblewrap backend。
  * - shell 命令不再允许回退到宿主机普通子进程执行。
  */
 
@@ -11,6 +11,7 @@ import type { AgentContext } from "@/types/runtime/agent/AgentContext.js";
 import type { SandboxSpawnResult } from "@/sandbox/types/SandboxRuntime.js";
 import { resolveSandboxConfig, resolveSandboxCwd } from "@/sandbox/SandboxConfigResolver.js";
 import { spawnMacOsSeatbeltSandbox } from "@/sandbox/MacOsSeatbeltSandbox.js";
+import { spawnLinuxBubblewrapSandbox } from "@/sandbox/LinuxBubblewrapSandbox.js";
 
 /**
  * 启动 shell 子进程。
@@ -31,7 +32,7 @@ export async function spawnShellProcess(params: {
     requestedCwd: params.cwd,
     context: params.context,
   });
-  return spawnMacOsSeatbeltSandbox({
+  const spawnParams = {
     shellId: params.shellId,
     shellDir: params.shellDir,
     cmd: params.cmd,
@@ -41,7 +42,14 @@ export async function spawnShellProcess(params: {
     baseEnv: params.baseEnv,
     config,
     actualCwd,
-  });
+  };
+  if (config.backend === "macos-seatbelt") {
+    return spawnMacOsSeatbeltSandbox(spawnParams);
+  }
+  if (config.backend === "linux-bubblewrap") {
+    return spawnLinuxBubblewrapSandbox(spawnParams);
+  }
+  throw new Error(`unsupported sandbox backend: ${config.backend}`);
 }
 
 /**

package/src/sandbox/types/SandboxRuntime.ts

@@ -11,6 +11,11 @@ import type { ChildProcessWithoutNullStreams } from "node:child_process";
 import type { SandboxConfig } from "@/sandbox/types/Sandbox.js";
 import type { SandboxNetworkMode } from "@/sandbox/types/Sandbox.js";
 
+/**
+ * 当前内置支持的 sandbox backend。
+ */
+export type SandboxBackend = "macos-seatbelt" | "linux-bubblewrap";
+
 /**
  * sandbox 会话状态。
  *
@@ -298,7 +303,7 @@ export interface ResolvedSandboxConfig extends SandboxConfig {
   /**
    * 当前运行时选中的 backend。
    */
-  backend: "macos-seatbelt";
+  backend: SandboxBackend;
 }
 
 /**
@@ -368,7 +373,7 @@ export interface SandboxSpawnResult {
   /**
    * 当前使用的 backend 名称。
    */
-  backend: "macos-seatbelt";
+  backend: SandboxBackend;
 
   /**
    * 当前实际采用的网络模式。

package/src/session/Session.ts

@@ -130,6 +130,7 @@ export class Session implements AgentSession {
     });
     this.turnService = new SessionTurnService({
       session_id: this.id,
+      project_root: this.projectRoot,
       executor: this.executor,
       state_service: this.stateService,
       event_hub: this.eventHub,

package/src/session/services/SessionTurnService.ts

@@ -32,6 +32,11 @@ type SessionTurnServiceOptions = {
    */
   session_id: string;
 
+  /**
+   * 当前项目根目录。
+   */
+  project_root: string;
+
   /**
    * 当前 session 执行器。
    */
@@ -53,6 +58,7 @@ type SessionTurnServiceOptions = {
  */
 export class SessionTurnService {
   private readonly session_id: string;
+  private readonly project_root: string;
   private readonly executor: Executor;
   private readonly state_service: SessionStateService;
   private readonly event_hub: SessionEventHub;
@@ -60,6 +66,7 @@ export class SessionTurnService {
 
   constructor(options: SessionTurnServiceOptions) {
     this.session_id = options.session_id;
+    this.project_root = options.project_root;
     this.executor = options.executor;
     this.state_service = options.state_service;
     this.event_hub = options.event_hub;
@@ -134,6 +141,7 @@ export class SessionTurnService {
     const tool_name_by_call_id = new Map<string, string>();
     const run_context: SessionRunContext = {
       sessionId: this.session_id,
+      projectRoot: this.project_root,
       onStepCallback: input.onStepMerge,
       onAssistantStepCallback: async (step) => {
         this.publish_event({

package/src/types/executor/SessionRunContext.ts

@@ -23,6 +23,15 @@ export interface SessionRunContext {
    */
   sessionId: string;
 
+  /**
+   * 当前执行所属的项目根目录。
+   *
+   * 关键点（中文）
+   * - 用于 tool/plugin 运行期把二进制资源写入项目级 `.downcity/resources`。
+   * - 未提供时，底层资源写入逻辑会回退到当前进程工作目录，兼容旧入口。
+   */
+  projectRoot?: string;
+
   /**
    * step 边界合并回调。
    *

package/src/types/plugin/ImagePlugin.ts

@@ -88,6 +88,73 @@ export interface ImagePluginInput {
  */
 export type ImagePluginResult = UIMessage;
 
+/**
+ * ImagePlugin 图片任务状态。
+ */
+export type ImagePluginJobStatus = "queued" | "running" | "succeeded" | "failed";
+
+/**
+ * ImagePlugin 图片任务创建结果。
+ */
+export interface ImagePluginJobCreateResult {
+  /** 图片任务唯一 ID。 */
+  job_id: string;
+  /** 当前任务状态。 */
+  status: ImagePluginJobStatus;
+  /** 查询任务状态的路径或 URL。 */
+  status_path?: string;
+  /** 读取任务结果的路径或 URL。 */
+  result_path?: string;
+  /** 人类可读状态说明。 */
+  message?: string;
+  /** 建议下次轮询前等待的毫秒数。 */
+  poll_after_ms?: number;
+  /** 任务创建时间。 */
+  created_at?: string;
+  /** 任务更新时间。 */
+  updated_at?: string;
+}
+
+/**
+ * ImagePlugin 图片任务状态查询结果。
+ */
+export interface ImagePluginJobStatusResult {
+  /** 图片任务唯一 ID。 */
+  job_id: string;
+  /** 当前任务状态。 */
+  status: ImagePluginJobStatus;
+  /** 人类可读状态说明。 */
+  message?: string;
+  /** 失败时的错误信息。 */
+  error?: string;
+  /** 建议下次轮询前等待的毫秒数。 */
+  poll_after_ms?: number;
+  /** 任务创建时间。 */
+  created_at?: string;
+  /** 任务更新时间。 */
+  updated_at?: string;
+}
+
+/**
+ * ImagePlugin 图片任务结果查询结果。
+ */
+export interface ImagePluginJobResult {
+  /** 图片任务唯一 ID。 */
+  job_id: string;
+  /** 当前任务状态。 */
+  status: ImagePluginJobStatus;
+  /** 成功时的图片结果。 */
+  result?: ImagePluginResult;
+  /** 失败时的错误信息。 */
+  error?: string;
+  /** 人类可读状态说明。 */
+  message?: string;
+  /** 任务创建时间。 */
+  created_at?: string;
+  /** 任务更新时间。 */
+  updated_at?: string;
+}
+
 /**
  * ImagePlugin 构造参数。
  */
@@ -98,6 +165,16 @@ export interface ImagePluginOptions {
   title?: string;
   /** Plugin 用途说明。 */
   description?: string;
-  /** 图片生成函数，通常传入 `(input) => city.ai.image(input)`。 */
-  image: (input: ImagePluginInput) => Promise<ImagePluginResult> | ImagePluginResult;
+  /** 可选：图片生成函数；未传 `create/status/result` 时用于本地后台任务兼容。 */
+  image?: (input: ImagePluginInput) => Promise<ImagePluginResult> | ImagePluginResult;
+  /** 可选：创建图片生成任务，通常传入 `(input) => city.ai.imageJobCreate(input)`。 */
+  create?: (input: ImagePluginInput) => Promise<ImagePluginJobCreateResult> | ImagePluginJobCreateResult;
+  /** 可选：查询图片生成任务状态，通常传入 `(input) => city.ai.imageJobStatus(input)`。 */
+  status?: (input: { job_id: string }) => Promise<ImagePluginJobStatusResult> | ImagePluginJobStatusResult;
+  /** 可选：读取图片生成任务结果，通常传入 `(input) => city.ai.imageJobResult(input)`。 */
+  result?: (input: { job_id: string }) => Promise<ImagePluginJobResult> | ImagePluginJobResult;
+  /** 兼容 `generate` 动作等待任务完成的最长毫秒数。 */
+  wait_timeout_ms?: number;
+  /** 兼容 `generate` 动作每次轮询间隔毫秒数。 */
+  poll_interval_ms?: number;
 }