@downcity/agent 1.1.111 → 1.1.118

package/src/agent/remote/RemoteTransport.ts

@@ -15,9 +15,15 @@ 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";
+import type {
+  ShellApprovalDecisionResult,
+  ShellApprovalView,
+} from "@downcity/shell";
 
 /**
  * Transport 持有的事件订阅句柄。
@@ -66,6 +72,16 @@ export type RemoteAgentTransport = RemoteSessionTransport & {
   create_session(input?: AgentCreateSessionInput): Promise<AgentSessionInfo>;
   /** 列出 sessions。 */
   list_sessions(input?: AgentListSessionsInput): Promise<AgentSessionSummaryPage>;
+  /** 执行远程 Agent runtime 内的 plugin action。 */
+  run_plugin_action(
+    input: RemoteAgentPluginActionInput,
+  ): Promise<RemoteAgentPluginActionResult>;
+  /** 列出 shell approvals。 */
+  approvals(): Promise<ShellApprovalView[]>;
+  /** 批准 shell approval。 */
+  approve(input: { approval_id: string }): Promise<ShellApprovalDecisionResult>;
+  /** 拒绝 shell approval。 */
+  deny(input: { approval_id: string }): Promise<ShellApprovalDecisionResult>;
   /** 关闭 transport 持有的长期连接。 */
   close?(): Promise<void>;
 };

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";
@@ -22,6 +24,10 @@ import type {
   RemoteAgentTransport,
   TransportSubscription,
 } from "@/agent/remote/RemoteTransport.js";
