@xyit/wellspring 0.0.0-stage → 1.1.0

package/dist/sandbox/memory-limit.d.ts

@@ -0,0 +1,44 @@
+import type { LaunchSpec } from "./types.js";
+export declare const CGROUP_V2_ROOT = "/sys/fs/cgroup";
+export interface MemoryLimitState {
+    /** 是否真的挂上了 cgroup 限制 */
+    readonly active: boolean;
+    /** active=false 时的原因（给结果与日志用） */
+    readonly reason: string | null;
+    /** 把启动命令包进受限 cgroup；inactive 时原样返回 */
+    wrap(spec: LaunchSpec): LaunchSpec;
+    /** 读 oom 事件并清理 scope；可重复调用 */
+    finish(): Promise<{
+        oomKilled: boolean;
+    }>;
+}
+export interface MemoryLimitCommandResult {
+    readonly code: number | null;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+/** 便于单测替换外部命令、文件与时间 */
+export interface MemoryLimitDeps {
+    readonly platform: NodeJS.Platform;
+    readonly env: NodeJS.ProcessEnv;
+    readonly run: (command: string, args: readonly string[]) => Promise<MemoryLimitCommandResult>;
+    readonly spawnHolder: (command: string, args: readonly string[]) => {
+        readonly pid?: number;
+    };
+    readonly readText: (path: string) => string | null;
+    readonly writable: (path: string) => boolean;
+    readonly sleep: (ms: number) => Promise<void>;
+    readonly randomSuffix: () => string;
+}
+export interface MemoryLimitOptions {
+    /** 物理内存上限，字节 */
+    readonly bytes: number;
+    /** 沙箱超时；用来给 scope 的 RuntimeMaxSec 留余量，避免泄漏 */
+    readonly timeoutMs: number;
+    readonly deps?: Partial<MemoryLimitDeps>;
+}
+/** 从 memory.events 里读 oom_kill 计数 */
+export declare function parseOomKill(memoryEvents: string | null): boolean;
+/** sandbox 命令外层包一层 sh：先把自己放进 cgroup，再 exec 原命令 */
+export declare function wrapSpecInCgroup(spec: LaunchSpec, cgroupPath: string): LaunchSpec;
+export declare function createSandboxMemoryLimit(options: MemoryLimitOptions): Promise<MemoryLimitState>;

package/dist/sandbox/memory-limit.js

@@ -0,0 +1,193 @@
+/*
+ * 沙箱物理内存限制。
+ *
+ * RLIMIT_AS 限制的是虚拟地址空间，会直接打死 V8 / JVM / Go 这类需要预留大块地址空间的
+ * 运行时，且并不能约束真实物理内存。这里改用 cgroup v2 的 memory.max：
+ *
+ *   1. 用 `systemd-run --user --scope -p MemoryMax=<bytes> -p MemorySwapMax=0` 起一个
+ *      临时 scope（用户 session 下无需 root）；
+ *   2. 读 systemctl 的 ControlGroup 拿到 cgroup 路径；
+ *   3. 用一层 /bin/sh 包住真正的 sandbox 命令：先把 shell 自己写进 cgroup.procs，
+ *      再 exec bwrap，保证 bwrap 及其后代一出生就在受限 cgroup 里；
+ *   4. 结束后读 memory.events 判断是否发生过 oom_kill，再停掉 scope。
+ *
+ * 宿主没有 systemd user manager（例如容器、SSH 非登录环境）时返回 inactive，
+ * 调用方退回“只限制 V8 堆 + 超时”的方式，不阻塞命令执行。
+ */
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { accessSync, constants, readFileSync } from "node:fs";
+import { join } from "node:path";
+export const CGROUP_V2_ROOT = "/sys/fs/cgroup";
+const CGROUP_POLL_TIMES = 10;
+const CGROUP_POLL_INTERVAL_MS = 50;
+const SCOPE_RUNTIME_GRACE_MS = 120_000;
+function runCommand(command, args) {
+    return new Promise((resolveCommand) => {
+        const child = spawn(command, [...args], {
+            stdio: ["ignore", "pipe", "pipe"],
+            env: process.env,
+        });
+        const out = [];
+        const err = [];
+        child.stdout?.on("data", (chunk) => out.push(chunk));
+        child.stderr?.on("data", (chunk) => err.push(chunk));
+        child.once("error", (error) => {
+            resolveCommand({ code: null, stdout: "", stderr: error.message });
+        });
+        child.once("close", (code) => {
+            resolveCommand({
+                code,
+                stdout: Buffer.concat(out).toString("utf8"),
+                stderr: Buffer.concat(err).toString("utf8"),
+            });
+        });
+    });
+}
+const defaultDeps = {
+    platform: process.platform,
+    env: process.env,
+    run: runCommand,
+    spawnHolder: (command, args) => {
+        const child = spawn(command, [...args], {
+            stdio: "ignore",
+            env: process.env,
+            detached: true,
+        });
+        child.unref();
+        return { pid: child.pid };
+    },
+    readText: (path) => {
+        try {
+            return readFileSync(path, "utf8");
+        }
+        catch {
+            return null;
+        }
+    },
+    writable: (path) => {
+        try {
+            accessSync(path, constants.W_OK);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    },
+    sleep: (ms) => new Promise((resolveSleep) => setTimeout(resolveSleep, ms)),
+    randomSuffix: () => randomUUID().slice(0, 8),
+};
+function inactive(reason) {
+    return {
+        active: false,
+        reason,
+        wrap: (spec) => spec,
+        finish: async () => ({ oomKilled: false }),
+    };
+}
+/** 从 memory.events 里读 oom_kill 计数 */
+export function parseOomKill(memoryEvents) {
+    if (memoryEvents === null) {
+        return false;
+    }
+    const match = /^oom_kill\s+(\d+)\s*$/m.exec(memoryEvents);
+    return match !== null && Number(match[1]) > 0;
+}
+/** sandbox 命令外层包一层 sh：先把自己放进 cgroup，再 exec 原命令 */
+export function wrapSpecInCgroup(spec, cgroupPath) {
+    return {
+        ...spec,
+        command: "/bin/sh",
+        args: [
+            "-c",
+            'echo $$ > "$1/cgroup.procs" || exit 126; shift; exec "$@"',
+            "sh",
+            cgroupPath,
+            spec.command,
+            ...spec.args,
+        ],
+    };
+}
+export async function createSandboxMemoryLimit(options) {
+    const deps = { ...defaultDeps, ...options.deps };
+    const bytes = Math.trunc(options.bytes);
+    if (deps.platform !== "linux") {
+        return inactive("非 Linux 平台不使用 cgroup 内存限制");
+    }
+    if (!Number.isFinite(bytes) || bytes < 16 * 1024 * 1024) {
+        return inactive("内存上限过小，跳过 cgroup 限制");
+    }
+    const unit = `wellspring-sandbox-${process.pid}-${deps.randomSuffix()}`;
+    const runtimeSec = Math.ceil((Math.max(1, options.timeoutMs) + SCOPE_RUNTIME_GRACE_MS) / 1000);
+    const holderArgs = [
+        "--user",
+        "--scope",
+        "--quiet",
+        "--collect",
+        "--unit",
+        unit,
+        "--property",
+        `MemoryMax=${bytes}`,
+        // 不把物理内存挤进 swap，否则 memory.max 会被换页绕过
+        "--property",
+        "MemorySwapMax=0",
+        "--property",
+        `RuntimeMaxSec=${runtimeSec}`,
+        "--",
+        "/bin/sleep",
+        "infinity",
+    ];
+    try {
+        deps.spawnHolder("systemd-run", holderArgs);
+    }
+    catch (error) {
+        return inactive(`systemd-run 不可用：${error instanceof Error ? error.message : String(error)}`);
+    }
+    const unitName = `${unit}.scope`;
+    let cgroup = null;
+    let lastError = "";
+    for (let attempt = 0; attempt < CGROUP_POLL_TIMES; attempt += 1) {
+        const shown = await deps.run("systemctl", [
+            "--user",
+            "show",
+            "-p",
+            "ControlGroup",
+            "--value",
+            unitName,
+        ]);
+        const value = shown.stdout.trim();
+        if (value.startsWith("/")) {
+            cgroup = value;
+            break;
+        }
+        lastError = shown.stderr.trim();
+        await deps.sleep(CGROUP_POLL_INTERVAL_MS);
+    }
+    const stop = async () => {
+        await deps.run("systemctl", ["--user", "stop", unitName]);
+    };
+    if (cgroup === null) {
+        await stop();
+        return inactive(`systemd user scope 不可用${lastError === "" ? "" : `：${lastError}`}`);
+    }
+    const cgroupPath = join(CGROUP_V2_ROOT, cgroup);
+    if (!deps.writable(join(cgroupPath, "cgroup.procs"))) {
+        await stop();
+        return inactive(`无法写入 cgroup：${cgroupPath}`);
+    }
+    let finished = null;
+    return {
+        active: true,
+        reason: null,
+        wrap: (spec) => wrapSpecInCgroup(spec, cgroupPath),
+        finish: () => {
+            finished ??= (async () => {
+                const oomKilled = parseOomKill(deps.readText(join(cgroupPath, "memory.events")));
+                await stop();
+                return { oomKilled };
+            })();
+            return finished;
+        },
+    };
+}
+//# sourceMappingURL=memory-limit.js.map

package/dist/sandbox/memory-limit.js.map

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

package/dist/sandbox/plugin-client.d.ts

@@ -0,0 +1,80 @@
+import type { Logger } from "pino";
+import type { AppSetting } from "../config/types.js";
+import type { ResolvedPaths } from "../platform/path.js";
+import type { PluginDataService } from "../plugin/data-access.js";
+import type { HostCapabilities } from "../plugin/capabilities.js";
+import type { AgentTool, AgentToolIntroduction, PluginCommand, PluginConfig } from "../api/host/plugin.js";
+import type { HostModelsApi } from "../api/host/models.js";
+import type { HostNetworkApi } from "../api/host/network.js";
+import type { HostPluginsApi } from "../api/host/plugins.js";
+import type { HostAgentService } from "../plugin/agent-service.js";
+import type { SandboxBackend, SandboxLimits } from "./types.js";
+export declare function shutdownAllSandboxPlugins(): Promise<void>;
+export interface SandboxPluginMetadata {
+    readonly id: string;
+    readonly name: string;
+    readonly version: string;
+    readonly status: "ok" | "failed";
+    readonly deps: readonly string[];
+}
+export interface SandboxPluginCommandMeta {
+    readonly name: string;
+    readonly summary: string;
+    readonly usage?: string;
+    readonly aliases?: readonly string[];
+}
+export interface SandboxAgentToolMeta {
+    readonly name: string;
+    readonly introduction: AgentToolIntroduction;
+}
+export interface SandboxPluginReady {
+    readonly plugin: SandboxPluginMetadata;
+    readonly commands: readonly SandboxPluginCommandMeta[];
+    readonly agentTools: readonly SandboxAgentToolMeta[];
+    readonly hooks: readonly string[];
+}
+export interface PluginSandboxPermissions {
+    readonly hostApi: readonly string[];
+    readonly workspaceRead: boolean;
+    readonly workspaceWrite: boolean;
+}
+export interface PluginSandboxClientOptions {
+    readonly pluginId: string;
+    readonly pluginName: string;
+    readonly pluginVersion: string;
+    readonly pluginDir: string;
+    readonly pluginEntry: string;
+    readonly paths: ResolvedPaths;
+    readonly config: AppSetting;
+    readonly pluginConfig: PluginConfig;
+    readonly backend: SandboxBackend;
+    readonly limits: SandboxLimits;
+    readonly logger: Logger;
+    readonly permissions: PluginSandboxPermissions;
+    readonly dataAccess?: PluginDataService;
+    readonly capabilities?: HostCapabilities;
+    readonly agent?: HostAgentService;
+    readonly models?: HostModelsApi;
+    readonly network?: HostNetworkApi;
+    readonly plugins?: HostPluginsApi;
+}
+export declare class PluginSandboxError extends Error {
+    constructor(message: string);
+}
+export declare class PluginSandboxClient {
+    #private;
+    constructor(options: PluginSandboxClientOptions);
+    get sandboxId(): string;
+    get ready(): SandboxPluginReady | null;
+    get pluginDataDir(): string;
+    /** sandbox 插件声明的 Agent 工具，call 走 RPC */
+    agentToolStubs(): readonly AgentTool[];
+    start(options?: {
+        readonly deferInit?: boolean;
+    }): Promise<SandboxPluginReady>;
+    initialize(): Promise<SandboxPluginReady>;
+    runCommand(name: string, argv: readonly string[], cwd: string, json: boolean): Promise<number>;
+    runHook(hook: string, payload: Record<string, unknown>): Promise<unknown>;
+    commandStubs(): PluginCommand[];
+    close(): Promise<void>;
+}