@downcity/agent 1.1.86 → 1.1.91

package/src/plugin/core/ImagePlugin.ts

@@ -7,10 +7,14 @@
  * - action 返回 AI SDK UIMessage，后续由 plugin tool bridge 抽取 file parts 写回 assistant 消息。
  */
 
+import crypto from "node:crypto";
 import type { AgentContext } from "@/types/runtime/agent/AgentContext.js";
 import type { JsonObject, JsonValue } from "@/types/common/Json.js";
 import type {
   ImagePluginInput,
+  ImagePluginJobCreateResult,
+  ImagePluginJobResult,
+  ImagePluginJobStatusResult,
   ImagePluginOptions,
   ImagePluginResult,
 } from "@/types/plugin/ImagePlugin.js";
@@ -20,6 +24,39 @@ 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;
+
+type LocalImageJobRecord = {
+  /**
+   * 图片任务唯一 ID。
+   */
+  job_id: string;
+  /**
+   * 当前任务状态。
+   */
+  status: "queued" | "running" | "succeeded" | "failed";
+  /**
+   * 成功时的图片结果。
+   */
+  result?: ImagePluginResult;
+  /**
+   * 失败时的错误信息。
+   */
+  error?: string;
+  /**
+   * 人类可读状态说明。
+   */
+  message?: string;
+  /**
+   * 任务创建时间。
+   */
+  created_at: string;
+  /**
+   * 任务更新时间。
+   */
+  updated_at: string;
+};
 
 /**
  * 判断值是否为普通对象。
@@ -40,6 +77,15 @@ function normalize_image_payload(payload: JsonValue | undefined): ImagePluginInp
   return { ...record } as ImagePluginInput;
 }
 
+function normalize_job_id_payload(payload: JsonValue | undefined): { job_id: string } {
+  const record = to_record(payload ?? {});
+  const job_id = String(record?.job_id || "").trim();
+  if (!job_id) {
+    throw new TypeError("ImagePlugin job action requires job_id");
+  }
+  return { job_id };
+}
+
 /**
  * 校验 image 函数返回的 UIMessage。
  */
@@ -51,6 +97,25 @@ function normalize_image_result(result: ImagePluginResult): ImagePluginResult {
   return result;
 }
 
+/**
+ * 归一化任务状态查询结果，确保 status action 不携带图片结果。
+ */
+function normalize_job_status_result(
+  result: ImagePluginJobStatusResult,
+): ImagePluginJobStatusResult {
+  return {
+    job_id: result.job_id,
+    status: result.status,
+    ...(result.message ? { message: result.message } : {}),
+    ...(result.error ? { error: result.error } : {}),
+    ...(typeof result.poll_after_ms === "number"
+      ? { poll_after_ms: result.poll_after_ms }
+      : {}),
+    ...(result.created_at ? { created_at: result.created_at } : {}),
+    ...(result.updated_at ? { updated_at: result.updated_at } : {}),
+  };
+}
+
 /**
  * Agent 图片生成插件。
  */
