@downcity/agent 1.1.108 → 1.1.111

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

@@ -23,9 +23,11 @@
 - 需要向进程 stdin 输入内容时，使用 `shell_write`。
 - 命令会话完成后若不再需要，使用 `shell_close` 主动释放资源。
 - 不要把原始超长 shell 输出直接转发给用户，应先总结。
-- shell 命令默认在当前 agent 的 sandbox 中执行：项目目录可读写，网络可用，HOME 指向 `.downcity/sandbox/`，真实用户 HOME 与系统目录不可写。
+- shell 命令默认在 Safe Sandbox 中执行：项目目录可读写，网络可用，HOME 指向 `.downcity/sandbox/`，真实用户 HOME 与系统目录不可写。
 - 安装 Python 依赖时优先使用项目内 `.venv`，不要使用 `pip install --user`。
-- 不要尝试 `sudo`、`brew install`、Xcode Command Line Tools 安装或写 `/usr/local`、`/opt/homebrew`、`/System` 等宿主系统目录；如果确实缺少系统级依赖，直接告诉用户需要在宿主机安装。
+- 需要全局安装、写宿主目录、访问宿主级能力时，可以请求 `sandbox: "unrestricted"`；必须提供清楚的 `reason`，等待用户确认后才能执行。
+- 不要尝试 `sudo`、Xcode Command Line Tools 安装、修改 SSH/keychain/shell profile，或执行明显破坏性命令；这些请求即使使用 unrestricted sandbox 也会被拒绝。
+- 用户拒绝 unrestricted sandbox 请求后，不要反复请求同一命令，应解释影响并给出项目内替代方案。
 - 下载模型、工具缓存、临时状态应自然落在 `.downcity/sandbox/` 或项目目录中，不要假设可复用真实用户缓存。
 
 # 默认决策与澄清

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

