@downcity/agent 1.1.113 → 1.1.118

package/src/agent/local/Agent.ts

@@ -24,6 +24,11 @@ import type {
   AgentStartResult,
   AgentStopResult,
 } from "@/types/agent/AgentTypes.js";
+import type {
+  ShellApprovalDecisionResult,
+  ShellApprovalView,
+  Shell,
+} from "@downcity/shell";
 import { PluginRegistry } from "@/plugin/core/PluginRegistry.js";
 import { Logger } from "@/utils/logger/Logger.js";
 import { normalizeInstructionInput } from "@/agent/local/AgentInstructions.js";
@@ -53,6 +58,7 @@ export class Agent {
   private readonly SessionClass: AgentOptions["Session"];
   private readonly sessionManager: AgentSessionManager;
   private readonly lifecycleService: AgentLifecycleService;
+  private readonly shell?: AgentOptions["shell"];
 
   private instruction: string[];
 
@@ -88,6 +94,7 @@ export class Agent {
     this.config = assembly.config;
     this.env = assembly.env;
     this.instruction = assembly.instruction;
+    this.shell = assembly.shell;
 
     this.sessionManager = this.create_session_manager(assembly);
     session_manager_ref = this.sessionManager;
@@ -96,6 +103,7 @@ export class Agent {
       agent_context: this.agentContext,
       session_collection: this.sessionManager.get_session_collection(),
       get_runtime: () => this.runtime,
+      get_shell: () => this.shell,
     });
   }
 
@@ -136,6 +144,29 @@ export class Agent {
     return await this.lifecycleService.stop();
   }
 
+  /**
+   * 列出当前 shell pending approvals。
+   */
+  approvals(): ShellApprovalView[] {
+    return this.shell?.approvals() || [];
+  }
+
+  /**
+   * 批准当前 shell pending approval。
+   */
+  async approve(input: { approval_id: string }): Promise<ShellApprovalDecisionResult> {
+    if (!this.shell) throw new Error("Agent shell is not configured");
+    return await this.shell.approve(input);
+  }
+
+  /**
+   * 拒绝当前 shell pending approval。
+   */
+  async deny(input: { approval_id: string }): Promise<ShellApprovalDecisionResult> {
+    if (!this.shell) throw new Error("Agent shell is not configured");
+    return await this.shell.deny(input);
+  }
+
   /**
    * 更新当前 SDK Agent 的静态基础指令。
    */
@@ -178,6 +209,13 @@ export class Agent {
     return this.sessionManager.get_session_collection();
   }
 
