@downcity/agent 1.1.1

package/bin/runtime/ProcessSweep.js

@@ -0,0 +1,188 @@
+/**
+ * 孤儿进程清扫工具。
+ *
+ * 关键点（中文）
+ * - 处理“pid 文件不存在，但旧的 detached 进程还活着”的场景。
+ * - 仅匹配 Downcity CLI 自己拉起的 `run` / `console run` / `agent start --foreground true`。
+ * - 作为 stop/start 的兜底清理层，避免旧版本进程占住端口却无法被当前 pid 文件追踪。
+ * - `run` 指 city 后台，`console run` 指 Console 模块，二者需要明确区分。
+ */
+import { execFile as execFileCb } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFileCb);
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function normalizeCommand(command) {
+    return String(command || "").replace(/\s+/g, " ").trim();
+}
+/**
+ * 构建 detached 进程停机时的信号目标。
+ *
+ * 关键点（中文）
+ * - POSIX 下 `detached: true` 会让子进程成为新的进程组 leader。
+ * - `-pid` 表示向整个进程组发信号，可覆盖 ACP、shell、watcher 等孙进程。
+ * - Windows 不支持负 pid 进程组语义，只能回退到单 pid。
+ */
+export function buildDetachedProcessSignalTargets(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return [];
+    if (process.platform === "win32")
+        return [pid];
+    return [-pid, pid];
+}
+/**
+ * 向 detached 进程发送信号。
+ *
+ * 关键点（中文）
+ * - 优先发送到进程组；失败后再尝试单 pid。
+ * - 返回值只表示至少有一个目标接收到了信号，不代表进程已经退出。
+ */
+export function signalDetachedProcess(pid, signal) {
+    for (const target of buildDetachedProcessSignalTargets(pid)) {
+        try {
+            process.kill(target, signal);
+            return true;
+        }
+        catch {
+            // 尝试下一个目标。
+        }
+    }
+    return false;
+}
+export function isDowncityCliCommand(command) {
+    return /\/bin\/main\/modules\/cli\/Index\.js(?:\s|$)/.test(command);
+}
+/**
+ * 判断命令行是否属于本次清扫目标。
+ *
+ * 关键点（中文）
+ * - `Index.js run` 是 city runtime。
+ * - `Index.js console run` 是 Console UI runtime。
+ * - 两者都包含 `run`，因此必须按完整子命令匹配，不能只查 `run` 词元。
+ */
+export function shouldSweepDetachedCityCommand(command, params) {
+    if (!isDowncityCliCommand(command))
+        return false;
+    if (params.includeConsole &&
+        /\/bin\/main\/modules\/cli\/Index\.js\s+run(?:\s|$)/.test(command)) {
+        return true;
+    }
+    if (params.includeUi &&
+        /\/bin\/main\/modules\/cli\/Index\.js\s+console\s+run(?:\s|$)/.test(command)) {
+        return true;
+    }
+    if (params.includeAgent &&
+        /\/bin\/main\/modules\/cli\/Index\.js\s+agent\s+start(?:\s|$)/.test(command) &&
+        /--foreground\s+true\b/.test(command)) {
+        return true;
+    }
+    return false;
+}
+async function listDetachedCityProcesses(params) {
+    if (process.platform === "win32") {
+        return [];
+    }
+    try {
+        const { stdout } = await execFileAsync("ps", ["-axo", "pid=,command="], {
+            maxBuffer: 1024 * 1024,
+        });
+        return String(stdout || "")
+            .split("\n")
+            .map((line) => line.match(/^\s*(\d+)\s+(.*)$/))
+            .filter((item) => Boolean(item))
+            .map((item) => ({
+            pid: Number.parseInt(item[1] || "", 10),
+            command: normalizeCommand(item[2] || ""),
+        }))
+            .filter((item) => Number.isInteger(item.pid) && item.pid > 0)
+            .filter((item) => !params.excludePids.has(item.pid))
+            .filter((item) => shouldSweepDetachedCityCommand(item.command, params));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * 只探测失联的 Downcity detached 进程，不执行停止动作。
+ */
+export async function findDetachedCityProcesses(params) {
+    const excludePids = new Set([
+        process.pid,
+        ...(Array.isArray(params?.excludePids) ? params.excludePids : []),
+    ]);
+    return listDetachedCityProcesses({
+        includeConsole: params?.includeConsole,
+        includeUi: params?.includeUi,
+        includeAgent: params?.includeAgent,
+        excludePids,
+    });
+}
+async function stopPid(pid, timeoutMs) {
+    if (!isProcessAlive(pid))
+        return true;
+    if (!signalDetachedProcess(pid, "SIGTERM")) {
+        return !isProcessAlive(pid);
+    }
+    const termStart = Date.now();
+    while (Date.now() - termStart < timeoutMs) {
+        if (!isProcessAlive(pid))
+            return true;
+        await new Promise((resolve) => setTimeout(resolve, 200));
+    }
+    try {
+        if (isProcessAlive(pid)) {
+            signalDetachedProcess(pid, "SIGKILL");
+        }
+    }
+    catch {
+        return !isProcessAlive(pid);
+    }
+    const killStart = Date.now();
+    while (Date.now() - killStart < 2_000) {
+        if (!isProcessAlive(pid))
+            return true;
+        await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+    return !isProcessAlive(pid);
+}
+/**
+ * 清扫失联的 Downcity detached 进程。
+ */
+export async function sweepDetachedCityProcesses(params) {
+    const timeoutMs = params?.timeoutMs ?? 8_000;
+    const excludePids = new Set([
+        process.pid,
+        ...(Array.isArray(params?.excludePids) ? params.excludePids : []),
+    ]);
+    const matched = await listDetachedCityProcesses({
+        includeConsole: params?.includeConsole,
+        includeUi: params?.includeUi,
+        includeAgent: params?.includeAgent,
+        excludePids,
+    });
+    const stopped = [];
+    const alive = [];
+    for (const item of matched) {
+        // 关键点（中文）：逐个停止，避免并发 kill 时输出与状态难以对应。
+        const ok = await stopPid(item.pid, timeoutMs);
+        if (ok) {
+            stopped.push(item);
+        }
+        else {
+            alive.push(item);
+        }
+    }
+    return {
+        matched,
+        stopped,
+        alive,
+    };
+}
+//# sourceMappingURL=ProcessSweep.js.map

package/bin/runtime/ProcessSweep.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProcessSweep.js","sourceRoot":"","sources":["../../src/runtime/ProcessSweep.ts"],"names":[],"mappings":"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"}

package/bin/sandbox/MacOsSeatbeltSandbox.d.ts

@@ -0,0 +1,16 @@
+/**
+ * macOS Seatbelt sandbox backend。
+ *
+ * 关键点（中文）
+ * - 当前最小实现直接基于系统自带 `sandbox-exec`。
+ * - 目标不是抽象完整 provider 体系，而是先把 shell 命令从“宿主机直跑”收敛成“带边界执行”。
+ * - 边界只保留四类：路径、环境变量、网络、隔离后的 HOME/TMPDIR。
+ */
+import type { SandboxSpawnParams, SandboxSpawnResult } from "../types/sandbox/SandboxRuntime.js";
+/**
+ * 在 macOS seatbelt sandbox 中启动 shell 子进程。
+ */
+export declare function spawnMacOsSeatbeltSandbox(params: SandboxSpawnParams & {
+    actualCwd: string;
+}): Promise<SandboxSpawnResult>;
+//# sourceMappingURL=MacOsSeatbeltSandbox.d.ts.map

package/bin/sandbox/MacOsSeatbeltSandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MacOsSeatbeltSandbox.d.ts","sourceRoot":"","sources":["../../src/sandbox/MacOsSeatbeltSandbox.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EACV,kBAAkB,EAClB,kBAAkB,EACnB,MAAM,mCAAmC,CAAC;AAiI3C;;GAEG;AACH,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,kBAAkB,GAAG;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,GACjD,OAAO,CAAC,kBAAkB,CAAC,CA8C7B"}

package/bin/sandbox/MacOsSeatbeltSandbox.js

@@ -0,0 +1,152 @@
+/**
+ * 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";
+const DEFAULT_PATH_VALUE = "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin";
+function escapeSeatbeltString(value) {
+    return String(value || "").replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+function dedupePaths(values) {
+    const seen = new Set();
+    const result = [];
+    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) {
+    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) {
+    return dedupePaths([
+        ...params.config.writablePaths,
+        params.shellDir,
+        params.shellHomeDir,
+        params.shellTmpDir,
+    ]);
+}
+function buildNetworkRules(networkMode) {
+    if (networkMode === "restricted" || networkMode === "full") {
+        return ["(allow network-outbound)", "(allow network-inbound)"];
+    }
+    return [];
+}
+function buildSeatbeltProfile(params) {
+    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) {
+    const env = {};
+    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) {
+    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,
+    };
+}
+//# sourceMappingURL=MacOsSeatbeltSandbox.js.map

package/bin/sandbox/MacOsSeatbeltSandbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MacOsSeatbeltSandbox.js","sourceRoot":"","sources":["../../src/sandbox/MacOsSeatbeltSandbox.ts"],"names":[],"mappings":"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"}

package/bin/sandbox/SandboxConfigResolver.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Sandbox 配置解析器。
+ *
+ * 关键点（中文）
+ * - 这里负责把 `downcity.json` 中面向用户的最小配置，收敛成运行时可直接执行的绝对路径配置。
+ * - 当前版本只服务 shell / CLI 这条命令执行链，不引入审批、profile 绑定或用户权限系统。
+ * - 解析结果只回答一个问题：这次命令执行的 sandbox 边界是什么。
+ */
+import type { AgentContext } from "../types/agent/AgentContext.js";
+import type { ResolvedSandboxConfig } from "../types/sandbox/SandboxRuntime.js";
+/**
+ * 判断目标路径是否位于根目录内，或与根目录本身相同。
+ */
+export declare function isPathInsideRoot(rootPath: string, targetPath: string): boolean;
+/**
+ * 解析当前请求最终使用的 sandbox 配置。
+ */
+export declare function resolveSandboxConfig(context: AgentContext): ResolvedSandboxConfig;
+/**
+ * 归一化 sandbox 内实际使用的工作目录。
+ *
+ * 说明（中文）
+ * - sandbox 启用时，工作目录必须收敛在 `rootPath` 范围内。
+ * - 超出项目根目录的 `cwd` 会被强制拉回 `rootPath`，避免宿主目录通过 `cwd` 泄漏回去。
+ */
+export declare function resolveSandboxCwd(params: {
+    rootPath: string;
+    requestedCwd: string;
+    context: AgentContext;
+}): string;
+//# sourceMappingURL=SandboxConfigResolver.d.ts.map

package/bin/sandbox/SandboxConfigResolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SandboxConfigResolver.d.ts","sourceRoot":"","sources":["../../src/sandbox/SandboxConfigResolver.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,mCAAmC,CAAC;AA0B/E;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAM9E;AAwCD;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,YAAY,GAAG,qBAAqB,CAqBjF;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,YAAY,CAAC;CACvB,GAAG,MAAM,CAUT"}

package/bin/sandbox/SandboxConfigResolver.js

@@ -0,0 +1,113 @@
+/**
+ * Sandbox 配置解析器。
+ *
+ * 关键点（中文）
+ * - 这里负责把 `downcity.json` 中面向用户的最小配置，收敛成运行时可直接执行的绝对路径配置。
+ * - 当前版本只服务 shell / CLI 这条命令执行链，不引入审批、profile 绑定或用户权限系统。
+ * - 解析结果只回答一个问题：这次命令执行的 sandbox 边界是什么。
+ */
+import path from "node:path";
+const DEFAULT_ENV_ALLOWLIST = [
+    "PATH",
+    "LANG",
+    "TERM",
+    "COLORTERM",
+    "LC_ALL",
+    "LC_CTYPE",
+    "SHELL",
+    "USER",
+    "LOGNAME",
+];
+function normalizeEnvAllowlist(values) {
+    const seen = new Set();
+    const result = [];
+    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, targetPath) {
+    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) {
+    const { rootPath, writablePaths, context } = params;
+    const rawValues = Array.isArray(writablePaths) && writablePaths.length > 0
+        ? writablePaths
+        : [rootPath];
+    const seen = new Set();
+    const result = [];
+    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) {
+    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) {
+    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;
+}
+//# sourceMappingURL=SandboxConfigResolver.js.map

package/bin/sandbox/SandboxConfigResolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SandboxConfigResolver.js","sourceRoot":"","sources":["../../src/sandbox/SandboxConfigResolver.ts"],"names":[],"mappings":"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"}

package/bin/sandbox/SandboxRunner.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 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";
+/**
+ * 启动 shell 子进程。
+ */
+export declare function spawnShellProcess(params: {
+    context: AgentContext;
+    shellId: string;
+    shellDir: string;
+    cmd: string;
+    cwd: string;
+    shellPath: string;
+    login: boolean;
+    baseEnv: NodeJS.ProcessEnv;
+}): Promise<SandboxSpawnResult>;
+/**
+ * 执行一次 one-shot sandbox 命令并等待结束。
+ *
+ * 关键点（中文）
+ * - 供 task script 这类“直接执行命令但不需要 shell session 管理”的路径复用。
+ * - 非零退出码会直接抛错，行为与原先 `execa(..., { reject: true })` 保持一致。
+ */
+export declare 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;
+}>;
+//# sourceMappingURL=SandboxRunner.d.ts.map

package/bin/sandbox/SandboxRunner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SandboxRunner.d.ts","sourceRoot":"","sources":["../../src/sandbox/SandboxRunner.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mCAAmC,CAAC;AAI5E;;GAEG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE;IAC9C,OAAO,EAAE,YAAY,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,UAAU,CAAC;CAC5B,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAkB9B;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE;IAC9C,OAAO,EAAE,YAAY,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,UAAU,CAAC;CAC5B,GAAG,OAAO,CAAC;IACV,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,kBAAkB,CAAC;CAC3B,CAAC,CAiCD"}

package/bin/sandbox/SandboxRunner.js

@@ -0,0 +1,70 @@
+/**
+ * SandboxRunner 入口。
+ *
+ * 关键点（中文）
+ * - 这里不实现完整的 session/read/write 协议，只负责 shell 子进程创建时统一进入 sandbox backend。
+ * - 当前版本只接入 macOS seatbelt backend。
+ * - shell 命令不再允许回退到宿主机普通子进程执行。
+ */
+import { resolveSandboxConfig, resolveSandboxCwd } from "../sandbox/SandboxConfigResolver.js";
+import { spawnMacOsSeatbeltSandbox } from "../sandbox/MacOsSeatbeltSandbox.js";
+/**
+ * 启动 shell 子进程。
+ */
+export async function spawnShellProcess(params) {
+    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) {
+    const spawn = await spawnShellProcess(params);
+    const stdoutChunks = [];
+    const stderrChunks = [];
+    spawn.child.stdout.on("data", (chunk) => {
+        stdoutChunks.push(String(chunk ?? ""));
+    });
+    spawn.child.stderr.on("data", (chunk) => {
+        stderrChunks.push(String(chunk ?? ""));
+    });
+    const exitCode = await new Promise((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,
+    };
+}
+//# sourceMappingURL=SandboxRunner.js.map

package/bin/sandbox/SandboxRunner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SandboxRunner.js","sourceRoot":"","sources":["../../src/sandbox/SandboxRunner.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AAC7F,OAAO,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAC;AAE9E;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,MASvC;IACC,MAAM,MAAM,GAAG,oBAAoB,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACpD,MAAM,SAAS,GAAG,iBAAiB,CAAC;QAClC,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,YAAY,EAAE,MAAM,CAAC,GAAG;QACxB,OAAO,EAAE,MAAM,CAAC,OAAO;KACxB,CAAC,CAAC;IACH,OAAO,yBAAyB,CAAC;QAC/B,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,GAAG,EAAE,MAAM,CAAC,GAAG;QACf,GAAG,EAAE,MAAM,CAAC,GAAG;QACf,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,MAAM;QACN,SAAS;KACV,CAAC,CAAC;AACL,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,MASvC;IAMC,MAAM,KAAK,GAAG,MAAM,iBAAiB,CAAC,MAAM,CAAC,CAAC;IAC9C,MAAM,YAAY,GAAa,EAAE,CAAC;IAClC,MAAM,YAAY,GAAa,EAAE,CAAC;IAElC,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAsB,EAAE,EAAE;QACvD,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC;IACzC,CAAC,CAAC,CAAC;IACH,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAsB,EAAE,EAAE;QACvD,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC;IACzC,CAAC,CAAC,CAAC;IAEH,MAAM,QAAQ,GAAG,MAAM,IAAI,OAAO,CAAS,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAC7D,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QAClD,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACnF,CAAC,CAAC,CAAC;IAEH,MAAM,MAAM,GAAG,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACrC,MAAM,MAAM,GAAG,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACrC,IAAI,QAAQ,KAAK,CAAC,EAAE,CAAC;QACnB,MAAM,OAAO,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC;aAC3C,MAAM,CAAC,OAAO,CAAC;aACf,IAAI,CAAC,IAAI,CAAC;aACV,IAAI,EAAE,CAAC;QACV,MAAM,IAAI,KAAK,CAAC,OAAO,IAAI,yCAAyC,QAAQ,EAAE,CAAC,CAAC;IAClF,CAAC;IAED,OAAO;QACL,MAAM;QACN,MAAM;QACN,QAAQ;QACR,KAAK;KACN,CAAC;AACJ,CAAC"}