@downcity/plugins 1.0.61 → 1.0.66

package/src/shell/runtime/ShellActionRuntime.ts

@@ -19,6 +19,7 @@ import { generateId } from "@downcity/agent/internal/utils/Id.js";
 import { readChatMetaBySessionId } from "@/chat/runtime/ChatMetaStore.js";
 import type {
   ShellActionResponse,
+  ShellApprovalStatus,
   ShellCloseRequest,
   ShellExecRequest,
   ShellQueryRequest,
@@ -46,6 +47,12 @@ import {
   updateSessionSnapshot,
 } from "./ShellActionRuntimeSupport.js";
 import { attachShellProcessEventHandlers } from "./ShellProcessEvents.js";
+import {
+  listPendingApprovals,
+  requestUnrestrictedApproval,
+  resolveApproval,
+  validateUnrestrictedRequest,
+} from "./ShellApprovalRuntime.js";
 
 export { createShellPluginState } from "./ShellActionRuntimeSupport.js";
 
@@ -72,6 +79,20 @@ export async function closeAllShellSessions(
   state: ShellPluginState,
   force = false,
 ): Promise<void> {
+  for (const approval of Array.from(state.approvals.values())) {
+    if (state.context) {
+      await resolveApproval({
+        state,
+        context: state.context,
+        approvalId: approval.approvalId,
+        decision: "expired",
+      }).catch(() => undefined);
+      continue;
+    }
+    clearTimeout(approval.timer);
+    state.approvals.delete(approval.approvalId);
+    approval.resolve("expired");
+  }
   const closing = Array.from(state.sessions.values()).map(async (session) => {
     if (
       session.snapshot.status !== "running" &&
@@ -93,6 +114,95 @@ export async function closeAllShellSessions(
   await Promise.all(closing);
 }
 
+function resolveSandboxMode(value: unknown): "safe" | "unrestricted" {
+  return value === "unrestricted" ? "unrestricted" : "safe";
+}
+
+function buildDeniedApprovalResponse(params: {
+  shellId: string;
+  ownerContextId?: string;
+  cmd: string;
+  cwd: string;
+  shellPath: string;
+  approvalId: string;
+  reason: string;
+  approvalStatus: ShellApprovalStatus;
+}): ShellActionResponse {
+  const now = nowMs();
+  const message = params.approvalStatus === "expired"
+    ? "Unrestricted sandbox approval expired."
+    : "User denied unrestricted sandbox execution.";
+  return buildActionResponse({
+    shell: {
+      shellId: params.shellId,
+      ...(params.ownerContextId ? { ownerContextId: params.ownerContextId } : {}),
+      cmd: params.cmd,
+      cwd: params.cwd,
+      shellPath: params.shellPath,
+      sandboxed: false,
+      sandboxMode: "unrestricted",
+      sandboxBackend: "unrestricted-host",
+      sandboxNetworkMode: "full",
+      approvalStatus: params.approvalStatus,
+      approvalId: params.approvalId,
+      approvalReason: params.reason,
+      stdinWritable: true,
+      status: params.approvalStatus === "expired" ? "expired" : "failed",
+      startedAt: now,
+      updatedAt: now,
+      endedAt: now,
+      exitCode: -1,
+      lastOutputPreview: message,
+      outputChars: message.length,
+      droppedChars: 0,
+      version: 1,
+      autoNotifyOnExit: false,
+      notificationSent: false,
+      externalRefs: [],
+    },
+    chunk: {
+      shellId: params.shellId,
+      output: message,
+      startCursor: 0,
+      endCursor: message.length,
+      originalChars: message.length,
+      originalLines: 1,
+      hasMoreOutput: false,
+    },
+    note: message,
+  });
+}
+
+function buildDeniedWriteApprovalResponse(params: {
+  session: ShellSessionRuntimeState;
+  approvalId: string;
+  reason: string;
+  approvalStatus: ShellApprovalStatus;
+}): ShellActionResponse {
+  const message = params.approvalStatus === "expired"
+    ? "Unrestricted sandbox approval expired."
+    : "User denied unrestricted sandbox execution.";
+  return buildActionResponse({
+    shell: {
+      ...params.session.snapshot,
+      approvalStatus: params.approvalStatus,
+      approvalId: params.approvalId,
+      approvalReason: params.reason,
+      stdinWritable: true,
+    },
+    chunk: {
+      shellId: params.session.snapshot.shellId,
+      output: message,
+      startCursor: 0,
+      endCursor: message.length,
+      originalChars: message.length,
+      originalLines: 1,
+      hasMoreOutput: false,
+    },
+    note: message,
+  });
+}
+
 /**
  * 启动一个 shell session。
  */
@@ -111,6 +221,8 @@ export async function startShellSession(
   const shellPath =
     String(request.shell || resolveDefaultShellPath()).trim() || resolveDefaultShellPath();
   const login = request.login !== false;
+  const sandboxMode = resolveSandboxMode(request.sandbox);
+  const reason = String(request.reason || "").trim();
   const ownerContextId = resolveOwnerContextId(request.ownerContextId);
   const canAutoNotifyByContext = ownerContextId
     ? Boolean(
@@ -124,6 +236,37 @@ export async function startShellSession(
   await fs.ensureDir(shellDir);
   await fs.writeFile(outputFilePath, "", "utf-8");
 
+  let approvalId: string | undefined;
+  let approvalStatus: ShellApprovalStatus | undefined;
+  if (sandboxMode === "unrestricted") {
+    const validationError = validateUnrestrictedRequest({ cmd, reason });
+    if (validationError) throw new Error(validationError);
+    const approval = await requestUnrestrictedApproval({
+      state,
+      context,
+      shellId,
+      toolName: request.approvalToolName || "shell_start",
+      cmd,
+      cwd,
+      reason,
+      ...(ownerContextId ? { ownerContextId } : {}),
+    });
+    approvalId = approval.approvalId;
+    approvalStatus = approval.status;
+    if (approval.status !== "approved") {
+      return buildDeniedApprovalResponse({
+        shellId,
+        ...(ownerContextId ? { ownerContextId } : {}),
+        cmd,
+        cwd,
+        shellPath,
+        approvalId: approval.approvalId,
+        reason,
+        approvalStatus: approval.status,
+      });
+    }
+  }
+
   const spawnResult = await spawnShellProcess({
     context,
     shellId,
@@ -133,6 +276,7 @@ export async function startShellSession(
     shellPath,
     login,
     baseEnv: buildShellEnv(context),
+    sandboxMode,
   });
   const child = spawnResult.child;
   const actualCwd = spawnResult.cwd;
@@ -150,12 +294,17 @@ export async function startShellSession(
       cwd: actualCwd,
       shellPath,
       sandboxed: spawnResult.sandboxed,
+      sandboxMode: spawnResult.sandboxMode || sandboxMode,
       sandboxBackend: spawnResult.backend,
       sandboxNetworkMode: spawnResult.networkMode,
       sandboxDir: spawnResult.sandboxDir,
       sandboxHomeDir: spawnResult.homeDir,
       sandboxTmpDir: spawnResult.tmpDir,
       sandboxCacheDir: spawnResult.cacheDir,
+      ...(approvalStatus ? { approvalStatus } : {}),
+      ...(approvalId ? { approvalId } : {}),
+      ...(reason ? { approvalReason: reason } : {}),
+      stdinWritable: true,
       status: "running",
       ...(typeof child.pid === "number" ? { pid: child.pid } : {}),
       startedAt,
@@ -302,6 +451,39 @@ export async function writeShellSession(
   if (!session.child.stdin.writable) {
     throw new Error(`shell session ${shellId} stdin is closed`);
   }
+  if (session.snapshot.stdinWritable === false) {
+    throw new Error(`shell session ${shellId} stdin is closed`);
+  }
+
+  let approvalId: string | undefined;
+  let approvalStatus: ShellApprovalStatus | undefined;
+  const reason = String(request.reason || "").trim();
+  if (session.snapshot.sandboxMode === "unrestricted") {
+    const validationError = validateUnrestrictedRequest({ cmd: chars, reason });
+    if (validationError) throw new Error(validationError);
+    const approval = await requestUnrestrictedApproval({
+      state,
+      context,
+      shellId,
+      toolName: "shell_write",
+      cmd: chars,
+      cwd: session.snapshot.cwd,
+      reason,
+      ...(session.snapshot.ownerContextId ? { ownerContextId: session.snapshot.ownerContextId } : {}),
+      inputPreview: chars,
+      inputChars: chars.length,
+    });
+    approvalId = approval.approvalId;
+    approvalStatus = approval.status;
+    if (approval.status !== "approved") {
+      return buildDeniedWriteApprovalResponse({
+        session,
+        approvalId: approval.approvalId,
+        reason,
+        approvalStatus: approval.status,
+      });
+    }
+  }
   await new Promise<void>((resolve, reject) => {
     session.child.stdin.write(chars, (error) => {
       if (error) {
@@ -312,7 +494,13 @@ export async function writeShellSession(
     });
   });
   return buildActionResponse({
-    shell: session.snapshot,
+    shell: {
+      ...session.snapshot,
+      ...(approvalStatus ? { approvalStatus } : {}),
+      ...(approvalId ? { approvalId } : {}),
+      ...(reason ? { approvalReason: reason } : {}),
+      stdinWritable: true,
+    },
     note: chars ? "stdin written" : "no chars written",
   });
 }
@@ -460,6 +648,9 @@ export async function execShellCommand(
     ...(request.cwd ? { cwd: request.cwd } : {}),
     ...(request.shell ? { shell: request.shell } : {}),
     login: request.login,
+    sandbox: request.sandbox,
+    reason: request.reason,
+    approvalToolName: "shell_exec",
     inlineWaitMs: Math.min(state.options.defaultInlineWaitMs, timeoutMs),
     maxOutputTokens: request.maxOutputTokens,
     autoNotifyOnExit: false,
@@ -562,3 +753,42 @@ export async function execShellCommand(
     note: "shell exec completed in one-shot mode",
   });
 }
+
+/**
+ * 列出 pending unrestricted sandbox 审批。
+ */
+export function listShellApprovals(state: ShellPluginState) {
+  return listPendingApprovals(state);
+}
+
+/**
+ * 批准 pending unrestricted sandbox 审批。
+ */
+export async function approveShellApproval(
+  state: ShellPluginState,
+  context: AgentContext,
+  approvalId: string,
+): Promise<boolean> {
+  return await resolveApproval({
+    state,
+    context,
+    approvalId,
+    decision: "approved",
+  });
+}
+
+/**
+ * 拒绝 pending unrestricted sandbox 审批。
+ */
+export async function denyShellApproval(
+  state: ShellPluginState,
+  context: AgentContext,
+  approvalId: string,
+): Promise<boolean> {
+  return await resolveApproval({
+    state,
+    context,
+    approvalId,
+    decision: "denied",
+  });
+}

package/src/shell/runtime/ShellActionRuntimeSupport.ts

@@ -46,6 +46,7 @@ const DEFAULT_SHELL_PLUGIN_OPTIONS: ResolvedShellPluginOptions = {
   defaultInlineWaitMs: 1_200,
   defaultWaitTimeoutMs: 10_000,
   defaultExecTimeoutMs: 60_000,
+  defaultApprovalTimeoutMs: 120_000,
 };
 
 /**
@@ -121,6 +122,10 @@ export function resolveShellPluginOptions(
       options.defaultExecTimeoutMs,
       DEFAULT_SHELL_PLUGIN_OPTIONS.defaultExecTimeoutMs,
     ),
+    defaultApprovalTimeoutMs: readPositiveInteger(
+      options.defaultApprovalTimeoutMs,
+      DEFAULT_SHELL_PLUGIN_OPTIONS.defaultApprovalTimeoutMs,
+    ),
   };
 }
 
@@ -133,6 +138,7 @@ export function createShellPluginState(
   return {
     options: resolveShellPluginOptions(options),
     sessions: new Map<string, ShellSessionRuntimeState>(),
+    approvals: new Map(),
     context: null,
   };
 }

package/src/shell/runtime/ShellApprovalRuntime.ts

@@ -0,0 +1,276 @@
+/**
+ * Shell unrestricted sandbox 审批运行时。
+ *
+ * 关键点（中文）
+ * - agent 只能通过 shell tool 请求 unrestricted sandbox；真正执行前必须等待用户确认。
+ * - 审批结果最终回到原 tool result；session event 只用于 UI/CLI/Console 展示和操作。
+ * - V1 授权粒度固定为单次命令、单次 shell_start 启动，或单次 shell_write 输入。
+ */
+
+import fs from "fs-extra";
+import path from "node:path";
+import { generateId } from "@downcity/agent/internal/utils/Id.js";
+import { getSessionRunContext } from "@downcity/agent/internal/executor/SessionRunScope.js";
+import type { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.js";
+import type {
+  ShellApprovalStatus,
+  ShellApprovalToolName,
+} from "@downcity/agent/internal/executor/tools/shell/types/ShellPlugin.js";
+import type { ShellPluginState } from "@/shell/ShellRuntimeTypes.js";
+import { nowMs } from "./ShellActionRuntimeSupport.js";
+
+const DANGEROUS_COMMAND_PATTERNS = [
+  /\bsudo\b/,
+  /\brm\s+-[^&|;\n]*r[^&|;\n]*f\s+\/(?:\s|$)/,
+  /\bchmod\s+-R\s+777\s+\/(?:\s|$)/,
+  /\bssh-keygen\b/,
+  /\bsecurity\s+(?:add|delete|unlock|set|import|export)-/i,
+  /(?:^|[\s;&|])(?:nohup\s+)?[^;&|\n]*(?:&)\s*$/,
+];
+
+function isDangerousCommand(cmd: string): boolean {
+  return DANGEROUS_COMMAND_PATTERNS.some((pattern) => pattern.test(cmd));
+}
+
+function resolveApprovalOperation(toolName: ShellApprovalToolName): "exec" | "start" | "write" {
+  if (toolName === "shell_write") return "write";
+  if (toolName === "shell_exec") return "exec";
+  return "start";
+}
+
+function buildInputPreview(value: string): string {
+  const normalized = String(value || "");
+  if (normalized.length <= 240) return normalized;
+  return `${normalized.slice(0, 240)}...`;
+}
+
+function resolveAuditPath(context: AgentContext): string {
+  return path.join(context.rootPath, ".downcity", "logs", "unrestricted-sandbox-audit.jsonl");
+}
+
+async function appendAudit(params: {
+  context: AgentContext;
+  record: Record<string, unknown>;
+}): Promise<void> {
+  const filePath = resolveAuditPath(params.context);
+  await fs.ensureDir(path.dirname(filePath));
+  await fs.appendFile(filePath, `${JSON.stringify(params.record)}\n`, "utf-8");
+}
+
+function publishApprovalResult(params: {
+  context: AgentContext;
+  ownerContextId?: string;
+  approvalId: string;
+  shellId: string;
+  toolName: ShellApprovalToolName;
+  decision: ShellApprovalStatus;
+}): void {
+  const sessionId = String(params.ownerContextId || "").trim();
+  if (!sessionId) return;
+  const turnId = String(getSessionRunContext()?.turnId || sessionId).trim();
+  try {
+    params.context.session.get(sessionId).publishEvent({
+      type: "tool-approval-result",
+      turnId,
+      toolCallId: params.shellId,
+      toolName: params.toolName,
+      approvalId: params.approvalId,
+      decision: params.decision,
+    });
+  } catch {
+    // ignore event delivery failures
+  }
+}
+
+/**
+ * 校验 unrestricted sandbox 请求。
+ */
+export function validateUnrestrictedRequest(params: {
+  cmd: string;
+  reason?: string;
+}): string | null {
+  const reason = String(params.reason || "").trim();
+  if (!reason) {
+    return "unrestricted sandbox requires a non-empty reason";
+  }
+  if (isDangerousCommand(params.cmd)) {
+    return "unrestricted sandbox rejected a dangerous command";
+  }
+  return null;
+}
+
+/**
+ * 请求用户批准 unrestricted sandbox 执行。
+ */
+export async function requestUnrestrictedApproval(params: {
+  state: ShellPluginState;
+  context: AgentContext;
+  shellId: string;
+  toolName: ShellApprovalToolName;
+  cmd: string;
+  cwd: string;
+  reason: string;
+  ownerContextId?: string;
+  inputPreview?: string;
+  inputChars?: number;
+}): Promise<{
+  approvalId: string;
+  status: ShellApprovalStatus;
+}> {
+  const approvalId = `ap_${generateId()}`;
+  const createdAt = nowMs();
+  const ownerContextId = String(params.ownerContextId || "").trim() || undefined;
+  const operation = resolveApprovalOperation(params.toolName);
+  const inputPreview = params.inputPreview !== undefined
+    ? buildInputPreview(params.inputPreview)
+    : undefined;
+
+  const status = await new Promise<ShellApprovalStatus>((resolve) => {
+    const timer = setTimeout(() => {
+      resolveApproval({
+        state: params.state,
+        context: params.context,
+        approvalId,
+        decision: "expired",
+      }).catch(() => undefined);
+    }, params.state.options.defaultApprovalTimeoutMs);
+    if (typeof timer.unref === "function") timer.unref();
+
+    params.state.approvals.set(approvalId, {
+      approvalId,
+      shellId: params.shellId,
+      ...(ownerContextId ? { ownerContextId } : {}),
+      toolName: params.toolName,
+      cmd: params.cmd,
+      operation,
+      ...(inputPreview !== undefined ? { inputPreview } : {}),
+      ...(typeof params.inputChars === "number" ? { inputChars: params.inputChars } : {}),
+      cwd: params.cwd,
+      reason: params.reason,
+      createdAt,
+      timer,
+      resolve,
+    });
+
+    if (ownerContextId) {
+      const turnId = String(getSessionRunContext()?.turnId || ownerContextId).trim();
+      try {
+        params.context.session.get(ownerContextId).publishEvent({
+          type: "tool-approval-request",
+          turnId,
+          toolCallId: params.shellId,
+          toolName: params.toolName,
+          approvalId,
+          sandbox: "unrestricted",
+          cmd: params.cmd,
+          cwd: params.cwd,
+          reason: params.reason,
+          status: "pending",
+          operation,
+          shellId: params.shellId,
+          ...(inputPreview !== undefined ? { inputPreview } : {}),
+          ...(typeof params.inputChars === "number" ? { inputChars: params.inputChars } : {}),
+        });
+      } catch {
+        // ignore event delivery failures
+      }
+    }
+
+    appendAudit({
+      context: params.context,
+      record: {
+        event: "approval_requested",
+        approval_id: approvalId,
+        session_id: ownerContextId || null,
+        tool_call_id: params.shellId,
+        agent_id: params.context.config?.id || null,
+        cmd: params.cmd,
+        operation,
+        ...(inputPreview !== undefined ? { input_preview: inputPreview } : {}),
+        ...(typeof params.inputChars === "number" ? { input_chars: params.inputChars } : {}),
+        cwd: params.cwd,
+        reason: params.reason,
+        created_at: new Date(createdAt).toISOString(),
+      },
+    }).catch(() => undefined);
+  });
+
+  return { approvalId, status };
+}
+
+/**
+ * 兑现 unrestricted sandbox 审批。
+ */
+export async function resolveApproval(params: {
+  state: ShellPluginState;
+  context: AgentContext;
+  approvalId: string;
+  decision: ShellApprovalStatus;
+}): Promise<boolean> {
+  const approval = params.state.approvals.get(params.approvalId);
+  if (!approval) return false;
+  params.state.approvals.delete(params.approvalId);
+  clearTimeout(approval.timer);
+  approval.resolve(params.decision);
+
+  publishApprovalResult({
+    context: params.context,
+    ownerContextId: approval.ownerContextId,
+    approvalId: approval.approvalId,
+    shellId: approval.shellId,
+    toolName: approval.toolName,
+    decision: params.decision,
+  });
+
+  await appendAudit({
+    context: params.context,
+    record: {
+      event: "approval_resolved",
+      approval_id: approval.approvalId,
+      session_id: approval.ownerContextId || null,
+      tool_call_id: approval.shellId,
+      agent_id: params.context.config?.id || null,
+      cmd: approval.cmd,
+      operation: approval.operation,
+      ...(approval.inputPreview !== undefined ? { input_preview: approval.inputPreview } : {}),
+      ...(typeof approval.inputChars === "number" ? { input_chars: approval.inputChars } : {}),
+      cwd: approval.cwd,
+      reason: approval.reason,
+      decision: params.decision,
+      resolved_at: new Date(nowMs()).toISOString(),
+    },
+  }).catch(() => undefined);
+
+  return true;
+}
+
+/**
+ * 列出 pending unrestricted sandbox 审批。
+ */
+export function listPendingApprovals(state: ShellPluginState): Array<{
+  approvalId: string;
+  shellId: string;
+  ownerContextId?: string;
+  toolName: ShellApprovalToolName;
+  cmd: string;
+  operation: "exec" | "start" | "write";
+  inputPreview?: string;
+  inputChars?: number;
+  cwd: string;
+  reason: string;
+  createdAt: number;
+}> {
+  return Array.from(state.approvals.values()).map((approval) => ({
+    approvalId: approval.approvalId,
+    shellId: approval.shellId,
+    ...(approval.ownerContextId ? { ownerContextId: approval.ownerContextId } : {}),
+    toolName: approval.toolName,
+    cmd: approval.cmd,
+    operation: approval.operation,
+    ...(approval.inputPreview !== undefined ? { inputPreview: approval.inputPreview } : {}),
+    ...(typeof approval.inputChars === "number" ? { inputChars: approval.inputChars } : {}),
+    cwd: approval.cwd,
+    reason: approval.reason,
+    createdAt: approval.createdAt,
+  }));
+}

package/src/shell/types/ShellPluginOptions.ts

@@ -59,6 +59,11 @@ export interface ShellPluginOptions {
    * `shell.exec` 默认总超时，单位毫秒。
    */
   defaultExecTimeoutMs?: number;
+
+  /**
+   * unrestricted sandbox 审批默认超时时间，单位毫秒。
+   */
+  defaultApprovalTimeoutMs?: number;
 }
 
 /**
@@ -109,4 +114,9 @@ export interface ResolvedShellPluginOptions {
    * `shell.exec` 默认总超时，单位毫秒。
    */
   defaultExecTimeoutMs: number;
+
+  /**
+   * unrestricted sandbox 审批默认超时时间，单位毫秒。
+   */
+  defaultApprovalTimeoutMs: number;
 }