@runko/sandbox-cloudflare 0.1.0

package/dist/index.js

@@ -0,0 +1,307 @@
+import { _ as readdirResponseSchema, a as SANDBOX_ID_HEADER, b as statResponseSchema, d as globResponseSchema, h as readResponseSchema, l as execStreamEventSchema, o as errorBodySchema, p as okResponseSchema, r as ENDPOINTS, t as AUTH_HEADER } from "./protocol-Dj8Yv54w.js";
+import { DirectoryNotEmptyError, NotFoundError, normalizePath } from "@runko/virtual-fs";
+import "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",
+			[AUTH_HEADER]: `Bearer ${ctx.token}`,
+			[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 = 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 NotFoundError(path);
+	if (body.code === "dir_not_empty") return new 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 = normalizePath(path);
+	const { dataBase64 } = await fsCall(ctx, ENDPOINTS.read, { path: p }, readResponseSchema, p);
+	return base64ToBytes(dataBase64);
+}
+async function writeFileImpl(ctx, path, data) {
+	const p = normalizePath(path);
+	const bytes = typeof data === "string" ? textEncoder.encode(data) : data;
+	await fsCall(ctx, ENDPOINTS.write, {
+		path: p,
+		dataBase64: bytesToBase64(bytes)
+	}, okResponseSchema, p);
+}
+async function rmImpl(ctx, path, opts) {
+	const p = normalizePath(path);
+	await fsCall(ctx, ENDPOINTS.rm, {
+		path: p,
+		recursive: opts?.recursive
+	}, okResponseSchema, p);
+}
+async function mkdirImpl(ctx, path) {
+	const p = normalizePath(path);
+	await fsCall(ctx, ENDPOINTS.mkdir, { path: p }, okResponseSchema, p);
+}
+async function readdirImpl(ctx, path) {
+	const p = normalizePath(path);
+	const { entries } = await fsCall(ctx, ENDPOINTS.readdir, { path: p }, readdirResponseSchema, p);
+	return entries.map((entry) => ({
+		name: entry.name,
+		type: entry.type
+	}));
+}
+async function statImpl(ctx, path) {
+	const p = normalizePath(path);
+	const res = await fsCall(ctx, ENDPOINTS.stat, { path: p }, 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, ENDPOINTS.glob, { pattern }, 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 = 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 ? 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}${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
+export { cloudflareWorkspace };

package/dist/protocol-BXejIk9L.cjs

@@ -0,0 +1,226 @@
+let zod = require("zod");
+//#region src/protocol.ts
+/**
+* `@runko/sandbox-cloudflare` 网关协议（tech-spec 见 docs/tech/sandbox.md
+* §8.3）：`.`（客户端）与 `./worker`（网关）两端共用同一份 zod schema——schema 是
+* wire 契约的唯一事实来源，两端各自 `parse()` 校验后再消费，任何一端改了字段形状
+* 都会在另一端的 parse() 上炸出来，而不是悄悄读到 `undefined`。
+*
+* 全部端点 `POST` + JSON body；鉴权 `Authorization: Bearer <token>`；沙盒选择
+* `x-runko-sandbox: <id>`（缺省 `"default"`）；二进制经 base64；错误响应统一
+* `{ code, message }` 形状（`errorBodySchema`），配对应 HTTP 状态码。
+*/
+/** 八个端点的路径常量——两端都从这里引用，避免字面量拼写不一致。 */
+const ENDPOINTS = {
+	read: "/fs/read",
+	write: "/fs/write",
+	rm: "/fs/rm",
+	mkdir: "/fs/mkdir",
+	readdir: "/fs/readdir",
+	stat: "/fs/stat",
+	glob: "/fs/glob",
+	exec: "/exec"
+};
+const AUTH_HEADER = "authorization";
+const SANDBOX_ID_HEADER = "x-runko-sandbox";
+const DEFAULT_SANDBOX_ID = "default";
+const readRequestSchema = zod.z.object({ path: zod.z.string() });
+const readResponseSchema = zod.z.object({ dataBase64: zod.z.string() });
+const writeRequestSchema = zod.z.object({
+	path: zod.z.string(),
+	dataBase64: zod.z.string()
+});
+/** write/rm/mkdir 共用的成功响应形状。 */
+const okResponseSchema = zod.z.object({ ok: zod.z.literal(true) });
+const rmRequestSchema = zod.z.object({
+	path: zod.z.string(),
+	recursive: zod.z.boolean().optional()
+});
+const mkdirRequestSchema = zod.z.object({ path: zod.z.string() });
+const readdirRequestSchema = zod.z.object({ path: zod.z.string() });
+/** `RunkoFS.FileStat.type` 的沙盒子集——沙盒工作区没有 reference 条目（§3.1），但
+* 该字面量仍保留在 wire 类型里，让客户端可以直接复用 core 的 `DirEntry`/`FileStat`
+* 类型而不必再窄化一次。 */
+const entryTypeSchema = zod.z.enum([
+	"file",
+	"dir",
+	"reference"
+]);
+const wireDirEntrySchema = zod.z.object({
+	name: zod.z.string(),
+	type: entryTypeSchema
+});
+const readdirResponseSchema = zod.z.object({ entries: zod.z.array(wireDirEntrySchema) });
+const statRequestSchema = zod.z.object({ path: zod.z.string() });
+const statResponseSchema = zod.z.object({
+	type: entryTypeSchema,
+	size: zod.z.number().optional(),
+	mtime: zod.z.number().optional()
+});
+const globRequestSchema = zod.z.object({ pattern: zod.z.string() });
+const globResponseSchema = zod.z.object({ paths: zod.z.array(zod.z.string()) });
+const execRequestSchema = zod.z.object({
+	command: zod.z.string(),
+	cwd: zod.z.string().optional(),
+	timeoutMs: zod.z.number().optional()
+});
+const execOutputEventSchema = zod.z.object({
+	type: zod.z.literal("output"),
+	stream: zod.z.enum(["stdout", "stderr"]),
+	data: zod.z.string()
+});
+const execExitEventSchema = zod.z.object({
+	type: zod.z.literal("exit"),
+	exitCode: zod.z.number(),
+	stdout: zod.z.string(),
+	stderr: zod.z.string(),
+	durationMs: zod.z.number()
+});
+/** NDJSON 逐行的判别联合：N 个 output 块 + 恰好一个终块 exit。 */
+const execStreamEventSchema = zod.z.discriminatedUnion("type", [execOutputEventSchema, execExitEventSchema]);
+const NDJSON_CONTENT_TYPE = "application/x-ndjson";
+/**
+* `not_found`/`not_dir`/`dir_not_empty`/`sandbox_error` 是 §8.3 原文列出的 FS 错误码；
+* `unauthorized`/`bad_request` 是本工单施工时的裁量补充（鉴权失败 401、请求体
+* 解析/校验失败 400 都需要一个结构化 code，而不是把 401/400 的语义硬塞进上面四个
+* FS 专用码里）。
+*/
+const errorCodeSchema = zod.z.enum([
+	"not_found",
+	"not_dir",
+	"dir_not_empty",
+	"sandbox_error",
+	"unauthorized",
+	"bad_request"
+]);
+const errorBodySchema = zod.z.object({
+	code: errorCodeSchema,
+	message: zod.z.string()
+});
+//#endregion
+Object.defineProperty(exports, "AUTH_HEADER", {
+	enumerable: true,
+	get: function() {
+		return AUTH_HEADER;
+	}
+});
+Object.defineProperty(exports, "DEFAULT_SANDBOX_ID", {
+	enumerable: true,
+	get: function() {
+		return DEFAULT_SANDBOX_ID;
+	}
+});
+Object.defineProperty(exports, "ENDPOINTS", {
+	enumerable: true,
+	get: function() {
+		return ENDPOINTS;
+	}
+});
+Object.defineProperty(exports, "NDJSON_CONTENT_TYPE", {
+	enumerable: true,
+	get: function() {
+		return NDJSON_CONTENT_TYPE;
+	}
+});
+Object.defineProperty(exports, "SANDBOX_ID_HEADER", {
+	enumerable: true,
+	get: function() {
+		return SANDBOX_ID_HEADER;
+	}
+});
+Object.defineProperty(exports, "errorBodySchema", {
+	enumerable: true,
+	get: function() {
+		return errorBodySchema;
+	}
+});
+Object.defineProperty(exports, "execExitEventSchema", {
+	enumerable: true,
+	get: function() {
+		return execExitEventSchema;
+	}
+});
+Object.defineProperty(exports, "execRequestSchema", {
+	enumerable: true,
+	get: function() {
+		return execRequestSchema;
+	}
+});
+Object.defineProperty(exports, "execStreamEventSchema", {
+	enumerable: true,
+	get: function() {
+		return execStreamEventSchema;
+	}
+});
+Object.defineProperty(exports, "globRequestSchema", {
+	enumerable: true,
+	get: function() {
+		return globRequestSchema;
+	}
+});
+Object.defineProperty(exports, "globResponseSchema", {
+	enumerable: true,
+	get: function() {
+		return globResponseSchema;
+	}
+});
+Object.defineProperty(exports, "mkdirRequestSchema", {
+	enumerable: true,
+	get: function() {
+		return mkdirRequestSchema;
+	}
+});
+Object.defineProperty(exports, "okResponseSchema", {
+	enumerable: true,
+	get: function() {
+		return okResponseSchema;
+	}
+});
+Object.defineProperty(exports, "readRequestSchema", {
+	enumerable: true,
+	get: function() {
+		return readRequestSchema;
+	}
+});
+Object.defineProperty(exports, "readResponseSchema", {
+	enumerable: true,
+	get: function() {
+		return readResponseSchema;
+	}
+});
+Object.defineProperty(exports, "readdirRequestSchema", {
+	enumerable: true,
+	get: function() {
+		return readdirRequestSchema;
+	}
+});
+Object.defineProperty(exports, "readdirResponseSchema", {
+	enumerable: true,
+	get: function() {
+		return readdirResponseSchema;
+	}
+});
+Object.defineProperty(exports, "rmRequestSchema", {
+	enumerable: true,
+	get: function() {
+		return rmRequestSchema;
+	}
+});
+Object.defineProperty(exports, "statRequestSchema", {
+	enumerable: true,
+	get: function() {
+		return statRequestSchema;
+	}
+});
+Object.defineProperty(exports, "statResponseSchema", {
+	enumerable: true,
+	get: function() {
+		return statResponseSchema;
+	}
+});
+Object.defineProperty(exports, "writeRequestSchema", {
+	enumerable: true,
+	get: function() {
+		return writeRequestSchema;
+	}
+});

package/dist/protocol-Dj8Yv54w.js

@@ -0,0 +1,101 @@
+import { z } from "zod";
+//#region src/protocol.ts
+/**
+* `@runko/sandbox-cloudflare` 网关协议（tech-spec 见 docs/tech/sandbox.md
+* §8.3）：`.`（客户端）与 `./worker`（网关）两端共用同一份 zod schema——schema 是
+* wire 契约的唯一事实来源，两端各自 `parse()` 校验后再消费，任何一端改了字段形状
+* 都会在另一端的 parse() 上炸出来，而不是悄悄读到 `undefined`。
+*
+* 全部端点 `POST` + JSON body；鉴权 `Authorization: Bearer <token>`；沙盒选择
+* `x-runko-sandbox: <id>`（缺省 `"default"`）；二进制经 base64；错误响应统一
+* `{ code, message }` 形状（`errorBodySchema`），配对应 HTTP 状态码。
+*/
+/** 八个端点的路径常量——两端都从这里引用，避免字面量拼写不一致。 */
+const ENDPOINTS = {
+	read: "/fs/read",
+	write: "/fs/write",
+	rm: "/fs/rm",
+	mkdir: "/fs/mkdir",
+	readdir: "/fs/readdir",
+	stat: "/fs/stat",
+	glob: "/fs/glob",
+	exec: "/exec"
+};
+const AUTH_HEADER = "authorization";
+const SANDBOX_ID_HEADER = "x-runko-sandbox";
+const DEFAULT_SANDBOX_ID = "default";
+const readRequestSchema = z.object({ path: z.string() });
+const readResponseSchema = z.object({ dataBase64: z.string() });
+const writeRequestSchema = z.object({
+	path: z.string(),
+	dataBase64: z.string()
+});
+/** write/rm/mkdir 共用的成功响应形状。 */
+const okResponseSchema = z.object({ ok: z.literal(true) });
+const rmRequestSchema = z.object({
+	path: z.string(),
+	recursive: z.boolean().optional()
+});
+const mkdirRequestSchema = z.object({ path: z.string() });
+const readdirRequestSchema = z.object({ path: z.string() });
+/** `RunkoFS.FileStat.type` 的沙盒子集——沙盒工作区没有 reference 条目（§3.1），但
+* 该字面量仍保留在 wire 类型里，让客户端可以直接复用 core 的 `DirEntry`/`FileStat`
+* 类型而不必再窄化一次。 */
+const entryTypeSchema = z.enum([
+	"file",
+	"dir",
+	"reference"
+]);
+const wireDirEntrySchema = z.object({
+	name: z.string(),
+	type: entryTypeSchema
+});
+const readdirResponseSchema = z.object({ entries: z.array(wireDirEntrySchema) });
+const statRequestSchema = z.object({ path: z.string() });
+const statResponseSchema = z.object({
+	type: entryTypeSchema,
+	size: z.number().optional(),
+	mtime: z.number().optional()
+});
+const globRequestSchema = z.object({ pattern: z.string() });
+const globResponseSchema = z.object({ paths: z.array(z.string()) });
+const execRequestSchema = z.object({
+	command: z.string(),
+	cwd: z.string().optional(),
+	timeoutMs: z.number().optional()
+});
+const execOutputEventSchema = z.object({
+	type: z.literal("output"),
+	stream: z.enum(["stdout", "stderr"]),
+	data: z.string()
+});
+const execExitEventSchema = z.object({
+	type: z.literal("exit"),
+	exitCode: z.number(),
+	stdout: z.string(),
+	stderr: z.string(),
+	durationMs: z.number()
+});
+/** NDJSON 逐行的判别联合：N 个 output 块 + 恰好一个终块 exit。 */
+const execStreamEventSchema = z.discriminatedUnion("type", [execOutputEventSchema, execExitEventSchema]);
+const NDJSON_CONTENT_TYPE = "application/x-ndjson";
+/**
+* `not_found`/`not_dir`/`dir_not_empty`/`sandbox_error` 是 §8.3 原文列出的 FS 错误码；
+* `unauthorized`/`bad_request` 是本工单施工时的裁量补充（鉴权失败 401、请求体
+* 解析/校验失败 400 都需要一个结构化 code，而不是把 401/400 的语义硬塞进上面四个
+* FS 专用码里）。
+*/
+const errorCodeSchema = z.enum([
+	"not_found",
+	"not_dir",
+	"dir_not_empty",
+	"sandbox_error",
+	"unauthorized",
+	"bad_request"
+]);
+const errorBodySchema = z.object({
+	code: errorCodeSchema,
+	message: z.string()
+});
+//#endregion
+export { readdirResponseSchema as _, SANDBOX_ID_HEADER as a, statResponseSchema as b, execRequestSchema as c, globResponseSchema as d, mkdirRequestSchema as f, readdirRequestSchema as g, readResponseSchema as h, NDJSON_CONTENT_TYPE as i, execStreamEventSchema as l, readRequestSchema as m, DEFAULT_SANDBOX_ID as n, errorBodySchema as o, okResponseSchema as p, ENDPOINTS as r, execExitEventSchema as s, AUTH_HEADER as t, globRequestSchema as u, rmRequestSchema as v, writeRequestSchema as x, statRequestSchema as y };