@runko/sandbox-e2b 0.1.0

package/README.md

@@ -0,0 +1,73 @@
+# @runko/sandbox-e2b
+
+把一个已创建好的 [E2B](https://e2b.dev)（真实 Firecracker microVM）沙盒包成 `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)）。
+
+## 安装
+
+```sh
+pnpm add @runko/sandbox-e2b e2b
+```
+
+`e2b` 需要单独装——本包运行时**不 import** `e2b`（见下方"结构化接口"），但宿主要创建真实沙盒实例（`Sandbox.create()`）离不开它。本包不随 `@runko/sdk` 一起装，属于按需显式安装的可选集成。
+
+## 快速上手
+
+```ts
+import { Sandbox } from "e2b";
+import { e2bWorkspace } from "@runko/sandbox-e2b";
+import { createSession, defineAgent } from "@runko/sdk";
+
+const sandbox = await Sandbox.create();          // BYO：本包不创建/销毁沙盒
+try {
+  const workspace = e2bWorkspace(sandbox);        // 默认 root: "/home/user"
+  const session = createSession(defineAgent({ model: "anthropic/claude-sonnet-5" }), { workspace });
+  const result = await session.send("在 notes.txt 里写一句问候语，然后用 bash 验证内容。");
+  console.log(result.finalResponse);
+} finally {
+  await sandbox.kill();
+}
+```
+
+完整可跑示例（含零凭证的 fake 沙盒演示，证明"BYO 实例 + 结构化接口"不需要真实网络）见 [examples/09-sandbox-e2b.ts](../../examples/src/09-sandbox-e2b.ts)。
+
+## 结构化接口 / BYO
+
+```ts
+function e2bWorkspace(
+  sandbox: E2bSandboxLike,
+  opts?: { root?: string; keepAlive?: KeepAliveOptions },
+): E2bWorkspace;
+```
+
+- `E2bSandboxLike` 是以 e2b 官方 d.ts 为蓝本手写的结构化最小子集（`files.read/write/list/remove/makeDir/getInfo` + `commands.run`）——本包运行时零 `import "e2b"`，`e2bWorkspace()` 收的是这份结构接口而非具体类，真实 e2b `Sandbox` 实例无需任何转换即可直接传入（`test/type-conformance.ts` 的编译期证明），任何实现了同一结构的对象（例如测试/演示用的进程内 fake）同样可以传入。
+- **BYO 实例**是唯一入口：`e2bWorkspace()` 不创建、不销毁沙盒——创建（`Sandbox.create()`）、暂停/恢复、`kill()` 完全由宿主自己管理。唯一的例外是[保活](../../docs/terms.md)，见下。
+- `opts.root`（默认 `/home/user`，e2b 官方模板的登录用户主目录）：虚拟绝对路径 `/` 锚定到的沙盒内真实目录。
+
+## 保活（keepalive）
+
+**沙盒的存活时长是倒计时，在里面跑命令不会把它往后推。** 所以一轮 agent 只要跑得比沙盒超时长，就会在跑到一半时被平台暂停掉。传 `keepAlive` 即可让适配器自动续期：
+
+```ts
+const sandbox = await Sandbox.create({ timeoutMs: 300_000 });
+const workspace = e2bWorkspace(sandbox, {
+  keepAlive: { idleTimeoutMs: 300_000 },   // 与建盒 timeoutMs 保持一致
+});
+```
+
+- **不传 `keepAlive` = 完全不保活**，一次网络调用都不会发生，行为与没有这个功能时一致。保活会花钱，不该在你没要求时悄悄发生。
+- 续期是**补足**语义（补到至少 `idleTimeoutMs`，够了就什么都不做），不是无脑加时。
+- 这一轮真的卡死时信号自然停止，沙盒会正常休眠——它不会给一个已经死掉的任务无限续命。
+- 其余可调项（`maxTurnMs` 单轮上限、`approvalBudgetMs` 审批预算、`onRenew` 观测回调）见 `@runko/core` 的 `KeepAliveOptions` 与 [沙盒保活（keepalive） · 功能](../../docs/logic/orchestration/features/sandbox-keepalive.md)。
+
+⚠️ 两个要注意的：
+
+- **`idleTimeoutMs` 要和建盒时的 `timeoutMs` 一致。** 不一致很难查——比如建盒 5 分钟、这里按 10 分钟补足，就永远补不上去。
+- **E2B 有硬上限**：Pro 账户 24 小时、Hobby 账户 1 小时（`Sandbox.setTimeout` 的官方文档）。超了会报错。保活不是长生药。
+
+## 已知限制（docs/host/contract/tech/sandbox.md §8.2 / docs/logic/engine/plans/core-sdk.md P10-1 实际改动，如实照抄不发明）
+
+- **取消 = 放弃等待，不是真的杀掉远程进程**：`exec()` 的 abort/超时只保证及时返回（退出码 124/130），命令本身可能在沙盒里继续跑到自然结束——真正杀掉远程进程需要 e2b 的 `background: true` + `CommandHandle.kill()`，是另一条调用路径，不在本适配器 v1 范围内。
+- **bash 越出工作区根**：文件工具（`read_file`/`write_file`/...）锚定在 `root` 之下，但 `bash` 是沙盒里的真实 shell，能读写/`cd` 到磁盘任何位置——绝对路径的 bash 命令（如 `cat /notes.txt`）落在沙盒真实文件系统根，而不是 `root`；同一份文件要在文件工具和 bash 之间互通，bash 侧要用相对路径（沙盒默认 cwd 与 `root` 一致时，`cat notes.txt` 即可命中文件工具写的同一个文件）。
+- **每次 RunkoFS 文件工具调用都是一次网络往返**（几十到几百毫秒）——扫描类操作（大量 glob、grep-like 搜索）优先用一条 bash 命令，而不是逐个 `glob`/`read_file` 调用。
+- **非递归删除非空目录**：e2b 的 `remove()` 本身恒递归，适配器自己先 `list` 一层子项判断目录是否为空再决定要不要拒绝（`DirectoryNotEmptyError`），比原生多一次调用。
+- **沙盒已停止/过期**：v1 = 报错指导（`exec()`/文件方法翻译成带操作建议的失败结果），不做自动恢复——宿主需要自己延长沙盒超时或重新创建实例并重新调用 `e2bWorkspace()`。

package/dist/index.cjs

@@ -0,0 +1,310 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _runko_virtual_fs = require("@runko/virtual-fs");
+let _runko_core = require("@runko/core");
+//#region src/errors.ts
+/**
+* e2b 错误的结构判别（docs/tech/sandbox.md §8.1："错误识别一律结构判别不用 instanceof"——
+* 宿主与本包各自安装的 `e2b` 副本类不同一，`instanceof` 天然不可靠）。
+* `instanceof Error` 本身没问题（`Error` 是当前 realm 的全局内置类，不是
+* e2b 的导出类），只有对 e2b 自家导出的错误类才不能用 instanceof。
+*/
+/** e2b 的具名错误（`SandboxError` 及其子类）都在构造函数里把 `this.name` 设成子类名——按这个字符串字段判别，不按类名/`instanceof`。 */
+function isE2bErrorNamed(error, ...names) {
+	return error instanceof Error && names.includes(error.name);
+}
+function describeError(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+function isCommandExitErrorLike(error) {
+	if (typeof error !== "object" || error === null) return false;
+	if (!("exitCode" in error) || typeof error.exitCode !== "number") return false;
+	if (!("stdout" in error) || typeof error.stdout !== "string") return false;
+	if (!("stderr" in error) || typeof error.stderr !== "string") return false;
+	return true;
+}
+//#endregion
+//#region src/exec.ts
+const DESCRIBE = [
+	"e2b: a real Firecracker microVM sandbox (E2B cloud) — full Linux userspace, not a virtual filesystem.",
+	"Mode A same-source workspace: this RunkoFS view and bash commands share the exact same filesystem inside",
+	"the sandbox, so there is nothing to reconcile and no snapshot lag between the two.",
+	"The sandbox is a real machine: commands can read, write, and cd anywhere on its disk, not just under this",
+	"workspace's root — isolation (the whole VM is disposable) is the security boundary here, not path confinement",
+	"the way an in-process VirtualFS enforces it.",
+	"Each RunkoFS file-tool call is a network round trip (tens to hundreds of milliseconds). Prefer running",
+	"scan-heavy work (grep/find over many files, recursive listings) as a single bash command inside the sandbox",
+	"rather than many individual file-tool calls."
+].join(" ");
+var E2bExecAbortedError = class extends Error {
+	constructor(reason) {
+		super(reason === "timeout" ? "e2b: command timed out" : "e2b: aborted");
+		this.name = "E2bExecAbortedError";
+	}
+};
+/**
+* `signal` 先触发就立刻 reject，不等待 `work`（远程 `commands.run()`）真正
+* 落定——`work` 可能因为网络问题永久悬挂，这正是需要独立赛跑的原因。给
+* `work` 补一个空 catch，避免它在赛跑结束后才 reject 时产生 unhandled
+* rejection（`@runko/just-bash`/`@runko/mini-bash` 的同款 `raceAbort`）。
+*/
+function raceAbort(work, signal) {
+	return new Promise((resolve, reject) => {
+		const settleAborted = () => {
+			work.catch(() => {});
+			reject(new E2bExecAbortedError("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)));
+		});
+	});
+}
+function createE2bExec(sandbox, anchor, keepAlive) {
+	return {
+		defaultApproval: "allow",
+		describe() {
+			return DESCRIBE;
+		},
+		async exec(req, opts) {
+			const start = Date.now();
+			const cwd = req.cwd !== void 0 ? anchor.toReal(req.cwd) : anchor.rootReal;
+			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]);
+			/**
+			* [保活](../../../docs/terms.md)的第二个信号源（docs/tech/sandbox-keepalive.md §3.1）：
+			* 命令跑起来之后 core **一个 chunk 都不会产出**——`@runko/core` 的 `loop.ts`
+			* 把工具进度先缓冲、等命令 resolve 之后才重放。所以一条跑十分钟的命令，这十分钟
+			* 里 core 侧的活动信号是零。而这恰恰是最容易把沙盒跑没的场景。
+			*
+			* 补法就在这里：适配器自己就是那个在 `await` 的人，手里握着一个没落定的远程调用，
+			* 这是比 chunk 更硬的「还活着」证据，根本不需要谁来通知。
+			*/
+			const stopKeepAlive = keepAlive?.beginExec();
+			const work = sandbox.commands.run(req.command, {
+				cwd,
+				timeoutMs: req.timeoutMs,
+				onStdout: (data) => opts?.onOutput?.({
+					stream: "stdout",
+					data
+				}),
+				onStderr: (data) => opts?.onOutput?.({
+					stream: "stderr",
+					data
+				})
+			});
+			try {
+				const result = await raceAbort(work, combined);
+				return {
+					exitCode: result.exitCode,
+					stdout: result.stdout,
+					stderr: result.stderr,
+					durationMs: Date.now() - start
+				};
+			} catch (error) {
+				if (error instanceof E2bExecAbortedError) {
+					const timedOut = timeoutController.signal.aborted;
+					return {
+						exitCode: timedOut ? 124 : 130,
+						stdout: "",
+						stderr: timedOut ? `e2b: command timed out after ${String(req.timeoutMs)}ms` : "e2b: aborted",
+						durationMs: Date.now() - start
+					};
+				}
+				if (isCommandExitErrorLike(error)) return {
+					exitCode: error.exitCode,
+					stdout: error.stdout,
+					stderr: error.stderr,
+					durationMs: Date.now() - start
+				};
+				if (isE2bErrorNamed(error, "TimeoutError")) return {
+					exitCode: 124,
+					stdout: "",
+					stderr: `e2b: command timed out: ${describeError(error)}`,
+					durationMs: Date.now() - start
+				};
+				return {
+					exitCode: 1,
+					stdout: "",
+					stderr: `e2b: sandbox command failed: ${describeError(error)}. The sandbox may have stopped or its connection was lost (e.g. it hit its idle/session timeout) — extend the sandbox's timeout or recreate it and pass a fresh instance to e2bWorkspace().`,
+					durationMs: Date.now() - start
+				};
+			} finally {
+				if (timer !== void 0) clearTimeout(timer);
+				stopKeepAlive?.();
+			}
+		}
+	};
+}
+//#endregion
+//#region src/fs.ts
+/**
+* e2b 的"未找到"错误家族：`FileNotFoundError` 是当前版本实测抛出的具体子类，
+* `NotFoundError`（e2b 自家、已废弃）是历史/兼容路径可能出现的旧变体——两者
+* 都翻译成 `@runko/virtual-fs` 的 `NotFoundError`（同名不同类，跨包结构判别，
+* 不是 `instanceof`）。
+*/
+const NOT_FOUND_NAMES = ["FileNotFoundError", "NotFoundError"];
+/** `list(root, { depth })` 用于 glob 的递归深度——远超"典型工作区目录嵌套层数"的量级，避免深层子目录被漏扫。 */
+const GLOB_LIST_DEPTH = 64;
+/** `EntryInfo.type` 非 `"file"` 一律视为目录（docs/tech/sandbox.md §8.2："FileType 非 file 视为 dir"）；`size` 只在文件类型下有意义，仿 MemoryFS 用条件展开省略而非填 0/undefined。 */
+function toFileStat(entry) {
+	const type = entry.type === "file" ? "file" : "dir";
+	const mtime = entry.modifiedTime?.getTime();
+	return {
+		type,
+		...type === "file" ? { size: entry.size } : {},
+		...mtime !== void 0 ? { mtime } : {}
+	};
+}
+/** e2b 的 `write()` 不接受 `Uint8Array`（只收 `string | ArrayBuffer | Blob | ReadableStream`）——转成一份拷贝的 `ArrayBuffer`，避免子视图的 `byteOffset` 被忽略。 */
+function toArrayBuffer(data) {
+	return data.slice().buffer;
+}
+function createE2bFs(sandbox, anchor) {
+	return {
+		async readFile(path) {
+			const real = anchor.toReal(path);
+			try {
+				return await sandbox.files.read(real, { format: "bytes" });
+			} catch (error) {
+				if (isE2bErrorNamed(error, ...NOT_FOUND_NAMES)) throw new _runko_virtual_fs.NotFoundError(path);
+				throw error;
+			}
+		},
+		async writeFile(path, data) {
+			const payload = typeof data === "string" ? data : toArrayBuffer(data);
+			await sandbox.files.write(anchor.toReal(path), payload);
+		},
+		async rm(path, opts) {
+			const real = anchor.toReal(path);
+			let info;
+			try {
+				info = await sandbox.files.getInfo(real);
+			} catch (error) {
+				if (isE2bErrorNamed(error, ...NOT_FOUND_NAMES)) throw new _runko_virtual_fs.NotFoundError(path);
+				throw error;
+			}
+			if (opts?.recursive !== true && info.type !== "file") {
+				if ((await sandbox.files.list(real, { depth: 1 })).length > 0) throw new _runko_virtual_fs.DirectoryNotEmptyError(path);
+			}
+			await sandbox.files.remove(real);
+		},
+		async mkdir(path) {
+			await sandbox.files.makeDir(anchor.toReal(path));
+		},
+		async readdir(path) {
+			const real = anchor.toReal(path);
+			let entries;
+			try {
+				entries = await sandbox.files.list(real, { depth: 1 });
+			} catch (error) {
+				if (isE2bErrorNamed(error, ...NOT_FOUND_NAMES)) throw new _runko_virtual_fs.NotFoundError(path);
+				throw error;
+			}
+			return entries.map((entry) => ({
+				name: entry.name,
+				...toFileStat(entry)
+			})).sort((a, b) => a.name.localeCompare(b.name));
+		},
+		async stat(path) {
+			const real = anchor.toReal(path);
+			try {
+				return toFileStat(await sandbox.files.getInfo(real));
+			} catch (error) {
+				if (isE2bErrorNamed(error, ...NOT_FOUND_NAMES)) throw new _runko_virtual_fs.NotFoundError(path);
+				throw error;
+			}
+		},
+		async glob(pattern) {
+			let entries;
+			try {
+				entries = await sandbox.files.list(anchor.rootReal, { depth: GLOB_LIST_DEPTH });
+			} catch (error) {
+				if (isE2bErrorNamed(error, ...NOT_FOUND_NAMES)) throw new _runko_virtual_fs.NotFoundError("/");
+				throw error;
+			}
+			const matches = [];
+			for (const entry of entries) {
+				if (entry.type !== "file") continue;
+				const virtual = anchor.toVirtual(entry.path);
+				if ((0, _runko_virtual_fs.matchesGlob)(pattern, virtual)) matches.push(virtual);
+			}
+			return matches.sort();
+		}
+	};
+}
+//#endregion
+//#region src/keepalive.ts
+/** 沙盒实例没有 `setTimeout` 时的指引——出现在这里说明宿主传了保活配置，但传进来的对象补不了期。 */
+const KEEPALIVE_UNSUPPORTED_MESSAGE = "e2bWorkspace({ keepAlive }) needs the sandbox instance to expose setTimeout(timeoutMs) — a real e2b Sandbox does; a hand-written fake may not. Either pass a real sandbox, add setTimeout to the fake, or drop the keepAlive option (keepalive is entirely opt-in).";
+function createDriver(sandbox) {
+	return {
+		remainingMs: async () => void 0,
+		renew: async (targetMs) => {
+			if (sandbox.setTimeout === void 0) throw new Error(KEEPALIVE_UNSUPPORTED_MESSAGE);
+			await sandbox.setTimeout(targetMs);
+		}
+	};
+}
+/**
+* 造一个绑好这个沙盒的保活器。`opts` 为 `undefined`（宿主没开保活）时返回
+* `undefined`——调用方据此整段跳过，**不开就是一次网络调用都不会发生**。
+*/
+function createE2bKeepAlive(sandbox, opts) {
+	if (opts === void 0) return;
+	if (sandbox.setTimeout === void 0) throw new Error(KEEPALIVE_UNSUPPORTED_MESSAGE);
+	return (0, _runko_core.createKeepAlive)(createDriver(sandbox), opts);
+}
+//#endregion
+//#region src/path.ts
+/**
+* 虚拟绝对路径 ↔ 沙盒内真实路径的锚定换算（`E2bWorkspaceOptions.root`）。
+* `..` 越界的拒绝完全交给 `normalizePath` 的既有语义（抛 `PathEscapesRootError`）
+* ——沙盒工作区不重复实现这层校验，只负责把规范化后的虚拟路径接到 `root` 之下。
+*/
+function createPathAnchor(root) {
+	const rootReal = root === "/" ? "/" : root.replace(/\/+$/, "");
+	const childPrefix = rootReal === "/" ? "" : rootReal;
+	return {
+		rootReal,
+		toReal(virtualPath) {
+			const normalized = (0, _runko_virtual_fs.normalizePath)(virtualPath);
+			return normalized === "/" ? rootReal : `${childPrefix}${normalized}`;
+		},
+		toVirtual(realPath) {
+			if (realPath === rootReal) return "/";
+			if (childPrefix.length > 0 && realPath.startsWith(`${childPrefix}/`)) return realPath.slice(childPrefix.length);
+			return realPath;
+		}
+	};
+}
+//#endregion
+//#region src/workspace.ts
+/** e2b 官方模板默认的登录用户主目录——多数模板下也是命令的默认 cwd。 */
+const DEFAULT_ROOT = "/home/user";
+function e2bWorkspace(sandbox, opts = {}) {
+	const anchor = createPathAnchor(opts.root ?? DEFAULT_ROOT);
+	const keepAlive = createE2bKeepAlive(sandbox, opts.keepAlive);
+	const workspace = {
+		...createE2bFs(sandbox, anchor),
+		...createE2bExec(sandbox, anchor, keepAlive)
+	};
+	if (keepAlive !== void 0) {
+		workspace.onActivity = (signal) => keepAlive.onActivity(signal);
+		workspace.keepAlive = (targetMs) => keepAlive.keepAlive(targetMs);
+	}
+	return workspace;
+}
+//#endregion
+exports.KEEPALIVE_UNSUPPORTED_MESSAGE = KEEPALIVE_UNSUPPORTED_MESSAGE;
+exports.e2bWorkspace = e2bWorkspace;

package/dist/index.d.cts

@@ -0,0 +1,105 @@
+import { KeepAliveOptions, RunkoActivityAware, RunkoExec, RunkoFS, RunkoKeepAliveCapable } from "@runko/core";
+//#region src/types.d.ts
+/**
+ * `e2b` SDK 面的最小结构化子集（docs/tech/core-sdk.md §4.5a 施工依据 docs/tech/sandbox.md §8.1
+ * "依赖策略"）：只声明适配器实际调用到的方法/字段，以官方 d.ts
+ * （`e2b@2.32.0`，`node_modules/e2b/dist/index.d.ts`）为蓝本手写。`e2bWorkspace()`
+ * 收的是这份结构接口而非 `import("e2b").Sandbox` 具体类——宿主与本包各自安装的
+ * `e2b` 副本互不知晓对方存在，结构类型让真实 `Sandbox` 免转换即可传入
+ * （见 `test/type-conformance.ts` 的对照证明），也让契约测试免真实网络即可
+ * 全覆盖（`test/helpers.ts` 的 `FakeE2bSandbox` 实现同一接口）。
+ */
+/**
+ * 对应真实 `EntryInfo`（`Filesystem.list/getInfo` 的返回值）。`type` 字段真实
+ * 类型是 e2b 的字符串枚举 `FileType`；这里放宽成 `string` 而非照抄该枚举——
+ * 枚举成员本就能单向宽化赋值给 `string`，没有必要为了对照真实类型而在这个
+ * "结构最小面"里引入一个额外的类型名。运行时按字面量值 `"file"` 比较即可
+ * （非 `"file"` 一律视为目录，见 `fs.ts`）。
+ */
+interface E2bEntryInfo {
+  name: string;
+  type?: string;
+  path: string;
+  size: number;
+  modifiedTime?: Date;
+}
+/** `Filesystem.write()` 的返回值：适配器不消费它，只声明会被结构对照到的字段。 */
+interface E2bWriteInfo {
+  name: string;
+  path: string;
+}
+interface E2bFilesystemListOpts {
+  depth?: number;
+}
+interface E2bFilesystemLike {
+  read(path: string, opts: {
+    format: "bytes";
+  }): Promise<Uint8Array>;
+  /**
+   * 真实 `Filesystem.write()` 接受 `string | ArrayBuffer | Blob | ReadableStream`
+   * ——**不**接受 `Uint8Array` 直接传入。`RunkoFS.writeFile` 的入参是
+   * `Uint8Array | string`，所以适配器（`fs.ts`）在调用这里之前把 `Uint8Array`
+   * 转成 `ArrayBuffer`（拷贝一份，避免 `byteOffset`/子视图语义出错）。
+   */
+  write(path: string, data: string | ArrayBuffer): Promise<E2bWriteInfo>;
+  list(path: string, opts?: E2bFilesystemListOpts): Promise<E2bEntryInfo[]>;
+  remove(path: string): Promise<void>;
+  makeDir(path: string): Promise<boolean>;
+  getInfo(path: string): Promise<E2bEntryInfo>;
+}
+interface E2bCommandResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+interface E2bCommandRunOpts {
+  cwd?: string;
+  timeoutMs?: number;
+  onStdout?: (data: string) => void;
+  onStderr?: (data: string) => void;
+}
+interface E2bCommandsLike {
+  run(command: string, opts?: E2bCommandRunOpts): Promise<E2bCommandResult>;
+}
+/**
+ * `e2bWorkspace()` 接受的最小面——BYO 已创建好的 e2b `Sandbox` 实例即满足这个形状。
+ *
+ * `setTimeout` 是**可选**的，这一点是刻意的：它只有开[保活](../../../docs/terms.md)
+ * 时才用得上，而把它列成必填会当场打死所有手写 fake（`examples/09` 的假沙盒、
+ * `test/helpers.ts` 的 `FakeE2bSandbox`），违背 [BYO 实例](../../../docs/terms.md)
+ * 与「最小结构面」两条纪律。真实 `Sandbox` 天然带这个方法，所以宿主零改动即可获得能力。
+ */
+interface E2bSandboxLike {
+  files: E2bFilesystemLike;
+  commands: E2bCommandsLike;
+  /**
+   * 把沙盒的存活时长**重置**为「从现在起 `timeoutMs`」（不是加时——E2B 与 Vercel
+   * 在这里语义相反，见 docs/tech/sandbox-keepalive.md §1）。
+   *
+   * 上限：Pro 账户 24 小时、Hobby 账户 1 小时（`e2b@2.32.0` 的 `Sandbox.setTimeout`
+   * 文档注释），超了会报错。
+   */
+  setTimeout?(timeoutMs: number): Promise<void>;
+}
+//#endregion
+//#region src/workspace.d.ts
+interface E2bWorkspaceOptions {
+  /** 沙盒内锚定虚拟根 `/` 的真实目录，默认 `/home/user`。 */
+  root?: string;
+  /**
+   * 开启[保活](../../../docs/terms.md)。**不传 = 不保活**（默认行为不变）。
+   *
+   * `idleTimeoutMs` 应与建盒时 `Sandbox.create({ timeoutMs })` 的值一致——两处不一致
+   * 很难查（比如建盒 5 分钟、这里按 10 分钟补足，就永远补不上去）。
+   */
+  keepAlive?: KeepAliveOptions;
+}
+/** `e2bWorkspace()` 的返回形状：工作区两面 + 两个可选的保活面（只在开了 `keepAlive` 时真的存在）。 */
+type E2bWorkspace = RunkoFS & RunkoExec & RunkoActivityAware & RunkoKeepAliveCapable;
+declare function e2bWorkspace(sandbox: E2bSandboxLike, opts?: E2bWorkspaceOptions): E2bWorkspace;
+//#endregion
+//#region src/keepalive.d.ts
+/** 沙盒实例没有 `setTimeout` 时的指引——出现在这里说明宿主传了保活配置，但传进来的对象补不了期。 */
+declare const KEEPALIVE_UNSUPPORTED_MESSAGE: string;
+//#endregion
+export { type E2bCommandResult, type E2bCommandRunOpts, type E2bCommandsLike, type E2bEntryInfo, type E2bFilesystemLike, type E2bFilesystemListOpts, type E2bSandboxLike, type E2bWorkspace, type E2bWorkspaceOptions, type E2bWriteInfo, KEEPALIVE_UNSUPPORTED_MESSAGE, e2bWorkspace };

package/dist/index.d.ts

@@ -0,0 +1,105 @@
+import { KeepAliveOptions, RunkoActivityAware, RunkoExec, RunkoFS, RunkoKeepAliveCapable } from "@runko/core";
+//#region src/types.d.ts
+/**
+ * `e2b` SDK 面的最小结构化子集（docs/tech/core-sdk.md §4.5a 施工依据 docs/tech/sandbox.md §8.1
+ * "依赖策略"）：只声明适配器实际调用到的方法/字段，以官方 d.ts
+ * （`e2b@2.32.0`，`node_modules/e2b/dist/index.d.ts`）为蓝本手写。`e2bWorkspace()`
+ * 收的是这份结构接口而非 `import("e2b").Sandbox` 具体类——宿主与本包各自安装的
+ * `e2b` 副本互不知晓对方存在，结构类型让真实 `Sandbox` 免转换即可传入
+ * （见 `test/type-conformance.ts` 的对照证明），也让契约测试免真实网络即可
+ * 全覆盖（`test/helpers.ts` 的 `FakeE2bSandbox` 实现同一接口）。
+ */
+/**
+ * 对应真实 `EntryInfo`（`Filesystem.list/getInfo` 的返回值）。`type` 字段真实
+ * 类型是 e2b 的字符串枚举 `FileType`；这里放宽成 `string` 而非照抄该枚举——
+ * 枚举成员本就能单向宽化赋值给 `string`，没有必要为了对照真实类型而在这个
+ * "结构最小面"里引入一个额外的类型名。运行时按字面量值 `"file"` 比较即可
+ * （非 `"file"` 一律视为目录，见 `fs.ts`）。
+ */
+interface E2bEntryInfo {
+  name: string;
+  type?: string;
+  path: string;
+  size: number;
+  modifiedTime?: Date;
+}
+/** `Filesystem.write()` 的返回值：适配器不消费它，只声明会被结构对照到的字段。 */
+interface E2bWriteInfo {
+  name: string;
+  path: string;
+}
+interface E2bFilesystemListOpts {
+  depth?: number;
+}
+interface E2bFilesystemLike {
+  read(path: string, opts: {
+    format: "bytes";
+  }): Promise<Uint8Array>;
+  /**
+   * 真实 `Filesystem.write()` 接受 `string | ArrayBuffer | Blob | ReadableStream`
+   * ——**不**接受 `Uint8Array` 直接传入。`RunkoFS.writeFile` 的入参是
+   * `Uint8Array | string`，所以适配器（`fs.ts`）在调用这里之前把 `Uint8Array`
+   * 转成 `ArrayBuffer`（拷贝一份，避免 `byteOffset`/子视图语义出错）。
+   */
+  write(path: string, data: string | ArrayBuffer): Promise<E2bWriteInfo>;
+  list(path: string, opts?: E2bFilesystemListOpts): Promise<E2bEntryInfo[]>;
+  remove(path: string): Promise<void>;
+  makeDir(path: string): Promise<boolean>;
+  getInfo(path: string): Promise<E2bEntryInfo>;
+}
+interface E2bCommandResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+interface E2bCommandRunOpts {
+  cwd?: string;
+  timeoutMs?: number;
+  onStdout?: (data: string) => void;
+  onStderr?: (data: string) => void;
+}
+interface E2bCommandsLike {
+  run(command: string, opts?: E2bCommandRunOpts): Promise<E2bCommandResult>;
+}
+/**
+ * `e2bWorkspace()` 接受的最小面——BYO 已创建好的 e2b `Sandbox` 实例即满足这个形状。
+ *
+ * `setTimeout` 是**可选**的，这一点是刻意的：它只有开[保活](../../../docs/terms.md)
+ * 时才用得上，而把它列成必填会当场打死所有手写 fake（`examples/09` 的假沙盒、
+ * `test/helpers.ts` 的 `FakeE2bSandbox`），违背 [BYO 实例](../../../docs/terms.md)
+ * 与「最小结构面」两条纪律。真实 `Sandbox` 天然带这个方法，所以宿主零改动即可获得能力。
+ */
+interface E2bSandboxLike {
+  files: E2bFilesystemLike;
+  commands: E2bCommandsLike;
+  /**
+   * 把沙盒的存活时长**重置**为「从现在起 `timeoutMs`」（不是加时——E2B 与 Vercel
+   * 在这里语义相反，见 docs/tech/sandbox-keepalive.md §1）。
+   *
+   * 上限：Pro 账户 24 小时、Hobby 账户 1 小时（`e2b@2.32.0` 的 `Sandbox.setTimeout`
+   * 文档注释），超了会报错。
+   */
+  setTimeout?(timeoutMs: number): Promise<void>;
+}
+//#endregion
+//#region src/workspace.d.ts
+interface E2bWorkspaceOptions {
+  /** 沙盒内锚定虚拟根 `/` 的真实目录，默认 `/home/user`。 */
+  root?: string;
+  /**
+   * 开启[保活](../../../docs/terms.md)。**不传 = 不保活**（默认行为不变）。
+   *
+   * `idleTimeoutMs` 应与建盒时 `Sandbox.create({ timeoutMs })` 的值一致——两处不一致
+   * 很难查（比如建盒 5 分钟、这里按 10 分钟补足，就永远补不上去）。
+   */
+  keepAlive?: KeepAliveOptions;
+}
+/** `e2bWorkspace()` 的返回形状：工作区两面 + 两个可选的保活面（只在开了 `keepAlive` 时真的存在）。 */
+type E2bWorkspace = RunkoFS & RunkoExec & RunkoActivityAware & RunkoKeepAliveCapable;
+declare function e2bWorkspace(sandbox: E2bSandboxLike, opts?: E2bWorkspaceOptions): E2bWorkspace;
+//#endregion
+//#region src/keepalive.d.ts
+/** 沙盒实例没有 `setTimeout` 时的指引——出现在这里说明宿主传了保活配置，但传进来的对象补不了期。 */
+declare const KEEPALIVE_UNSUPPORTED_MESSAGE: string;
+//#endregion
+export { type E2bCommandResult, type E2bCommandRunOpts, type E2bCommandsLike, type E2bEntryInfo, type E2bFilesystemLike, type E2bFilesystemListOpts, type E2bSandboxLike, type E2bWorkspace, type E2bWorkspaceOptions, type E2bWriteInfo, KEEPALIVE_UNSUPPORTED_MESSAGE, e2bWorkspace };

package/dist/index.js

@@ -0,0 +1,308 @@
+import { DirectoryNotEmptyError, NotFoundError, matchesGlob, normalizePath } from "@runko/virtual-fs";
+import { createKeepAlive } from "@runko/core";
+//#region src/errors.ts
+/**
+* e2b 错误的结构判别（docs/tech/sandbox.md §8.1："错误识别一律结构判别不用 instanceof"——
+* 宿主与本包各自安装的 `e2b` 副本类不同一，`instanceof` 天然不可靠）。
+* `instanceof Error` 本身没问题（`Error` 是当前 realm 的全局内置类，不是
+* e2b 的导出类），只有对 e2b 自家导出的错误类才不能用 instanceof。
+*/
+/** e2b 的具名错误（`SandboxError` 及其子类）都在构造函数里把 `this.name` 设成子类名——按这个字符串字段判别，不按类名/`instanceof`。 */
+function isE2bErrorNamed(error, ...names) {
+	return error instanceof Error && names.includes(error.name);
+}
+function describeError(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+function isCommandExitErrorLike(error) {
+	if (typeof error !== "object" || error === null) return false;
+	if (!("exitCode" in error) || typeof error.exitCode !== "number") return false;
+	if (!("stdout" in error) || typeof error.stdout !== "string") return false;
+	if (!("stderr" in error) || typeof error.stderr !== "string") return false;
+	return true;
+}
+//#endregion
+//#region src/exec.ts
+const DESCRIBE = [
+	"e2b: a real Firecracker microVM sandbox (E2B cloud) — full Linux userspace, not a virtual filesystem.",
+	"Mode A same-source workspace: this RunkoFS view and bash commands share the exact same filesystem inside",
+	"the sandbox, so there is nothing to reconcile and no snapshot lag between the two.",
+	"The sandbox is a real machine: commands can read, write, and cd anywhere on its disk, not just under this",
+	"workspace's root — isolation (the whole VM is disposable) is the security boundary here, not path confinement",
+	"the way an in-process VirtualFS enforces it.",
+	"Each RunkoFS file-tool call is a network round trip (tens to hundreds of milliseconds). Prefer running",
+	"scan-heavy work (grep/find over many files, recursive listings) as a single bash command inside the sandbox",
+	"rather than many individual file-tool calls."
+].join(" ");
+var E2bExecAbortedError = class extends Error {
+	constructor(reason) {
+		super(reason === "timeout" ? "e2b: command timed out" : "e2b: aborted");
+		this.name = "E2bExecAbortedError";
+	}
+};
+/**
+* `signal` 先触发就立刻 reject，不等待 `work`（远程 `commands.run()`）真正
+* 落定——`work` 可能因为网络问题永久悬挂，这正是需要独立赛跑的原因。给
+* `work` 补一个空 catch，避免它在赛跑结束后才 reject 时产生 unhandled
+* rejection（`@runko/just-bash`/`@runko/mini-bash` 的同款 `raceAbort`）。
+*/
+function raceAbort(work, signal) {
+	return new Promise((resolve, reject) => {
+		const settleAborted = () => {
+			work.catch(() => {});
+			reject(new E2bExecAbortedError("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)));
+		});
+	});
+}
+function createE2bExec(sandbox, anchor, keepAlive) {
+	return {
+		defaultApproval: "allow",
+		describe() {
+			return DESCRIBE;
+		},
+		async exec(req, opts) {
+			const start = Date.now();
+			const cwd = req.cwd !== void 0 ? anchor.toReal(req.cwd) : anchor.rootReal;
+			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]);
+			/**
+			* [保活](../../../docs/terms.md)的第二个信号源（docs/tech/sandbox-keepalive.md §3.1）：
+			* 命令跑起来之后 core **一个 chunk 都不会产出**——`@runko/core` 的 `loop.ts`
+			* 把工具进度先缓冲、等命令 resolve 之后才重放。所以一条跑十分钟的命令，这十分钟
+			* 里 core 侧的活动信号是零。而这恰恰是最容易把沙盒跑没的场景。
+			*
+			* 补法就在这里：适配器自己就是那个在 `await` 的人，手里握着一个没落定的远程调用，
+			* 这是比 chunk 更硬的「还活着」证据，根本不需要谁来通知。
+			*/
+			const stopKeepAlive = keepAlive?.beginExec();
+			const work = sandbox.commands.run(req.command, {
+				cwd,
+				timeoutMs: req.timeoutMs,
+				onStdout: (data) => opts?.onOutput?.({
+					stream: "stdout",
+					data
+				}),
+				onStderr: (data) => opts?.onOutput?.({
+					stream: "stderr",
+					data
+				})
+			});
+			try {
+				const result = await raceAbort(work, combined);
+				return {
+					exitCode: result.exitCode,
+					stdout: result.stdout,
+					stderr: result.stderr,
+					durationMs: Date.now() - start
+				};
+			} catch (error) {
+				if (error instanceof E2bExecAbortedError) {
+					const timedOut = timeoutController.signal.aborted;
+					return {
+						exitCode: timedOut ? 124 : 130,
+						stdout: "",
+						stderr: timedOut ? `e2b: command timed out after ${String(req.timeoutMs)}ms` : "e2b: aborted",
+						durationMs: Date.now() - start
+					};
+				}
+				if (isCommandExitErrorLike(error)) return {
+					exitCode: error.exitCode,
+					stdout: error.stdout,
+					stderr: error.stderr,
+					durationMs: Date.now() - start
+				};
+				if (isE2bErrorNamed(error, "TimeoutError")) return {
+					exitCode: 124,
+					stdout: "",
+					stderr: `e2b: command timed out: ${describeError(error)}`,
+					durationMs: Date.now() - start
+				};
+				return {
+					exitCode: 1,
+					stdout: "",
+					stderr: `e2b: sandbox command failed: ${describeError(error)}. The sandbox may have stopped or its connection was lost (e.g. it hit its idle/session timeout) — extend the sandbox's timeout or recreate it and pass a fresh instance to e2bWorkspace().`,
+					durationMs: Date.now() - start
+				};
+			} finally {
+				if (timer !== void 0) clearTimeout(timer);
+				stopKeepAlive?.();
+			}
+		}
+	};
+}
+//#endregion
+//#region src/fs.ts
+/**
+* e2b 的"未找到"错误家族：`FileNotFoundError` 是当前版本实测抛出的具体子类，
+* `NotFoundError`（e2b 自家、已废弃）是历史/兼容路径可能出现的旧变体——两者
+* 都翻译成 `@runko/virtual-fs` 的 `NotFoundError`（同名不同类，跨包结构判别，
+* 不是 `instanceof`）。
+*/
+const NOT_FOUND_NAMES = ["FileNotFoundError", "NotFoundError"];
+/** `list(root, { depth })` 用于 glob 的递归深度——远超"典型工作区目录嵌套层数"的量级，避免深层子目录被漏扫。 */
+const GLOB_LIST_DEPTH = 64;
+/** `EntryInfo.type` 非 `"file"` 一律视为目录（docs/tech/sandbox.md §8.2："FileType 非 file 视为 dir"）；`size` 只在文件类型下有意义，仿 MemoryFS 用条件展开省略而非填 0/undefined。 */
+function toFileStat(entry) {
+	const type = entry.type === "file" ? "file" : "dir";
+	const mtime = entry.modifiedTime?.getTime();
+	return {
+		type,
+		...type === "file" ? { size: entry.size } : {},
+		...mtime !== void 0 ? { mtime } : {}
+	};
+}
+/** e2b 的 `write()` 不接受 `Uint8Array`（只收 `string | ArrayBuffer | Blob | ReadableStream`）——转成一份拷贝的 `ArrayBuffer`，避免子视图的 `byteOffset` 被忽略。 */
+function toArrayBuffer(data) {
+	return data.slice().buffer;
+}
+function createE2bFs(sandbox, anchor) {
+	return {
+		async readFile(path) {
+			const real = anchor.toReal(path);
+			try {
+				return await sandbox.files.read(real, { format: "bytes" });
+			} catch (error) {
+				if (isE2bErrorNamed(error, ...NOT_FOUND_NAMES)) throw new NotFoundError(path);
+				throw error;
+			}
+		},
+		async writeFile(path, data) {
+			const payload = typeof data === "string" ? data : toArrayBuffer(data);
+			await sandbox.files.write(anchor.toReal(path), payload);
+		},
+		async rm(path, opts) {
+			const real = anchor.toReal(path);
+			let info;
+			try {
+				info = await sandbox.files.getInfo(real);
+			} catch (error) {
+				if (isE2bErrorNamed(error, ...NOT_FOUND_NAMES)) throw new NotFoundError(path);
+				throw error;
+			}
+			if (opts?.recursive !== true && info.type !== "file") {
+				if ((await sandbox.files.list(real, { depth: 1 })).length > 0) throw new DirectoryNotEmptyError(path);
+			}
+			await sandbox.files.remove(real);
+		},
+		async mkdir(path) {
+			await sandbox.files.makeDir(anchor.toReal(path));
+		},
+		async readdir(path) {
+			const real = anchor.toReal(path);
+			let entries;
+			try {
+				entries = await sandbox.files.list(real, { depth: 1 });
+			} catch (error) {
+				if (isE2bErrorNamed(error, ...NOT_FOUND_NAMES)) throw new NotFoundError(path);
+				throw error;
+			}
+			return entries.map((entry) => ({
+				name: entry.name,
+				...toFileStat(entry)
+			})).sort((a, b) => a.name.localeCompare(b.name));
+		},
+		async stat(path) {
+			const real = anchor.toReal(path);
+			try {
+				return toFileStat(await sandbox.files.getInfo(real));
+			} catch (error) {
+				if (isE2bErrorNamed(error, ...NOT_FOUND_NAMES)) throw new NotFoundError(path);
+				throw error;
+			}
+		},
+		async glob(pattern) {
+			let entries;
+			try {
+				entries = await sandbox.files.list(anchor.rootReal, { depth: GLOB_LIST_DEPTH });
+			} catch (error) {
+				if (isE2bErrorNamed(error, ...NOT_FOUND_NAMES)) throw new NotFoundError("/");
+				throw error;
+			}
+			const matches = [];
+			for (const entry of entries) {
+				if (entry.type !== "file") continue;
+				const virtual = anchor.toVirtual(entry.path);
+				if (matchesGlob(pattern, virtual)) matches.push(virtual);
+			}
+			return matches.sort();
+		}
+	};
+}
+//#endregion
+//#region src/keepalive.ts
+/** 沙盒实例没有 `setTimeout` 时的指引——出现在这里说明宿主传了保活配置，但传进来的对象补不了期。 */
+const KEEPALIVE_UNSUPPORTED_MESSAGE = "e2bWorkspace({ keepAlive }) needs the sandbox instance to expose setTimeout(timeoutMs) — a real e2b Sandbox does; a hand-written fake may not. Either pass a real sandbox, add setTimeout to the fake, or drop the keepAlive option (keepalive is entirely opt-in).";
+function createDriver(sandbox) {
+	return {
+		remainingMs: async () => void 0,
+		renew: async (targetMs) => {
+			if (sandbox.setTimeout === void 0) throw new Error(KEEPALIVE_UNSUPPORTED_MESSAGE);
+			await sandbox.setTimeout(targetMs);
+		}
+	};
+}
+/**
+* 造一个绑好这个沙盒的保活器。`opts` 为 `undefined`（宿主没开保活）时返回
+* `undefined`——调用方据此整段跳过，**不开就是一次网络调用都不会发生**。
+*/
+function createE2bKeepAlive(sandbox, opts) {
+	if (opts === void 0) return;
+	if (sandbox.setTimeout === void 0) throw new Error(KEEPALIVE_UNSUPPORTED_MESSAGE);
+	return createKeepAlive(createDriver(sandbox), opts);
+}
+//#endregion
+//#region src/path.ts
+/**
+* 虚拟绝对路径 ↔ 沙盒内真实路径的锚定换算（`E2bWorkspaceOptions.root`）。
+* `..` 越界的拒绝完全交给 `normalizePath` 的既有语义（抛 `PathEscapesRootError`）
+* ——沙盒工作区不重复实现这层校验，只负责把规范化后的虚拟路径接到 `root` 之下。
+*/
+function createPathAnchor(root) {
+	const rootReal = root === "/" ? "/" : root.replace(/\/+$/, "");
+	const childPrefix = rootReal === "/" ? "" : rootReal;
+	return {
+		rootReal,
+		toReal(virtualPath) {
+			const normalized = normalizePath(virtualPath);
+			return normalized === "/" ? rootReal : `${childPrefix}${normalized}`;
+		},
+		toVirtual(realPath) {
+			if (realPath === rootReal) return "/";
+			if (childPrefix.length > 0 && realPath.startsWith(`${childPrefix}/`)) return realPath.slice(childPrefix.length);
+			return realPath;
+		}
+	};
+}
+//#endregion
+//#region src/workspace.ts
+/** e2b 官方模板默认的登录用户主目录——多数模板下也是命令的默认 cwd。 */
+const DEFAULT_ROOT = "/home/user";
+function e2bWorkspace(sandbox, opts = {}) {
+	const anchor = createPathAnchor(opts.root ?? DEFAULT_ROOT);
+	const keepAlive = createE2bKeepAlive(sandbox, opts.keepAlive);
+	const workspace = {
+		...createE2bFs(sandbox, anchor),
+		...createE2bExec(sandbox, anchor, keepAlive)
+	};
+	if (keepAlive !== void 0) {
+		workspace.onActivity = (signal) => keepAlive.onActivity(signal);
+		workspace.keepAlive = (targetMs) => keepAlive.keepAlive(targetMs);
+	}
+	return workspace;
+}
+//#endregion
+export { KEEPALIVE_UNSUPPORTED_MESSAGE, e2bWorkspace };

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@runko/sandbox-e2b",
+  "version": "0.1.0",
+  "description": "RunkoFS & RunkoExec 同源工作区：适配 E2B 云沙盒（e2b SDK 仅类型依赖，BYO sandbox 实例）",
+  "type": "module",
+  "license": "ISC",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@runko/core": "^0.1.0",
+    "@runko/virtual-fs": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.3",
+    "ai": "^7.0.20",
+    "e2b": "^2.32.0",
+    "tsdown": "^0.22.4",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint . --report-unused-disable-directives --max-warnings 0",
+    "lint:fix": "eslint . --fix",
+    "test": "vitest run"
+  }
+}