@downcity/agent 1.1.113 → 1.1.118

package/bin/sandbox/SandboxRunner.js

@@ -1,107 +0,0 @@
-/**
- * SandboxRunner 入口。
- *
- * 关键点（中文）
- * - 这里不实现完整的 session/read/write 协议，只负责本地子进程创建时统一进入 agent sandbox backend。
- * - 当前版本接入 macOS seatbelt 与 Linux bubblewrap backend。
- * - 本地命令不再允许回退到宿主机普通子进程执行。
- */
-import { resolveSandboxConfig, resolveSandboxCwd } from "../sandbox/SandboxConfigResolver.js";
-import { spawnMacOsSeatbeltSandbox } from "../sandbox/MacOsSeatbeltSandbox.js";
-import { spawnLinuxBubblewrapSandbox } from "../sandbox/LinuxBubblewrapSandbox.js";
-import { spawnUnrestrictedSandbox } from "../sandbox/UnrestrictedSandbox.js";
-/**
- * 启动 shell 子进程。
- */
-export async function spawnShellProcess(params) {
-    return spawnInSandbox({
-        context: params.context,
-        executionId: params.shellId,
-        executionDir: params.shellDir,
-        cmd: params.cmd,
-        cwd: params.cwd,
-        shellPath: params.shellPath,
-        login: params.login,
-        baseEnv: params.baseEnv,
-        sandboxMode: params.sandboxMode,
-    });
-}
-/**
- * 在当前 agent sandbox 中启动本地子进程。
- */
-export async function spawnInSandbox(params) {
-    if (params.sandboxMode === "unrestricted") {
-        return spawnUnrestrictedSandbox({
-            executionId: params.executionId,
-            executionDir: params.executionDir,
-            cmd: params.cmd,
-            cwd: params.cwd,
-            shellPath: params.shellPath,
-            login: params.login,
-            baseEnv: params.baseEnv,
-            actualCwd: params.cwd,
-        });
-    }
-    const config = resolveSandboxConfig(params.context);
-    const actualCwd = resolveSandboxCwd({
-        rootPath: config.rootPath,
-        requestedCwd: params.cwd,
-        context: params.context,
-    });
-    const spawnParams = {
-        executionId: params.executionId,
-        executionDir: params.executionDir,
-        cmd: params.cmd,
-        cwd: params.cwd,
-        shellPath: params.shellPath,
-        login: params.login,
-        baseEnv: params.baseEnv,
-        config,
-        actualCwd,
-    };
-    if (config.backend === "macos-seatbelt") {
-        return spawnMacOsSeatbeltSandbox(spawnParams);
-    }
-    if (config.backend === "linux-bubblewrap") {
-        return spawnLinuxBubblewrapSandbox(spawnParams);
-    }
-    throw new Error(`unsupported sandbox backend: ${config.backend}`);
-}
-/**
- * 执行一次 one-shot sandbox 命令并等待结束。
- *
- * 关键点（中文）
- * - 供 task script 这类“直接执行命令但不需要 shell session 管理”的路径复用。
- * - 非零退出码会直接抛错，行为与原先 `execa(..., { reject: true })` 保持一致。
- */
-export async function runSandboxCommand(params) {
-    const spawn = await spawnInSandbox(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

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

package/bin/sandbox/UnrestrictedSandbox.d.ts

@@ -1,16 +0,0 @@
-/**
- * Unrestricted sandbox backend。
- *
- * 关键点（中文）
- * - 这是 Downcity Runtime 管理的高权限执行环境，不是 agent 直接访问宿主 shell。
- * - 进程继承宿主可见文件系统与环境边界，但必须由上层 approval 流程批准后才能调用。
- * - 本 backend 只负责 spawn，不做审批、审计或风险判断。
- */
-import type { SandboxSpawnParams, SandboxSpawnResult } from "../sandbox/types/SandboxRuntime.js";
-/**
- * 在 unrestricted sandbox 中启动 shell 子进程。
- */
-export declare function spawnUnrestrictedSandbox(params: Omit<SandboxSpawnParams, "config"> & {
-    actualCwd: string;
-}): Promise<SandboxSpawnResult>;
-//# sourceMappingURL=UnrestrictedSandbox.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"UnrestrictedSandbox.d.ts","sourceRoot":"","sources":["../../src/sandbox/UnrestrictedSandbox.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EACV,kBAAkB,EAClB,kBAAkB,EACnB,MAAM,mCAAmC,CAAC;AAE3C;;GAEG;AACH,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,IAAI,CAAC,kBAAkB,EAAE,QAAQ,CAAC,GAAG;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,GACjE,OAAO,CAAC,kBAAkB,CAAC,CA+B7B"}

package/bin/sandbox/UnrestrictedSandbox.js

@@ -1,39 +0,0 @@
-/**
- * Unrestricted sandbox backend。
- *
- * 关键点（中文）
- * - 这是 Downcity Runtime 管理的高权限执行环境，不是 agent 直接访问宿主 shell。
- * - 进程继承宿主可见文件系统与环境边界，但必须由上层 approval 流程批准后才能调用。
- * - 本 backend 只负责 spawn，不做审批、审计或风险判断。
- */
-import { spawn } from "node:child_process";
-import fs from "fs-extra";
-/**
- * 在 unrestricted sandbox 中启动 shell 子进程。
- */
-export async function spawnUnrestrictedSandbox(params) {
-    await fs.ensureDir(params.executionDir);
-    const child = spawn(params.shellPath, [
-        params.login ? "-lc" : "-c",
-        params.cmd,
-    ], {
-        cwd: params.actualCwd,
-        stdio: "pipe",
-        env: params.baseEnv,
-    });
-    child.stdout.setEncoding("utf8");
-    child.stderr.setEncoding("utf8");
-    return {
-        child,
-        cwd: params.actualCwd,
-        sandboxed: false,
-        sandboxMode: "unrestricted",
-        backend: "unrestricted-host",
-        networkMode: "full",
-        sandboxDir: "",
-        homeDir: String(params.baseEnv.HOME || ""),
-        tmpDir: String(params.baseEnv.TMPDIR || "/tmp"),
-        cacheDir: String(params.baseEnv.XDG_CACHE_HOME || ""),
-    };
-}
-//# sourceMappingURL=UnrestrictedSandbox.js.map

package/bin/sandbox/UnrestrictedSandbox.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"UnrestrictedSandbox.js","sourceRoot":"","sources":["../../src/sandbox/UnrestrictedSandbox.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,OAAO,EAAE,MAAM,UAAU,CAAC;AAM1B;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,MAAkE;IAElE,MAAM,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;IAExC,MAAM,KAAK,GAAG,KAAK,CACjB,MAAM,CAAC,SAAS,EAChB;QACE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI;QAC3B,MAAM,CAAC,GAAG;KACX,EACD;QACE,GAAG,EAAE,MAAM,CAAC,SAAS;QACrB,KAAK,EAAE,MAAM;QACb,GAAG,EAAE,MAAM,CAAC,OAAO;KACpB,CACF,CAAC;IAEF,KAAK,CAAC,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;IACjC,KAAK,CAAC,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;IAEjC,OAAO;QACL,KAAK;QACL,GAAG,EAAE,MAAM,CAAC,SAAS;QACrB,SAAS,EAAE,KAAK;QAChB,WAAW,EAAE,cAAc;QAC3B,OAAO,EAAE,mBAAmB;QAC5B,WAAW,EAAE,MAAM;QACnB,UAAU,EAAE,EAAE;QACd,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,EAAE,CAAC;QAC1C,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,IAAI,MAAM,CAAC;QAC/C,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,cAAc,IAAI,EAAE,CAAC;KACtD,CAAC;AACJ,CAAC"}

package/bin/sandbox/types/Sandbox.d.ts

@@ -1,130 +0,0 @@
-/**
- * Sandbox 共享类型定义。
- *
- * 关键点（中文）
- * - 这里放的是 console 模块与 agent 执行层都会使用的最小 sandbox 协议。
- * - 当前版本不引入复杂 profile / binding / permission 模型，只表达“命令执行边界”。
- * - 运行时句柄与状态化 session 类型放在 `src/sandbox/types/`。
- */
-/**
- * Sandbox 网络模式。
- *
- * 说明（中文）
- * - `off`：完全禁止网络访问。
- * - `restricted`：允许受限网络访问（后续实现白名单时再细化）。
- * - `full`：允许完整网络访问。
- */
-export type SandboxNetworkMode = "off" | "restricted" | "full";
-/**
- * Sandbox 路径访问模式。
- *
- * 说明（中文）
- * - `ro`：只读。
- * - `rw`：可读写。
- */
-export type SandboxPathAccessMode = "ro" | "rw";
-/**
- * 单条路径边界规则。
- */
-export interface SandboxPathRule {
-    /**
-     * 宿主机上的绝对路径。
-     */
-    path: string;
-    /**
-     * 当前路径在 sandbox 中的访问模式。
-     */
-    access: SandboxPathAccessMode;
-    /**
-     * 当前规则的说明文本。
-     */
-    reason?: string;
-}
-/**
- * sandbox 最小配置。
- *
- * 说明（中文）
- * - 当前只表达命令执行边界，不表达 chat 用户授权与审批流。
- * - `rootPath` 是默认工作根目录。
- * - `writablePaths` 决定哪些路径允许写入。
- * - `envAllowlist` 决定哪些环境变量允许导出到 sandbox。
- */
-export interface SandboxConfig {
-    /**
-     * 当前 sandbox 的默认根目录。
-     */
-    rootPath: string;
-    /**
-     * 允许导出的环境变量名集合。
-     *
-     * 说明（中文）
-     * - 这里仅声明允许导出的 key，不在共享配置层直接保存明文值。
-     */
-    envAllowlist: string[];
-    /**
-     * 允许写入的路径集合。
-     *
-     * 说明（中文）
-     * - 路径可以是绝对路径，也可以是相对 `rootPath` 的相对路径。
-     * - 运行时会统一解析为绝对路径，并限制在 `rootPath` 范围内。
-     */
-    writablePaths: string[];
-    /**
-     * 当前 sandbox 的网络模式。
-     */
-    networkMode: SandboxNetworkMode;
-}
-/**
- * 项目级 sandbox 配置。
- *
- * 说明（中文）
- * - 这是 `downcity.json` 中面向用户暴露的最小配置。
- * - 当前版本只服务 CLI / shell 执行边界，不扩展到审批或用户权限系统。
- */
-export interface SandboxProjectConfig {
-    /**
-     * 允许导出的环境变量名集合。
-     *
-     * 说明（中文）
-     * - 这里只声明允许导出的 key，不直接保存变量值。
-     * - 运行时仍会注入少量必需变量，例如隔离后的 `HOME`、`TMPDIR`。
-     */
-    envAllowlist?: string[];
-    /**
-     * 允许写入的路径集合。
-     *
-     * 说明（中文）
-     * - 路径可以是绝对路径，也可以是相对 `rootPath` 的相对路径。
-     * - 当前版本会把越出 `rootPath` 的路径裁掉，避免把宿主文件系统重新暴露回去。
-     */
-    writablePaths?: string[];
-    /**
-     * 当前 sandbox 的网络模式。
-     *
-     * 说明（中文）
-     * - 默认建议使用 `off`。
-     * - `restricted` 先保留为受限网络语义占位，当前实现会按保守策略处理。
-     */
-    networkMode?: SandboxNetworkMode;
-}
-/**
- * console 模块中保存的 agent sandbox 配置记录。
- */
-export interface AgentSandboxConfigRecord {
-    /**
-     * 当前 agent 的稳定标识。
-     *
-     * 说明（中文）
-     * - 当前建议直接使用 agent 项目根目录绝对路径。
-     */
-    agentId: string;
-    /**
-     * 当前 agent 使用的 sandbox 配置。
-     */
-    config: SandboxConfig;
-    /**
-     * 最近更新时间（ISO8601）。
-     */
-    updatedAt: string;
-}
-//# sourceMappingURL=Sandbox.d.ts.map

package/bin/sandbox/types/Sandbox.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"Sandbox.d.ts","sourceRoot":"","sources":["../../../src/sandbox/types/Sandbox.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GAAG,KAAK,GAAG,YAAY,GAAG,MAAM,CAAC;AAE/D;;;;;;GAMG;AACH,MAAM,MAAM,qBAAqB,GAAG,IAAI,GAAG,IAAI,CAAC;AAEhD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,MAAM,EAAE,qBAAqB,CAAC;IAE9B;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;;;OAKG;IACH,YAAY,EAAE,MAAM,EAAE,CAAC;IAEvB;;;;;;OAMG;IACH,aAAa,EAAE,MAAM,EAAE,CAAC;IAExB;;OAEG;IACH,WAAW,EAAE,kBAAkB,CAAC;CACjC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IAExB;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IAEzB;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,kBAAkB,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;;;OAKG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,MAAM,EAAE,aAAa,CAAC;IAEtB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB"}

package/bin/sandbox/types/Sandbox.js

@@ -1,10 +0,0 @@
-/**
- * Sandbox 共享类型定义。
- *
- * 关键点（中文）
- * - 这里放的是 console 模块与 agent 执行层都会使用的最小 sandbox 协议。
- * - 当前版本不引入复杂 profile / binding / permission 模型，只表达“命令执行边界”。
- * - 运行时句柄与状态化 session 类型放在 `src/sandbox/types/`。
- */
-export {};
-//# sourceMappingURL=Sandbox.js.map

package/bin/sandbox/types/Sandbox.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"Sandbox.js","sourceRoot":"","sources":["../../../src/sandbox/types/Sandbox.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/bin/sandbox/types/SandboxRuntime.d.ts

@@ -1,370 +0,0 @@
-/**
- * SandboxRuntime 类型定义。
- *
- * 关键点（中文）
- * - 这里放的是 agent 执行层内部使用的最小 sandbox 运行时类型。
- * - 当前只围绕 agent 级 sandbox spawn 设计，不引入复杂 provider / policy / binding 对象。
- * - 目标是让 shell、task script 等本地执行入口都能复用同一个 agent sandbox 边界。
- */
-import type { ChildProcessWithoutNullStreams } from "node:child_process";
-import type { SandboxConfig } from "../../sandbox/types/Sandbox.js";
-import type { SandboxNetworkMode } from "../../sandbox/types/Sandbox.js";
-/**
- * 当前内置支持的 sandbox backend。
- */
-export type SandboxBackend = "macos-seatbelt" | "linux-bubblewrap" | "unrestricted-host";
-/**
- * sandbox 会话状态。
- *
- * 说明（中文）
- * - `shell_exec` 这类 one-shot 命令通常会很快走到终态。
- * - `shell_start` 则会维持一个状态化 sandbox session。
- */
-export type SandboxSessionStatus = "starting" | "running" | "completed" | "failed" | "killed" | "expired";
-/**
- * 单个 sandbox session 快照。
- */
-export interface SandboxSessionSnapshot {
-    /**
-     * sandbox 唯一标识。
-     */
-    sandboxId: string;
-    /**
-     * 原始命令文本。
-     */
-    cmd: string;
-    /**
-     * 当前 sandbox 实际工作目录。
-     */
-    cwd: string;
-    /**
-     * 当前 sandbox 状态。
-     */
-    status: SandboxSessionStatus;
-    /**
-     * 进程 pid。
-     *
-     * 说明（中文）
-     * - 某些 backend 可能拿不到宿主 pid，这时为空。
-     */
-    pid?: number;
-    /**
-     * 创建时间戳（毫秒）。
-     */
-    startedAt: number;
-    /**
-     * 最近更新时间戳（毫秒）。
-     */
-    updatedAt: number;
-    /**
-     * 结束时间戳（毫秒）。
-     */
-    endedAt?: number;
-    /**
-     * 退出码。
-     */
-    exitCode?: number;
-    /**
-     * 最近输出预览。
-     */
-    lastOutputPreview?: string;
-    /**
-     * 累计输出字符数。
-     */
-    outputChars: number;
-    /**
-     * 版本号。
-     *
-     * 说明（中文）
-     * - 任意状态或输出变化都递增，供 wait/read 增量判断使用。
-     */
-    version: number;
-}
-/**
- * sandbox 输出块。
- */
-export interface SandboxOutputChunk {
-    /**
-     * 当前输出块所属 sandbox 标识。
-     */
-    sandboxId: string;
-    /**
-     * 输出文本。
-     */
-    output: string;
-    /**
-     * 起始游标。
-     */
-    startCursor: number;
-    /**
-     * 结束游标。
-     */
-    endCursor: number;
-    /**
-     * 原始输出字符数。
-     */
-    originalChars: number;
-    /**
-     * 是否还有更多输出未读。
-     */
-    hasMoreOutput: boolean;
-}
-/**
- * one-shot 命令执行请求。
- */
-export interface SandboxExecRequest {
-    /**
-     * 最终使用的 sandbox 配置。
-     */
-    config: SandboxConfig;
-    /**
-     * 要执行的命令文本。
-     */
-    cmd: string;
-    /**
-     * 可选工作目录。
-     */
-    cwd?: string;
-    /**
-     * 可选 shell 可执行文件。
-     */
-    shell?: string;
-    /**
-     * 是否以 login shell 语义执行。
-     */
-    login?: boolean;
-}
-/**
- * 状态化 sandbox session 启动请求。
- */
-export interface SandboxStartRequest extends SandboxExecRequest {
-}
-/**
- * sandbox 会话读取请求。
- */
-export interface SandboxReadRequest {
-    /**
-     * 目标 sandbox 标识。
-     */
-    sandboxId: string;
-    /**
-     * 从哪个游标开始增量读取。
-     */
-    fromCursor?: number;
-}
-/**
- * sandbox 会话写入请求。
- */
-export interface SandboxWriteRequest {
-    /**
-     * 目标 sandbox 标识。
-     */
-    sandboxId: string;
-    /**
-     * 要写入 stdin 的原始文本。
-     */
-    chars: string;
-}
-/**
- * sandbox 会话等待请求。
- */
-export interface SandboxWaitRequest {
-    /**
-     * 目标 sandbox 标识。
-     */
-    sandboxId: string;
-    /**
-     * 仅当版本号大于该值时才立即返回。
-     */
-    afterVersion?: number;
-    /**
-     * 最长等待毫秒数。
-     */
-    timeoutMs?: number;
-}
-/**
- * sandbox 会话关闭请求。
- */
-export interface SandboxCloseRequest {
-    /**
-     * 目标 sandbox 标识。
-     */
-    sandboxId: string;
-    /**
-     * 是否强制关闭。
-     */
-    force?: boolean;
-}
-/**
- * `SandboxRunner` 最小接口。
- *
- * 说明（中文）
- * - `exec` 用于 one-shot 命令。
- * - `start/read/write/wait/close` 用于状态化 shell session。
- */
-export interface SandboxRunner {
-    /**
-     * 执行一次 one-shot 命令并等待完成。
-     */
-    exec(request: SandboxExecRequest): Promise<{
-        snapshot: SandboxSessionSnapshot;
-        chunk: SandboxOutputChunk;
-    }>;
-    /**
-     * 启动一个状态化 sandbox session。
-     */
-    start(request: SandboxStartRequest): Promise<{
-        snapshot: SandboxSessionSnapshot;
-        chunk: SandboxOutputChunk;
-    }>;
-    /**
-     * 读取 sandbox 输出。
-     */
-    read(request: SandboxReadRequest): Promise<{
-        snapshot: SandboxSessionSnapshot;
-        chunk: SandboxOutputChunk;
-    }>;
-    /**
-     * 向 sandbox stdin 写入内容。
-     */
-    write(request: SandboxWriteRequest): Promise<{
-        snapshot: SandboxSessionSnapshot;
-    }>;
-    /**
-     * 等待 sandbox 状态变化。
-     */
-    wait(request: SandboxWaitRequest): Promise<{
-        snapshot: SandboxSessionSnapshot;
-        chunk: SandboxOutputChunk;
-    }>;
-    /**
-     * 关闭 sandbox session。
-     */
-    close(request: SandboxCloseRequest): Promise<{
-        snapshot: SandboxSessionSnapshot;
-    }>;
-}
-/**
- * 运行时归一化后的 sandbox 配置。
- *
- * 说明（中文）
- * - 这里的路径都已经解析成绝对路径。
- * - 当前版本强制要求 shell 命令走 sandbox，不再允许回退到宿主机普通子进程执行。
- */
-export interface ResolvedSandboxConfig extends SandboxConfig {
-    /**
-     * 当前运行时选中的 backend。
-     */
-    backend: SandboxBackend;
-    /**
-     * 当前 Downcity sandbox 模式。
-     */
-    sandboxMode?: "safe" | "unrestricted";
-    /**
-     * 当前 agent 级 sandbox 的持久目录。
-     *
-     * 说明（中文）
-     * - 该目录不属于某个 shellId，而属于当前 agent 项目。
-     * - shell、task script 等所有 sandbox 子进程共享它作为 HOME/cache 根。
-     */
-    sandboxDir: string;
-    /**
-     * sandbox 子进程使用的 HOME。
-     */
-    homeDir: string;
-    /**
-     * sandbox 子进程使用的临时目录。
-     */
-    tmpDir: string;
-    /**
-     * sandbox 子进程使用的 XDG cache 目录。
-     */
-    cacheDir: string;
-}
-/**
- * 单次 shell 启动时传给 sandbox backend 的归一化参数。
- */
-export interface SandboxSpawnParams {
-    /**
-     * 当前执行记录标识。
-     *
-     * 说明（中文）
-     * - shell plugin 传入 shellId，task script 可以传入自己的 executionId。
-     * - 它只用于日志与诊断，不参与 sandbox HOME/cache/权限边界的计算。
-     */
-    executionId: string;
-    /**
-     * 当前执行记录目录。
-     */
-    executionDir: string;
-    /**
-     * 要执行的原始命令文本。
-     */
-    cmd: string;
-    /**
-     * 最终工作目录。
-     */
-    cwd: string;
-    /**
-     * shell 可执行文件路径。
-     */
-    shellPath: string;
-    /**
-     * 是否使用 login shell 语义。
-     */
-    login: boolean;
-    /**
-     * sandbox 生效前的基础环境变量。
-     */
-    baseEnv: NodeJS.ProcessEnv;
-    /**
-     * 当前请求最终使用的 sandbox 配置。
-     */
-    config: ResolvedSandboxConfig;
-}
-/**
- * sandbox backend 返回的进程启动结果。
- */
-export interface SandboxSpawnResult {
-    /**
-     * 已启动的子进程句柄。
-     */
-    child: ChildProcessWithoutNullStreams;
-    /**
-     * 当前子进程实际使用的工作目录。
-     */
-    cwd: string;
-    /**
-     * 当前进程是否实际运行在 sandbox 中。
-     */
-    sandboxed: boolean;
-    /**
-     * 当前 Downcity sandbox 模式。
-     */
-    sandboxMode?: "safe" | "unrestricted";
-    /**
-     * 当前使用的 backend 名称。
-     */
-    backend: SandboxBackend;
-    /**
-     * 当前实际采用的网络模式。
-     */
-    networkMode: SandboxNetworkMode;
-    /**
-     * 当前 agent 级 sandbox 的持久目录。
-     */
-    sandboxDir: string;
-    /**
-     * 当前子进程使用的 HOME。
-     */
-    homeDir: string;
-    /**
-     * 当前子进程使用的临时目录。
-     */
-    tmpDir: string;
-    /**
-     * 当前子进程使用的 XDG cache 目录。
-     */
-    cacheDir: string;
-}
-//# sourceMappingURL=SandboxRuntime.d.ts.map