@xyit/wellspring 0.0.0-stage → 1.1.0

package/src/sandbox/protocol.ts

@@ -0,0 +1,142 @@
+/*
+ * Sandbox RPC v1 帧协议：4 字节大端长度 + UTF-8 JSON。
+ * 供宿主 ↔ 插件 sandbox、agent-code 控制通道复用。
+ */
+
+export const SANDBOX_PROTOCOL_VERSION = 1
+export const MAX_FRAME_BYTES = 4 * 1024 * 1024
+
+export interface RpcErrorPayload {
+    readonly code: string
+    readonly message: string
+    readonly retryable?: boolean
+}
+
+export interface RpcRequest {
+    readonly v: 1
+    readonly type: "request"
+    readonly id: string
+    readonly method: string
+    readonly params?: unknown
+    readonly timeoutMs?: number
+}
+
+export interface RpcResponse {
+    readonly v: 1
+    readonly type: "response"
+    readonly id: string
+    readonly ok: boolean
+    readonly result?: unknown
+    readonly error?: RpcErrorPayload
+}
+
+export interface RpcEvent {
+    readonly v: 1
+    readonly type: "event"
+    readonly method: string
+    readonly params: unknown
+}
+
+export type RpcMessage = RpcRequest | RpcResponse | RpcEvent
+
+export class SandboxProtocolError extends Error {
+    readonly code: string
+
+    constructor(code: string, message: string) {
+        super(message)
+        this.name = "SandboxProtocolError"
+        this.code = code
+    }
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+function validateMessage(value: unknown): RpcMessage {
+    if (!isObject(value)) {
+        throw new SandboxProtocolError("sandbox.protocol", "消息不是对象")
+    }
+    if (value["v"] !== SANDBOX_PROTOCOL_VERSION) {
+        throw new SandboxProtocolError("sandbox.protocol-mismatch", "协议版本不一致")
+    }
+    const type = value["type"]
+    if (type === "request") {
+        if (typeof value["id"] !== "string" || typeof value["method"] !== "string") {
+            throw new SandboxProtocolError("sandbox.protocol", "request 缺少 id/method")
+        }
+        return value as unknown as RpcRequest
+    }
+    if (type === "response") {
+        if (typeof value["id"] !== "string" || typeof value["ok"] !== "boolean") {
+            throw new SandboxProtocolError("sandbox.protocol", "response 缺少 id/ok")
+        }
+        return value as unknown as RpcResponse
+    }
+    if (type === "event") {
+        if (typeof value["method"] !== "string") {
+            throw new SandboxProtocolError("sandbox.protocol", "event 缺少 method")
+        }
+        return value as unknown as RpcEvent
+    }
+    throw new SandboxProtocolError("sandbox.protocol", "未知消息类型")
+}
+
+export function encodeMessage(message: RpcMessage): Buffer {
+    const payload = Buffer.from(JSON.stringify(message), "utf8")
+    if (payload.length > MAX_FRAME_BYTES) {
+        throw new SandboxProtocolError("sandbox.protocol-limit", "帧超过上限")
+    }
+    const frame = Buffer.allocUnsafe(4 + payload.length)
+    frame.writeUInt32BE(payload.length, 0)
+    payload.copy(frame, 4)
+    return frame
+}
+
+/** 流式解码器；支持任意 chunk 切分 */
+export class FrameDecoder {
+    #buffer: Buffer = Buffer.alloc(0)
+    readonly #maxFrameBytes: number
+
+    constructor(maxFrameBytes = MAX_FRAME_BYTES) {
+        this.#maxFrameBytes = maxFrameBytes
+    }
+
+    push(chunk: Buffer): RpcMessage[] {
+        this.#buffer = Buffer.concat([this.#buffer, chunk])
+        const messages: RpcMessage[] = []
+        while (this.#buffer.length >= 4) {
+            const length = this.#buffer.readUInt32BE(0)
+            if (length > this.#maxFrameBytes) {
+                throw new SandboxProtocolError("sandbox.protocol-limit", "帧超过上限")
+            }
+            if (this.#buffer.length < 4 + length) {
+                break
+            }
+            const payload = this.#buffer.subarray(4, 4 + length)
+            this.#buffer = this.#buffer.subarray(4 + length)
+            let parsed: unknown
+            try {
+                parsed = JSON.parse(payload.toString("utf8"))
+            } catch (error) {
+                throw new SandboxProtocolError(
+                    "sandbox.protocol",
+                    `JSON 解析失败：${error instanceof Error ? error.message : String(error)}`,
+                )
+            }
+            messages.push(validateMessage(parsed))
+        }
+        return messages
+    }
+
+    get bufferedBytes(): number {
+        return this.#buffer.length
+    }
+}
+
+let requestCounter = 0
+
+export function nextRequestId(prefix = "req"): string {
+    requestCounter += 1
+    return `${prefix}-${Date.now().toString(36)}-${requestCounter}`
+}

package/src/sandbox/pty-bridge.py

@@ -0,0 +1,154 @@
+#!/usr/bin/env python3
+"""PTY 桥接器：在没有 node-pty 的机器上提供真 tty。
+
+由宿主 spawn，标准输出直接是 pty 的原始字节流；控制命令从 fd 3 读，
+每行一个 JSON：
+
+    {"type": "input", "data": "ls\r"}
+    {"type": "resize", "cols": 120, "rows": 30}
+    {"type": "kill"}
+
+退出码沿用子进程的退出码，宿主据此判断会话结束。
+"""
+
+import errno
+import fcntl
+import json
+import os
+import select
+import signal
+import struct
+import subprocess
+import sys
+import termios
+
+
+def set_size(fd: int, cols: int, rows: int) -> None:
+    winsize = struct.pack("HHHH", max(1, rows), max(1, cols), 0, 0)
+    fcntl.ioctl(fd, termios.TIOCSWINSZ, winsize)
+
+
+def main() -> int:
+    config = json.loads(sys.argv[1]) if len(sys.argv) > 1 else {}
+    shell = config.get("shell") or os.environ.get("SHELL") or "/bin/bash"
+    args = config.get("args") or []
+    cwd = config.get("cwd") or os.getcwd()
+    cols = int(config.get("cols") or 100)
+    rows = int(config.get("rows") or 28)
+    extra_env = config.get("env") or {}
+
+    env = dict(os.environ)
+    env.update({k: str(v) for k, v in extra_env.items()})
+    env.setdefault("TERM", "xterm-256color")
+
+    master, slave = os.openpty()
+    set_size(slave, cols, rows)
+
+    child = subprocess.Popen(
+        [shell, *args],
+        stdin=slave,
+        stdout=slave,
+        stderr=slave,
+        cwd=cwd,
+        env=env,
+        preexec_fn=os.setsid,
+        close_fds=True,
+    )
+    os.close(slave)
+
+    # 控制通道默认走 stdin（宿主用 stdio 的 pipe 直连）；也可指定别的 fd
+    control = int(config.get("controlFd") or 0)
+    out = sys.stdout.buffer
+    pending_control = b""
+    running = True
+
+    while running:
+        try:
+            readable, _, _ = select.select([master, control], [], [], 0.5)
+        except (OSError, ValueError):
+            break
+
+        if control in readable:
+            try:
+                chunk = os.read(control, 65536)
+            except OSError as error:
+                chunk = b"" if error.errno in (errno.EAGAIN, errno.EWOULDBLOCK) else b""
+            if chunk == b"" and child.poll() is not None:
+                running = False
+            else:
+                pending_control += chunk
+                while b"\n" in pending_control:
+                    line, pending_control = pending_control.split(b"\n", 1)
+                    line = line.strip()
+                    if not line:
+                        continue
+                    try:
+                        command = json.loads(line)
+                    except ValueError:
+                        continue
+                    kind = command.get("type")
+                    if kind == "input":
+                        data = command.get("data") or ""
+                        if data:
+                            try:
+                                os.write(master, data.encode("utf-8", "replace"))
+                            except OSError:
+                                running = False
+                    elif kind == "resize":
+                        try:
+                            set_size(master, int(command.get("cols") or cols), int(command.get("rows") or rows))
+                        except OSError:
+                            pass
+                    elif kind == "kill":
+                        try:
+                            os.killpg(os.getpgid(child.pid), signal.SIGKILL)
+                        except OSError:
+                            pass
+                        running = False
+
+        if master in readable:
+            try:
+                data = os.read(master, 65536)
+            except OSError as error:
+                # 子进程退出后 Linux 在 master 上返回 EIO
+                if error.errno == errno.EIO:
+                    break
+                if error.errno in (errno.EAGAIN, errno.EWOULDBLOCK):
+                    continue
+                break
+            if not data:
+                break
+            out.write(data)
+            out.flush()
+
+        if child.poll() is not None:
+            # 把 pty 里剩余的输出取完再退出
+            while True:
+                try:
+                    rest = os.read(master, 65536)
+                except OSError:
+                    rest = b""
+                if not rest:
+                    break
+                out.write(rest)
+                out.flush()
+            break
+
+    try:
+        os.close(master)
+    except OSError:
+        pass
+
+    code = child.poll()
+    if code is None:
+        try:
+            os.killpg(os.getpgid(child.pid), signal.SIGKILL)
+        except OSError:
+            pass
+        child.wait(timeout=2)
+        code = child.returncode
+    return code or 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/src/sandbox/rpc-timeouts.ts

@@ -0,0 +1,43 @@
+/*
+ * 插件 sandbox（child）→ 宿主（host）方向 RPC 的超时策略。
+ * 单位毫秒；null 表示不设上限，时长由被调用能力自己的步骤/网络超时兜底。
+ */
+
+export interface RpcTimeouts {
+    /** 普通 RPC：文件、事件、HTTP 建服务、插件数据等 */
+    readonly default: number
+    /** Agent 单轮对话（非流式）：耗时取决于模型与工具步骤 */
+    readonly agentChat: number
+    /** Agent 流式对话：一轮可能持续很久，不设上限 */
+    readonly agentStream: number | null
+    /** 拉取供应商模型列表：要等网络超时与重试 */
+    readonly modelsFetch: number
+    /** 安装插件：解压、写文件，以及按插件声明的包管理器自动安装依赖（最多 5 分钟） */
+    readonly pluginsInstall: number
+    /**
+     * 调用插件提供的 Agent 工具
+     *
+     * 工具自己决定执行多久（`api.exec` 的 timeoutMs 上限 600s），
+     * RPC 若用默认 30s 就会先超时：宿主放弃等待、插件仍在跑，
+     * 后续工具调用还会排在它后面，界面表现为「工具被中断后卡住」。
+     */
+    readonly agentTool: number
+    /**
+     * 执行沙箱命令（execute_code）
+     *
+     * 沙箱自己的 timeoutMs 最长 600s，RPC 必须比它长；否则宿主已经放弃等待，
+     * 沙箱里的进程还在跑，调用方只能看到一条「host RPC 超时」。
+     */
+    readonly sandboxExec: number
+}
+
+export const RPC_TIMEOUT_MS: RpcTimeouts = {
+    default: 30_000,
+    agentChat: 180_000,
+    agentStream: null,
+    modelsFetch: 120_000,
+    pluginsInstall: 660_000,
+    /* 比 exec 的最长上限（600s）再留一点余量；不设 null，避免坏插件把宿主永久挂住 */
+    agentTool: 660_000,
+    sandboxExec: 660_000,
+}

package/src/sandbox/supervisor.ts

@@ -0,0 +1,172 @@
+/*
+ * sandbox 进程 supervisor：输出上限、超时、SIGTERM→SIGKILL、退出码。
+ */
+
+import { spawn } from "node:child_process"
+
+import { SandboxExecutionError, type LaunchSpec, type StopMode } from "./types.ts"
+
+export interface ProcessLimits {
+    readonly timeoutMs: number
+    readonly outputLimitBytes: number
+}
+
+export interface ProcessResult {
+    readonly exitCode: number | null
+    readonly signal: string | null
+    readonly stdout: string
+    readonly stderr: string
+    readonly truncated: boolean
+    readonly timedOut: boolean
+    readonly durationMs: number
+}
+
+export interface ProcessHooks {
+    readonly onStdout?: (text: string) => void
+    readonly onStderr?: (text: string) => void
+}
+
+export interface ProcessOptions {
+    readonly stdin?: string
+    readonly hooks?: ProcessHooks
+}
+
+export interface SandboxProcessHandle {
+    readonly pid: number | undefined
+    readonly done: Promise<ProcessResult>
+    readonly stdout: string
+    readonly stderr: string
+    stop(mode: StopMode): void
+}
+
+export function startSandboxProcess(
+    spec: LaunchSpec,
+    limits: ProcessLimits,
+    options: ProcessOptions = {},
+): SandboxProcessHandle {
+    const startedAt = Date.now()
+    const child = spawn(spec.command, [...spec.args], {
+        cwd: spec.cwd,
+        env: { ...spec.env },
+        stdio: ["pipe", "pipe", "pipe"],
+        detached: true,
+    })
+
+    const outChunks: Buffer[] = []
+    const errChunks: Buffer[] = []
+    let totalBytes = 0
+    let truncated = false
+    let timedOut = false
+    let settled = false
+
+    const append = (target: Buffer[], chunk: Buffer): void => {
+        const remaining = Math.max(0, limits.outputLimitBytes - totalBytes)
+        if (chunk.length > remaining) {
+            if (remaining > 0) {
+                target.push(chunk.subarray(0, remaining))
+                totalBytes += remaining
+            }
+            truncated = true
+            return
+        }
+        target.push(chunk)
+        totalBytes += chunk.length
+    }
+
+    child.stdout?.on("data", (chunk: Buffer) => {
+        append(outChunks, chunk)
+        options.hooks?.onStdout?.(chunk.toString("utf8"))
+    })
+    child.stderr?.on("data", (chunk: Buffer) => {
+        append(errChunks, chunk)
+        options.hooks?.onStderr?.(chunk.toString("utf8"))
+    })
+
+    const signal = (name: NodeJS.Signals): void => {
+        try {
+            if (child.pid !== undefined) {
+                process.kill(-child.pid, name)
+                return
+            }
+        } catch {
+            // 进程组已不存在，落到单进程 kill
+        }
+        child.kill(name)
+    }
+
+    let forceKillTimer: NodeJS.Timeout | null = null
+    const timeoutTimer = setTimeout(
+        () => {
+            timedOut = true
+            signal("SIGTERM")
+            forceKillTimer = setTimeout(() => {
+                if (!settled) {
+                    signal("SIGKILL")
+                }
+            }, 2_000)
+            forceKillTimer.unref()
+        },
+        Math.max(100, limits.timeoutMs),
+    )
+    timeoutTimer.unref()
+
+    const cleanup = (): void => {
+        settled = true
+        clearTimeout(timeoutTimer)
+        if (forceKillTimer !== null) {
+            clearTimeout(forceKillTimer)
+        }
+    }
+
+    try {
+        child.stdin?.end(options.stdin ?? "")
+    } catch {
+        // 子进程可能已关闭 stdin
+    }
+
+    const done = new Promise<ProcessResult>((resolveExit, rejectExit) => {
+        child.once("error", (error) => {
+            cleanup()
+            rejectExit(
+                new SandboxExecutionError(
+                    `sandbox 启动失败：${error instanceof Error ? error.message : String(error)}`,
+                ),
+            )
+        })
+        child.once("exit", (code, exitSignal) => {
+            cleanup()
+            resolveExit({
+                exitCode: code,
+                signal: exitSignal,
+                stdout: Buffer.concat(outChunks).toString("utf8"),
+                stderr: Buffer.concat(errChunks).toString("utf8"),
+                truncated,
+                timedOut,
+                durationMs: Date.now() - startedAt,
+            })
+        })
+    })
+
+    const handle: SandboxProcessHandle = {
+        pid: child.pid,
+        done,
+        get stdout() {
+            return Buffer.concat(outChunks).toString("utf8")
+        },
+        get stderr() {
+            return Buffer.concat(errChunks).toString("utf8")
+        },
+        stop(mode) {
+            signal(mode === "ctrl_c" ? "SIGINT" : "SIGKILL")
+        },
+    }
+    return handle
+}
+
+export async function runSandboxProcess(
+    spec: LaunchSpec,
+    limits: ProcessLimits,
+    options: ProcessOptions = {},
+): Promise<ProcessResult> {
+    return await startSandboxProcess(spec, limits, options).done
+}

package/src/sandbox/types.ts

@@ -0,0 +1,149 @@
+/*
+ * Sandbox 公共类型。
+ * plugin profile 与 agent-code profile 共用 backend / supervisor；这里先定义 agent-code。
+ */
+
+import type { SandboxAccess, SandboxSetting } from "../config/types.ts"
+import type { ResolvedPaths } from "../platform/path.ts"
+
+export interface SandboxLimits {
+    readonly timeoutMs: number
+    readonly memoryMB: number
+    readonly pids: number
+    readonly outputLimitBytes: number
+}
+
+export interface SandboxArtifact {
+    readonly path: string
+    readonly size: number
+    readonly sha256: string
+}
+
+export interface AgentCodeRequest {
+    readonly sessionId?: string
+    readonly command: string
+    readonly argv: readonly string[]
+    /** 默认 process.cwd() */
+    readonly workspaceDir?: string
+    /** 必须位于 workspaceDir 内；默认 workspaceDir */
+    readonly cwd?: string
+    readonly stdin?: string
+    readonly timeoutMs?: number
+    readonly memoryMB?: number
+    readonly outputLimitBytes?: number
+    readonly access?: SandboxAccess
+    readonly network?: boolean
+    /** 模型给出的提权理由 */
+    readonly justification?: string
+}
+
+export interface AgentCodeResult {
+    readonly sandboxId: string
+    readonly backend: string
+    readonly access: SandboxAccess
+    readonly exitCode: number | null
+    readonly signal: string | null
+    readonly stdout: string
+    readonly stderr: string
+    readonly truncated: boolean
+    readonly timedOut: boolean
+    /** 物理内存限制方式：cgroup = 已挂 systemd user scope 的 MemoryMax；none = 宿主不支持/未启用 */
+    readonly memoryLimit: "cgroup" | "none"
+    /** memoryLimit 为 none 时的原因 */
+    readonly memoryLimitReason: string | null
+    /** cgroup 记录到 oom_kill（进程被内存上限杀掉） */
+    readonly oomKilled: boolean
+    readonly durationMs: number
+    readonly artifacts: readonly SandboxArtifact[]
+    /** sandbox 内可见路径；bwrap 下为 /scratch/artifacts */
+    readonly artifactDir: string | null
+    /** sandbox 内可见路径；bwrap 下为 /scratch */
+    readonly sandboxDir: string
+    /** 宿主侧路径，仅宿主使用 */
+    readonly hostArtifactDir: string | null
+    readonly hostSandboxDir: string
+}
+
+export type StopMode = "ctrl_c" | "kill"
+
+export interface AgentCodeTaskHandle {
+    readonly sandboxId: string
+    readonly backend: string
+    readonly access: SandboxAccess
+    readonly stdout: string
+    readonly stderr: string
+    stop(mode: StopMode): void
+    wait(): Promise<AgentCodeResult>
+}
+
+export interface SandboxBackendStatus {
+    readonly available: boolean
+    readonly backend: string
+    readonly reason: string | null
+    readonly version: string | null
+}
+
+export interface LaunchSpec {
+    readonly command: string
+    readonly args: readonly string[]
+    /** spawn 的宿主 cwd；sandbox 内部的 cwd 由 backend 参数控制 */
+    readonly cwd: string
+    readonly env: Readonly<Record<string, string>>
+}
+
+export interface PluginLaunchInput {
+    readonly pluginDir: string
+    /** 插件内入口的相对路径，例如 index.ts */
+    readonly pluginEntryRel: string
+    readonly pluginDataDir: string
+    /** 宿主编译后的 SDK 根目录（bwrap 下挂载到 /host） */
+    readonly hostSdkDir: string
+    /** runner 在宿主上的路径 */
+    readonly runnerPath: string
+    readonly env: Readonly<Record<string, string>>
+    readonly limits: SandboxLimits
+}
+
+export interface AgentLaunchInput {
+    readonly workspaceDir: string
+    readonly scratchDir: string
+    readonly cwd: string
+    readonly access?: SandboxAccess
+    readonly network?: boolean
+    readonly command: string
+    readonly argv: readonly string[]
+    readonly env: Readonly<Record<string, string>>
+    readonly limits: SandboxLimits
+}
+
+export interface SandboxBackend {
+    readonly name: string
+    probe(): Promise<SandboxBackendStatus>
+    buildAgentLaunch(input: AgentLaunchInput): LaunchSpec
+    buildPluginLaunch(input: PluginLaunchInput): LaunchSpec
+}
+
+export interface SandboxManagerOptions {
+    readonly settings: SandboxSetting
+    readonly paths: ResolvedPaths
+    /** 测试注入；生产由 probe 选择 */
+    readonly backend?: SandboxBackend
+    readonly logger?: {
+        warn(fields: Record<string, unknown>, message: string): void
+        info(fields: Record<string, unknown>, message: string): void
+    }
+}
+
+export class SandboxUnavailableError extends Error {
+    constructor(reason: string) {
+        super(`sandbox 不可用：${reason}`)
+        this.name = "SandboxUnavailableError"
+    }
+}
+
+export class SandboxExecutionError extends Error {
+    constructor(message: string) {
+        super(message)
+        this.name = "SandboxExecutionError"
+    }
+}