+import type {
+  ShellApprovalDecisionResult,
+  ShellApprovalView,
+} from "@downcity/shell";
 
 type SdkEventsReadyFrame = {
   /** SDK HTTP events 连接内部 ready 标记。 */
@@ -239,6 +245,70 @@ 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 approvals(): Promise<ShellApprovalView[]> {
+    const payload = await read_http_json<{
+      success?: boolean;
+      error?: string;
+      approvals?: ShellApprovalView[];
+    }>(`${this.base_url}/api/shell/approvals`, {
+      headers: this.headers(),
+    });
+    if (!payload.success || !Array.isArray(payload.approvals)) {
+      throw new Error(String(payload.error || "Remote shell approvals failed"));
+    }
+    return payload.approvals;
+  }
+
+  async approve(input: { approval_id: string }): Promise<ShellApprovalDecisionResult> {
+    return await this.run_shell_decision("approve", input.approval_id);
+  }
+
+  async deny(input: { approval_id: string }): Promise<ShellApprovalDecisionResult> {
+    return await this.run_shell_decision("deny", input.approval_id);
+  }
+
+  private async run_shell_decision(
+    action: "approve" | "deny",
+    approval_id: string,
+  ): Promise<ShellApprovalDecisionResult> {
+    const payload = await read_http_json<ShellApprovalDecisionResult & {
+      error?: string;
+    }>(`${this.base_url}/api/shell/${action}`, {
+      method: "POST",
+      headers: this.headers({
+        "Content-Type": "application/json",
+      }),
+      body: JSON.stringify({ approval_id }),
+    });
+    if (typeof payload.success !== "boolean") {
+      throw new Error(String(payload.error || `Remote shell ${action} failed`));
+    }
+    return payload;
+  }
 }
 
 async function read_http_json<T>(input: string, init?: RequestInit): Promise<T> {
@@ -251,6 +321,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";
@@ -23,6 +25,10 @@ import type {
   RemoteAgentTransport,
   TransportSubscription,
 } from "@/agent/remote/RemoteTransport.js";
+import type {
+  ShellApprovalDecisionResult,
+  ShellApprovalView,
+} from "@downcity/shell";
 
 /**
  * 本机 RPC transport。
@@ -101,6 +107,28 @@ 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 approvals(): Promise<ShellApprovalView[]> {
+    return await this.client.list_shell_approvals();
+  }
+
+  async approve(input: { approval_id: string }): Promise<ShellApprovalDecisionResult> {
+    return await this.client.approve_shell_approval(input.approval_id);
+  }
+
+  async deny(input: { approval_id: string }): Promise<ShellApprovalDecisionResult> {
+    return await this.client.deny_shell_approval(input.approval_id);
+  }
+
   async close(): Promise<void> {
     await this.client.close();
   }

package/src/executor/Executor.ts

@@ -8,6 +8,7 @@
  */
 
 import { streamText, type LanguageModel, type Tool } from "ai";
+import { withShellRunScope } from "@downcity/shell";
 import { SessionHistoryWriter } from "@executor/composer/history/SessionHistoryWriter.js";
 import type { SessionHistoryComposer } from "@executor/composer/history/SessionHistoryComposer.js";
 import type { SessionHistoryStore } from "@/executor/store/history/SessionHistoryStore.js";
@@ -267,7 +268,15 @@ export class Executor implements SessionExecutor {
           runContext: run_context,
         },
         async () =>
-          await this.recovery_policy.run_with_retry({
+          await withShellRunScope(
+            {
+              run_context: {
+                session_id: run_context.sessionId,
+                ...(run_context.turnId ? { turn_id: run_context.turnId } : {}),
+              },
+            },
+            async () =>
+              await this.recovery_policy.run_with_retry({
             query,
             model: this.resolveModelOrThrow(),
             run_context,
@@ -293,7 +302,8 @@ export class Executor implements SessionExecutor {
                 model,
                 next_run_context,
               ),
-          }),
+              }),
+          ),
       );
       return result;
     } finally {

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 命令默认在 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";
+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,6 +21,7 @@
 - 长任务期间，优先使用 `shell_status` 查询进度，或使用 `shell_wait` 等待状态变化；不要自己写高频空轮询循环。
 - 只有在确实需要原始增量输出时，才使用 `shell_read` 按 `from_cursor` 继续读取。
 - 需要向进程 stdin 输入内容时，使用 `shell_write`。
+- 向 unrestricted shell session 使用 `shell_write` 时，每一次写入都必须提供清楚的 `reason`，并等待用户确认；`shell_start` 的审批只授权启动进程，不授权后续 stdin 写入。
 - 命令会话完成后若不再需要，使用 `shell_close` 主动释放资源。
 - 不要把原始超长 shell 输出直接转发给用户，应先总结。
 - shell 命令默认在 Safe Sandbox 中执行：项目目录可读写，网络可用，HOME 指向 `.downcity/sandbox/`，真实用户 HOME 与系统目录不可写。

package/src/index.ts

@@ -46,6 +46,8 @@ export type {
   AgentSessionSystemSessionInfo,
   AgentSessionSystemSnapshot,
   AgentSessionTimelineEvent,
+  RemoteAgentPluginActionInput,
+  RemoteAgentPluginActionResult,
   RemoteAgentSession,
 } from "./types/agent/AgentTypes.js";
 export type {
@@ -103,7 +105,6 @@ export {
   loadStaticSystemPrompts,
   StaticPromptCatalog,
 } from "./executor/composer/system/default/StaticPromptCatalog.js";
-export { shellTools } from "./executor/tools/shell/ShellToolDefinition.js";
 
 // 通用 plugin 宿主工具
 export {

package/src/rpc/Client.ts

@@ -37,6 +37,10 @@ import type {
   RpcSessionSubscription,
   RpcSystemPromptPayload,
 } from "@/types/rpc/RpcProtocol.js";
+import type {
+  ShellApprovalDecisionResult,
+  ShellApprovalView,
+} from "@downcity/shell";
 
 export type {
   RpcClientEndpoint,
@@ -358,6 +362,40 @@ export class RpcClient {
     });
   }
 
+  /**
+   * 列出 shell approvals。
+   */
+  async list_shell_approvals(): Promise<ShellApprovalView[]> {
+    const data = await this.request<{ approvals: ShellApprovalView[] }>({
+      method: "internal.shell.approvals",
+    });
+    return Array.isArray(data.approvals) ? data.approvals : [];
+  }
+
+  /**
+   * 批准 shell approval。
+   */
+  async approve_shell_approval(approval_id: string): Promise<ShellApprovalDecisionResult> {
+    return await this.request<ShellApprovalDecisionResult>({
+      method: "internal.shell.approve",
+      params: {
+        approvalId: approval_id,
+      },
+    });
+  }
+
+  /**
+   * 拒绝 shell approval。
+   */
+  async deny_shell_approval(approval_id: string): Promise<ShellApprovalDecisionResult> {
+    return await this.request<ShellApprovalDecisionResult>({
+      method: "internal.shell.deny",
+      params: {
+        approvalId: approval_id,
+      },
+    });
+  }
+
   /**
    * 关闭底层连接。
    */

package/src/rpc/server/InternalHandlers.ts

@@ -154,11 +154,42 @@ export async function handleInternalRpcRequest(params: {
       });
       return true;
     }
+    case "internal.shell.approvals": {
+      const shell = requireShell(options);
+      write_success(request.id, {
+        approvals: shell.approvals(),
+      });
+      return true;
+    }
+    case "internal.shell.approve": {
+      const shell = requireShell(options);
+      const result = await shell.approve({
+        approval_id: String(request.params.approvalId || "").trim(),
+      });
+      write_success(request.id, result);
+      return true;
+    }
+    case "internal.shell.deny": {
+      const shell = requireShell(options);
+      const result = await shell.deny({
+        approval_id: String(request.params.approvalId || "").trim(),
+      });
+      write_success(request.id, result);
+      return true;
+    }
     default:
       return false;
   }
 }
 