+  /**
+   * 返回当前 agent 挂载的 Shell。
+   */
+  getShell(): Shell | undefined {
+    return this.shell;
+  }
+
   private create_session_manager(
     assembly: AgentAssemblyResult,
   ): AgentSessionManager {

package/src/agent/local/services/AgentAssemblyService.ts

@@ -28,13 +28,13 @@ import {
   createAgentContext,
   createAgentRuntime,
 } from "@/agent/local/AgentRuntimeFactory.js";
-import { setShellToolRuntime } from "@executor/tools/shell/ShellToolDefinition.js";
 import {
   plugin_tools,
   setPluginToolRuntime,
 } from "@executor/tools/plugin/PluginToolDefinition.js";
 import type { AgentManagedSession } from "@/types/agent/AgentTypes.js";
 import type { SessionPort } from "@/types/runtime/agent/AgentContext.js";
+import type { AgentSessionEvent } from "@/types/sdk/AgentSessionEvent.js";
 
 type AgentAssemblyServiceOptions = {
   /**
@@ -123,6 +123,11 @@ export interface AgentAssemblyResult {
    * 当前 agent context。
    */
   agent_context: AgentContext;
+
+  /**
+   * 当前 agent 挂载的内建 shell。
+   */
+  shell?: AgentOptions["shell"];
 }
 
 /**
@@ -201,7 +206,22 @@ export class AgentAssemblyService {
       resolve_session_model: async (session_id) =>
         await this.resolve_session_model(session_id),
     });
-    setShellToolRuntime(agent_context.invoke);
+    const shell = this.options.shell;
+    if (shell) {
+      shell.configure({
+        root_path: path,
+        env,
+        agent_id: id,
+        sandbox: config.sandbox,
+        logger,
+        emit_event: (event) => {
+          const session_id = String(event.session_id || "").trim();
+          if (!session_id) return;
+          agent_context.session.get(session_id).publishEvent(event as unknown as AgentSessionEvent);
+        },
+      });
+      Object.assign(tools, shell.tools);
+    }
     setPluginToolRuntime(plugins);
 
     return {
@@ -217,6 +237,7 @@ export class AgentAssemblyService {
       plugins,
       runtime,
       agent_context,
+      ...(shell ? { shell } : {}),
     };
   }
 

package/src/agent/local/services/AgentLifecycleService.ts

@@ -22,6 +22,7 @@ import { startActionScheduleRuntime } from "@/plugin/core/ActionScheduleRuntime.
 import { startAllPlugins, stopAllPlugins } from "@/plugin/core/Manager.js";
 import { startRpcServer } from "@/rpc/Server.js";
 import type { AgentRuntime } from "@/types/runtime/agent/AgentRuntime.js";
+import type { Shell } from "@downcity/shell";
 
 type AgentLifecycleServiceOptions = {
   /**
@@ -43,6 +44,11 @@ type AgentLifecycleServiceOptions = {
    * 读取当前 agent runtime。
    */
   get_runtime: () => AgentRuntime;
+
+  /**
+   * 读取当前 agent 挂载的 Shell。
+   */
+  get_shell?: () => Shell | undefined;
 };
 
 /**
@@ -53,6 +59,7 @@ export class AgentLifecycleService {
   private readonly agent_context: AgentContext;
   private readonly session_collection: AgentSessionCollection;
   private readonly get_runtime: AgentLifecycleServiceOptions["get_runtime"];
+  private readonly get_shell: AgentLifecycleServiceOptions["get_shell"];
 
   private plugins_started = false;
   private action_schedule_runtime: ActionScheduleRuntimeHandle | null = null;
@@ -64,6 +71,7 @@ export class AgentLifecycleService {
     this.agent_context = options.agent_context;
     this.session_collection = options.session_collection;
     this.get_runtime = options.get_runtime;
+    this.get_shell = options.get_shell;
   }
 
   /**
@@ -112,6 +120,8 @@ export class AgentLifecycleService {
       await this.stop_rpc();
     }
 
+    await this.get_shell?.()?.dispose();
+
     this.start_promise = null;
 
     return {
@@ -168,6 +178,7 @@ export class AgentLifecycleService {
       sessionCollection: this.session_collection,
       getAgentContext: () => this.agent_context,
       getAgentRuntime: () => this.get_runtime(),
+      getShell: () => this.get_shell?.(),
     });
     this.rpc_binding = {
       url: `rpc://${host}:${port}`,

package/src/agent/remote/RemoteAgent.ts

@@ -16,6 +16,10 @@ import type {
   RemoteAgentOptions,
   RemoteAgentSession,
 } from "@/types/agent/AgentTypes.js";
+import type {
+  ShellApprovalDecisionResult,
+  ShellApprovalView,
+} from "@downcity/shell";
 import type { RemoteAgentTransport } from "@/agent/remote/RemoteTransport.js";
 import { RemoteSession } from "@/agent/remote/RemoteSession.js";
 import { create_remote_agent_transport } from "@/agent/remote/TransportFactory.js";
@@ -70,7 +74,7 @@ export class RemoteAgent {
    *
    * 关键点（中文）
    * - 这是 RemoteAgent 顶层能力，不绑定某个 session。
-   * - 前端收到 `tool-approval-request` 后，可以用它调用 `shell.approve` / `shell.deny`。
+   * - Shell approval 请使用 `approvals()` / `approve()` / `deny()`。
    */
   async runPluginAction(
     input: RemoteAgentPluginActionInput,
@@ -90,6 +94,27 @@ export class RemoteAgent {
     });
   }
 
+  /**
+   * 列出远程 Agent 的 shell pending approvals。
+   */
+  async approvals(): Promise<ShellApprovalView[]> {
+    return await this.transport.approvals();
+  }
+
+  /**
+   * 批准远程 Agent 的 shell approval。
+   */
+  async approve(input: { approval_id: string }): Promise<ShellApprovalDecisionResult> {
+    return await this.transport.approve(input);
+  }
+
+  /**
+   * 拒绝远程 Agent 的 shell approval。
+   */
+  async deny(input: { approval_id: string }): Promise<ShellApprovalDecisionResult> {
+    return await this.transport.deny(input);
+  }
+
   /**
    * 关闭远程 transport。
    *

package/src/agent/remote/RemoteTransport.ts

@@ -20,6 +20,10 @@ import type {
 } 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 持有的事件订阅句柄。
@@ -72,6 +76,12 @@ export type RemoteAgentTransport = RemoteSessionTransport & {
   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

@@ -24,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 标记。 */
@@ -264,6 +268,47 @@ export class HttpRemoteAgentTransport implements RemoteAgentTransport {
     }
     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> {

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

@@ -25,6 +25,10 @@ import type {
   RemoteAgentTransport,
   TransportSubscription,
 } from "@/agent/remote/RemoteTransport.js";
+import type {
+  ShellApprovalDecisionResult,
+  ShellApprovalView,
+} from "@downcity/shell";
 
 /**
  * 本机 RPC transport。
@@ -113,6 +117,18 @@ export class RpcRemoteAgentTransport implements RemoteAgentTransport {
     });
   }
 
+  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/index.ts

@@ -105,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/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;
+      };
     };
 
 /**