@@ -71,6 +136,12 @@ export class ImagePlugin extends BasePlugin {
   readonly description: string;
 
   private readonly image: ImagePluginOptions["image"];
+  private readonly create_job?: ImagePluginOptions["create"];
+  private readonly read_job_status?: ImagePluginOptions["status"];
+  private readonly read_job_result?: ImagePluginOptions["result"];
+  private readonly wait_timeout_ms: number;
+  private readonly poll_interval_ms: number;
+  private readonly local_jobs = new Map<string, LocalImageJobRecord>();
 
   constructor(options: ImagePluginOptions) {
     super();
@@ -78,8 +149,23 @@ export class ImagePlugin extends BasePlugin {
     if (!name) {
       throw new Error("ImagePlugin requires a non-empty name");
     }
-    if (typeof options.image !== "function") {
-      throw new Error("ImagePlugin requires an image(input) function");
+    const has_custom_job_api = Boolean(
+      options.create || options.status || options.result,
+    );
+    if (
+      has_custom_job_api &&
+      (typeof options.create !== "function" ||
+        typeof options.status !== "function" ||
+        typeof options.result !== "function")
+    ) {
+      throw new Error(
+        "ImagePlugin custom job API requires create, status, and result functions",
+      );
+    }
+    if (!has_custom_job_api && typeof options.image !== "function") {
+      throw new Error(
+        "ImagePlugin requires either image(input) or create/status/result functions",
+      );
     }
     this.name = name;
     this.title = String(options.title || DEFAULT_IMAGE_PLUGIN_TITLE).trim();
@@ -87,6 +173,17 @@ export class ImagePlugin extends BasePlugin {
       options.description || DEFAULT_IMAGE_PLUGIN_DESCRIPTION,
     ).trim();
     this.image = options.image;
+    this.create_job = options.create;
+    this.read_job_status = options.status;
+    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;
   }
 
   /**
@@ -94,22 +191,202 @@ export class ImagePlugin extends BasePlugin {
    */
   system(_context: AgentContext): string {
     return [
-      "Image generation is available through the plugin_call tool.",
-      `Call plugin "${this.name}" action "generate" when the user asks to create, render, draw, or edit an image.`,
-      "Pass a JSON payload with prompt, optional size/aspect_ratio/quality/n, and optional provider_options.",
-      "The generated image files will be attached to the final assistant message automatically.",
+      "Image generation is available through the plugin_call tool as an observable job workflow.",
+      `Call plugin "${this.name}" action "create" when the user asks to create, render, draw, or edit an image.`,
+      `Then call plugin "${this.name}" action "status" with { job_id } to inspect progress.`,
+      `When status is succeeded, call plugin "${this.name}" action "result" with { job_id } to attach the generated files.`,
+      "Use action \"generate\" only as a compatibility shortcut when you explicitly need to wait for completion.",
+      "Pass a JSON payload with prompt, optional size/aspect_ratio/quality/n, and optional provider_options to create/generate.",
     ].join("\n");
   }
 
+  private create_local_job(input: ImagePluginInput): ImagePluginJobCreateResult {
+    if (typeof this.image !== "function") {
+      throw new Error("ImagePlugin local image job requires image(input)");
+    }
+    const now = new Date().toISOString();
+    const job_id = `img_${crypto.randomUUID()}`;
+    const record: LocalImageJobRecord = {
+      job_id,
+      status: "running",
+      message: "image job is running",
+      created_at: now,
+      updated_at: now,
+    };
+    this.local_jobs.set(job_id, record);
+
+    void this.run_local_job(record, input, this.image);
+
+    return {
+      job_id,
+      status: record.status,
+      message: record.message,
+      poll_after_ms: this.poll_interval_ms,
+      created_at: record.created_at,
+      updated_at: record.updated_at,
+    };
+  }
+
+  private async run_local_job(
+    record: LocalImageJobRecord,
+    input: ImagePluginInput,
+    image: NonNullable<ImagePluginOptions["image"]>,
+  ): Promise<void> {
+    try {
+      const message = normalize_image_result(await image(input));
+      record.status = "succeeded";
+      record.result = message;
+      record.message = "image job succeeded";
+      record.updated_at = new Date().toISOString();
+    } catch (error) {
+      record.status = "failed";
+      record.error = String(error);
+      record.message = "image job failed";
+      record.updated_at = new Date().toISOString();
+    }
+  }
+
+  private read_local_job(job_id: string): LocalImageJobRecord {
+    const record = this.local_jobs.get(job_id);
+    if (!record) {
+      throw new Error(`Unknown image job: ${job_id}`);
+    }
+    return record;
+  }
+
+  private serialize_local_status(record: LocalImageJobRecord): ImagePluginJobStatusResult {
+    return {
+      job_id: record.job_id,
+      status: record.status,
+      ...(record.message ? { message: record.message } : {}),
+      ...(record.error ? { error: record.error } : {}),
+      ...(record.status === "running" || record.status === "queued"
+        ? { poll_after_ms: this.poll_interval_ms }
+        : {}),
+      created_at: record.created_at,
+      updated_at: record.updated_at,
+    };
+  }
+
+  private serialize_local_result(record: LocalImageJobRecord): ImagePluginJobResult {
+    return {
+      job_id: record.job_id,
+      status: record.status,
+      ...(record.result ? { result: record.result } : {}),
+      ...(record.error ? { error: record.error } : {}),
+      ...(record.message ? { message: record.message } : {}),
+      created_at: record.created_at,
+      updated_at: record.updated_at,
+    };
+  }
+
+  private async wait_for_job(job_id: string): Promise<ImagePluginResult> {
+    const deadline = Date.now() + this.wait_timeout_ms;
+    while (Date.now() <= deadline) {
+      const result = this.read_job_result
+        ? await this.read_job_result({ job_id })
+        : this.serialize_local_result(this.read_local_job(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");
+      }
+      await new Promise((resolve) => setTimeout(resolve, this.poll_interval_ms));
+    }
+    throw new Error(`image job timed out: ${job_id}`);
+  }
+
   /**
    * 显式 action 集合。
    */
   readonly actions = {
+    create: {
+      execute: async ({ payload }: { payload: JsonValue }) => {
+        try {
+          const input = normalize_image_payload(payload);
+          const result = this.create_job
+            ? await this.create_job(input)
+            : this.create_local_job(input);
+          return {
+            success: true,
+            data: result as unknown as JsonObject,
+            message: result.message || "image job created",
+          };
+        } catch (error) {
+          return {
+            success: false,
+            error: String(error),
+            message: String(error),
+          };
+        }
+      },
+    },
+    status: {
+      execute: async ({ payload }: { payload: JsonValue }) => {
+        try {
+          const input = normalize_job_id_payload(payload);
+          const result = this.read_job_status
+            ? normalize_job_status_result(await this.read_job_status(input))
+            : this.serialize_local_status(this.read_local_job(input.job_id));
+          return {
+            success: true,
+            data: result as unknown as JsonObject,
+            message: result.message || `image job ${result.status}`,
+          };
+        } catch (error) {
+          return {
+            success: false,
+            error: String(error),
+            message: String(error),
+          };
+        }
+      },
+    },
+    result: {
+      execute: async ({ payload }: { payload: JsonValue }) => {
+        try {
+          const input = normalize_job_id_payload(payload);
+          const result = this.read_job_result
+            ? await this.read_job_result(input)
+            : this.serialize_local_result(this.read_local_job(input.job_id));
+          if (result.status === "succeeded" && result.result) {
+            return {
+              success: true,
+              data: result.result as unknown as JsonObject,
+              message: result.message || "image job succeeded",
+            };
+          }
+          if (result.status === "failed") {
+            return {
+              success: false,
+              data: result as unknown as JsonObject,
+              error: result.error || result.message || "image job failed",
+              message: result.message || "image job failed",
+            };
+          }
+          return {
+            success: true,
+            data: result as unknown as JsonObject,
+            message: result.message || `image job ${result.status}`,
+          };
+        } catch (error) {
+          return {
+            success: false,
+            error: String(error),
+            message: String(error),
+          };
+        }
+      },
+    },
     generate: {
       execute: async ({ payload }: { payload: JsonValue }) => {
         try {
           const input = normalize_image_payload(payload);
-          const message = normalize_image_result(await this.image(input));
+          const job = this.create_job
+            ? await this.create_job(input)
+            : this.create_local_job(input);
+          const message = await this.wait_for_job(job.job_id);
           return {
             success: true,
             data: message as unknown as JsonObject,

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/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;
 
   /**
    * 当前实际采用的网络模式。