+function requireShell(options: RpcRequestHandlerOptions) {
+  const shell = options.getShell?.();
+  if (!shell) {
+    throw new Error("Agent RPC server was started without Shell");
+  }
+  return shell;
+}
+
 function requireAgentContext(options: RpcRequestHandlerOptions): AgentContext {
   const context = options.getAgentContext?.();
   if (!context) {

package/src/rpc/server/ServerTypes.ts

@@ -10,6 +10,7 @@ import type { AgentSessionCollection } from "@/types/agent/AgentTypes.js";
 import type { AgentContext } from "@/types/runtime/agent/AgentContext.js";
 import type { AgentRuntime } from "@/types/runtime/agent/AgentRuntime.js";
 import type { RpcEventFrame } from "@/types/rpc/RpcProtocol.js";
+import type { Shell } from "@downcity/shell";
 
 /**
  * RPC Server 启动参数。
@@ -25,6 +26,8 @@ export interface RpcServerStartOptions {
   getAgentContext?: () => AgentContext;
   /** Agent 运行态访问口。 */
   getAgentRuntime?: () => AgentRuntime;
+  /** Shell 访问口。 */
+  getShell?: () => Shell | undefined;
 }
 
 /**
@@ -37,6 +40,8 @@ export interface RpcRequestHandlerOptions {
   getAgentContext?: () => AgentContext;
   /** Agent 运行态访问口。 */
   getAgentRuntime?: () => AgentRuntime;
+  /** Shell 访问口。 */
+  getShell?: () => Shell | undefined;
 }
 
 /**

package/src/types/agent/AgentOptions.ts

@@ -7,6 +7,7 @@
  */
 
 import type { Tool } from "ai";
+import type { Shell } from "@downcity/shell";
 import type { BasePlugin } from "@/plugin/core/BasePlugin.js";
 import type { AgentModel } from "@/model/CityModelAdapter.js";
 import type { RpcServerInstance } from "@/rpc/Server.js";
@@ -51,6 +52,15 @@ export interface AgentOptions {
    */
   tools?: Record<string, Tool>;
 
+  /**
+   * 当前 agent 内建 shell 能力。
+   *
+   * 关键点（中文）
+   * - Shell 不是 plugin，而是 agent 直接挂载的内建工具对象。
+   * - 未传入时，Agent 不会自动注入 shell tools。
+   */
+  shell?: Shell;
+
   /**
    * 调用方显式传入的静态基础指令。
    *

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,

package/src/types/agent/RemoteAgentPluginAction.ts

@@ -0,0 +1,52 @@
+/**
+ * RemoteAgent plugin action 类型。
+ *
+ * 关键点（中文）
+ * - RemoteAgent 是远程 runtime 的瘦客户端，因此这里只描述远程调用协议。
+ * - 业务 action 的具体 payload 与 data 由目标 plugin 自己定义。
+ */
+
+import type { JsonValue } from "@/types/common/Json.js";
+import type { PluginActionResult } from "@/types/plugin/PluginAction.js";
+
+/**
+ * RemoteAgent 远程 plugin action 调用输入。
+ */
+export interface RemoteAgentPluginActionInput {
+  /**
+   * 目标 plugin 名称。
+   *
+   * 示例：`shell`、`chat`、`task`。
+   */
+  plugin: string;
+
+  /**
+   * 目标 action 名称。
+   *
+   * 示例：`approve`、`deny`、`send`。
+   */
+  action: string;
+
+  /**
+   * 传给目标 action 的 JSON payload。
+   *
+   * shell approval 示例：`{ "approvalId": "ap_xxx" }`。
+   */
+  payload?: JsonValue;
+}
+
+/**
+ * RemoteAgent 远程 plugin action 调用结果。
+ */
+export type RemoteAgentPluginActionResult =
+  PluginActionResult<JsonValue> & {
+    /**
+     * Runtime 回传的 plugin 名称。
+     */
+    pluginName?: string;
+
+    /**
+     * Runtime 回传的 action 名称。
+     */
+    actionName?: string;
+  };

package/src/types/config/DowncityConfig.ts

@@ -8,7 +8,7 @@
 import type { LlmConfig } from "@/types/config/LlmConfig.js";
 import type { ExecutionBindingConfig } from "@/types/config/ExecutionBinding.js";
 import type { JsonObject } from "@/types/common/Json.js";
-import type { SandboxProjectConfig } from "@/sandbox/types/Sandbox.js";
+import type { SandboxProjectConfig } from "@downcity/shell/sandbox/types/Sandbox.js";
 
 /**
  * 单个聊天渠道配置。
@@ -165,7 +165,7 @@ export interface DowncityConfig {
    * shell / CLI 执行 sandbox 配置。
    *
    * 关键点（中文）
-   * - 当前只作用于 shell plugin 这条命令执行链。
+   * - 当前只作用于内建 shell 这条命令执行链。
    * - 这里不表达审批、用户授权与复杂策略系统，只表达最小边界。
    */
   sandbox?: SandboxProjectConfig;

package/src/types/rpc/RpcProtocol.ts

@@ -231,6 +231,34 @@ export type RpcRequest =
         /** action payload。 */
         payload?: JsonValue;
       };
