@downcity/agent 1.1.97 → 1.1.100

package/scripts/image-plugin-job.test.mjs

@@ -3,7 +3,7 @@
  *
  * 关键点（中文）
  * - Agent 只调用 `generate` action。
- * - 插件内部负责 image_create/image_result 轮询。
+ * - 插件内部直接调用注入的 image 函数。
  * - 成功后返回 UIMessage，后续由 plugin bridge 落盘 file parts。
  */
 
@@ -27,33 +27,13 @@ function create_image_message() {
   };
 }
 
-test("ImagePlugin generate polls create/result until the image succeeds", async () => {
+test("ImagePlugin generate calls image and returns the generated message", async () => {
   const calls = [];
   const plugin = new ImagePlugin({
-    create: (input) => {
-      calls.push(["create", input.prompt]);
-      return {
-        job_id: "img_custom",
-        status: "running",
-        poll_after_ms: 1,
-      };
+    image: (input) => {
+      calls.push(["image", input.prompt]);
+      return create_image_message();
     },
-    result: () => {
-      calls.push(["result"]);
-      return calls.filter(([name]) => name === "result").length === 1
-        ? {
-            job_id: "img_custom",
-            status: "running",
-            poll_after_ms: 1,
-          }
-        : {
-            job_id: "img_custom",
-            status: "succeeded",
-            result: create_image_message(),
-          };
-    },
-    poll_interval_ms: 1,
-    wait_timeout_ms: 100,
   });
 
   const result = await plugin.actions.generate.execute({
@@ -66,27 +46,14 @@ test("ImagePlugin generate polls create/result until the image succeeds", async
   assert.equal(result.success, true);
   assert.equal(result.data.role, "assistant");
   assert.equal(result.data.parts[0].type, "file");
-  assert.deepEqual(calls, [
-    ["create", "draw"],
-    ["result"],
-    ["result"],
-  ]);
+  assert.deepEqual(calls, [["image", "draw"]]);
 });
 
-test("ImagePlugin generate reports job failure", async () => {
+test("ImagePlugin generate reports image failure", async () => {
   const plugin = new ImagePlugin({
-    create: () => ({
-      job_id: "img_failed",
-      status: "running",
-      poll_after_ms: 1,
-    }),
-    result: () => ({
-      job_id: "img_failed",
-      status: "failed",
-      error: "provider failed",
-    }),
-    poll_interval_ms: 1,
-    wait_timeout_ms: 100,
+    image: () => {
+      throw new Error("provider failed");
+    },
   });
 
   const result = await plugin.actions.generate.execute({

package/scripts/linux-bubblewrap-sandbox.test.mjs

@@ -19,26 +19,29 @@ async function createSandboxFixture() {
   const projectRoot = path.join(root, "project");
   const writablePath = path.join(projectRoot, ".downcity");
   const shellDir = path.join(writablePath, "shell", "sh_test");
-  const shellHomeDir = path.join(shellDir, "sandbox", "home");
-  const shellTmpDir = path.join(shellDir, "sandbox", "tmp");
+  const sandboxDir = path.join(projectRoot, ".downcity", "sandbox");
+  const tmpDir = path.join(sandboxDir, "tmp");
+  const cacheDir = path.join(sandboxDir, ".cache");
 
-  await fs.mkdir(shellHomeDir, { recursive: true });
-  await fs.mkdir(shellTmpDir, { recursive: true });
+  await fs.mkdir(shellDir, { recursive: true });
+  await fs.mkdir(tmpDir, { recursive: true });
+  await fs.mkdir(cacheDir, { recursive: true });
 
   return {
     root,
     projectRoot,
     writablePath,
     shellDir,
-    shellHomeDir,
-    shellTmpDir,
+    sandboxDir,
+    tmpDir,
+    cacheDir,
   };
 }
 
 function createParams(fixture, overrides = {}) {
   return {
-    shellId: "sh_test",
-    shellDir: fixture.shellDir,
+    executionId: "sh_test",
+    executionDir: fixture.shellDir,
     cmd: "printf hello",
     cwd: fixture.projectRoot,
     actualCwd: fixture.projectRoot,
@@ -52,12 +55,14 @@ function createParams(fixture, overrides = {}) {
     config: {
       backend: "linux-bubblewrap",
       rootPath: fixture.projectRoot,
+      sandboxDir: fixture.sandboxDir,
+      homeDir: fixture.sandboxDir,
+      tmpDir: fixture.tmpDir,
+      cacheDir: fixture.cacheDir,
       envAllowlist: ["PATH", "LANG"],
-      writablePaths: [fixture.writablePath],
+      writablePaths: [fixture.projectRoot, fixture.sandboxDir],
       networkMode: "off",
     },
-    shellHomeDir: fixture.shellHomeDir,
-    shellTmpDir: fixture.shellTmpDir,
     ...overrides,
   };
 }
@@ -96,9 +101,9 @@ test("Linux bubblewrap args isolate network and overlay writable project paths",
     assert.equal(hasArg(args, "--die-with-parent"), true);
     assert.equal(hasArg(args, "--unshare-pid"), true);
     assert.equal(hasArg(args, "--unshare-net"), true);
-    assert.equal(hasOptionPair(args, "--ro-bind", fixture.projectRoot), true);
-    assert.equal(hasOptionPair(args, "--bind", fixture.writablePath), true);
-    assert.equal(hasOptionPair(args, "--bind", fixture.projectRoot), false);
+    assert.equal(hasOptionPair(args, "--bind", fixture.projectRoot), true);
+    assert.equal(hasOptionPair(args, "--bind", fixture.sandboxDir), false);
+    assert.equal(hasOptionPair(args, "--ro-bind", fixture.projectRoot), false);
     assert.equal(hasOptionValue(args, "--dir", fixture.writablePath), false);
     assert.deepEqual(args.slice(-5), [
       "--chdir",
@@ -119,6 +124,10 @@ test("Linux bubblewrap args keep root writable when sandbox writablePaths includ
       config: {
         backend: "linux-bubblewrap",
         rootPath: fixture.projectRoot,
+        sandboxDir: fixture.sandboxDir,
+        homeDir: fixture.sandboxDir,
+        tmpDir: fixture.tmpDir,
+        cacheDir: fixture.cacheDir,
         envAllowlist: ["PATH"],
         writablePaths: [fixture.projectRoot],
         networkMode: "full",

package/src/executor/composer/system/default/assets/core.prompt.ts

@@ -4,6 +4,6 @@
  */
 
 // Source: src/executor/composer/system/default/assets/core.prompt.ts.txt
-const TEXT_MODULE_CONTENT = "你拥有且仅拥有当前项目 {{project_path}} 的使用权和修改权。当前年份是 {{current_year}} 年。\n1. `.downcity/` 是 Downcity 的运行时数据目录（通常不需要你手动读取/修改；系统会自动写入与注入）。结构与逻辑如下：\n   - `.downcity/agents/<agentId>/sessions/` 是会话消息。\n   - `.downcity/memory/` 是中长期记忆。\n   - `.downcity/profile/Primary.md`、`.downcity/profile/other.md`：全局 profile 记忆；存在时会自动作为 system prompt 注入。\n   - `.downcity/public/`：对外静态资源目录，通过 `GET /downcity/public/<path>` 访问；用于给外部访问的路径。不要存放敏感信息，Town Agent HTTP gateway 会把 `.downcity/public/` 暴露为 HTTP 静态资源：`GET /downcity/public/<path>`，你可以把该 URL 发给用户用于下载/查看生成的文件（注意不要暴露敏感信息）。\n   - `.downcity/logs/<YYYY-MM-DD>.jsonl`：运行日志（JSONL）；用于排查问题，避免把原始日志整段贴给用户。\n   - `.downcity/.cache/`：幂等/去重缓存（ingress/egress）；不要手动改。\n   - `.downcity/.debug/`：调试产物（Town 托管进程 pid/log/meta、适配器事件抓取等）；仅在排查问题时查看。\n   - `.downcity/data/`：小型持久化数据（预留）。\n   - `.downcity/task/`：Task 目录。\n2. PROFILE.md + SOUL.md + downcity.json 是你的一些配置文件，你不需要读取。\n\n# 最重要\n【关于命令执行工具】（重要）\n- 短命令、一次性命令优先使用 `shell_exec`。\n- 长任务、需要中途查状态、需要 stdin 交互时，使用 `shell_start` / `shell_status` / `shell_read` / `shell_write` / `shell_wait` / `shell_close`。\n- 先用 `shell_start` 启动命令并拿到 `shell_id`。\n- `shell_id` 是 shell 会话标识；它不是 chat `session_id`。\n- 长任务期间，优先使用 `shell_status` 查询进度，或使用 `shell_wait` 等待状态变化；不要自己写高频空轮询循环。\n- 只有在确实需要原始增量输出时，才使用 `shell_read` 按 `from_cursor` 继续读取。\n- 需要向进程 stdin 输入内容时，使用 `shell_write`。\n- 命令会话完成后若不再需要，使用 `shell_close` 主动释放资源。\n- 不要把原始超长 shell 输出直接转发给用户，应先总结。\n\n# 默认决策与澄清\n- 默认先执行，再沟通：对低风险、可回滚、用户意图已经足够明显的请求，优先基于当前日期、时区、聊天上下文与常见默认值直接执行，不要在事件标题、默认平台、显然的时间表达上反复追问。\n- 只有当“缺失信息会实质改变结果”时才追问；例如：会影响日期/对象/金额/账户/发送目标，或会触发不可逆、高风险、涉隐私操作。\n- 处理时间表达时，优先使用当前环境提供的 `current_date`、`current_time` 与 `timezone`；如果入站 `<info>` 明确提供了 `user_timezone`，则优先按 `user_timezone` 解析，否则按 runtime clock 的 `timezone` 解析。像“今天/明天/下午两点/提前两小时”这类表达，应先解析为绝对时间，再执行，并在回复里明确写出绝对日期时间。\n- 当任务依赖外部权限、系统能力或第三方连接（如日历、提醒事项、聊天渠道、系统授权）时，先探测可用性，再决定是否承诺“我来创建/发送/写入”。\n- 如果探测结果显示被系统权限、宿主环境或连接状态阻塞，要直接说明真实阻塞点和下一步，而不是先给出“可以，我来做”的承诺后再多轮追问。\n- 若已经有足够信息可以一次完成多个低风险默认动作，应直接完成，并在结果里简短说明采用了哪些默认假设。\n\n# 很重要\n\n安全与边界\n- 不要执行破坏性命令（如 `rm -rf`、`git reset --hard`）除非用户明确要求。\n- 遇到 API Key、Token、Secret、环境变量、bot 凭据等密钥管理问题时，优先指导用户使用 Console（如 `Global / Env`、`Global / Channel Accounts`）维护，不要要求用户把密钥明文直接发送到当前聊天里。\n- `town keys` 只能列出已配置的 key 名与描述，不会返回密钥值。不要让用户把密钥“发给你自己”或继续尝试通过 `town keys` 获取明文。\n";
+const TEXT_MODULE_CONTENT = "你拥有且仅拥有当前项目 {{project_path}} 的使用权和修改权。当前年份是 {{current_year}} 年。\n1. `.downcity/` 是 Downcity 的运行时数据目录（通常不需要你手动读取/修改；系统会自动写入与注入）。结构与逻辑如下：\n   - `.downcity/agents/<agentId>/sessions/` 是会话消息。\n   - `.downcity/memory/` 是中长期记忆。\n   - `.downcity/profile/Primary.md`、`.downcity/profile/other.md`：全局 profile 记忆；存在时会自动作为 system prompt 注入。\n   - `.downcity/public/`：对外静态资源目录，通过 `GET /downcity/public/<path>` 访问；用于给外部访问的路径。不要存放敏感信息，Town Agent HTTP gateway 会把 `.downcity/public/` 暴露为 HTTP 静态资源：`GET /downcity/public/<path>`，你可以把该 URL 发给用户用于下载/查看生成的文件（注意不要暴露敏感信息）。\n   - `.downcity/logs/<YYYY-MM-DD>.jsonl`：运行日志（JSONL）；用于排查问题，避免把原始日志整段贴给用户。\n   - `.downcity/.cache/`：幂等/去重缓存（ingress/egress）；不要手动改。\n   - `.downcity/.debug/`：调试产物（Town 托管进程 pid/log/meta、适配器事件抓取等）；仅在排查问题时查看。\n   - `.downcity/data/`：小型持久化数据（预留）。\n   - `.downcity/task/`：Task 目录。\n   - `.downcity/sandbox/`：当前 agent 的本地命令执行 sandbox HOME/cache/tmp；shell 与 script 命令会共享它。\n2. PROFILE.md + SOUL.md + downcity.json 是你的一些配置文件，你不需要读取。\n\n# 最重要\n【关于命令执行工具】（重要）\n- 短命令、一次性命令优先使用 `shell_exec`。\n- 长任务、需要中途查状态、需要 stdin 交互时，使用 `shell_start` / `shell_status` / `shell_read` / `shell_write` / `shell_wait` / `shell_close`。\n- 先用 `shell_start` 启动命令并拿到 `shell_id`。\n- `shell_id` 是 shell 会话标识；它不是 chat `session_id`。\n- 长任务期间，优先使用 `shell_status` 查询进度，或使用 `shell_wait` 等待状态变化；不要自己写高频空轮询循环。\n- 只有在确实需要原始增量输出时，才使用 `shell_read` 按 `from_cursor` 继续读取。\n- 需要向进程 stdin 输入内容时，使用 `shell_write`。\n- 命令会话完成后若不再需要，使用 `shell_close` 主动释放资源。\n- 不要把原始超长 shell 输出直接转发给用户，应先总结。\n- shell 命令默认在当前 agent 的 sandbox 中执行：项目目录可读写，网络可用，HOME 指向 `.downcity/sandbox/`，真实用户 HOME 与系统目录不可写。\n- 安装 Python 依赖时优先使用项目内 `.venv`，不要使用 `pip install --user`。\n- 不要尝试 `sudo`、`brew install`、Xcode Command Line Tools 安装或写 `/usr/local`、`/opt/homebrew`、`/System` 等宿主系统目录；如果确实缺少系统级依赖，直接告诉用户需要在宿主机安装。\n- 下载模型、工具缓存、临时状态应自然落在 `.downcity/sandbox/` 或项目目录中，不要假设可复用真实用户缓存。\n\n# 默认决策与澄清\n- 默认先执行，再沟通：对低风险、可回滚、用户意图已经足够明显的请求，优先基于当前日期、时区、聊天上下文与常见默认值直接执行，不要在事件标题、默认平台、显然的时间表达上反复追问。\n- 只有当“缺失信息会实质改变结果”时才追问；例如：会影响日期/对象/金额/账户/发送目标，或会触发不可逆、高风险、涉隐私操作。\n- 处理时间表达时，优先使用当前环境提供的 `current_date`、`current_time` 与 `timezone`；如果入站 `<info>` 明确提供了 `user_timezone`，则优先按 `user_timezone` 解析，否则按 runtime clock 的 `timezone` 解析。像“今天/明天/下午两点/提前两小时”这类表达，应先解析为绝对时间，再执行，并在回复里明确写出绝对日期时间。\n- 当任务依赖外部权限、系统能力或第三方连接（如日历、提醒事项、聊天渠道、系统授权）时，先探测可用性，再决定是否承诺“我来创建/发送/写入”。\n- 如果探测结果显示被系统权限、宿主环境或连接状态阻塞，要直接说明真实阻塞点和下一步，而不是先给出“可以，我来做”的承诺后再多轮追问。\n- 若已经有足够信息可以一次完成多个低风险默认动作，应直接完成，并在结果里简短说明采用了哪些默认假设。\n\n# 很重要\n\n安全与边界\n- 不要执行破坏性命令（如 `rm -rf`、`git reset --hard`）除非用户明确要求。\n- 遇到 API Key、Token、Secret、环境变量、bot 凭据等密钥管理问题时，优先指导用户使用 Console（如 `Global / Env`、`Global / Channel Accounts`）维护，不要要求用户把密钥明文直接发送到当前聊天里。\n- `town keys` 只能列出已配置的 key 名与描述，不会返回密钥值。不要让用户把密钥“发给你自己”或继续尝试通过 `town keys` 获取明文。\n";
 
 export default TEXT_MODULE_CONTENT;

package/src/executor/composer/system/default/assets/core.prompt.ts.txt

@@ -9,6 +9,7 @@
    - `.downcity/.debug/`：调试产物（Town 托管进程 pid/log/meta、适配器事件抓取等）；仅在排查问题时查看。
    - `.downcity/data/`：小型持久化数据（预留）。
    - `.downcity/task/`：Task 目录。
+   - `.downcity/sandbox/`：当前 agent 的本地命令执行 sandbox HOME/cache/tmp；shell 与 script 命令会共享它。
 2. PROFILE.md + SOUL.md + downcity.json 是你的一些配置文件，你不需要读取。
 
 # 最重要
@@ -22,6 +23,10 @@
 - 需要向进程 stdin 输入内容时，使用 `shell_write`。
 - 命令会话完成后若不再需要，使用 `shell_close` 主动释放资源。
 - 不要把原始超长 shell 输出直接转发给用户，应先总结。
+- shell 命令默认在当前 agent 的 sandbox 中执行：项目目录可读写，网络可用，HOME 指向 `.downcity/sandbox/`，真实用户 HOME 与系统目录不可写。
+- 安装 Python 依赖时优先使用项目内 `.venv`，不要使用 `pip install --user`。
+- 不要尝试 `sudo`、`brew install`、Xcode Command Line Tools 安装或写 `/usr/local`、`/opt/homebrew`、`/System` 等宿主系统目录；如果确实缺少系统级依赖，直接告诉用户需要在宿主机安装。
+- 下载模型、工具缓存、临时状态应自然落在 `.downcity/sandbox/` 或项目目录中，不要假设可复用真实用户缓存。
 
 # 默认决策与澄清
 - 默认先执行，再沟通：对低风险、可回滚、用户意图已经足够明显的请求，优先基于当前日期、时区、聊天上下文与常见默认值直接执行，不要在事件标题、默认平台、显然的时间表达上反复追问。

package/src/executor/tools/shell/ShellToolBridge.ts

@@ -211,6 +211,13 @@ export function flattenShellActionResponse(params: {
     status: shell.status,
     cmd: shell.cmd,
     cwd: shell.cwd,
+    sandboxed: shell.sandboxed === true,
+    sandbox_backend: shell.sandboxBackend || null,
+    sandbox_network_mode: shell.sandboxNetworkMode || null,
+    sandbox_dir: shell.sandboxDir || null,
+    sandbox_home_dir: shell.sandboxHomeDir || null,
+    sandbox_tmp_dir: shell.sandboxTmpDir || null,
+    sandbox_cache_dir: shell.sandboxCacheDir || null,
     pid: typeof shell.pid === "number" ? shell.pid : null,
     version: shell.version,
     started_at: shell.startedAt,
@@ -255,6 +262,13 @@ export function flattenShellExecResponse(params: {
     status: shell.status,
     cmd: shell.cmd,
     cwd: shell.cwd,
+    sandboxed: shell.sandboxed === true,
+    sandbox_backend: shell.sandboxBackend || null,
+    sandbox_network_mode: shell.sandboxNetworkMode || null,
+    sandbox_dir: shell.sandboxDir || null,
+    sandbox_home_dir: shell.sandboxHomeDir || null,
+    sandbox_tmp_dir: shell.sandboxTmpDir || null,
+    sandbox_cache_dir: shell.sandboxCacheDir || null,
     exit_code: typeof shell.exitCode === "number" ? shell.exitCode : null,
     output: chunk?.output || "",
     original_chars: chunk?.originalChars ?? 0,

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

@@ -54,6 +54,14 @@ export type ShellSessionSnapshot = {
   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；若尚未创建成功则为空。 */

package/src/index.ts

@@ -229,9 +229,6 @@ export type {
   ImagePluginContent,
   ImagePluginFileContent,
   ImagePluginInput,
-  ImagePluginJobCreateResult,
-  ImagePluginJobResult,
-  ImagePluginJobStatus,
   ImagePluginMessage,
   ImagePluginOptions,
   ImagePluginTextContent,

package/src/plugin/core/ImagePlugin.ts

@@ -3,7 +3,7 @@
  *
  * 关键点（中文）
  * - 对 Agent 只暴露同步体验的 `generate` action。
- * - City / provider 的异步任务细节由插件内部 create + result 轮询封装。
+ * - City / provider 的图片能力通过单个 image 函数注入。
  * - action 返回 AI SDK UIMessage，后续由 plugin tool bridge 抽取 file parts 写回 assistant 消息。
  */
 
@@ -20,8 +20,6 @@ const DEFAULT_IMAGE_PLUGIN_NAME = "image";
 const DEFAULT_IMAGE_PLUGIN_TITLE = "Image";
 const DEFAULT_IMAGE_PLUGIN_DESCRIPTION =
   "Generate images and return them as assistant file parts.";
-const DEFAULT_WAIT_TIMEOUT_MS = 60_000;
-const DEFAULT_POLL_INTERVAL_MS = 3_000;
 
 /**
  * 判断值是否为普通对象。
@@ -53,13 +51,6 @@ function normalize_image_result(result: ImagePluginResult): ImagePluginResult {
   return result;
 }
 
-/**
- * 等待指定毫秒数。
- */
-function sleep(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
 /**
  * Agent 图片生成插件。
  */
@@ -79,10 +70,7 @@ export class ImagePlugin extends BasePlugin {
    */
   readonly description: string;
 
-  private readonly create_job: NonNullable<ImagePluginOptions["create"]>;
-  private readonly read_job_result: NonNullable<ImagePluginOptions["result"]>;
-  private readonly wait_timeout_ms: number;
-  private readonly poll_interval_ms: number;
+  private readonly image: NonNullable<ImagePluginOptions["image"]>;
 
   constructor(options: ImagePluginOptions) {
     super();
@@ -90,24 +78,15 @@ export class ImagePlugin extends BasePlugin {
     if (!name) {
       throw new Error("ImagePlugin requires a non-empty name");
     }
-    if (typeof options.create !== "function" || typeof options.result !== "function") {
-      throw new Error("ImagePlugin requires create and result functions");
+    if (typeof options.image !== "function") {
+      throw new Error("ImagePlugin requires an image function");
     }
     this.name = name;
     this.title = String(options.title || DEFAULT_IMAGE_PLUGIN_TITLE).trim();
     this.description = String(
       options.description || DEFAULT_IMAGE_PLUGIN_DESCRIPTION,
     ).trim();
-    this.create_job = options.create;
-    this.read_job_result = options.result;
-    this.wait_timeout_ms =
-      typeof options.wait_timeout_ms === "number" && options.wait_timeout_ms > 0
-        ? options.wait_timeout_ms
-        : DEFAULT_WAIT_TIMEOUT_MS;
-    this.poll_interval_ms =
-      typeof options.poll_interval_ms === "number" && options.poll_interval_ms > 0
-        ? options.poll_interval_ms
-        : DEFAULT_POLL_INTERVAL_MS;
+    this.image = options.image;
   }
 
   /**
@@ -123,32 +102,7 @@ export class ImagePlugin extends BasePlugin {
   }
 
   private async generate_image(input: ImagePluginInput): Promise<ImagePluginResult> {
-    const job = await this.create_job(input);
-    const job_id = String(job.job_id || "").trim();
-    if (!job_id) {
-      throw new Error("ImagePlugin image_create result requires job_id");
-    }
-
-    const deadline = Date.now() + this.wait_timeout_ms;
-    let poll_after_ms =
-      typeof job.poll_after_ms === "number" && job.poll_after_ms > 0
-        ? job.poll_after_ms
-        : this.poll_interval_ms;
-    while (Date.now() <= deadline) {
-      const result = await this.read_job_result({ job_id });
-      if (result.status === "succeeded" && result.result) {
-        return normalize_image_result(result.result);
-      }
-      if (result.status === "failed") {
-        throw new Error(result.error || result.message || "image job failed");
-      }
-      poll_after_ms =
-        typeof result.poll_after_ms === "number" && result.poll_after_ms > 0
-          ? result.poll_after_ms
-          : this.poll_interval_ms;
-      await sleep(poll_after_ms);
-    }
-    throw new Error(`image job timed out: ${job_id}`);
+    return normalize_image_result(await this.image(input));
   }
 
   /**

package/src/sandbox/LinuxBubblewrapSandbox.ts

@@ -4,7 +4,7 @@
  * 关键点（中文）
  * - 基于 `bwrap` 提供 Linux 本机 shell sandbox。
  * - 继续保持“shell 命令必须进入 sandbox”的安全语义，不提供宿主机裸跑回退。
- * - 边界与 macOS backend 对齐：路径、环境变量、网络、隔离 HOME/TMPDIR。
+ * - 边界与 macOS backend 对齐：路径、环境变量、网络、agent 级共享 HOME/TMPDIR/cache。
  */
 
 import { spawn } from "node:child_process";
@@ -34,8 +34,9 @@ function dedupeExistingPaths(values: string[]): string[] {
 function buildReadablePaths(params: {
   rootPath: string;
   shellPath: string;
-  shellHomeDir: string;
-  shellTmpDir: string;
+  sandboxDir: string;
+  tmpDir: string;
+  cacheDir: string;
 }): string[] {
   return dedupeExistingPaths([
     "/usr",
@@ -45,21 +46,20 @@ function buildReadablePaths(params: {
     "/lib64",
     "/etc",
     params.rootPath,
-    params.shellHomeDir,
-    params.shellTmpDir,
+    params.sandboxDir,
+    params.tmpDir,
+    params.cacheDir,
     path.dirname(params.shellPath),
   ]);
 }
 
-function buildWritablePaths(params: SandboxSpawnParams & {
-  shellHomeDir: string;
-  shellTmpDir: string;
-}): string[] {
+function buildWritablePaths(params: SandboxSpawnParams): string[] {
   return dedupeExistingPaths([
     ...params.config.writablePaths,
-    params.shellDir,
-    params.shellHomeDir,
-    params.shellTmpDir,
+    params.executionDir,
+    params.config.sandboxDir,
+    params.config.tmpDir,
+    params.config.cacheDir,
   ]);
 }
 
@@ -73,10 +73,7 @@ function isPathCoveredBy(paths: string[], targetPath: string): boolean {
   });
 }
 
-function buildSandboxEnv(params: SandboxSpawnParams & {
-  shellHomeDir: string;
-  shellTmpDir: string;
-}): NodeJS.ProcessEnv {
+function buildSandboxEnv(params: SandboxSpawnParams): NodeJS.ProcessEnv {
   const env: NodeJS.ProcessEnv = {};
   for (const key of params.config.envAllowlist) {
     const value = params.baseEnv[key];
@@ -91,8 +88,13 @@ function buildSandboxEnv(params: SandboxSpawnParams & {
   }
 
   env.PATH = String(env.PATH || params.baseEnv.PATH || DEFAULT_PATH_VALUE);
-  env.HOME = params.shellHomeDir;
-  env.TMPDIR = params.shellTmpDir;
+  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;
@@ -119,20 +121,15 @@ function addParentDirs(args: string[], targetPath: string, createdDirs: Set<stri
 
 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,
+    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[] = [];
@@ -159,9 +156,8 @@ export function buildLinuxBubblewrapArgs(params: SandboxSpawnParams & {
   }
 
   for (const writablePath of writablePaths) {
-    if (!isPathCoveredBy(mountedPaths, writablePath)) {
-      addParentDirs(args, writablePath, createdDirs);
-    }
+    if (isPathCoveredBy(mountedPaths, writablePath)) continue;
+    addParentDirs(args, writablePath, createdDirs);
     addWritableBind(args, writablePath);
     mountedPaths.push(writablePath);
   }
@@ -192,28 +188,20 @@ export function buildLinuxBubblewrapArgs(params: SandboxSpawnParams & {
 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);
+  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,
-    shellHomeDir,
-    shellTmpDir,
   }), {
     cwd: params.actualCwd,
     stdio: "pipe",
-    env: buildSandboxEnv({
-      ...params,
-      shellHomeDir,
-      shellTmpDir,
-    }),
+    env: buildSandboxEnv(params),
   });
 
   child.stdout.setEncoding("utf8");
@@ -225,5 +213,9 @@ export async function spawnLinuxBubblewrapSandbox(
     sandboxed: true,
     backend: "linux-bubblewrap",
     networkMode: params.config.networkMode,
+    sandboxDir: params.config.sandboxDir,
+    homeDir: params.config.homeDir,
+    tmpDir: params.config.tmpDir,
+    cacheDir: params.config.cacheDir,
   };
 }

package/src/sandbox/MacOsSeatbeltSandbox.ts

@@ -4,7 +4,7 @@
  * 关键点（中文）
  * - 当前最小实现直接基于系统自带 `sandbox-exec`。
  * - 目标不是抽象完整 provider 体系，而是先把 shell 命令从“宿主机直跑”收敛成“带边界执行”。
- * - 边界只保留四类：路径、环境变量、网络、隔离后的 HOME/TMPDIR。
+ * - 边界只保留四类：路径、环境变量、网络、agent 级共享 HOME/TMPDIR/cache。
  */
 
 import { spawn } from "node:child_process";
@@ -37,8 +37,9 @@ function dedupePaths(values: string[]): string[] {
 function buildReadablePaths(params: {
   rootPath: string;
   shellPath: string;
-  shellHomeDir: string;
-  shellTmpDir: string;
+  sandboxDir: string;
+  tmpDir: string;
+  cacheDir: string;
 }): string[] {
   return dedupePaths([
     "/bin",
@@ -50,21 +51,20 @@ function buildReadablePaths(params: {
     "/opt/homebrew",
     "/usr/local",
     params.rootPath,
-    params.shellHomeDir,
-    params.shellTmpDir,
+    params.sandboxDir,
+    params.tmpDir,
+    params.cacheDir,
     path.dirname(params.shellPath),
   ]);
 }
 
-function buildWritablePaths(params: SandboxSpawnParams & {
-  shellHomeDir: string;
-  shellTmpDir: string;
-}): string[] {
+function buildWritablePaths(params: SandboxSpawnParams): string[] {
   return dedupePaths([
     ...params.config.writablePaths,
-    params.shellDir,
-    params.shellHomeDir,
-    params.shellTmpDir,
+    params.executionDir,
+    params.config.sandboxDir,
+    params.config.tmpDir,
+    params.config.cacheDir,
   ]);
 }
 
@@ -77,20 +77,15 @@ function buildNetworkRules(networkMode: SandboxSpawnParams["config"]["networkMod
 
 function buildSeatbeltProfile(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,
+    sandboxDir: params.config.sandboxDir,
+    tmpDir: params.config.tmpDir,
+    cacheDir: params.config.cacheDir,
   });
+  const writablePaths = buildWritablePaths(params);
   const lines = [
     "(version 1)",
     "(deny default)",
@@ -116,10 +111,7 @@ function buildSeatbeltProfile(params: SandboxSpawnParams & {
   return `${lines.join("\n")}\n`;
 }
 
-function buildSandboxEnv(params: SandboxSpawnParams & {
-  shellHomeDir: string;
-  shellTmpDir: string;
-}): NodeJS.ProcessEnv {
+function buildSandboxEnv(params: SandboxSpawnParams): NodeJS.ProcessEnv {
   const env: NodeJS.ProcessEnv = {};
   for (const key of params.config.envAllowlist) {
     const value = params.baseEnv[key];
@@ -134,9 +126,14 @@ function buildSandboxEnv(params: SandboxSpawnParams & {
   }
 
   env.PATH = String(env.PATH || params.baseEnv.PATH || DEFAULT_PATH_VALUE);
-  env.HOME = params.shellHomeDir;
-  env.ZDOTDIR = params.shellHomeDir;
-  env.TMPDIR = params.shellTmpDir;
+  env.HOME = params.config.homeDir;
+  env.ZDOTDIR = 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;
@@ -148,18 +145,15 @@ function buildSandboxEnv(params: SandboxSpawnParams & {
 export async function spawnMacOsSeatbeltSandbox(
   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");
-  const profilePath = path.join(sandboxRootDir, "profile.sb");
+  const profilePath = path.join(params.executionDir, "sandbox-profile.sb");
 
-  await fs.ensureDir(shellHomeDir);
-  await fs.ensureDir(shellTmpDir);
+  await fs.ensureDir(params.config.sandboxDir);
+  await fs.ensureDir(params.config.tmpDir);
+  await fs.ensureDir(params.config.cacheDir);
+  await fs.ensureDir(params.executionDir);
 
   const profile = buildSeatbeltProfile({
     ...params,
-    shellHomeDir,
-    shellTmpDir,
   });
   await fs.writeFile(profilePath, profile, "utf-8");
 
@@ -175,11 +169,7 @@ export async function spawnMacOsSeatbeltSandbox(
     {
       cwd: params.actualCwd,
       stdio: "pipe",
-      env: buildSandboxEnv({
-        ...params,
-        shellHomeDir,
-        shellTmpDir,
-      }),
+      env: buildSandboxEnv(params),
     },
   );
 
@@ -192,5 +182,9 @@ export async function spawnMacOsSeatbeltSandbox(
     sandboxed: true,
     backend: "macos-seatbelt",
     networkMode: params.config.networkMode,
+    sandboxDir: params.config.sandboxDir,
+    homeDir: params.config.homeDir,
+    tmpDir: params.config.tmpDir,
+    cacheDir: params.config.cacheDir,
   };
 }