@downcity/agent 1.1.97 → 1.1.100

package/src/sandbox/SandboxConfigResolver.ts

@@ -3,6 +3,7 @@
  *
  * 关键点（中文）
  * - 这里负责把 `downcity.json` 中面向用户的最小配置，收敛成运行时可直接执行的绝对路径配置。
+ * - sandbox 是 agent 项目级能力，持久目录固定为 `<project>/.downcity/sandbox`。
  * - 当前版本只服务 shell / CLI 这条命令执行链，不引入审批、profile 绑定或用户权限系统。
  * - 解析结果只回答一个问题：这次命令执行的 sandbox 边界是什么。
  */
@@ -24,6 +25,8 @@ const DEFAULT_ENV_ALLOWLIST = [
   "LOGNAME",
 ];
 
+const SANDBOX_RELATIVE_DIR = path.join(".downcity", "sandbox");
+
 function normalizeEnvAllowlist(values?: string[]): string[] {
   const seen = new Set<string>();
   const result: string[] = [];
@@ -49,14 +52,15 @@ export function isPathInsideRoot(rootPath: string, targetPath: string): boolean
 
 function normalizeWritablePaths(params: {
   rootPath: string;
+  sandboxDir: string;
   writablePaths?: string[];
   context: AgentContext;
 }): string[] {
-  const { rootPath, writablePaths, context } = params;
+  const { rootPath, sandboxDir, writablePaths, context } = params;
   const rawValues =
     Array.isArray(writablePaths) && writablePaths.length > 0
-      ? writablePaths
-      : [rootPath];
+      ? [rootPath, sandboxDir, ...writablePaths]
+      : [rootPath, sandboxDir];
   const seen = new Set<string>();
   const result: string[] = [];
 
@@ -102,13 +106,21 @@ export function resolveSandboxBackend(): SandboxBackend {
 export function resolveSandboxConfig(context: AgentContext): ResolvedSandboxConfig {
   const rootPath = path.resolve(context.rootPath);
   const projectConfig = context.config?.sandbox;
+  const sandboxDir = path.join(rootPath, SANDBOX_RELATIVE_DIR);
+  const tmpDir = path.join(sandboxDir, "tmp");
+  const cacheDir = path.join(sandboxDir, ".cache");
 
   return {
     backend: resolveSandboxBackend(),
     rootPath,
+    sandboxDir,
+    homeDir: sandboxDir,
+    tmpDir,
+    cacheDir,
     envAllowlist: normalizeEnvAllowlist(projectConfig?.envAllowlist),
     writablePaths: normalizeWritablePaths({
       rootPath,
+      sandboxDir,
       writablePaths: projectConfig?.writablePaths,
       context,
     }),

package/src/sandbox/SandboxRunner.ts

@@ -2,9 +2,9 @@
  * SandboxRunner 入口。
  *
  * 关键点（中文）
- * - 这里不实现完整的 session/read/write 协议，只负责 shell 子进程创建时统一进入 sandbox backend。
+ * - 这里不实现完整的 session/read/write 协议，只负责本地子进程创建时统一进入 agent sandbox backend。
  * - 当前版本接入 macOS seatbelt 与 Linux bubblewrap backend。
- * - shell 命令不再允许回退到宿主机普通子进程执行。
+ * - 本地命令不再允许回退到宿主机普通子进程执行。
  */
 
 import type { AgentContext } from "@/types/runtime/agent/AgentContext.js";
@@ -25,6 +25,31 @@ export async function spawnShellProcess(params: {
   shellPath: string;
   login: boolean;
   baseEnv: NodeJS.ProcessEnv;
+}): Promise<SandboxSpawnResult> {
+  return spawnInSandbox({
+    context: params.context,
+    executionId: params.shellId,
+    executionDir: params.shellDir,
+    cmd: params.cmd,
+    cwd: params.cwd,
+    shellPath: params.shellPath,
+    login: params.login,
+    baseEnv: params.baseEnv,
+  });
+}
+
+/**
+ * 在当前 agent sandbox 中启动本地子进程。
+ */
+export async function spawnInSandbox(params: {
+  context: AgentContext;
+  executionId: string;
+  executionDir: string;
+  cmd: string;
+  cwd: string;
+  shellPath: string;
+  login: boolean;
+  baseEnv: NodeJS.ProcessEnv;
 }): Promise<SandboxSpawnResult> {
   const config = resolveSandboxConfig(params.context);
   const actualCwd = resolveSandboxCwd({
@@ -33,8 +58,8 @@ export async function spawnShellProcess(params: {
     context: params.context,
   });
   const spawnParams = {
-    shellId: params.shellId,
-    shellDir: params.shellDir,
+    executionId: params.executionId,
+    executionDir: params.executionDir,
     cmd: params.cmd,
     cwd: params.cwd,
     shellPath: params.shellPath,
@@ -61,8 +86,8 @@ export async function spawnShellProcess(params: {
  */
 export async function runSandboxCommand(params: {
   context: AgentContext;
-  shellId: string;
-  shellDir: string;
+  executionId: string;
+  executionDir: string;
   cmd: string;
   cwd: string;
   shellPath: string;
@@ -74,7 +99,7 @@ export async function runSandboxCommand(params: {
   exitCode: number;
   spawn: SandboxSpawnResult;
 }> {
-  const spawn = await spawnShellProcess(params);
+  const spawn = await spawnInSandbox(params);
   const stdoutChunks: string[] = [];
   const stderrChunks: string[] = [];
 

package/src/sandbox/types/SandboxRuntime.ts

@@ -3,8 +3,8 @@
  *
  * 关键点（中文）
  * - 这里放的是 agent 执行层内部使用的最小 sandbox 运行时类型。
- * - 当前只围绕 `SandboxRunner` 设计，不引入复杂 provider / policy / binding 对象。
- * - 目标是让 shell plugin runtime 可以直接把命令交给 `SandboxRunner` 执行。
+ * - 当前只围绕 agent 级 sandbox spawn 设计，不引入复杂 provider / policy / binding 对象。
+ * - 目标是让 shell、task script 等本地执行入口都能复用同一个 agent sandbox 边界。
  */
 
 import type { ChildProcessWithoutNullStreams } from "node:child_process";
@@ -304,6 +304,30 @@ export interface ResolvedSandboxConfig extends SandboxConfig {
    * 当前运行时选中的 backend。
    */
   backend: SandboxBackend;
+
+  /**
+   * 当前 agent 级 sandbox 的持久目录。
+   *
+   * 说明（中文）
+   * - 该目录不属于某个 shellId，而属于当前 agent 项目。
+   * - shell、task script 等所有 sandbox 子进程共享它作为 HOME/cache 根。
+   */
+  sandboxDir: string;
+
+  /**
+   * sandbox 子进程使用的 HOME。
+   */
+  homeDir: string;
+
+  /**
+   * sandbox 子进程使用的临时目录。
+   */
+  tmpDir: string;
+
+  /**
+   * sandbox 子进程使用的 XDG cache 目录。
+   */
+  cacheDir: string;
 }
 
 /**
@@ -311,14 +335,18 @@ export interface ResolvedSandboxConfig extends SandboxConfig {
  */
 export interface SandboxSpawnParams {
   /**
-   * 当前 shell 会话标识。
+   * 当前执行记录标识。
+   *
+   * 说明（中文）
+   * - shell plugin 传入 shellId，task script 可以传入自己的 executionId。
+   * - 它只用于日志与诊断，不参与 sandbox HOME/cache/权限边界的计算。
    */
-  shellId: string;
+  executionId: string;
 
   /**
-   * shell 会话目录。
+   * 当前执行记录目录。
    */
-  shellDir: string;
+  executionDir: string;
 
   /**
    * 要执行的原始命令文本。
@@ -379,4 +407,24 @@ export interface SandboxSpawnResult {
    * 当前实际采用的网络模式。
    */
   networkMode: SandboxNetworkMode;
+
+  /**
+   * 当前 agent 级 sandbox 的持久目录。
+   */
+  sandboxDir: string;
+
+  /**
+   * 当前子进程使用的 HOME。
+   */
+  homeDir: string;
+
+  /**
+   * 当前子进程使用的临时目录。
+   */
+  tmpDir: string;
+
+  /**
+   * 当前子进程使用的 XDG cache 目录。
+   */
+  cacheDir: string;
 }

package/src/types/plugin/ImagePlugin.ts

@@ -75,7 +75,7 @@ export interface ImagePluginInput {
   quality?: string;
   /** 随机种子。 */
   seed?: number;
-  /** 业务侧任务 ID，用于异步图片任务幂等、追踪和恢复。 */
+  /** 业务侧任务 ID，用于 provider 侧幂等、追踪和恢复。 */
   client_job_id?: string;
   /** Provider 私有参数，例如 `{ openai: {...}, gemini: {...}, luchi: {...} }`。 */
   provider_options?: JsonObject;
@@ -83,58 +83,11 @@ export interface ImagePluginInput {
   [key: string]: JsonValue | ImagePluginMessage[] | undefined;
 }
 
-/**
- * ImagePlugin 图片任务状态。
- */
-export type ImagePluginJobStatus = "queued" | "running" | "succeeded" | "failed";
-
 /**
  * ImagePlugin 生成结果。
  */
 export type ImagePluginResult = UIMessage;
 
-/**
- * ImagePlugin 图片任务创建结果。
- */
-export interface ImagePluginJobCreateResult {
-  /** 图片任务唯一 ID。 */
-  job_id: string;
-  /** 当前任务状态。 */
-  status: ImagePluginJobStatus;
-  /** 读取任务结果的路径或 URL。 */
-  result_path?: string;
-  /** 人类可读状态说明。 */
-  message?: 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;
-  /** 任务未完成时建议下次轮询前等待的毫秒数。 */
-  poll_after_ms?: number;
-  /** 任务创建时间。 */
-  created_at?: string;
-  /** 任务更新时间。 */
-  updated_at?: string;
-}
-
 /**
  * ImagePlugin 构造参数。
  */
@@ -145,12 +98,6 @@ export interface ImagePluginOptions {
   title?: string;
   /** Plugin 用途说明。 */
   description?: string;
-  /** 可选：创建图片生成任务，通常传入 `(input) => city.ai.image_create(input)`。 */
-  create?: (input: ImagePluginInput) => Promise<ImagePluginJobCreateResult> | ImagePluginJobCreateResult;
-  /** 可选：读取图片生成任务结果，通常传入 `(input) => city.ai.image_result(input)`。 */
-  result?: (input: { job_id: string }) => Promise<ImagePluginJobResult> | ImagePluginJobResult;
-  /** 兼容 `generate` 动作等待任务完成的最长毫秒数。 */
-  wait_timeout_ms?: number;
-  /** 兼容 `generate` 动作每次轮询间隔毫秒数。 */
-  poll_interval_ms?: number;
+  /** 图片生成函数，通常传入 `(input) => city.ai.image(input)`。 */
+  image?: (input: ImagePluginInput) => Promise<ImagePluginResult> | ImagePluginResult;
 }