第 10 章 — Bash 工具：进程管理、PTY 与沙箱执行

export const execSchema = Type.Object({
  command: Type.String({ description: "Shell command to execute" }),
  workdir: Type.Optional(Type.String()),
  env: Type.Optional(Type.Record(Type.String(), Type.String())),
  yieldMs: Type.Optional(Type.Number()),
  background: Type.Optional(Type.Boolean()),
  timeout: Type.Optional(Type.Number()),
  pty: Type.Optional(Type.Boolean()),
  elevated: Type.Optional(Type.Boolean()),
  host: Type.Optional(Type.String()),  // auto|sandbox|gateway|node
  security: Type.Optional(Type.String()),  // deny|allowlist|full
  ask: Type.Optional(Type.String()),  // off|on-miss|always
  node: Type.Optional(Type.String()),
});

// bash-process-registry.ts:80-81
const runningSessions = new Map<string, ProcessSession>();
const finishedSessions = new Map<string, FinishedSession>();

// bash-process-registry.ts:30-61
export interface ProcessSession {
  id: string;
  command: string;
  pid?: number;
  startedAt: number;
  cwd?: string;
  maxOutputChars: number;
  totalOutputChars: number;
  pendingStdout: string[];
  pendingStderr: string[];
  aggregated: string;      // 全量输出（有上限截断）
  tail: string;            // 最后 2000 字符
  exited: boolean;
  exitCode?: number | null;
  backgrounded: boolean;
  cursorKeyMode: "unknown" | "normal" | "application";
  // ...更多字段
}

// bash-process-registry.ts:111-139
export function appendOutput(session: ProcessSession, stream: "stdout" | "stderr", chunk: string) {
  // ...缓冲到 pending
  const aggregated = trimWithCap(session.aggregated + chunk, session.maxOutputChars);
  session.truncated =
    session.truncated || aggregated.length < session.aggregated.length + chunk.length;
  session.aggregated = aggregated;
  session.tail = tail(session.aggregated, 2000);
}

// bash-process-registry.ts:170-223
function moveToFinished(session: ProcessSession, status: ProcessStatus) {
  runningSessions.delete(session.id);
  if (session.child) {
    session.child.stdin?.destroy?.();
    session.child.stdout?.destroy?.();
    session.child.stderr?.destroy?.();
    session.child.removeAllListeners();
    delete session.child;
  }
  // ...stdin 清理
  if (!session.backgrounded) {
    return;  // 前台完成，不保留
  }
  finishedSessions.set(session.id, { /* 快照 */ });
}

command → 解析 host/security/ask
        → 决定执行目标（gateway/sandbox/node）
        → 解析工作目录
        → 安全校验

// bash-tools.exec-runtime.ts:275
const effectiveHost =
  resolvedTarget === "auto" ? (params.sandboxAvailable ? "sandbox" : "gateway") : resolvedTarget;

// bash-tools.exec.ts:1011-1029
const envVarRegex = /\$[A-Z_][A-Z0-9_]{1,}/g;
const first = envVarRegex.exec(content);
if (first) {
  throw new Error(
    `exec preflight: detected likely shell variable injection (${token}) ` +
    `in ${target.kind} script: ${path.basename(absPath)}:${line}.\n` +
    `In Python, use os.environ.get(...) instead of raw ${token}.`
  );
}

// bash-tools.exec.ts:1837-1850
if (allowBackground && yieldWindow !== null) {
  if (yieldWindow === 0) {
    onYieldNow();  // 立即后台化
  } else {
    yieldTimer = setTimeout(() => {
      yielded = true;
      markBackgrounded(run.session);
      resolveRunning();
    }, yieldWindow);
  }
}

// bash-tools.process.ts:307-314
if (pollWaitMs > 0 && !scopedSession.exited) {
  const deadline = Date.now() + pollWaitMs;
  while (!scopedSession.exited && Date.now() < deadline) {
    await new Promise((resolve) =>
      setTimeout(resolve, Math.max(0, Math.min(250, deadline - Date.now()))),
    );
  }
}

// bash-tools.exec-runtime.ts:715-732
if (opts.usePty) {
  return {
    mode: "pty",
    ptyCommand: execCommand,
    childFallbackArgv: childArgv,
    env: shellRuntimeEnv,
    stdinMode: "pipe-open",
  };
}
return {
  mode: "child",
  argv: childArgv,
  env: shellRuntimeEnv,
  stdinMode: "pipe-closed",  // 非 PTY 默认关闭 stdin
};

// bash-tools.exec-runtime.ts:779-801
} catch (err) {
  if (spawnSpec.mode === "pty") {
    opts.warnings.push(`Warning: PTY spawn failed; retrying without PTY.`);
    usingPty = false;
    managedRun = await supervisor.spawn({
      mode: "child",
      argv: spawnSpec.childFallbackArgv,
      stdinMode: "pipe-open",  // 降级后打开 stdin，因为用户期望交互
      // ...
    });
  }
}

