@runko/sandbox-cloudflare 0.1.0

package/README.md

@@ -0,0 +1,81 @@
+# @runko/sandbox-cloudflare
+
+把一个 [Cloudflare Sandbox](https://developers.cloudflare.com/sandbox/)（真实 Linux 容器）通过一个自部署的 HTTP 网关包成 `RunkoFS & RunkoExec`，一次注入 `createSession(agent, { workspace })`——"模式 A 同源工作区"落在真实云沙盒上的实现（对照 [core-sdk · 技术方案 §4.5a](../../docs/logic/engine/tech/core-sdk.md) / [沙盒工作区（Sandbox Workspace） · 技术方案 §8](../../docs/host/contract/tech/sandbox.md)）。
+
+与 E2B/Vercel 两个适配器架构不同：Cloudflare Sandbox 只能从 Cloudflare Worker 内部访问（Durable Object binding），没有办法从任意 Node 进程直连——因此本包是**两个入口**：
+
+- `.`（本文档的客户端，跑在**任意** Node ≥20 进程）：纯 `fetch` 协议客户端，不 import `@cloudflare/sandbox`（该包只能在 workerd 里加载）。
+- `./worker`（网关，部署在**宿主自己的** wrangler 项目里）：把协议翻译成对真实 `@cloudflare/sandbox` 的调用。
+
+## 安装
+
+```sh
+pnpm add @runko/sandbox-cloudflare
+```
+
+客户端侧零 provider SDK——本包不随 `@runko/sdk` 一起装，属于按需显式安装的可选集成。网关侧 `@cloudflare/sandbox` 是本包的 `peerDependency`（版本跟宿主的 wrangler 项目走），装在部署网关的那个 wrangler 项目里，不装在跑 agent 的 Node 进程里。
+
+## 网关部署
+
+先把网关部署到你自己的 Cloudflare 账号（需要 Workers Paid 计划，无免费层）。一个完整可跑可部署的参考项目见 [apps/cloudflare-worker-server/](../../apps/cloudflare-worker-server/README.md)——自备 CF 账号后 `pnpm --filter @runko-chat/cloudflare-worker-server deploy` 即可部署；本包自身只发布 `createSandboxGateway` 这层纯函数，网关的部署形态维护在该项目里。核心装配只有几行：
+
+```ts
+// 你的 wrangler 项目的 Worker 入口（见 apps/cloudflare-worker-server/src/index.ts）
+import { getSandbox } from "@cloudflare/sandbox";
+import { createSandboxGateway } from "@runko/sandbox-cloudflare/worker";
+
+export { Sandbox } from "@cloudflare/sandbox"; // Durable Object 类必须从 Worker 入口导出
+
+export default {
+  async fetch(request: Request, env: { Sandbox: DurableObjectNamespace; RUNKO_GATEWAY_TOKEN: string }) {
+    const gateway = createSandboxGateway({
+      token: env.RUNKO_GATEWAY_TOKEN,
+      getSandbox: (sandboxId) => getSandbox(env.Sandbox, sandboxId),
+    });
+    return gateway.fetch(request);
+  },
+};
+```
+
+## 快速上手（客户端）
+
+```ts
+import { cloudflareWorkspace } from "@runko/sandbox-cloudflare";
+import { createSession, defineAgent } from "@runko/sdk";
+
+const workspace = cloudflareWorkspace({
+  url: process.env.RUNKO_CF_GATEWAY_URL!,     // 部署好的网关 URL
+  token: process.env.RUNKO_CF_GATEWAY_TOKEN!, // 与 `wrangler secret put RUNKO_GATEWAY_TOKEN` 相同的值
+});
+const session = createSession(defineAgent({ model: "anthropic/claude-sonnet-5" }), { workspace });
+const result = await session.send("在 notes.txt 里写一句问候语，然后用 bash 验证内容。");
+console.log(result.finalResponse);
+```
+
+没有 `Sandbox` 风格的 SDK 对象需要创建/销毁——沙盒生命周期由宿主的 wrangler 项目（`getSandbox()` 那一行）管理，不由这个客户端管理。
+
+完整可跑示例（含**零部署**的进程内 client → gateway → fake sandbox 完整协议往返演示）见 [examples/src/11-sandbox-cloudflare.ts](../../examples/src/11-sandbox-cloudflare.ts)。
+
+## 结构化接口 / BYO
+
+```ts
+// 客户端（"."）
+function cloudflareWorkspace(opts: { url: string; token: string; sandboxId?: string; fetch?: typeof fetch }): RunkoFS & RunkoExec;
+
+// 网关（"./worker"）
+function createSandboxGateway(opts: { token: string; getSandbox: (sandboxId: string) => CfSandboxLike | Promise<CfSandboxLike> }): {
+  fetch(request: Request): Promise<Response>;
+};
+```
+
+- 客户端没有"实例"概念（E2B/Vercel 是 BYO 一个已创建的沙盒对象；这里 BYO 的是一个已部署的**网关**——一个 URL + token）；`fetch` 可注入自定义传输（测试/演示用直连网关 handler，见 examples 11 的进程内演示）。
+- `CfSandboxLike` 是以 `@cloudflare/sandbox@0.12.3` 的 `ISandbox` 为蓝本手写的结构化最小子集（`exec`/`readFile`/`writeFile`/`mkdir`/`deleteFile`/`listFiles`）——`./worker` 运行时零 `import "@cloudflare/sandbox"`，真实装配（`getSandbox(env.Sandbox, id)` 的返回值）天然结构兼容这个接口，留给宿主项目经 `createSandboxGateway({ getSandbox })` 注入。
+- 全部 `POST` + JSON body，`Authorization: Bearer <token>` 鉴权，`x-runko-sandbox` 头选择沙盒（缺省 `"default"`），二进制经 base64，`/exec` 走 NDJSON 流式响应——完整协议见 [沙盒工作区（Sandbox Workspace） · 技术方案 §8.3](../../docs/host/contract/tech/sandbox.md)。
+
+## 已知限制（docs/host/contract/tech/sandbox.md §8.2–§8.3 / docs/logic/engine/plans/core-sdk.md P10-3 实际改动，如实照抄不发明）
+
+- **路径锚定是隐式的、发生在网关一侧，没有 `root` 配置项**：不同于 E2B/Vercel 的客户端 `opts.root`，这里的虚拟根 `/` 锚定在**沙盒自身的默认工作目录**——网关把客户端送来的虚拟绝对路径去掉前导 `/` 就得到沙盒相对路径，两端都不需要显式配置真实目录。**副作用**：bash 命令里带前导 `/` 的绝对路径（如 `cat /notes.txt`）落在沙盒真实文件系统根，而不是虚拟工作区根——同一份文件要在文件工具和 bash 之间互通，bash 侧要用相对路径。这是"真实 FS + root 锚定"的固有语义，E2B（`/home/user`）/Vercel（`/vercel/sandbox`）同样存在，只是那两家的锚点是客户端可见的配置项，这里锚点藏在网关内部。
+- **`readdir`/`stat` 对 symlink 与其他非常规条目一律归一为 `"file"`**——真实沙盒文件系统没有 `MemoryFS` 那种"reference"概念。
+- **`mtime` 精度是容器真实的文件修改时间**（常见是秒级精度），不是 `MemoryFS` 那种毫秒级递增时间戳。
+- **每次 RunkoFS/RunkoExec 调用都是一次 HTTP 往返**（经 Durable Object，几十到几百毫秒）——扫描类操作（globbing 大目录树、grep-like 搜索）优先用一条 bash 命令（`find`/`grep`），而不是逐个文件工具调用。
+- **沙盒生命周期（idle 睡眠、重启、过期）由宿主的 wrangler 项目管理**，不由这个客户端/网关管理——沙盒不可达时以网关错误的形式从 `exec()`/文件方法浮出，宿主负责唤醒或重建沙盒。沙盒磁盘本身是临时的：Durable Object idle 睡眠（默认 10 分钟）后文件系统丢失（见 [apps/cloudflare-worker-server/README.md](../../apps/cloudflare-worker-server/README.md)），长期数据需要宿主自己接 R2 backup，v1 网关不代理这一层。

package/dist/index.cjs

@@ -0,0 +1,308 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_protocol = require("./protocol-BXejIk9L.cjs");
+let _runko_virtual_fs = require("@runko/virtual-fs");
+require("zod");
+//#region src/index.ts
+/**
+* `.`：Cloudflare Sandbox 网关的纯 fetch 客户端（任意 Node ≥20 进程）——`cloudflareWorkspace(opts)`
+* 返回 `RunkoFS & RunkoExec`，供 `createSession({ workspace })` 一次注入（docs/tech/core-sdk.md §4.5a 模式 A）。
+* 本文件与 `./worker`（`src/worker.ts`）通过 `src/protocol.ts` 的 zod schema 共用同一份 wire 契约；
+* 不 import `@cloudflare/sandbox`——这一侧只说 HTTP，不知道也不需要知道对面跑的是不是真沙盒。
+*/
+const DESCRIBE = [
+	"cloudflareWorkspace: Cloudflare Sandbox accessed through a self-deployed HTTP gateway (\"./worker\"'s",
+	"createSandboxGateway, running in the host's own wrangler project) — every RunkoFS/RunkoExec call is one",
+	"HTTP round trip (tens to hundreds of ms), not an in-process operation.",
+	"Real Linux container (Cloudflare Containers). Same-origin workspace (mode A): bash and the file tools read",
+	"and write the exact same filesystem, so a bash redirect write is immediately visible to read-file and",
+	"vice versa — there is nothing to reconcile.",
+	"The virtual root \"/\" is anchored at the sandbox's own default working directory, not the container's real",
+	"filesystem root — but this is not a VirtualFS-style security boundary: the container is real Linux, and",
+	"anything the sandbox can execute (e.g. bash `cd /`) can reach the real root. Isolation is the boundary,",
+	"not path validation.",
+	"readdir/stat report type \"file\" for symlinks and other non-regular entries (no \"reference\" concept here);",
+	"mtime comes from the container's real file modification time (commonly second-level precision).",
+	"Scanning operations (globbing a large tree, grep-like search) cost one HTTP round trip per file tool call —",
+	"prefer a single bash call (`find`/`grep`) for anything beyond a handful of files.",
+	"Sandbox lifecycle (idle sleep, restarts, expiry) is managed by the host's wrangler project, not by this",
+	"adapter — a stopped/unreachable sandbox surfaces as a gateway error from exec()/the file methods; the host",
+	"is responsible for waking or recreating it."
+].join(" ");
+const textEncoder = new TextEncoder();
+/**
+* `Uint8Array` ↔ base64 往返，靠全局 `btoa`/`atob`（Node ≥18 与 Cloudflare Workers 都原生提供），
+* 不用 `Buffer`——这一侧刻意保持零 Node-only 便利 API，理由与 `./worker` 零 cloudflare import
+* 同源：本包的两个入口都应该能在对方的运行时环境里被复用而不报错。
+*/
+function bytesToBase64(bytes) {
+	let binary = "";
+	for (const byte of bytes) binary += String.fromCharCode(byte);
+	return btoa(binary);
+}
+function base64ToBytes(base64) {
+	const binary = atob(base64);
+	const bytes = new Uint8Array(binary.length);
+	for (let i = 0; i < binary.length; i += 1) bytes[i] = binary.charCodeAt(i);
+	return bytes;
+}
+function describeError(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+function requestInit(ctx, body) {
+	return {
+		method: "POST",
+		headers: {
+			"content-type": "application/json",
+			[require_protocol.AUTH_HEADER]: `Bearer ${ctx.token}`,
+			[require_protocol.SANDBOX_ID_HEADER]: ctx.sandboxId
+		},
+		body: JSON.stringify(body)
+	};
+}
+async function parseErrorBody(res) {
+	let raw;
+	try {
+		raw = await res.json();
+	} catch {
+		return {
+			code: "sandbox_error",
+			message: `gateway returned ${String(res.status)} ${res.statusText} with a non-JSON body`
+		};
+	}
+	const parsed = require_protocol.errorBodySchema.safeParse(raw);
+	if (!parsed.success) return {
+		code: "sandbox_error",
+		message: `gateway returned ${String(res.status)} with an unrecognized error body`
+	};
+	return parsed.data;
+}
+/** 把网关的 `{code,message}` 翻译成调用方能 `instanceof` 判别的错误——`path` 用调用方本地已知的值，不依赖 wire 回传。 */
+async function fsErrorFromResponse(res, path) {
+	const body = await parseErrorBody(res);
+	if (body.code === "not_found") return new _runko_virtual_fs.NotFoundError(path);
+	if (body.code === "dir_not_empty") return new _runko_virtual_fs.DirectoryNotEmptyError(path);
+	return /* @__PURE__ */ new Error(`cloudflare sandbox gateway error (${body.code}): ${body.message}`);
+}
+async function fsCall(ctx, endpoint, req, responseSchema, errorPath) {
+	const res = await ctx.fetchImpl(`${ctx.baseUrl}${endpoint}`, requestInit(ctx, req));
+	if (!res.ok) throw await fsErrorFromResponse(res, errorPath);
+	const json = await res.json();
+	return responseSchema.parse(json);
+}
+async function readFileImpl(ctx, path) {
+	const p = (0, _runko_virtual_fs.normalizePath)(path);
+	const { dataBase64 } = await fsCall(ctx, require_protocol.ENDPOINTS.read, { path: p }, require_protocol.readResponseSchema, p);
+	return base64ToBytes(dataBase64);
+}
+async function writeFileImpl(ctx, path, data) {
+	const p = (0, _runko_virtual_fs.normalizePath)(path);
+	const bytes = typeof data === "string" ? textEncoder.encode(data) : data;
+	await fsCall(ctx, require_protocol.ENDPOINTS.write, {
+		path: p,
+		dataBase64: bytesToBase64(bytes)
+	}, require_protocol.okResponseSchema, p);
+}
+async function rmImpl(ctx, path, opts) {
+	const p = (0, _runko_virtual_fs.normalizePath)(path);
+	await fsCall(ctx, require_protocol.ENDPOINTS.rm, {
+		path: p,
+		recursive: opts?.recursive
+	}, require_protocol.okResponseSchema, p);
+}
+async function mkdirImpl(ctx, path) {
+	const p = (0, _runko_virtual_fs.normalizePath)(path);
+	await fsCall(ctx, require_protocol.ENDPOINTS.mkdir, { path: p }, require_protocol.okResponseSchema, p);
+}
+async function readdirImpl(ctx, path) {
+	const p = (0, _runko_virtual_fs.normalizePath)(path);
+	const { entries } = await fsCall(ctx, require_protocol.ENDPOINTS.readdir, { path: p }, require_protocol.readdirResponseSchema, p);
+	return entries.map((entry) => ({
+		name: entry.name,
+		type: entry.type
+	}));
+}
+async function statImpl(ctx, path) {
+	const p = (0, _runko_virtual_fs.normalizePath)(path);
+	const res = await fsCall(ctx, require_protocol.ENDPOINTS.stat, { path: p }, require_protocol.statResponseSchema, p);
+	return {
+		type: res.type,
+		...res.size !== void 0 ? { size: res.size } : {},
+		...res.mtime !== void 0 ? { mtime: res.mtime } : {}
+	};
+}
+async function globImpl(ctx, pattern) {
+	const { paths } = await fsCall(ctx, require_protocol.ENDPOINTS.glob, { pattern }, require_protocol.globResponseSchema, pattern);
+	return paths;
+}
+var CloudflareExecAbortedError = class extends Error {
+	constructor(reason) {
+		super(reason === "timeout" ? "cloudflareWorkspace: exec timed out" : "cloudflareWorkspace: exec aborted");
+		this.name = "CloudflareExecAbortedError";
+	}
+};
+/**
+* 同 mini-bash/just-bash 的 `raceAbort`：`signal` 先触发就立刻 reject，不等 `work` 真正
+* 落定——`work` 可能因为网络分区/网关挂死而长期不 settle，仅靠 fetch 自身的 `signal` 支持
+* 不足以保证"绝不永久挂起"。给 `work` 补一个空 catch，避免它在竞速结束后才 settle 时
+* 产生 unhandled rejection。
+*/
+function raceAbort(work, signal) {
+	return new Promise((resolve, reject) => {
+		const settleAborted = () => {
+			work.catch(() => {});
+			reject(new CloudflareExecAbortedError("signal"));
+		};
+		if (signal.aborted) {
+			settleAborted();
+			return;
+		}
+		const onAbort = () => settleAborted();
+		signal.addEventListener("abort", onAbort, { once: true });
+		work.then((value) => {
+			signal.removeEventListener("abort", onAbort);
+			resolve(value);
+		}, (error) => {
+			signal.removeEventListener("abort", onAbort);
+			reject(error instanceof Error ? error : new Error(String(error)));
+		});
+	});
+}
+/** NDJSON 逐行解析：必须正确处理一行被 chunk 边界切断的情况——按 `\n` 切分前先攒一个跨 chunk 的 buffer。 */
+async function readExecResultFromStream(res, onOutput, start) {
+	if (res.body === null) return {
+		exitCode: 1,
+		stdout: "",
+		stderr: "cloudflareWorkspace: gateway response has no body",
+		durationMs: Date.now() - start
+	};
+	const reader = res.body.getReader();
+	const decoder = new TextDecoder();
+	let buffer = "";
+	let exitEvent;
+	const processLine = (line) => {
+		const trimmed = line.trim();
+		if (trimmed.length === 0) return;
+		let raw;
+		try {
+			raw = JSON.parse(trimmed);
+		} catch {
+			return;
+		}
+		const parsed = require_protocol.execStreamEventSchema.safeParse(raw);
+		if (!parsed.success) return;
+		if (parsed.data.type === "output") onOutput?.({
+			stream: parsed.data.stream,
+			data: parsed.data.data
+		});
+		else exitEvent = parsed.data;
+	};
+	try {
+		for (;;) {
+			const { value, done } = await reader.read();
+			if (done) break;
+			buffer += decoder.decode(value, { stream: true });
+			let newlineIndex = buffer.indexOf("\n");
+			while (newlineIndex !== -1) {
+				processLine(buffer.slice(0, newlineIndex));
+				buffer = buffer.slice(newlineIndex + 1);
+				newlineIndex = buffer.indexOf("\n");
+			}
+		}
+		buffer += decoder.decode();
+		if (buffer.length > 0) processLine(buffer);
+	} finally {
+		reader.releaseLock();
+	}
+	if (exitEvent === void 0) return {
+		exitCode: 1,
+		stdout: "",
+		stderr: "cloudflareWorkspace: gateway stream ended without a final exit event",
+		durationMs: Date.now() - start
+	};
+	return {
+		exitCode: exitEvent.exitCode,
+		stdout: exitEvent.stdout,
+		stderr: exitEvent.stderr,
+		durationMs: exitEvent.durationMs
+	};
+}
+async function execImpl(ctx, req, opts) {
+	const start = Date.now();
+	const timeoutController = new AbortController();
+	const timer = req.timeoutMs !== void 0 ? setTimeout(() => timeoutController.abort(), req.timeoutMs) : void 0;
+	const combined = AbortSignal.any([req.signal, timeoutController.signal]);
+	const work = (async () => {
+		try {
+			const cwd = req.cwd !== void 0 ? (0, _runko_virtual_fs.normalizePath)(req.cwd) : void 0;
+			const body = {
+				command: req.command,
+				...cwd !== void 0 ? { cwd } : {},
+				...req.timeoutMs !== void 0 ? { timeoutMs: req.timeoutMs } : {}
+			};
+			const res = await ctx.fetchImpl(`${ctx.baseUrl}${require_protocol.ENDPOINTS.exec}`, {
+				...requestInit(ctx, body),
+				signal: combined
+			});
+			if (!res.ok) {
+				const errorBody = await parseErrorBody(res);
+				return {
+					exitCode: 1,
+					stdout: "",
+					stderr: `cloudflareWorkspace: gateway rejected the exec request (${errorBody.code}): ${errorBody.message}`,
+					durationMs: Date.now() - start
+				};
+			}
+			return await readExecResultFromStream(res, opts?.onOutput, start);
+		} catch (error) {
+			return {
+				exitCode: 1,
+				stdout: "",
+				stderr: `cloudflareWorkspace: exec request failed: ${describeError(error)}. If this looks like a network error, check that the gateway worker at "${ctx.baseUrl}" is deployed and reachable, and that url/token/sandboxId are correct.`,
+				durationMs: Date.now() - start
+			};
+		}
+	})();
+	try {
+		return await raceAbort(work, combined);
+	} catch (error) {
+		const timedOut = timeoutController.signal.aborted;
+		if (error instanceof CloudflareExecAbortedError || timedOut) return {
+			exitCode: timedOut ? 124 : 130,
+			stdout: "",
+			stderr: timedOut ? `cloudflareWorkspace: exec timed out after ${String(req.timeoutMs)}ms` : "cloudflareWorkspace: exec aborted",
+			durationMs: Date.now() - start
+		};
+		return {
+			exitCode: 1,
+			stdout: "",
+			stderr: `cloudflareWorkspace: internal error: ${describeError(error)}`,
+			durationMs: Date.now() - start
+		};
+	} finally {
+		if (timer !== void 0) clearTimeout(timer);
+	}
+}
+function cloudflareWorkspace(opts) {
+	const ctx = {
+		fetchImpl: opts.fetch ?? globalThis.fetch,
+		baseUrl: opts.url.endsWith("/") ? opts.url.slice(0, -1) : opts.url,
+		token: opts.token,
+		sandboxId: opts.sandboxId ?? "default"
+	};
+	return {
+		defaultApproval: "allow",
+		describe() {
+			return DESCRIBE;
+		},
+		readFile: (path) => readFileImpl(ctx, path),
+		writeFile: (path, data) => writeFileImpl(ctx, path, data),
+		rm: (path, rmOpts) => rmImpl(ctx, path, rmOpts),
+		mkdir: (path) => mkdirImpl(ctx, path),
+		readdir: (path) => readdirImpl(ctx, path),
+		stat: (path) => statImpl(ctx, path),
+		glob: (pattern) => globImpl(ctx, pattern),
+		exec: (req, execOpts) => execImpl(ctx, req, execOpts)
+	};
+}
+//#endregion
+exports.cloudflareWorkspace = cloudflareWorkspace;

package/dist/index.d.cts

@@ -0,0 +1,12 @@
+import { RunkoExec, RunkoFS } from "@runko/core";
+//#region src/index.d.ts
+interface CloudflareWorkspaceOptions {
+  url: string;
+  token: string;
+  sandboxId?: string;
+  /** 注入自定义传输——测试用（直连内存网关 handler）或自定义中间层。默认 `globalThis.fetch`。 */
+  fetch?: typeof globalThis.fetch;
+}
+declare function cloudflareWorkspace(opts: CloudflareWorkspaceOptions): RunkoFS & RunkoExec;
+//#endregion
+export { CloudflareWorkspaceOptions, cloudflareWorkspace };

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+import { RunkoExec, RunkoFS } from "@runko/core";
+//#region src/index.d.ts
+interface CloudflareWorkspaceOptions {
+  url: string;
+  token: string;
+  sandboxId?: string;
+  /** 注入自定义传输——测试用（直连内存网关 handler）或自定义中间层。默认 `globalThis.fetch`。 */
+  fetch?: typeof globalThis.fetch;
+}
+declare function cloudflareWorkspace(opts: CloudflareWorkspaceOptions): RunkoFS & RunkoExec;
+//#endregion
+export { CloudflareWorkspaceOptions, cloudflareWorkspace };