@downcity/agent 1.1.108 → 1.1.113

package/src/agent/remote/transports/HttpRemoteAgentTransport.ts

@@ -15,6 +15,8 @@ import type {
   AgentSessionInfo,
   AgentSessionSummaryPage,
   AgentSessionSystemSnapshot,
+  RemoteAgentPluginActionInput,
+  RemoteAgentPluginActionResult,
 } from "@/types/agent/AgentTypes.js";
 import type { AgentSessionEvent } from "@/types/sdk/AgentSessionEvent.js";
 import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
@@ -239,6 +241,29 @@ export class HttpRemoteAgentTransport implements RemoteAgentTransport {
     }
     return payload.page;
   }
+
+  async run_plugin_action(
+    input: RemoteAgentPluginActionInput,
+  ): Promise<RemoteAgentPluginActionResult> {
+    const payload = await read_http_action_json<RemoteAgentPluginActionResult>(
+      `${this.base_url}/api/plugins/action`,
+      {
+        method: "POST",
+        headers: this.headers({
+          "Content-Type": "application/json",
+        }),
+        body: JSON.stringify({
+          pluginName: input.plugin,
+          actionName: input.action,
+          ...(input.payload !== undefined ? { payload: input.payload } : {}),
+        }),
+      },
+    );
+    if (typeof payload.success !== "boolean") {
+      throw new Error("Remote plugin action returned an invalid response");
+    }
+    return payload;
+  }
 }
 
 async function read_http_json<T>(input: string, init?: RequestInit): Promise<T> {
@@ -251,6 +276,19 @@ async function read_http_json<T>(input: string, init?: RequestInit): Promise<T>
   return payload;
 }
 
