@downcity/plugins 1.0.60 → 1.0.64

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,
@@ -31,12 +32,9 @@ import { getShellDir, getShellOutputPath, getShellSnapshotPath } from "./Paths.j
 import {
   buildActionResponse,
   buildShellEnv,
-  clampWaitMs,
+  clampWaitMsWithOptions,
   createOutputChunk,
   createShellPluginState,
-  DEFAULT_EXEC_TIMEOUT_MS,
-  DEFAULT_INLINE_WAIT_MS,
-  DEFAULT_WAIT_TIMEOUT_MS,
   ensureCapacity,
   isInMemorySession,
   isTerminalStatus,
@@ -49,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";
 
@@ -65,7 +69,7 @@ export function bindShellRuntime(
   state: ShellPluginState,
   context: AgentContext,
 ): void {
-  state.boundRuntime = context;
+  state.context = context;
 }
 
 /**
@@ -75,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" &&
@@ -96,6 +114,65 @@ 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: false,
+      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,
+  });
+}
+
 /**
  * 启动一个 shell session。
  */
@@ -114,6 +191,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(
@@ -127,6 +206,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,
@@ -136,6 +246,7 @@ export async function startShellSession(
     shellPath,
     login,
     baseEnv: buildShellEnv(context),
+    sandboxMode,
   });
   const child = spawnResult.child;
   const actualCwd = spawnResult.cwd;
@@ -153,12 +264,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: sandboxMode === "safe",
       status: "running",
       ...(typeof child.pid === "number" ? { pid: child.pid } : {}),
       startedAt,
@@ -189,7 +305,11 @@ export async function startShellSession(
   attachShellProcessEventHandlers({ state, session });
   await persistSnapshot(session);
 
-  const inlineWaitMs = clampWaitMs(request.inlineWaitMs, DEFAULT_INLINE_WAIT_MS);
+  const inlineWaitMs = clampWaitMsWithOptions(
+    state.options,
+    request.inlineWaitMs,
+    state.options.defaultInlineWaitMs,
+  );
   await waitShellSession(state, context, {
     shellId,
     afterVersion: 1,
@@ -301,6 +421,9 @@ 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} does not allow stdin writes`);
+  }
   await new Promise<void>((resolve, reject) => {
     session.child.stdin.write(chars, (error) => {
       if (error) {
@@ -351,7 +474,11 @@ export async function waitShellSession(
       };
       const timer = setTimeout(() => {
         finish();
-      }, clampWaitMs(request.timeoutMs, DEFAULT_WAIT_TIMEOUT_MS));
+      }, clampWaitMsWithOptions(
+        state.options,
+        request.timeoutMs,
+        state.options.defaultWaitTimeoutMs,
+      ));
       waiter = {
         resolve: finish,
         timer,
@@ -445,13 +572,20 @@ export async function execShellCommand(
   context: AgentContext,
   request: ShellExecRequest,
 ): Promise<ShellActionResponse> {
-  const timeoutMs = clampWaitMs(request.timeoutMs, DEFAULT_EXEC_TIMEOUT_MS);
+  const timeoutMs = clampWaitMsWithOptions(
+    state.options,
+    request.timeoutMs,
+    state.options.defaultExecTimeoutMs,
+  );
   const started = await startShellSession(state, context, {
     cmd: request.cmd,
     ...(request.cwd ? { cwd: request.cwd } : {}),
     ...(request.shell ? { shell: request.shell } : {}),
     login: request.login,
-    inlineWaitMs: Math.min(DEFAULT_INLINE_WAIT_MS, timeoutMs),
+    sandbox: request.sandbox,
+    reason: request.reason,
+    approvalToolName: "shell_exec",
+    inlineWaitMs: Math.min(state.options.defaultInlineWaitMs, timeoutMs),
     maxOutputTokens: request.maxOutputTokens,
     autoNotifyOnExit: false,
   });
@@ -553,3 +687,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

@@ -13,6 +13,10 @@ import type {
   ShellPluginState,
   ShellSessionRuntimeState,
 } from "@/shell/ShellRuntimeTypes.js";
+import type {
+  ResolvedShellPluginOptions,
+  ShellPluginOptions,
+} from "@/shell/types/ShellPluginOptions.js";
 import type {
   ShellQueryRequest,
   ShellSessionSnapshot,
@@ -32,35 +36,110 @@ export {
   createOutputChunk,
 } from "./ShellActionResponse.js";
 
-const MAX_ACTIVE_SHELLS = 64;
-const SESSION_CLEANUP_DELAY_MS = 10 * 60 * 1000;
-const MAX_IN_MEMORY_OUTPUT_CHARS = 1_000_000;
-const MIN_WAIT_MS = 50;
-const MAX_WAIT_MS = 30_000;
-const OUTPUT_PREVIEW_CHARS = 280;
+const DEFAULT_SHELL_PLUGIN_OPTIONS: ResolvedShellPluginOptions = {
+  maxActiveShells: 64,
+  cleanupDelayMs: 10 * 60 * 1000,
+  maxInMemoryOutputChars: 1_000_000,
+  outputPreviewChars: 280,
+  minWaitMs: 50,
+  maxWaitMs: 30_000,
+  defaultInlineWaitMs: 1_200,
+  defaultWaitTimeoutMs: 10_000,
+  defaultExecTimeoutMs: 60_000,
+  defaultApprovalTimeoutMs: 120_000,
+};
 
 /**
  * shell.start 默认内联等待时间。
  */
-export const DEFAULT_INLINE_WAIT_MS = 1_200;
+export const DEFAULT_INLINE_WAIT_MS = DEFAULT_SHELL_PLUGIN_OPTIONS.defaultInlineWaitMs;
 
 /**
  * shell.wait 默认等待超时。
  */
-export const DEFAULT_WAIT_TIMEOUT_MS = 10_000;
+export const DEFAULT_WAIT_TIMEOUT_MS = DEFAULT_SHELL_PLUGIN_OPTIONS.defaultWaitTimeoutMs;
 
 /**
  * shell.exec 默认总超时。
  */
-export const DEFAULT_EXEC_TIMEOUT_MS = 60_000;
+export const DEFAULT_EXEC_TIMEOUT_MS = DEFAULT_SHELL_PLUGIN_OPTIONS.defaultExecTimeoutMs;
+
+function readPositiveInteger(
+  value: number | undefined,
+  fallback: number,
+): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return fallback;
+  }
+  return Math.max(1, Math.floor(value));
+}
+
+/**
+ * 归一化 ShellPlugin 可选运行参数。
+ */
+export function resolveShellPluginOptions(
+  options: ShellPluginOptions = {},
+): ResolvedShellPluginOptions {
+  const minWaitMs = readPositiveInteger(
+    options.minWaitMs,
+    DEFAULT_SHELL_PLUGIN_OPTIONS.minWaitMs,
+  );
+  const maxWaitMs = Math.max(
+    minWaitMs,
+    readPositiveInteger(
+      options.maxWaitMs,
+      DEFAULT_SHELL_PLUGIN_OPTIONS.maxWaitMs,
+    ),
+  );
+  return {
+    maxActiveShells: readPositiveInteger(
+      options.maxActiveShells,
+      DEFAULT_SHELL_PLUGIN_OPTIONS.maxActiveShells,
+    ),
+    cleanupDelayMs: readPositiveInteger(
+      options.cleanupDelayMs,
+      DEFAULT_SHELL_PLUGIN_OPTIONS.cleanupDelayMs,
+    ),
+    maxInMemoryOutputChars: readPositiveInteger(
+      options.maxInMemoryOutputChars,
+      DEFAULT_SHELL_PLUGIN_OPTIONS.maxInMemoryOutputChars,
+    ),
+    outputPreviewChars: readPositiveInteger(
+      options.outputPreviewChars,
+      DEFAULT_SHELL_PLUGIN_OPTIONS.outputPreviewChars,
+    ),
+    minWaitMs,
+    maxWaitMs,
+    defaultInlineWaitMs: readPositiveInteger(
+      options.defaultInlineWaitMs,
+      DEFAULT_SHELL_PLUGIN_OPTIONS.defaultInlineWaitMs,
+    ),
+    defaultWaitTimeoutMs: readPositiveInteger(
+      options.defaultWaitTimeoutMs,
+      DEFAULT_SHELL_PLUGIN_OPTIONS.defaultWaitTimeoutMs,
+    ),
+    defaultExecTimeoutMs: readPositiveInteger(
+      options.defaultExecTimeoutMs,
+      DEFAULT_SHELL_PLUGIN_OPTIONS.defaultExecTimeoutMs,
+    ),
+    defaultApprovalTimeoutMs: readPositiveInteger(
+      options.defaultApprovalTimeoutMs,
+      DEFAULT_SHELL_PLUGIN_OPTIONS.defaultApprovalTimeoutMs,
+    ),
+  };
+}
 
 /**
  * 创建 shell plugin runtime 初始状态。
  */
-export function createShellPluginState(): ShellPluginState {
+export function createShellPluginState(
+  options: ShellPluginOptions = {},
+): ShellPluginState {
   return {
+    options: resolveShellPluginOptions(options),
     sessions: new Map<string, ShellSessionRuntimeState>(),
-    boundRuntime: null,
+    approvals: new Map(),
+    context: null,
   };
 }
 
@@ -75,11 +154,22 @@ export function nowMs(): number {
  * 归一化 wait/timeout 参数。
  */
 export function clampWaitMs(value: number | undefined, fallback: number): number {
+  return clampWaitMsWithOptions(DEFAULT_SHELL_PLUGIN_OPTIONS, value, fallback);
+}
+
+/**
+ * 结合 ShellPlugin options 归一化 wait/timeout 参数。
+ */
+export function clampWaitMsWithOptions(
+  options: ResolvedShellPluginOptions,
+  value: number | undefined,
+  fallback: number,
+): number {
   const raw =
     typeof value === "number" && Number.isFinite(value)
       ? Math.floor(value)
       : fallback;
-  return Math.min(MAX_WAIT_MS, Math.max(MIN_WAIT_MS, raw));
+  return Math.min(options.maxWaitMs, Math.max(options.minWaitMs, raw));
 }
 
 function normalizeOutputChunk(raw: string): string {
@@ -223,6 +313,7 @@ export async function updateSessionSnapshot(
  * 追加 shell 输出并同步更新快照。
  */
 export async function appendSessionOutput(
+  state: ShellPluginState,
   session: ShellSessionRuntimeState,
   raw: string,
 ): Promise<void> {
@@ -230,8 +321,8 @@ export async function appendSessionOutput(
   if (!text) return;
 
   session.outputText += text;
-  if (session.outputText.length > MAX_IN_MEMORY_OUTPUT_CHARS) {
-    const overflow = session.outputText.length - MAX_IN_MEMORY_OUTPUT_CHARS;
+  if (session.outputText.length > state.options.maxInMemoryOutputChars) {
+    const overflow = session.outputText.length - state.options.maxInMemoryOutputChars;
     session.outputText = session.outputText.slice(overflow);
     session.snapshot.droppedChars += overflow;
   }
@@ -239,7 +330,7 @@ export async function appendSessionOutput(
   session.snapshot.outputChars += text.length;
   session.snapshot.lastOutputAt = nowMs();
   session.snapshot.lastOutputPreview = session.outputText
-    .slice(-OUTPUT_PREVIEW_CHARS)
+    .slice(-state.options.outputPreviewChars)
     .trim();
   session.snapshot.externalRefs = extractExternalRefsFromText(
     text,
@@ -260,7 +351,7 @@ export function scheduleCleanup(state: ShellPluginState, shellId: string): void
     const current = state.sessions.get(shellId);
     if (!current) return;
     state.sessions.delete(shellId);
-  }, SESSION_CLEANUP_DELAY_MS);
+  }, state.options.cleanupDelayMs);
   if (typeof session.cleanupTimer.unref === "function") {
     session.cleanupTimer.unref();
   }
@@ -270,15 +361,15 @@ export function scheduleCleanup(state: ShellPluginState, shellId: string): void
  * 控制 in-memory shell session 容量。
  */
 export function ensureCapacity(state: ShellPluginState): void {
-  if (state.sessions.size < MAX_ACTIVE_SHELLS) return;
+  if (state.sessions.size < state.options.maxActiveShells) return;
   const removable = Array.from(state.sessions.values())
     .filter((item) => item.snapshot.status !== "running" && item.snapshot.status !== "starting")
     .sort((a, b) => a.snapshot.updatedAt - b.snapshot.updatedAt);
   for (const item of removable) {
-    if (state.sessions.size < MAX_ACTIVE_SHELLS) break;
+    if (state.sessions.size < state.options.maxActiveShells) break;
     state.sessions.delete(item.snapshot.shellId);
   }
-  if (state.sessions.size >= MAX_ACTIVE_SHELLS) {
+  if (state.sessions.size >= state.options.maxActiveShells) {
     throw new Error(
       `Too many active shell sessions (${state.sessions.size}). Please close or wait older sessions first.`,
     );
@@ -377,9 +468,9 @@ export async function finalizeExit(
   if (
     session.snapshot.autoNotifyOnExit &&
     session.snapshot.notificationSent === false &&
-    state.boundRuntime
+    state.context
   ) {
-    await emitChatCompletionEvent(state.boundRuntime, session.snapshot);
+    await emitChatCompletionEvent(state.context, session.snapshot);
     session.snapshot.notificationSent = true;
     await persistSnapshot(session);
   }