@downcity/agent 1.1.1

package/src/sandbox/MacOsSeatbeltSandbox.ts

@@ -0,0 +1,196 @@
+/**
+ * macOS Seatbelt sandbox backend。
+ *
+ * 关键点（中文）
+ * - 当前最小实现直接基于系统自带 `sandbox-exec`。
+ * - 目标不是抽象完整 provider 体系，而是先把 shell 命令从“宿主机直跑”收敛成“带边界执行”。
+ * - 边界只保留四类：路径、环境变量、网络、隔离后的 HOME/TMPDIR。
+ */
+
+import { spawn } from "node:child_process";
+import path from "node:path";
+import fs from "fs-extra";
+import type {
+  SandboxSpawnParams,
+  SandboxSpawnResult,
+} from "@/types/sandbox/SandboxRuntime.js";
+
+const DEFAULT_PATH_VALUE =
+  "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin";
+
+function escapeSeatbeltString(value: string): string {
+  return String(value || "").replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+
+function dedupePaths(values: string[]): string[] {
+  const seen = new Set<string>();
+  const result: string[] = [];
+  for (const value of values) {
+    const normalized = path.resolve(String(value || "").trim());
+    if (!normalized || seen.has(normalized)) continue;
+    seen.add(normalized);
+    result.push(normalized);
+  }
+  return result;
+}
+
+function buildReadablePaths(params: {
+  rootPath: string;
+  shellPath: string;
+  shellHomeDir: string;
+  shellTmpDir: string;
+}): string[] {
+  return dedupePaths([
+    "/bin",
+    "/usr",
+    "/System",
+    "/etc",
+    "/dev",
+    "/Library",
+    "/opt/homebrew",
+    "/usr/local",
+    params.rootPath,
+    params.shellHomeDir,
+    params.shellTmpDir,
+    path.dirname(params.shellPath),
+  ]);
+}
+
+function buildWritablePaths(params: SandboxSpawnParams & {
+  shellHomeDir: string;
+  shellTmpDir: string;
+}): string[] {
+  return dedupePaths([
+    ...params.config.writablePaths,
+    params.shellDir,
+    params.shellHomeDir,
+    params.shellTmpDir,
+  ]);
+}
+
+function buildNetworkRules(networkMode: SandboxSpawnParams["config"]["networkMode"]): string[] {
+  if (networkMode === "restricted" || networkMode === "full") {
+    return ["(allow network-outbound)", "(allow network-inbound)"];
+  }
+  return [];
+}
+
+function buildSeatbeltProfile(params: SandboxSpawnParams & {
+  actualCwd: string;
+  shellHomeDir: string;
+  shellTmpDir: string;
+}): string {
+  const readablePaths = buildReadablePaths({
+    rootPath: params.config.rootPath,
+    shellPath: params.shellPath,
+    shellHomeDir: params.shellHomeDir,
+    shellTmpDir: params.shellTmpDir,
+  });
+  const writablePaths = buildWritablePaths({
+    ...params,
+    shellHomeDir: params.shellHomeDir,
+    shellTmpDir: params.shellTmpDir,
+  });
+  const lines = [
+    "(version 1)",
+    "(deny default)",
+    '(import "system.sb")',
+    "(allow process*)",
+    "(allow sysctl-read)",
+    "(allow file-read-metadata)",
+    ...readablePaths.map(
+      (value) => `(allow file-read* (subpath "${escapeSeatbeltString(value)}"))`,
+    ),
+    ...writablePaths.map(
+      (value) => `(allow file-write* (subpath "${escapeSeatbeltString(value)}"))`,
+    ),
+    ...buildNetworkRules(params.config.networkMode),
+  ];
+
+  // 关键点（中文）
+  // - `cwd` 需要显式出现在读集合里，否则很多命令刚启动时就会因为工作目录不可见而失败。
+  // - 这里单独追加，避免未来 rootPath 与 cwd 的关系变化时被遗漏。
+  if (!readablePaths.includes(params.actualCwd)) {
+    lines.push(`(allow file-read* (subpath "${escapeSeatbeltString(params.actualCwd)}"))`);
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+function buildSandboxEnv(params: SandboxSpawnParams & {
+  shellHomeDir: string;
+  shellTmpDir: string;
+}): NodeJS.ProcessEnv {
+  const env: NodeJS.ProcessEnv = {};
+  for (const key of params.config.envAllowlist) {
+    const value = params.baseEnv[key];
+    if (typeof value !== "string" || !value.trim()) continue;
+    env[key] = value;
+  }
+
+  for (const [key, value] of Object.entries(params.baseEnv)) {
+    if (!key.startsWith("DC_")) continue;
+    if (typeof value !== "string" || !value.trim()) continue;
+    env[key] = value;
+  }
+
+  env.PATH = String(env.PATH || params.baseEnv.PATH || DEFAULT_PATH_VALUE);
+  env.HOME = params.shellHomeDir;
+  env.ZDOTDIR = params.shellHomeDir;
+  env.TMPDIR = params.shellTmpDir;
+  env.SHELL = params.shellPath;
+
+  return env;
+}
+
+/**
+ * 在 macOS seatbelt sandbox 中启动 shell 子进程。
+ */
+export async function spawnMacOsSeatbeltSandbox(
+  params: SandboxSpawnParams & { actualCwd: string },
+): Promise<SandboxSpawnResult> {
+  const sandboxRootDir = path.join(params.shellDir, "sandbox");
+  const shellHomeDir = path.join(sandboxRootDir, "home");
+  const shellTmpDir = path.join(sandboxRootDir, "tmp");
+  const profilePath = path.join(sandboxRootDir, "profile.sb");
+
+  await fs.ensureDir(shellHomeDir);
+  await fs.ensureDir(shellTmpDir);
+
+  const profile = buildSeatbeltProfile({
+    ...params,
+    shellHomeDir,
+    shellTmpDir,
+  });
+  await fs.writeFile(profilePath, profile, "utf-8");
+
+  const child = spawn(
+    "sandbox-exec",
+    [
+      "-f",
+      profilePath,
+      params.shellPath,
+      params.login ? "-lc" : "-c",
+      params.cmd,
+    ],
+    {
+      cwd: params.actualCwd,
+      stdio: "pipe",
+      env: buildSandboxEnv({
+        ...params,
+        shellHomeDir,
+        shellTmpDir,
+      }),
+    },
+  );
+
+  child.stdout.setEncoding("utf8");
+  child.stderr.setEncoding("utf8");
+
+  return {
+    child,
+    cwd: params.actualCwd,
+    sandboxed: true,
+    backend: "macos-seatbelt",
+    networkMode: params.config.networkMode,
+  };
+}

package/src/sandbox/SandboxConfigResolver.ts

@@ -0,0 +1,134 @@
+/**
+ * Sandbox 配置解析器。
+ *
+ * 关键点（中文）
+ * - 这里负责把 `downcity.json` 中面向用户的最小配置，收敛成运行时可直接执行的绝对路径配置。
+ * - 当前版本只服务 shell / CLI 这条命令执行链，不引入审批、profile 绑定或用户权限系统。
+ * - 解析结果只回答一个问题：这次命令执行的 sandbox 边界是什么。
+ */
+
+import path from "node:path";
+import type { AgentContext } from "@/types/agent/AgentContext.js";
+import type { ResolvedSandboxConfig } from "@/types/sandbox/SandboxRuntime.js";
+
+const DEFAULT_ENV_ALLOWLIST = [
+  "PATH",
+  "LANG",
+  "TERM",
+  "COLORTERM",
+  "LC_ALL",
+  "LC_CTYPE",
+  "SHELL",
+  "USER",
+  "LOGNAME",
+];
+
+function normalizeEnvAllowlist(values?: string[]): string[] {
+  const seen = new Set<string>();
+  const result: string[] = [];
+  for (const value of values || DEFAULT_ENV_ALLOWLIST) {
+    const normalized = String(value || "").trim();
+    if (!normalized || seen.has(normalized)) continue;
+    seen.add(normalized);
+    result.push(normalized);
+  }
+  return result;
+}
+
+/**
+ * 判断目标路径是否位于根目录内，或与根目录本身相同。
+ */
+export function isPathInsideRoot(rootPath: string, targetPath: string): boolean {
+  const normalizedRoot = path.resolve(rootPath);
+  const normalizedTarget = path.resolve(targetPath);
+  if (normalizedRoot === normalizedTarget) return true;
+  const relative = path.relative(normalizedRoot, normalizedTarget);
+  return Boolean(relative) && !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+
+function normalizeWritablePaths(params: {
+  rootPath: string;
+  writablePaths?: string[];
+  context: AgentContext;
+}): string[] {
+  const { rootPath, writablePaths, context } = params;
+  const rawValues =
+    Array.isArray(writablePaths) && writablePaths.length > 0
+      ? writablePaths
+      : [rootPath];
+  const seen = new Set<string>();
+  const result: string[] = [];
+
+  for (const rawValue of rawValues) {
+    const normalizedValue = String(rawValue || "").trim();
+    if (!normalizedValue) continue;
+    const resolvedPath = path.resolve(
+      path.isAbsolute(normalizedValue) ? normalizedValue : path.join(rootPath, normalizedValue),
+    );
+    if (!isPathInsideRoot(rootPath, resolvedPath)) {
+      context.logger.warn("[sandbox] writable path ignored because it escapes project root", {
+        rootPath,
+        ignoredPath: normalizedValue,
+        resolvedPath,
+      });
+      continue;
+    }
+    if (seen.has(resolvedPath)) continue;
+    seen.add(resolvedPath);
+    result.push(resolvedPath);
+  }
+
+  if (result.length === 0) {
+    result.push(path.resolve(rootPath));
+  }
+  return result;
+}
+
+/**
+ * 解析当前请求最终使用的 sandbox 配置。
+ */
+export function resolveSandboxConfig(context: AgentContext): ResolvedSandboxConfig {
+  const rootPath = path.resolve(context.rootPath);
+  const projectConfig = context.config?.sandbox;
+
+  if (process.platform !== "darwin") {
+    throw new Error(
+      `sandbox backend is required for shell execution, but current platform is unsupported: ${process.platform}`,
+    );
+  }
+
+  return {
+    backend: "macos-seatbelt",
+    rootPath,
+    envAllowlist: normalizeEnvAllowlist(projectConfig?.envAllowlist),
+    writablePaths: normalizeWritablePaths({
+      rootPath,
+      writablePaths: projectConfig?.writablePaths,
+      context,
+    }),
+    networkMode: projectConfig?.networkMode || "full",
+  };
+}
+
+/**
+ * 归一化 sandbox 内实际使用的工作目录。
+ *
+ * 说明（中文）
+ * - sandbox 启用时，工作目录必须收敛在 `rootPath` 范围内。
+ * - 超出项目根目录的 `cwd` 会被强制拉回 `rootPath`，避免宿主目录通过 `cwd` 泄漏回去。
+ */
+export function resolveSandboxCwd(params: {
+  rootPath: string;
+  requestedCwd: string;
+  context: AgentContext;
+}): string {
+  const normalizedCwd = path.resolve(params.requestedCwd);
+  if (isPathInsideRoot(params.rootPath, normalizedCwd)) {
+    return normalizedCwd;
+  }
+  params.context.logger.warn("[sandbox] cwd escapes project root and was reset to rootPath", {
+    rootPath: params.rootPath,
+    requestedCwd: normalizedCwd,
+  });
+  return params.rootPath;
+}

package/src/sandbox/SandboxRunner.ts

@@ -0,0 +1,101 @@
+/**
+ * SandboxRunner 入口。
+ *
+ * 关键点（中文）
+ * - 这里不实现完整的 session/read/write 协议，只负责 shell 子进程创建时统一进入 sandbox backend。
+ * - 当前版本只接入 macOS seatbelt backend。
+ * - shell 命令不再允许回退到宿主机普通子进程执行。
+ */
+
+import type { AgentContext } from "@/types/agent/AgentContext.js";
+import type { SandboxSpawnResult } from "@/types/sandbox/SandboxRuntime.js";
+import { resolveSandboxConfig, resolveSandboxCwd } from "@/sandbox/SandboxConfigResolver.js";
+import { spawnMacOsSeatbeltSandbox } from "@/sandbox/MacOsSeatbeltSandbox.js";
+
+/**
+ * 启动 shell 子进程。
+ */
+export async function spawnShellProcess(params: {
+  context: AgentContext;
+  shellId: string;
+  shellDir: string;
+  cmd: string;
+  cwd: string;
+  shellPath: string;
+  login: boolean;
+  baseEnv: NodeJS.ProcessEnv;
+}): Promise<SandboxSpawnResult> {
+  const config = resolveSandboxConfig(params.context);
+  const actualCwd = resolveSandboxCwd({
+    rootPath: config.rootPath,
+    requestedCwd: params.cwd,
+    context: params.context,
+  });
+  return spawnMacOsSeatbeltSandbox({
+    shellId: params.shellId,
+    shellDir: params.shellDir,
+    cmd: params.cmd,
+    cwd: params.cwd,
+    shellPath: params.shellPath,
+    login: params.login,
+    baseEnv: params.baseEnv,
+    config,
+    actualCwd,
+  });
+}
+
+/**
+ * 执行一次 one-shot sandbox 命令并等待结束。
+ *
+ * 关键点（中文）
+ * - 供 task script 这类“直接执行命令但不需要 shell session 管理”的路径复用。
+ * - 非零退出码会直接抛错，行为与原先 `execa(..., { reject: true })` 保持一致。
+ */
+export async function runSandboxCommand(params: {
+  context: AgentContext;
+  shellId: string;
+  shellDir: string;
+  cmd: string;
+  cwd: string;
+  shellPath: string;
+  login: boolean;
+  baseEnv: NodeJS.ProcessEnv;
+}): Promise<{
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+  spawn: SandboxSpawnResult;
+}> {
+  const spawn = await spawnShellProcess(params);
+  const stdoutChunks: string[] = [];
+  const stderrChunks: string[] = [];
+
+  spawn.child.stdout.on("data", (chunk: string | Buffer) => {
+    stdoutChunks.push(String(chunk ?? ""));
+  });
+  spawn.child.stderr.on("data", (chunk: string | Buffer) => {
+    stderrChunks.push(String(chunk ?? ""));
+  });
+
+  const exitCode = await new Promise<number>((resolve, reject) => {
+    spawn.child.on("error", (error) => reject(error));
+    spawn.child.on("close", (code) => resolve(typeof code === "number" ? code : -1));
+  });
+
+  const stdout = stdoutChunks.join("");
+  const stderr = stderrChunks.join("");
+  if (exitCode !== 0) {
+    const message = [stdout.trim(), stderr.trim()]
+      .filter(Boolean)
+      .join("\n")
+      .trim();
+    throw new Error(message || `Sandbox command failed with exit code ${exitCode}`);
+  }
+
+  return {
+    stdout,
+    stderr,
+    exitCode,
+    spawn,
+  };
+}

package/src/service/Manager.ts

@@ -0,0 +1,25 @@
+/**
+ * Service Manager 门面模块。
+ *
+ * 关键点（中文）
+ * - `main/service/*` 是 service 的管理层，不是具体 service 实现层。
+ * - 对外继续保持 `main/service/Manager.ts` 这个稳定入口，统一暴露常用管理能力。
+ * - 具体实现位于 `src/services/*`，这里负责注册、生命周期控制、命令转发与远程接口装配。
+ */
+
+export type {
+  ServiceStateControlAction,
+  ServiceStateControlResult,
+  ServiceStateSnapshot,
+} from "@/shared/types/ServiceState.js";
+export {
+  controlServiceState,
+  getServiceRootCommandNames,
+  getStaticServices,
+  isServiceRunning,
+  listServiceStates,
+  startAllServices,
+  stopAllServices,
+} from "./ServiceStateController.js";
+export { runServiceCommand } from "./ServiceActionRunner.js";
+export { registerAllServicesForServer } from "./ServiceActionApi.js";