+async function read_http_action_json<T extends { success?: boolean }>(
+  input: string,
+  init?: RequestInit,
+): Promise<T> {
+  const response = await fetch(input, init);
+  const payload = (await response.json().catch(() => ({}))) as T;
+  if (!response.ok && typeof payload.success !== "boolean") {
+    const message = extract_error_message(payload);
+    throw new Error(message || `HTTP ${response.status}`);
+  }
+  return payload;
+}
+
 async function consume_http_event_stream(params: {
   body: ReadableStream<Uint8Array>;
   abort_controller: AbortController;

package/src/agent/remote/transports/RpcRemoteAgentTransport.ts

@@ -15,6 +15,8 @@ import type {
   AgentSessionInfo,
   AgentSessionSummaryPage,
   AgentSessionSystemSnapshot,
+  RemoteAgentPluginActionInput,
+  RemoteAgentPluginActionResult,
 } from "@/types/agent/AgentTypes.js";
 import type { AgentSessionEvent } from "@/types/sdk/AgentSessionEvent.js";
 import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
@@ -101,6 +103,16 @@ export class RpcRemoteAgentTransport implements RemoteAgentTransport {
     return await this.client.list_sessions(input);
   }
 
+  async run_plugin_action(
+    input: RemoteAgentPluginActionInput,
+  ): Promise<RemoteAgentPluginActionResult> {
+    return await this.client.run_internal_plugin_action({
+      plugin_name: input.plugin,
+      action_name: input.action,
+      ...(input.payload !== undefined ? { payload: input.payload } : {}),
+    });
+  }
+
   async close(): Promise<void> {
     await this.client.close();
   }

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>` 访问；用于给外部访问的路径。不要存放敏感信息，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/`：调试产物（托管进程 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- 密钥列表能力只能返回已配置的 key 名与描述，不会返回密钥值。不要让用户把密钥“发给你自己”或继续尝试获取明文。\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>` 访问；用于给外部访问的路径。不要存放敏感信息，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/`：调试产物（托管进程 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- 向 unrestricted shell session 使用 `shell_write` 时，每一次写入都必须提供清楚的 `reason`，并等待用户确认；`shell_start` 的审批只授权启动进程，不授权后续 stdin 写入。\n- 命令会话完成后若不再需要，使用 `shell_close` 主动释放资源。\n- 不要把原始超长 shell 输出直接转发给用户，应先总结。\n- shell 命令默认在 Safe Sandbox 中执行：项目目录可读写，网络可用，HOME 指向 `.downcity/sandbox/`，真实用户 HOME 与系统目录不可写。\n- 安装 Python 依赖时优先使用项目内 `.venv`，不要使用 `pip install --user`。\n- 需要全局安装、写宿主目录、访问宿主级能力时，可以请求 `sandbox: \"unrestricted\"`；必须提供清楚的 `reason`，等待用户确认后才能执行。\n- 不要尝试 `sudo`、Xcode Command Line Tools 安装、修改 SSH/keychain/shell profile，或执行明显破坏性命令；这些请求即使使用 unrestricted sandbox 也会被拒绝。\n- 用户拒绝 unrestricted sandbox 请求后，不要反复请求同一命令，应解释影响并给出项目内替代方案。\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- 密钥列表能力只能返回已配置的 key 名与描述，不会返回密钥值。不要让用户把密钥“发给你自己”或继续尝试获取明文。\n";
 
 export default TEXT_MODULE_CONTENT;

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

@@ -21,11 +21,14 @@
 - 长任务期间，优先使用 `shell_status` 查询进度，或使用 `shell_wait` 等待状态变化；不要自己写高频空轮询循环。
 - 只有在确实需要原始增量输出时，才使用 `shell_read` 按 `from_cursor` 继续读取。
 - 需要向进程 stdin 输入内容时，使用 `shell_write`。
+- 向 unrestricted shell session 使用 `shell_write` 时，每一次写入都必须提供清楚的 `reason`，并等待用户确认；`shell_start` 的审批只授权启动进程，不授权后续 stdin 写入。
 - 命令会话完成后若不再需要，使用 `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 } : {}),
         },
       });
 
@@ -348,9 +360,10 @@ export const shell_read = tool({
  * `shell_write`：向 shell stdin 写入内容。
  */
 export const shell_write = tool({
-  description: "Write text to the stdin of an existing shell session.",
+  description:
+    "Write text to the stdin of an existing shell session. When the target session runs in unrestricted sandbox mode, provide reason; every write requires user approval.",
   inputSchema: shellWriteInputSchema,
-  execute: async ({ shell_id, chars }: ShellWriteInput) => {
+  execute: async ({ shell_id, chars, reason }: ShellWriteInput) => {
     const startedAt = Date.now();
     try {
       console.log(
@@ -358,6 +371,7 @@ export const shell_write = tool({
         JSON.stringify({
           shell_id,
           input_chars: String(chars || "").length,
+          reason: reason || "",
         }),
       );
       const response = await invokeShellAction({
@@ -365,6 +379,7 @@ export const shell_write = tool({
         payload: {
           shellId: shell_id,
           chars,
+          ...(reason ? { reason } : {}),
         },
       });
       const flatResponse = flattenShellActionResponse({ response, startedAt });

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({
@@ -87,6 +102,10 @@ export const shellReadInputSchema = z.object({
 export const shellWriteInputSchema = z.object({
   shell_id: z.string().describe("Existing shell identifier."),
   chars: z.string().describe("Bytes to write to stdin."),
+  reason: z
+    .string()
+    .optional()
+    .describe("Required when writing to an unrestricted shell session. Explain why this stdin input is needed."),
 });
 
 export const shellWaitInputSchema = z.object({

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

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

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

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

package/src/index.ts

@@ -46,6 +46,8 @@ export type {
   AgentSessionSystemSessionInfo,
   AgentSessionSystemSnapshot,
   AgentSessionTimelineEvent,
+  RemoteAgentPluginActionInput,
+  RemoteAgentPluginActionResult,
   RemoteAgentSession,
 } from "./types/agent/AgentTypes.js";
 export type {

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/agent/AgentTypes.ts

@@ -27,6 +27,10 @@ export type {
   AgentStopResult,
 } from "@/types/agent/AgentOptions.js";
 export type { RemoteAgentOptions } from "@/types/agent/RemoteAgentOptions.js";
+export type {
+  RemoteAgentPluginActionInput,
+  RemoteAgentPluginActionResult,
+} from "@/types/agent/RemoteAgentPluginAction.js";
 export type {
   AgentCreateSessionInput,
   AgentListSessionsInput,