+    }
+  | {
+      /** 请求 id，用于匹配响应。 */
+      id: string;
+      /** 列出 shell approvals。 */
+      method: "internal.shell.approvals";
+    }
+  | {
+      /** 请求 id，用于匹配响应。 */
+      id: string;
+      /** 批准 shell approval。 */
+      method: "internal.shell.approve";
+      /** approval 参数。 */
+      params: {
+        /** approval id。 */
+        approvalId: string;
+      };
+    }
+  | {
+      /** 请求 id，用于匹配响应。 */
+      id: string;
+      /** 拒绝 shell approval。 */
+      method: "internal.shell.deny";
+      /** approval 参数。 */
+      params: {
+        /** approval id。 */
+        approvalId: string;
+      };
     };
 
 /**

package/src/types/sdk/AgentSessionEvent.ts

@@ -90,7 +90,7 @@ export interface AgentSessionToolCallEvent {
   /**
    * 当前工具名称。
    */
-  toolName: string;
+  toolName: "shell_exec" | "shell_start" | "shell_write" | string;
 
   /**
    * 当前工具输入参数。
@@ -120,7 +120,7 @@ export interface AgentSessionToolResultEvent {
   /**
    * 当前工具名称。
    */
-  toolName: string;
+  toolName: "shell_exec" | "shell_start" | "shell_write" | string;
 
   /**
    * 当前工具输出结果。
@@ -150,7 +150,7 @@ export interface AgentSessionToolApprovalRequestEvent {
   /**
    * 当前工具名称。
    */
-  toolName: string;
+  toolName: "shell_exec" | "shell_start" | "shell_write" | string;
 
   /**
    * 当前审批请求唯一标识。
@@ -164,9 +164,33 @@ export interface AgentSessionToolApprovalRequestEvent {
 
   /**
    * 请求执行的命令文本。
+   *
+   * 说明（中文）
+   * - `shell_exec` / `shell_start` 中是命令文本。
+   * - `shell_write` 中是 stdin 写入内容，用于兼容旧 UI 展示。
    */
   cmd: string;
 
+  /**
+   * 当前审批动作类型。
+   */
+  operation?: "exec" | "start" | "write";
+
+  /**
+   * 关联 shell_id；`shell_write` 审批时用于标识目标会话。
+   */
+  shellId?: string;
+
+  /**
+   * stdin 写入内容预览；仅 `shell_write` 审批存在。
+   */
+  inputPreview?: string;
+
+  /**
+   * stdin 写入字符数；仅 `shell_write` 审批存在。
+   */
+  inputChars?: number;
+
   /**
    * 命令执行目录。
    */
@@ -205,7 +229,7 @@ export interface AgentSessionToolApprovalResultEvent {
   /**
    * 当前工具名称。
    */
-  toolName: string;
+  toolName: "shell_exec" | "shell_start" | "shell_write" | string;
 
   /**
    * 当前审批请求唯一标识。