@downcity/plugins 1.0.61 → 1.0.66

package/scripts/unrestricted-sandbox-approval.test.mjs

@@ -0,0 +1,335 @@
+/**
+ * @file 验证 shell unrestricted sandbox 审批运行时。
+ *
+ * 关键点（中文）
+ * - 测试编译后的 bin 输出，避免测试文件进入 package 源码导出面。
+ * - 直接驱动 shell runtime state，模拟 UI/Console 收到 approval_id 后批准或拒绝。
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import {
+  approveShellApproval,
+  closeAllShellSessions,
+  createShellPluginState,
+  denyShellApproval,
+  execShellCommand,
+  readShellSession,
+  startShellSession,
+  writeShellSession,
+} from "../bin/shell/runtime/ShellActionRuntime.js";
+
+async function create_fixture() {
+  const root_path = await fs.mkdtemp(path.join(os.tmpdir(), "downcity-unrestricted-"));
+  const events = [];
+  const context = {
+    rootPath: root_path,
+    env: {},
+    config: { id: "test-agent" },
+    paths: {
+      getDowncityChannelMetaPath: () => path.join(root_path, ".downcity", "channel", "meta.json"),
+    },
+    session: {
+      get: () => ({
+        publishEvent: (event) => {
+          events.push(event);
+        },
+      }),
+    },
+  };
+  return {
+    root_path,
+    events,
+    context,
+  };
+}
+
+async function wait_for_approval(state) {
+  const started_at = Date.now();
+  while (Date.now() - started_at < 2000) {
+    const approval = Array.from(state.approvals.values())[0];
+    if (approval) return approval;
+    await new Promise((resolve) => setTimeout(resolve, 10));
+  }
+  throw new Error("approval request was not created");
+}
+
+test("shell_start unrestricted requires reason", async () => {
+  const fixture = await create_fixture();
+  const state = createShellPluginState({ defaultApprovalTimeoutMs: 500 });
+  try {
+    await assert.rejects(
+      startShellSession(state, fixture.context, {
+        cmd: "printf should-not-run",
+        cwd: fixture.root_path,
+        shell: "/bin/sh",
+        login: false,
+        sandbox: "unrestricted",
+      }),
+      /requires a non-empty reason/,
+    );
+  } finally {
+    await closeAllShellSessions(state, true);
+    await fs.rm(fixture.root_path, { recursive: true, force: true });
+  }
+});
+
+test("shell_start unrestricted denied returns denied tool result without execution", async () => {
+  const fixture = await create_fixture();
+  const state = createShellPluginState({
+    defaultApprovalTimeoutMs: 2000,
+    defaultInlineWaitMs: 20,
+  });
+  try {
+    const marker_path = path.join(fixture.root_path, "should-not-exist.txt");
+    const pending_result = startShellSession(state, fixture.context, {
+      cmd: `printf denied > ${JSON.stringify(marker_path)}`,
+      cwd: fixture.root_path,
+      shell: "/bin/sh",
+      login: false,
+      sandbox: "unrestricted",
+      reason: "测试拒绝 unrestricted sandbox 不会执行命令。",
+      ownerContextId: "session_test",
+    });
+
+    const approval = await wait_for_approval(state);
+    assert.equal(approval.toolName, "shell_start");
+    assert.equal(fixture.events[0]?.type, "tool-approval-request");
+    assert.equal(fixture.events[0]?.approvalId, approval.approvalId);
+
+    assert.equal(
+      await denyShellApproval(state, fixture.context, approval.approvalId),
+      true,
+    );
+    const result = await pending_result;
+
+    assert.equal(result.shell.sandboxMode, "unrestricted");
+    assert.equal(result.shell.approvalStatus, "denied");
+    assert.equal(result.shell.status, "failed");
+    assert.match(result.chunk.output, /User denied unrestricted sandbox execution/);
+    await assert.rejects(fs.stat(marker_path), /ENOENT/);
+    assert.equal(fixture.events.at(-1)?.type, "tool-approval-result");
+    assert.equal(fixture.events.at(-1)?.decision, "denied");
+  } finally {
+    await closeAllShellSessions(state, true);
+    await fs.rm(fixture.root_path, { recursive: true, force: true });
+  }
+});
+
+test("shell_exec unrestricted approved executes in unrestricted sandbox", async () => {
+  const fixture = await create_fixture();
+  const state = createShellPluginState({
+    defaultApprovalTimeoutMs: 2000,
+    defaultInlineWaitMs: 20,
+    defaultExecTimeoutMs: 2000,
+  });
+  try {
+    const pending_result = execShellCommand(state, fixture.context, {
+      cmd: "printf unrestricted-ok",
+      cwd: fixture.root_path,
+      shell: "/bin/sh",
+      login: false,
+      sandbox: "unrestricted",
+      reason: "测试批准后执行 unrestricted sandbox 命令。",
+      timeoutMs: 2000,
+    });
+
+    const approval = await wait_for_approval(state);
+    assert.equal(approval.toolName, "shell_exec");
+    assert.equal(
+      await approveShellApproval(state, fixture.context, approval.approvalId),
+      true,
+    );
+    const result = await pending_result;
+
+    assert.equal(result.shell.sandboxed, false);
+    assert.equal(result.shell.sandboxMode, "unrestricted");
+    assert.equal(result.shell.approvalStatus, "approved");
+    assert.equal(result.shell.exitCode, 0);
+    assert.equal(result.chunk.output, "unrestricted-ok");
+  } finally {
+    await closeAllShellSessions(state, true);
+    await fs.rm(fixture.root_path, { recursive: true, force: true });
+  }
+});
+
+test("shell_write unrestricted requires reason", async () => {
+  const fixture = await create_fixture();
+  const state = createShellPluginState({
+    defaultApprovalTimeoutMs: 2000,
+    defaultInlineWaitMs: 20,
+  });
+  try {
+    const pending_result = startShellSession(state, fixture.context, {
+      cmd: "cat",
+      cwd: fixture.root_path,
+      shell: "/bin/sh",
+      login: false,
+      sandbox: "unrestricted",
+      reason: "测试启动 unrestricted 交互进程。",
+      ownerContextId: "session_test",
+      inlineWaitMs: 20,
+    });
+    const start_approval = await wait_for_approval(state);
+    await approveShellApproval(state, fixture.context, start_approval.approvalId);
+    const started = await pending_result;
+
+    await assert.rejects(
+      writeShellSession(state, fixture.context, {
+        shellId: started.shell.shellId,
+        chars: "should-not-write\n",
+      }),
+      /requires a non-empty reason/,
+    );
+  } finally {
+    await closeAllShellSessions(state, true);
+    await fs.rm(fixture.root_path, { recursive: true, force: true });
+  }
+});
+
+test("shell_write unrestricted denied does not write stdin", async () => {
+  const fixture = await create_fixture();
+  const state = createShellPluginState({
+    defaultApprovalTimeoutMs: 2000,
+    defaultInlineWaitMs: 20,
+  });
+  try {
+    const pending_result = startShellSession(state, fixture.context, {
+      cmd: "cat",
+      cwd: fixture.root_path,
+      shell: "/bin/sh",
+      login: false,
+      sandbox: "unrestricted",
+      reason: "测试启动 unrestricted 交互进程。",
+      ownerContextId: "session_test",
+      inlineWaitMs: 20,
+    });
+    const start_approval = await wait_for_approval(state);
+    await approveShellApproval(state, fixture.context, start_approval.approvalId);
+    const started = await pending_result;
+
+    const pending_write = writeShellSession(state, fixture.context, {
+      shellId: started.shell.shellId,
+      chars: "denied-write\n",
+      reason: "测试拒绝 unrestricted shell_write 不会写入 stdin。",
+    });
+    const write_approval = await wait_for_approval(state);
+    assert.equal(write_approval.toolName, "shell_write");
+    assert.equal(write_approval.operation, "write");
+    assert.equal(write_approval.inputPreview, "denied-write\n");
+    assert.equal(write_approval.inputChars, "denied-write\n".length);
+    assert.equal(fixture.events.at(-1)?.type, "tool-approval-request");
+    assert.equal(fixture.events.at(-1)?.toolName, "shell_write");
+    assert.equal(fixture.events.at(-1)?.operation, "write");
+
+    await denyShellApproval(state, fixture.context, write_approval.approvalId);
+    const denied = await pending_write;
+    assert.equal(denied.shell.approvalStatus, "denied");
+    assert.match(denied.chunk.output, /User denied unrestricted sandbox execution/);
+
+    const read = await readShellSession(state, fixture.context, {
+      shellId: started.shell.shellId,
+      fromCursor: 0,
+      maxOutputTokens: 1000,
+    });
+    assert.equal(read.chunk.output, "");
+  } finally {
+    await closeAllShellSessions(state, true);
+    await fs.rm(fixture.root_path, { recursive: true, force: true });
+  }
+});
+
+test("shell_write unrestricted approved writes stdin", async () => {
+  const fixture = await create_fixture();
+  const state = createShellPluginState({
+    defaultApprovalTimeoutMs: 2000,
+    defaultInlineWaitMs: 20,
+  });
+  try {
+    const pending_result = startShellSession(state, fixture.context, {
+      cmd: "cat",
+      cwd: fixture.root_path,
+      shell: "/bin/sh",
+      login: false,
+      sandbox: "unrestricted",
+      reason: "测试启动 unrestricted 交互进程。",
+      ownerContextId: "session_test",
+      inlineWaitMs: 20,
+    });
+    const start_approval = await wait_for_approval(state);
+    await approveShellApproval(state, fixture.context, start_approval.approvalId);
+    const started = await pending_result;
+
+    const pending_write = writeShellSession(state, fixture.context, {
+      shellId: started.shell.shellId,
+      chars: "approved-write\n",
+      reason: "测试批准 unrestricted shell_write 后写入 stdin。",
+    });
+    const write_approval = await wait_for_approval(state);
+    assert.equal(write_approval.toolName, "shell_write");
+    await approveShellApproval(state, fixture.context, write_approval.approvalId);
+    const written = await pending_write;
+    assert.equal(written.shell.approvalStatus, "approved");
+
+    const started_at = Date.now();
+    let output = "";
+    while (Date.now() - started_at < 1000) {
+      const read = await readShellSession(state, fixture.context, {
+        shellId: started.shell.shellId,
+        fromCursor: 0,
+        maxOutputTokens: 1000,
+      });
+      output = read.chunk.output;
+      if (output.includes("approved-write")) break;
+      await new Promise((resolve) => setTimeout(resolve, 20));
+    }
+    assert.match(output, /approved-write/);
+  } finally {
+    await closeAllShellSessions(state, true);
+    await fs.rm(fixture.root_path, { recursive: true, force: true });
+  }
+});
+
+test("shell_write safe writes without approval", async () => {
+  const fixture = await create_fixture();
+  const state = createShellPluginState({
+    defaultApprovalTimeoutMs: 2000,
+    defaultInlineWaitMs: 20,
+  });
+  try {
+    const started = await startShellSession(state, fixture.context, {
+      cmd: "cat",
+      cwd: fixture.root_path,
+      shell: "/bin/sh",
+      login: false,
+      sandbox: "safe",
+      inlineWaitMs: 20,
+    });
+    await writeShellSession(state, fixture.context, {
+      shellId: started.shell.shellId,
+      chars: "safe-write\n",
+    });
+    assert.equal(state.approvals.size, 0);
+
+    const started_at = Date.now();
+    let output = "";
+    while (Date.now() - started_at < 1000) {
+      const read = await readShellSession(state, fixture.context, {
+        shellId: started.shell.shellId,
+        fromCursor: 0,
+        maxOutputTokens: 1000,
+      });
+      output = read.chunk.output;
+      if (output.includes("safe-write")) break;
+      await new Promise((resolve) => setTimeout(resolve, 20));
+    }
+    assert.match(output, /safe-write/);
+  } finally {
+    await closeAllShellSessions(state, true);
+    await fs.rm(fixture.root_path, { recursive: true, force: true });
+  }
+});

package/src/shell/ShellPlugin.ts

@@ -29,8 +29,11 @@ import {
   closeAllShellSessions,
   closeShellSession,
   createShellPluginState,
+  approveShellApproval,
+  denyShellApproval,
   execShellCommand,
   getShellSessionStatus,
+  listShellApprovals,
   readShellSession,
   startShellSession,
   waitShellSession,
@@ -108,6 +111,42 @@ export class ShellPlugin extends BasePlugin {
           data: await this.close(params.context, params.payload as ShellCloseRequest),
         }),
       },
+      approvals: {
+        execute: async () => ({
+          success: true,
+          data: { approvals: listShellApprovals(this.state) },
+        }),
+      },
+      approve: {
+        execute: async (params) => {
+          const payload = params.payload as { approvalId?: unknown; approval_id?: unknown };
+          const approvalId = String(payload?.approvalId || payload?.approval_id || "").trim();
+          if (!approvalId) {
+            return { success: false, error: "approvalId is required" };
+          }
+          const ok = await approveShellApproval(this.state, params.context, approvalId);
+          return {
+            success: ok,
+            data: { approvalId, approved: ok },
+            ...(ok ? {} : { error: "approval request not found" }),
+          };
+        },
+      },
+      deny: {
+        execute: async (params) => {
+          const payload = params.payload as { approvalId?: unknown; approval_id?: unknown };
+          const approvalId = String(payload?.approvalId || payload?.approval_id || "").trim();
+          if (!approvalId) {
+            return { success: false, error: "approvalId is required" };
+          }
+          const ok = await denyShellApproval(this.state, params.context, approvalId);
+          return {
+            success: ok,
+            data: { approvalId, denied: ok },
+            ...(ok ? {} : { error: "approval request not found" }),
+          };
+        },
+      },
     };
 
     this.lifecycle = {
@@ -122,6 +161,7 @@ export class ShellPlugin extends BasePlugin {
           }
         }
         this.state.sessions.clear();
+        this.state.approvals.clear();
         this.state.context = null;
       },
     };

package/src/shell/ShellRuntimeTypes.ts

@@ -9,9 +9,74 @@
 
 import type { ChildProcessWithoutNullStreams } from "node:child_process";
 import type { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.js";
-import type { ShellSessionSnapshot } from "@downcity/agent/internal/executor/tools/shell/types/ShellPlugin.js";
+import type {
+  ShellApprovalStatus,
+  ShellApprovalToolName,
+  ShellSessionSnapshot,
+} from "@downcity/agent/internal/executor/tools/shell/types/ShellPlugin.js";
 import type { ResolvedShellPluginOptions } from "@/shell/types/ShellPluginOptions.js";
 
+/**
+ * unrestricted sandbox 审批运行态。
+ */
+export type ShellApprovalRuntimeState = {
+  /**
+   * 当前审批请求 ID。
+   */
+  approvalId: string;
+  /**
+   * 关联的 shell_id。
+   */
+  shellId: string;
+  /**
+   * 所属 session/聊天上下文。
+   */
+  ownerContextId?: string;
+  /**
+   * 关联工具名。
+   */
+  toolName: ShellApprovalToolName;
+  /**
+   * 申请执行的命令。
+   *
+   * 说明（中文）
+   * - `shell_write` 使用该字段保存 stdin 写入预览，保持审批队列结构统一。
+   */
+  cmd: string;
+  /**
+   * 审批动作类型。
+   */
+  operation: "exec" | "start" | "write";
+  /**
+   * stdin 写入内容预览；仅 `shell_write` 审批存在。
+   */
+  inputPreview?: string;
+  /**
+   * stdin 写入字符数；仅 `shell_write` 审批存在。
+   */
+  inputChars?: number;
+  /**
+   * 命令执行目录。
+   */
+  cwd: string;
+  /**
+   * 申请原因。
+   */
+  reason: string;
+  /**
+   * 当前审批创建时间。
+   */
+  createdAt: number;
+  /**
+   * 审批超时定时器。
+   */
+  timer: NodeJS.Timeout;
+  /**
+   * 兑现审批结果。
+   */
+  resolve: (status: ShellApprovalStatus) => void;
+};
+
 /**
  * 单个 shell wait 调用挂起时注册的 waiter。
  */
@@ -88,6 +153,10 @@ export type ShellPluginState = {
    * 当前实例持有的全部 in-memory shell session。
    */
   sessions: Map<string, ShellSessionRuntimeState>;
+  /**
+   * 当前实例持有的全部 pending unrestricted sandbox 审批。
+   */
+  approvals: Map<string, ShellApprovalRuntimeState>;
   /**
    * 当前实例最近一次启动时绑定的 agent context。
    *