// pty-keys.ts:28-83
const namedKeyMap = new Map<string, string>([
  ["enter", CR],
  ["tab", TAB],
  ["escape", ESC],
  ["up", `${ESC}[A`],
  ["down", `${ESC}[B`],
  ["f1", `${ESC}OP`],
  // ...40+ 个按键映射
]);

// bash-tools.exec-runtime.ts:356-400
export function buildApprovalPendingMessage(params: { ... }) {
  lines.push(`Approval required (id ${params.approvalSlug}, full ${params.approvalId}).`);
  lines.push(`Host: ${params.host}`);
  lines.push(`CWD: ${params.cwd ?? "(node default)"}`);
  lines.push("Command:");
  lines.push(commandBlock);
  lines.push(`Reply with: /approve ${params.approvalSlug} allow-once|allow-always|deny`);
}

// bash-tools.exec.ts:1555-1565
if (elevatedRequested && elevatedMode === "full") {
  security = "full";
}
const bypassApprovals = elevatedRequested && elevatedMode === "full";
if (bypassApprovals) {
  ask = "off";
}

export type BashSandboxConfig = {
  containerName: string;
  workspaceDir: string;       // 宿主机上的工作空间目录
  containerWorkdir: string;   // 容器内的工作目录
  env?: Record<string, string>;
  buildExecSpec?: (...) => Promise<SandboxBackendExecSpec>;  // 可扩展的后端
  finalizeExec?: (...) => Promise<void>;
};

// bash-tools.shared.ts:62-100
export function buildDockerExecArgs(params: { ... }) {
  const args = ["exec", "-i"];
  if (params.tty) args.push("-t");
  if (params.workdir) args.push("-w", params.workdir);
  for (const [key, value] of Object.entries(params.env)) {
    if (key === "PATH") continue;  // PATH 特殊处理
    args.push("-e", `${key}=${value}`);
  }
  // PATH 通过 OPENCLAW_PREPEND_PATH 注入，避免覆盖容器内的系统 PATH
  args.push(params.containerName, "/bin/sh", "-lc", `${pathExport}${params.command}`);
  return args;
}

Command timed out after 300 seconds. If this command is expected to take longer,
re-run with a higher timeout (e.g., exec timeout=300). If it should keep running,
start it with exec background=true or yieldMs so OpenClaw can register a pollable
process session.

// bash-tools.exec-runtime.ts:318-350
function maybeNotifyOnExit(session: ProcessSession, status: "completed" | "failed") {
  if (!session.backgrounded || !session.notifyOnExit || session.exitNotified) return;
  session.exitNotified = true;
  const summary = output
    ? `Exec ${status} (${session.id.slice(0, 8)}, ${exitLabel}) :: ${output}`
    : `Exec ${status} (${session.id.slice(0, 8)}, ${exitLabel})`;
  enqueueSystemEvent(summary, { sessionKey, deliveryContext: session.notifyDeliveryContext });
  requestHeartbeatNow(scopedHeartbeatWakeOptions(sessionKey, { reason: "exec-event" }));
}

// bash-tools.exec.ts:1783-1796
const onAbortSignal = () => {
  run.disableUpdates();  // 先禁用更新回调
  if (yielded || run.session.backgrounded) {
    return;  // 后台进程不受 abort 影响
  }
  run.kill();  // 前台进程直接终止
};

┌─────────────────────────────────────────────────────────┐
│                    exec("rm -rf /")                     │
└─────────────┬───────────────────────────────────────────┘
              │
              ▼
┌─────────────────────────────────────────────────────────┐
│  1. rejectUnsafeControlShellCommand                     │
│     拦截 /approve、openclaw channels login 等控制命令    │
└─────────────┬───────────────────────────────────────────┘
              │
              ▼
┌─────────────────────────────────────────────────────────┐
│  2. sanitizeHostExecEnvWithDiagnostics                  │
│     过滤 LD_PRELOAD 等危险环境变量，禁止自定义 PATH      │
└─────────────┬───────────────────────────────────────────┘
              │
              ▼
┌─────────────────────────────────────────────────────────┐
│  3. validateScriptFileForShellBleed                     │
│     检测 Python/JS 脚本中的 Shell 变量注入               │
└─────────────┬───────────────────────────────────────────┘
              │
              ▼
┌─────────────────────────────────────────────────────────┐
│  4. Gateway Allowlist / Approval                        │
│     白名单匹配 + safeBins 策略 + 人工审批                │
└─────────────┬───────────────────────────────────────────┘
              │
              ▼
┌─────────────────────────────────────────────────────────┐
│  5. 执行隔离                                             │
│     sandbox=Docker 容器 / gateway=宿主机 / node=远程     │
└─────────────────────────────────────────────────────────┘

const raw = await callGatewayTool(
  "node.invoke",
  { timeoutMs: target.invokeTimeoutMs },
  buildNodeSystemRunInvoke({ target, command: prepared.argv, ... }),
);