@@ -205,13 +205,23 @@ export function flattenShellActionResponse(params: {
 }): JsonObject {
   const shell = params.response.shell;
   const chunk = params.response.chunk;
+  const exitCode = typeof shell.exitCode === "number" ? shell.exitCode : null;
+  const success =
+    shell.approvalStatus !== "denied" &&
+    shell.approvalStatus !== "expired" &&
+    (exitCode === null || exitCode === 0);
   return {
-    success: true,
+    success,
     shell_id: shell.shellId,
     status: shell.status,
     cmd: shell.cmd,
     cwd: shell.cwd,
     sandboxed: shell.sandboxed === true,
+    sandbox: shell.sandboxMode || (shell.sandboxed === false ? "unrestricted" : "safe"),
+    approval_status: shell.approvalStatus || null,
+    approval_id: shell.approvalId || null,
+    approval_reason: shell.approvalReason || null,
+    stdin_writable: shell.stdinWritable !== false,
     sandbox_backend: shell.sandboxBackend || null,
     sandbox_network_mode: shell.sandboxNetworkMode || null,
     sandbox_dir: shell.sandboxDir || null,
@@ -223,7 +233,7 @@ export function flattenShellActionResponse(params: {
     started_at: shell.startedAt,
     updated_at: shell.updatedAt,
     ended_at: typeof shell.endedAt === "number" ? shell.endedAt : null,
-    exit_code: typeof shell.exitCode === "number" ? shell.exitCode : null,
+    exit_code: exitCode,
     output: chunk?.output || "",
     start_cursor: typeof chunk?.startCursor === "number" ? chunk.startCursor : null,
     end_cursor: typeof chunk?.endCursor === "number" ? chunk.endCursor : null,
@@ -257,19 +267,29 @@ export function flattenShellExecResponse(params: {
 }): JsonObject {
   const shell = params.response.shell;
   const chunk = params.response.chunk;
+  const exitCode = typeof shell.exitCode === "number" ? shell.exitCode : null;
+  const success =
+    shell.approvalStatus !== "denied" &&
+    shell.approvalStatus !== "expired" &&
+    (exitCode === null || exitCode === 0);
   return {
-    success: true,
+    success,
     status: shell.status,
     cmd: shell.cmd,
     cwd: shell.cwd,
     sandboxed: shell.sandboxed === true,
+    sandbox: shell.sandboxMode || (shell.sandboxed === false ? "unrestricted" : "safe"),
+    approval_status: shell.approvalStatus || null,
+    approval_id: shell.approvalId || null,
+    approval_reason: shell.approvalReason || null,
+    stdin_writable: shell.stdinWritable !== false,
     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,
+    exit_code: exitCode,
     output: chunk?.output || "",
     original_chars: chunk?.originalChars ?? 0,
     original_lines: chunk?.originalLines ?? 0,

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

@@ -85,6 +85,8 @@ export const shell_start = tool({
     inline_wait_ms = 1200,
     max_output_tokens,
     auto_notify_on_exit,
+    sandbox = "safe",
+    reason,
   }: ShellStartInput) => {
     const startedAt = Date.now();
 
@@ -99,6 +101,8 @@ export const shell_start = tool({
           inline_wait_ms,
           max_output_tokens: max_output_tokens ?? null,
           auto_notify_on_exit: auto_notify_on_exit ?? null,
+          sandbox,
+          reason: reason || "",
         }),
       );
 
@@ -128,6 +132,8 @@ export const shell_start = tool({
           ...(typeof auto_notify_on_exit === "boolean"
             ? { autoNotifyOnExit: auto_notify_on_exit }
             : {}),
+          sandbox,
+          ...(reason ? { reason } : {}),
         },
       });
 
@@ -173,6 +179,8 @@ export const shell_exec = tool({
     login = true,
     timeout_ms = 60000,
     max_output_tokens,
+    sandbox = "safe",
+    reason,
   }: ShellExecInput) => {
     const startedAt = Date.now();
 
@@ -186,6 +194,8 @@ export const shell_exec = tool({
           login,
           timeout_ms,
           max_output_tokens: max_output_tokens ?? null,
+          sandbox,
+          reason: reason || "",
         }),
       );
 
@@ -212,6 +222,8 @@ export const shell_exec = tool({
           ...(typeof max_output_tokens === "number"
             ? { maxOutputTokens: max_output_tokens }
             : {}),
+          sandbox,
+          ...(reason ? { reason } : {}),
         },
       });
 

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

@@ -8,6 +8,17 @@
 
 import { z } from "zod";
 
+const shellSandboxModeSchema = z
+  .enum(["safe", "unrestricted"])
+  .optional()
+  .default("safe")
+  .describe("Sandbox mode. safe is the default; unrestricted requires user approval.");
+
+const shellUnrestrictedReasonSchema = z
+  .string()
+  .optional()
+  .describe("Required when sandbox is unrestricted. Explain why host-level execution is needed.");
+
 export const shellStartInputSchema = z.object({
   cmd: z.string().describe("Shell command to execute."),
   workdir: z
@@ -36,6 +47,8 @@ export const shellStartInputSchema = z.object({
     .boolean()
     .optional()
     .describe("Whether the shell plugin runtime should auto-return to the owning chat agent when the command exits."),
+  sandbox: shellSandboxModeSchema,
+  reason: shellUnrestrictedReasonSchema,
 });
 
 export const shellExecInputSchema = z.object({
@@ -62,6 +75,8 @@ export const shellExecInputSchema = z.object({
     .number()
     .optional()
     .describe("Maximum output tokens returned in the final result."),
+  sandbox: shellSandboxModeSchema,
+  reason: shellUnrestrictedReasonSchema,
 });
 
 export const shellStatusInputSchema = z.object({

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

@@ -6,6 +6,11 @@
  * - `shell_id` 与 chat `sessionId` 严格分离，避免语义混淆。
  */
 
+/**
+ * shell 执行 sandbox 模式。
+ */
+export type ShellSandboxMode = "safe" | "unrestricted";
+
 /**
  * 启动一个交互式 shell session 的输入。
  */
@@ -24,6 +29,10 @@ export type ShellStartInput = {
   max_output_tokens?: number;
   /** 进程退出时是否自动通知调用方。 */
   auto_notify_on_exit?: boolean;
+  /** 命令执行 sandbox 模式；默认 safe。 */
+  sandbox?: ShellSandboxMode;
+  /** 请求 unrestricted sandbox 时展示给用户的原因。 */
+  reason?: string;
 };
 
 /**
@@ -42,6 +51,10 @@ export type ShellExecInput = {
   timeout_ms?: number;
   /** 最多返回多少输出 token。 */
   max_output_tokens?: number;
+  /** 命令执行 sandbox 模式；默认 safe。 */
+  sandbox?: ShellSandboxMode;
+  /** 请求 unrestricted sandbox 时展示给用户的原因。 */
+  reason?: string;
 };
 
 /**

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

@@ -14,6 +14,16 @@ export type ShellSessionStatus =
   | "killed"
   | "expired";
 
+/**
+ * shell 执行 sandbox 模式。
+ */
+export type ShellSandboxMode = "safe" | "unrestricted";
+
+/**
+ * unrestricted sandbox 审批状态。
+ */
+export type ShellApprovalStatus = "approved" | "denied" | "expired";
+
 /**
  * shell 会话关联的外部引用。
  *
@@ -50,6 +60,16 @@ export type ShellSessionSnapshot = {
   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 网络模式。 */
@@ -112,6 +132,12 @@ export type ShellStartRequest = {
   ownerContextId?: string;
   /** 是否在 shell 结束后自动回投主 chat agent。 */
   autoNotifyOnExit?: boolean;
+  /** 命令执行 sandbox 模式；默认 safe。 */
+  sandbox?: ShellSandboxMode;
+  /** 请求 unrestricted sandbox 时展示给用户的原因。 */
+  reason?: string;
+  /** 内部审批来源工具名；普通调用方不需要传。 */
+  approvalToolName?: "shell_exec" | "shell_start";
 };
 
 /**
@@ -134,6 +160,10 @@ export type ShellExecRequest = {
   timeoutMs?: number;
   /** 单次读取输出返回给模型的 token 上限。 */
   maxOutputTokens?: number;
+  /** 命令执行 sandbox 模式；默认 safe。 */
+  sandbox?: ShellSandboxMode;
+  /** 请求 unrestricted sandbox 时展示给用户的原因。 */
+  reason?: string;
 };
 
 /**

package/src/sandbox/LinuxBubblewrapSandbox.ts

@@ -211,6 +211,7 @@ export async function spawnLinuxBubblewrapSandbox(
     child,
     cwd: params.actualCwd,
     sandboxed: true,
+    sandboxMode: "safe",
     backend: "linux-bubblewrap",
     networkMode: params.config.networkMode,
     sandboxDir: params.config.sandboxDir,

package/src/sandbox/MacOsSeatbeltSandbox.ts

@@ -180,6 +180,7 @@ export async function spawnMacOsSeatbeltSandbox(
     child,
     cwd: params.actualCwd,
     sandboxed: true,
+    sandboxMode: "safe",
     backend: "macos-seatbelt",
     networkMode: params.config.networkMode,
     sandboxDir: params.config.sandboxDir,

package/src/sandbox/SandboxRunner.ts

@@ -12,6 +12,7 @@ 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";
+import { spawnUnrestrictedSandbox } from "@/sandbox/UnrestrictedSandbox.js";
 
 /**
  * 启动 shell 子进程。
@@ -25,6 +26,7 @@ export async function spawnShellProcess(params: {
   shellPath: string;
   login: boolean;
   baseEnv: NodeJS.ProcessEnv;
+  sandboxMode?: "safe" | "unrestricted";
 }): Promise<SandboxSpawnResult> {
   return spawnInSandbox({
     context: params.context,
@@ -35,6 +37,7 @@ export async function spawnShellProcess(params: {
     shellPath: params.shellPath,
     login: params.login,
     baseEnv: params.baseEnv,
+    sandboxMode: params.sandboxMode,
   });
 }
 
@@ -50,7 +53,21 @@ export async function spawnInSandbox(params: {
   shellPath: string;
   login: boolean;
   baseEnv: NodeJS.ProcessEnv;
+  sandboxMode?: "safe" | "unrestricted";
 }): Promise<SandboxSpawnResult> {
+  if (params.sandboxMode === "unrestricted") {
+    return spawnUnrestrictedSandbox({
+      executionId: params.executionId,
+      executionDir: params.executionDir,
+      cmd: params.cmd,
+      cwd: params.cwd,
+      shellPath: params.shellPath,
+      login: params.login,
+      baseEnv: params.baseEnv,
+      actualCwd: params.cwd,
+    });
+  }
+
   const config = resolveSandboxConfig(params.context);
   const actualCwd = resolveSandboxCwd({
     rootPath: config.rootPath,

package/src/sandbox/UnrestrictedSandbox.ts

@@ -0,0 +1,53 @@
+/**
+ * Unrestricted sandbox backend。
+ *
+ * 关键点（中文）
+ * - 这是 Downcity Runtime 管理的高权限执行环境，不是 agent 直接访问宿主 shell。
+ * - 进程继承宿主可见文件系统与环境边界，但必须由上层 approval 流程批准后才能调用。
+ * - 本 backend 只负责 spawn，不做审批、审计或风险判断。
+ */
+
+import { spawn } from "node:child_process";
+import fs from "fs-extra";
+import type {
+  SandboxSpawnParams,
+  SandboxSpawnResult,
+} from "@/sandbox/types/SandboxRuntime.js";
+
+/**
+ * 在 unrestricted sandbox 中启动 shell 子进程。
+ */
+export async function spawnUnrestrictedSandbox(
+  params: Omit<SandboxSpawnParams, "config"> & { actualCwd: string },
+): Promise<SandboxSpawnResult> {
+  await fs.ensureDir(params.executionDir);
+
+  const child = spawn(
+    params.shellPath,
+    [
+      params.login ? "-lc" : "-c",
+      params.cmd,
+    ],
+    {
+      cwd: params.actualCwd,
+      stdio: "pipe",
+      env: params.baseEnv,
+    },
+  );
+
+  child.stdout.setEncoding("utf8");
+  child.stderr.setEncoding("utf8");
+
+  return {
+    child,
+    cwd: params.actualCwd,
+    sandboxed: false,
+    sandboxMode: "unrestricted",
+    backend: "unrestricted-host",
+    networkMode: "full",
+    sandboxDir: "",
+    homeDir: String(params.baseEnv.HOME || ""),
+    tmpDir: String(params.baseEnv.TMPDIR || "/tmp"),
+    cacheDir: String(params.baseEnv.XDG_CACHE_HOME || ""),
+  };
+}

package/src/sandbox/types/SandboxRuntime.ts

@@ -14,7 +14,7 @@ import type { SandboxNetworkMode } from "@/sandbox/types/Sandbox.js";
 /**
  * 当前内置支持的 sandbox backend。
  */
-export type SandboxBackend = "macos-seatbelt" | "linux-bubblewrap";
+export type SandboxBackend = "macos-seatbelt" | "linux-bubblewrap" | "unrestricted-host";
 
 /**
  * sandbox 会话状态。
@@ -305,6 +305,11 @@ export interface ResolvedSandboxConfig extends SandboxConfig {
    */
   backend: SandboxBackend;
 
+  /**
+   * 当前 Downcity sandbox 模式。
+   */
+  sandboxMode?: "safe" | "unrestricted";
+
   /**
    * 当前 agent 级 sandbox 的持久目录。
    *
@@ -398,6 +403,11 @@ export interface SandboxSpawnResult {
    */
   sandboxed: boolean;
 
+  /**
+   * 当前 Downcity sandbox 模式。
+   */
+  sandboxMode?: "safe" | "unrestricted";
+
   /**
    * 当前使用的 backend 名称。
    */

package/src/session/Session.ts

@@ -270,6 +270,9 @@ export class Session implements AgentSession {
       getExecutor: () => this.executor.getExecutor(),
       prompt: async (input) => await this.prompt(input),
       subscribe: (subscriber) => this.subscribe(subscriber),
+      publishEvent: (event) => {
+        this.eventHub.publish(event);
+      },
       clearExecutor: () => {
         this.executor.clearExecutor();
       },

package/src/session/services/SessionTurnService.ts

@@ -140,6 +140,7 @@ export class SessionTurnService {
   }> {
     const tool_name_by_call_id = new Map<string, string>();
     const run_context: SessionRunContext = {
+      turnId: input.turnId,
       sessionId: this.session_id,
       projectRoot: this.project_root,
       onStepCallback: input.onStepMerge,

package/src/session/storage/RuntimeSessionPort.ts

@@ -10,6 +10,7 @@ import type { SessionPort } from "@/types/runtime/agent/AgentContext.js";
 import type { SessionHistoryStore } from "@/executor/store/history/SessionHistoryStore.js";
 import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
 import type {
+  AgentSessionEvent,
   AgentSessionSubscriber,
   AgentSessionUnsubscribe,
 } from "@/types/sdk/AgentSessionEvent.js";
@@ -37,6 +38,10 @@ export interface CreateRuntimeSessionPortParams {
   subscribe: (
     subscriber: AgentSessionSubscriber,
   ) => AgentSessionUnsubscribe;
+  /**
+   * 发布一条 session runtime 事件。
+   */
+  publishEvent: (event: AgentSessionEvent) => void;
   /**
    * 清理当前 session executor 状态。
    */
@@ -88,6 +93,9 @@ export function createRuntimeSessionPort(
     subscribe: (subscriber) => {
       return params.subscribe(subscriber);
     },
+    publishEvent: (event) => {
+      params.publishEvent(event);
+    },
     clearExecutor: () => {
       params.clearExecutor();
     },

package/src/types/executor/SessionRunContext.ts

@@ -18,6 +18,15 @@ import type { FileUIPart } from "ai";
  * 单次 session run 的运行上下文。
  */
 export interface SessionRunContext {
+  /**
+   * 当前执行所属的 turn 标识。
+   *
+   * 关键点（中文）
+   * - session 是长期对话容器，turn 是单次用户输入触发的执行轮次。
+   * - 工具运行时发布 session event 时应优先使用该字段，避免把 sessionId 误当 turnId。
+   */
+  turnId?: string;
+
   /**
    * 当前执行所属的 session 标识。
    */

package/src/types/runtime/agent/AgentContext.ts

@@ -31,6 +31,7 @@ import type {
 import type { SessionHistoryStore } from "@/executor/store/history/SessionHistoryStore.js";
 import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
 import type {
+  AgentSessionEvent,
   AgentSessionSubscriber,
   AgentSessionUnsubscribe,
 } from "@/types/sdk/AgentSessionEvent.js";
@@ -132,6 +133,14 @@ export interface SessionPort {
    * - 历史消息仍通过 `getHistoryStore()` / SDK `history()` 读取。
    */
   subscribe(subscriber: AgentSessionSubscriber): AgentSessionUnsubscribe;
+  /**
+   * 发布一条 session runtime 事件。
+   *
+   * 关键点（中文）
+   * - plugin runtime 用它把审批、外部进度等非模型 chunk 事件推送给订阅方。
+   * - 历史消息持久化仍由 appendUserMessage / appendAssistantMessage 负责。
+   */
+  publishEvent(event: AgentSessionEvent): void;
   /**
    * 清理当前 session 的 executor 缓存。
    */

package/src/types/sdk/AgentSessionEvent.ts

@@ -128,6 +128,96 @@ export interface AgentSessionToolResultEvent {
   result: JsonValue;
 }
 
+/**
+ * 工具审批请求事件。
+ */
+export interface AgentSessionToolApprovalRequestEvent {
+  /**
+   * 当前事件类型。
+   */
+  type: "tool-approval-request";
+
+  /**
+   * 当前审批所属 turn。
+   */
+  turnId: string;
+
+  /**
+   * 当前工具调用唯一标识。
+   */
+  toolCallId: string;
+
+  /**
+   * 当前工具名称。
+   */
+  toolName: string;
+
+  /**
+   * 当前审批请求唯一标识。
+   */
+  approvalId: string;
+
+  /**
+   * 请求执行的 sandbox 模式。
+   */
+  sandbox: "unrestricted";
+
+  /**
+   * 请求执行的命令文本。
+   */
+  cmd: string;
+
+  /**
+   * 命令执行目录。
+   */
+  cwd: string;
+
+  /**
+   * Agent 给用户展示的申请原因。
+   */
+  reason: string;
+
+  /**
+   * 当前审批状态。
+   */
+  status: "pending";
+}
+
+/**
+ * 工具审批结果事件。
+ */
+export interface AgentSessionToolApprovalResultEvent {
+  /**
+   * 当前事件类型。
+   */
+  type: "tool-approval-result";
+
+  /**
+   * 当前审批所属 turn。
+   */
+  turnId: string;
+
+  /**
+   * 当前工具调用唯一标识。
+   */
+  toolCallId: string;
+
+  /**
+   * 当前工具名称。
+   */
+  toolName: string;
+
+  /**
+   * 当前审批请求唯一标识。
+   */
+  approvalId: string;
+
+  /**
+   * 用户最终决策。
+   */
+  decision: "approved" | "denied" | "expired";
+}
+
 /**
  * assistant step 完成事件。
  */
@@ -236,6 +326,8 @@ export type AgentSessionEvent =
   | AgentSessionReasoningDeltaEvent
   | AgentSessionToolCallEvent
   | AgentSessionToolResultEvent
+  | AgentSessionToolApprovalRequestEvent
+  | AgentSessionToolApprovalResultEvent
   | AgentSessionAssistantStepEvent
   | AgentSessionTitleEvent
   | AgentSessionTurnFinishEvent