feat: Implement agentfs-just-bash backend with internal and public session management

- Added InternalSandboxSession and public SandboxSession implementations in agentfs-sandbox/session.ts.
- Introduced path resolution utilities for AgentFS data layout in agentfs/paths.ts.
- Refactored sandbox.ts to utilize the new session management structure and path utilities.
- Updated docker-entrypoint.mjs to enhance logging for workflow configurations.

.env.example

@@ -1,19 +1,22 @@
-# Workflow world（@workflow/world-postgres → Supabase Postgres）
+# Workflow world 切换
+# - local：@workflow/world-local → .workflow-data/（本机调试推荐，默认）
+# - postgres：@workflow/world-postgres → Supabase（HF / 生产；镜像默认 postgres）
+WORKFLOW_WORLD=local
+
+# 仅 WORKFLOW_WORLD=postgres 时必填
 # Session pooler :5432 或 Direct :5432；勿用 Transaction pooler :6543
 #
-# 重要：本地 Windows 与 HF Linux 若共用同一 WORKFLOW_POSTGRES_URL，
+# 若本机也用 postgres 且与 HF 共用同一 WORKFLOW_POSTGRES_URL，
 # 启动时会 Re-enqueue 对方留下的 active run；step 里若带本机绝对路径
 # （如 H:\...），在另一台机器上会 FatalError（ERR_INVALID_MODULE_SPECIFIER）。
-# 做法二选一：
-#   1) 不同环境用不同库 / 不同 project
-#   2) 至少设不同 JOB_PREFIX，并在切环境前取消残留 active run（见 README）
-WORKFLOW_POSTGRES_URL=postgresql://postgres.<project-ref>:<password>@aws-0-<region>.pooler.supabase.com:5432/postgres
-# 本地示例：local_  |  HF Secrets 示例：hf_
+# 推荐：本机用 local；若必须共库则至少不同 JOB_PREFIX，并在切环境前清 active run。
+# WORKFLOW_POSTGRES_URL=postgresql://postgres.<project-ref>:<password>@aws-0-<region>.pooler.supabase.com:5432/postgres
+# HF Secrets 示例：hf_  |  本机若走 postgres：local_
 # WORKFLOW_POSTGRES_JOB_PREFIX=local_
 # Supabase Session 模式常限 pool_size=15；单进程务必留余量（重启/本机/Dashboard 也会占连接）
 # 须 maxPoolSize >= concurrency。HF 镜像默认 3 / 5。超出会 EMAXCONNSESSION 直接退出。
-WORKFLOW_POSTGRES_WORKER_CONCURRENCY=3
-WORKFLOW_POSTGRES_MAX_POOL_SIZE=5
+# WORKFLOW_POSTGRES_WORKER_CONCURRENCY=3
+# WORKFLOW_POSTGRES_MAX_POOL_SIZE=5
 
 # 服务 API 鉴权（/eve/v1 与 /agentfs/api 共用）
 # 客户端请求头：Authorization: Bearer <AGENT_API_KEY>
@@ -26,5 +29,15 @@ CUSTOM_BASE_URL=http://127.0.0.1:8090/v1
 CUSTOM_API_KEY=
 CUSTOM_MODEL=LongCat-2.0
 
+# Message 功能中心 MCP（agent/connections/message.ts）
+# 注意用 /mcp/ 直连，不要用 /spaces/.../mcp（会 404）
+MESSAGE_MCP_URL=https://hunian003-message.hf.space/mcp/
+# 上游若要求 Bearer，再填；公网无鉴权的 Space 可留空
+# MESSAGE_MCP_TOKEN=
+
 # AgentFS / 沙箱数据目录（默认 <appRoot>/data）
 # EVEAGENT_DATA_DIR=
+
+# AgentFS HTTP 写接口（checkpoint 创建/回退/删除）。默认不注册写路由。
+# 本地需要存档时显式打开：AGENTFS_ENABLE_WRITES=1
+# AGENTFS_ENABLE_WRITES=

Dockerfile

@@ -19,9 +19,12 @@ RUN pnpm install --frozen-lockfile --ignore-scripts
 
 COPY agent/ ./agent/
 COPY tsconfig.json ./
-# 构建期通常无 Secrets；占位仅供 agent.ts load，runner 用 Space Secrets
+# 构建期通常无 Secrets；占位仅供 agent.ts / message 连接 load，runner 用 Space Secrets
+# local：构建不必连 Postgres（agent.ts 默认 / 显式 local 不 require URL）
+ENV WORKFLOW_WORLD=local
 ENV CUSTOM_BASE_URL=http://build-time-placeholder.invalid/v1
 ENV CUSTOM_MODEL=build-placeholder
+ENV MESSAGE_MCP_URL=https://build-time-placeholder.invalid/mcp/
 RUN pnpm build
 
 # ---- runner: 仅生产依赖 + 构建产物（linux 上现装，保证 turso .node）----
@@ -33,6 +36,8 @@ ENV PORT=3000
 ENV HOST=0.0.0.0
 ENV NITRO_HOST=0.0.0.0
 ENV NITRO_PORT=3000
+# 部署默认 Postgres world；Secrets 可改回 local（无持久卷则重启丢会话）
+ENV WORKFLOW_WORLD=postgres
 # Supabase Session pooler 常见 pool_size=15（EMAXCONNSESSION）。
 # 单进程 pool 必须远小于 15：重启时旧连接尚未释放，本地若同库也会占名额。
 # Graphile 要求 maxPoolSize >= concurrency。Secrets 可覆盖。

README.md

@@ -23,7 +23,7 @@ short_description: vercel eve 框架驱动的 agent 服务
 | 模型协议 | [AI SDK](https://ai-sdk.dev/) `^7.0.0` + `@ai-sdk/openai-compatible ^3.0.0` |
 | 沙箱 | just-bash `^3.0.1` 通过 `agentfs-sdk/just-bash` 落到 `agentfs-sdk ^0.6.4` (Turso / SQLite,默认本地文件,环境变量 `EVEAGENT_DATA_DIR` 改数据目录) |
 | 运行时 | Nitro (Node.js `24.x`) |
-| Workflow 状态 | `@workflow/world-postgres` → Supabase Postgres（`WORKFLOW_POSTGRES_URL`） |
+| Workflow 状态 | `WORKFLOW_WORLD=local` → `.workflow-data/`；`postgres` → Supabase（`WORKFLOW_POSTGRES_URL`） |
 | 镜像 | 多阶段 `node:24-bookworm-slim` |
 
 ## API
@@ -53,15 +53,15 @@ short_description: vercel eve 框架驱动的 agent 服务
 
 | 方法 | 路径 | 用途 |
 | --- | --- | --- |
-| `GET` | `/agentfs/api/sessions` | 列出 session 沙箱库 |
+| `GET` | `/agentfs/api/sessions` | 列出 session 沙箱库（`writesEnabled` 标明写面是否开启；**不**回传宿主机路径） |
 | `GET` | `/agentfs/api/sessions/:id/tree?path=` | 列目录 |
 | `GET` | `/agentfs/api/sessions/:id/file?path=` | 读文件预览（有大小上限） |
 | `GET` | `/agentfs/api/sessions/:id/checkpoints` | 列出存档点 |
-| `POST` | `/agentfs/api/sessions/:id/checkpoint` | 创建存档点（body: `{ name }`） |
-| `POST` | `/agentfs/api/sessions/:id/restore` | 回退到存档点（body: `{ checkpoint }`） |
-| `DELETE` | `/agentfs/api/sessions/:id/checkpoint` | 删除存档点（body: `{ name }`） |
+| `POST` | `/agentfs/api/sessions/:id/checkpoint` | 创建存档点（body: `{ name }`）**仅** `AGENTFS_ENABLE_WRITES=1` |
+| `POST` | `/agentfs/api/sessions/:id/restore` | 回退到存档点（body: `{ checkpoint }`）**仅**写面开启 |
+| `DELETE` | `/agentfs/api/sessions/:id/checkpoint` | 删除存档点（body: `{ name }`）**仅**写面开启 |
 
-实现：`agent/channels/agentfs.ts` + `agent/lib/agentfs-debug.ts`。浏览为只读；checkpoint 路由会写磁盘上的存档库并可能改写 session 库内容。鉴权与 `/eve` 相同（Bearer `AGENT_API_KEY` / 本机 `localDev`）。
+实现：`agent/channels/agentfs.ts` + `agent/lib/agentfs-debug.ts`（实现拆在 `agent/lib/agentfs-debug/`）。默认**只注册读路由**；checkpoint 写路由须 Secrets/`.env` 设 `AGENTFS_ENABLE_WRITES=1|true|yes` 才会挂载（避免公网默认暴露改写 session FS 的面）。鉴权与 `/eve` 相同（Bearer `AGENT_API_KEY` / 本机 `localDev`）。
 
 ### Workflow 队列回调
 
@@ -91,10 +91,14 @@ worker 会回打本服务的 `/.well-known/workflow/v1/flow|step`；只代理 `/
 | `CUSTOM_BASE_URL` | 是 | 模型 OpenAI-compatible base URL（无代码默认值） |
 | `CUSTOM_MODEL` | 是 | 模型 id（无代码默认值） |
 | `CUSTOM_API_KEY` | 视模型端 | 上游模型 API key |
-| `WORKFLOW_POSTGRES_URL` | 是 | Supabase Postgres；Session/Direct `:5432`，**勿用** Transaction `:6543` |
-| `WORKFLOW_POSTGRES_JOB_PREFIX` | 建议 | 与本地隔离，如 `hf_`（本地用 `local_`）；**只改 graphile 任务名，表仍共享** |
-| `WORKFLOW_POSTGRES_WORKER_CONCURRENCY` | 否 | 镜像默认 `3`（包默认 50 会瞬间打满 Session pool） |
-| `WORKFLOW_POSTGRES_MAX_POOL_SIZE` | 否 | 镜像默认 `5`；须 ≥ concurrency，且 **远小于** Supabase Session `pool_size`（常见 15） |
+| `MESSAGE_MCP_URL` | 是 | Message 功能中心 MCP 端点（如 `https://hunian003-message.hf.space/mcp/`） |
+| `MESSAGE_MCP_TOKEN` | 否 | 上游 MCP Bearer；无鉴权 Space 可省略 |
+| `AGENTFS_ENABLE_WRITES` | 否 | 设为 `1`/`true` 才注册 AgentFS checkpoint 写路由；默认不暴露 |
+| `WORKFLOW_WORLD` | 否 | `local` \| `postgres`。本机默认 `local`；**镜像 runner 默认 `postgres`**。`postgres` 时必须配 `WORKFLOW_POSTGRES_URL` |
+| `WORKFLOW_POSTGRES_URL` | `postgres` 时必填 | Supabase Postgres；Session/Direct `:5432`，**勿用** Transaction `:6543` |
+| `WORKFLOW_POSTGRES_JOB_PREFIX` | 建议（postgres） | 多实例共库时区分 queue job 名，如 `hf_`；**只改 graphile 任务名，表仍共享** |
+| `WORKFLOW_POSTGRES_WORKER_CONCURRENCY` | 否（postgres） | 镜像默认 `3`（包默认 50 会瞬间打满 Session pool） |
+| `WORKFLOW_POSTGRES_MAX_POOL_SIZE` | 否（postgres） | 镜像默认 `5`；须 ≥ concurrency，且 **远小于** Supabase Session `pool_size`（常见 15） |
 
 #### `EMAXCONNSESSION` / `max clients reached in session mode`
 
@@ -108,13 +112,13 @@ worker 会回打本服务的 `/.well-known/workflow/v1/flow|step`；只代理 `/
 
 1. **先等 1–3 分钟**（或 Supabase Dashboard → Database → 看连接数降下去）再重启 Space。  
 2. HF Secrets / 镜像把池子压小，例如：`WORKER_CONCURRENCY=3`、`MAX_POOL_SIZE=5`（已是 Dockerfile 默认）。  
-3. **不要** 本机 `pnpm dev` 与 HF **同时** 大池子连同一 URL。  
+3. **本机调试用 `WORKFLOW_WORLD=local`**，不要与 HF 同时大池子连同一 URL。  
 4. 若 Secrets 里曾设 `MAX_POOL_SIZE=12` 等，删掉或改成 ≤5，否则会覆盖镜像默认。  
 5. 仍���够：升 Supabase 算力 / 提高 pool，或本机与云端分库。
 
-首次部署前在能连库的环境执行 `pnpm workflow:db:setup`。
+`WORKFLOW_WORLD=postgres` 时，首次部署前在能连库的环境执行 `pnpm workflow:db:setup`。
 
-**不要把本地 Windows 的 active run 留给 HF 接着跑。** 两边若共用同一 `WORKFLOW_POSTGRES_URL`，启动日志会出现 `Re-enqueued N active run(s)`；本机路径（`H:\...`）在 Linux 容器里会变成类似：
+**推荐本机 `local`、HF `postgres`。** 若两边都设 `postgres` 且共用同一 `WORKFLOW_POSTGRES_URL`，启动日志会出现 `Re-enqueued N active run(s)`；本机路径（`H:\...`）在 Linux 容器里会变成类似：
 
 ```text
 Invalid module "/app/H:%5Cnewworkspace%5C...\\authored-module-map-loader.js"
@@ -179,19 +183,24 @@ pnpm install
 
 # 2) 配置环境变量（必填项见 .env.example，无代码 fallback）
 cp .env.example .env
-# 至少：CUSTOM_BASE_URL、CUSTOM_MODEL、WORKFLOW_POSTGRES_URL
+# 至少：CUSTOM_BASE_URL、CUSTOM_MODEL
+# 默认 WORKFLOW_WORLD=local（状态写 .workflow-data/，不必配 Postgres）
 # 建议：AGENT_API_KEY（公网必填；本机回环可暂空）
+# MESSAGE_MCP_URL 若走 message 连接也需配置
 
-# 3) 初始化 workflow 表（首次 / 升级 world-postgres 后）
-pnpm workflow:db:setup
+# 3) 仅当 WORKFLOW_WORLD=postgres 时：初始化 workflow 表
+# pnpm workflow:db:setup
 
 # 4) 跑 eve dev(Nitro + TUI,默认 :2000)
 pnpm dev
 ```
 
-会话 / run / event 存在 Postgres（`workflow_*` + `graphile_worker`），不再依赖 `.workflow-data/`。旧 local 文件状态不会自动迁移。
+| `WORKFLOW_WORLD` | 状态落点 | 适用 |
+| --- | --- | --- |
+| `local`（默认） | `.workflow-data/` | 本机调试，与 HF 天然隔离 |
+| `postgres` | Supabase（`WORKFLOW_POSTGRES_URL`） | HF / 生产；镜像 runner 默认 |
 
-本地若与 HF 共用同一 Supabase：**务必**设不同的 `WORKFLOW_POSTGRES_JOB_PREFIX`，且不要留下跨机器的 active run（见上文 SQL）。否则 HF 启动会 re-enqueue 本机 run 并 FatalError。
+本机若改 `WORKFLOW_WORLD=postgres` 且与 HF 共用同一库：**务必**设不同的 `WORKFLOW_POSTGRES_JOB_PREFIX`，且不要留下跨机器的 active run（见上文 SQL）。否则 HF 启动会 re-enqueue 本机 run 并 FatalError。local 与 postgres 的状态**不会**自动迁移。
 
 ## AgentFS 本地调试页（静态）
 
@@ -209,7 +218,7 @@ pnpm dev
 
 本 Space 的 `/eve` 与 `/agentfs` 已用 `serviceAuthChain`（Bearer `AGENT_API_KEY` + 本机 `localDev`），**不是** `none()`。未配置 `AGENT_API_KEY` 时公网请求会被拒绝。内置 bash / read_file / write_file 的虚拟文件系统通过 `agent/sandbox.ts` 落到本地 AgentFS(SQLite)；just-bash 不跑真二进制，命令局限在 `/workspace` 内的纯 JS 解释。沙箱网络默认关闭；为 websearch 子 agent 仅放行 `api.anysearch.com` / `api.firecrawl.dev`（GET/HEAD/POST）。
 
-**持有有效 API Key 的调用方可以让 LLM 在 AgentFS 沙箱里跑命令、读写沙箱文件，并调用 checkpoint 写接口；沙箱外的真实文件系统不会被触及，但 HF 容器非持久，Sandbox 数据库路径务必放到持久卷。**
+**持有有效 API Key 的调用方可以让 LLM 在 AgentFS 沙箱里跑命令、读写沙箱文件；若开启了 `AGENTFS_ENABLE_WRITES`，还可调用 checkpoint 写接口。沙箱外的真实文件系统不会被触及，但 HF 容器非持久，Sandbox 数据库路径务必放到持久卷。**
 
 ### Sandbox 数据布局与持久化
 
@@ -270,4 +279,4 @@ eve 当前是 beta,使用受 [Vercel Beta 条款](https://vercel.com/docs/releas
 - 配置审批策略、工具限制、连接权限、路由/会话鉴权、沙箱控制、遥测导出等
 - 在使用非公开、敏感、监管或生产数据前评估默认工具和自定义工具的风险
 
-HF Space 容器**非持久**——重启后 `.eve/sandbox-cache` 与本地 AgentFS 路径会丢。workflow 会话状态已改走 Supabase Postgres（`WORKFLOW_POSTGRES_URL`），不依赖容器内 `.workflow-data/`；免费 `cpu-basic` 档 48 小时无活动会 sleep,下次访问自动唤醒。
+HF Space 容器**非持久**——重启后 `.eve/sandbox-cache` 与本地 AgentFS 路径会丢。镜像默认 `WORKFLOW_WORLD=postgres` 时，workflow 会话状态在 Supabase（`WORKFLOW_POSTGRES_URL`），不依赖容器内 `.workflow-data/`；若改回 `local` 则须挂持久卷。免费 `cpu-basic` 档 48 小时无活动会 sleep,下次访问自动唤醒。

agent/agent.ts

@@ -16,21 +16,48 @@ function requiredEnv(name: string): string {
   return value;
 }
 
+/**
+ * WORKFLOW_WORLD=local | postgres
+ * - local：eve 默认 @workflow/world-local → .workflow-data/（本机调试默认，与云端隔离）
+ * - postgres：@workflow/world-postgres，需 WORKFLOW_POSTGRES_URL（HF / 生产）
+ */
+function resolveWorkflowWorld(): string | undefined {
+  const raw = process.env.WORKFLOW_WORLD?.trim().toLowerCase();
+  const mode = raw || "local";
+
+  if (mode === "local" || mode === "world-local") {
+    return undefined;
+  }
+  if (mode === "postgres" || mode === "world-postgres") {
+    requiredEnv("WORKFLOW_POSTGRES_URL");
+    return "@workflow/world-postgres";
+  }
+  throw new Error(
+    `WORKFLOW_WORLD 无效: "${mode}"（允许 local | postgres）`,
+  );
+}
+
 const customProvider = createOpenAICompatible({
   name: "custom",
   baseURL: requiredEnv("CUSTOM_BASE_URL"),
   apiKey: process.env.CUSTOM_API_KEY,
 });
 
+const workflowWorld = resolveWorkflowWorld();
+
 export default defineAgent({
   model: customProvider(requiredEnv("CUSTOM_MODEL")),
   modelContextWindowTokens: 400000,
-  // 自托管：会话/run 状态进 Postgres（Supabase），不再用默认 .workflow-data
-  experimental: {
-    workflow: {
-      world: "@workflow/world-postgres",
-    },
-  },
+  // 按 WORKFLOW_WORLD 选择状态后端；local 时不设 experimental.workflow（eve 默认磁盘 world）
+  ...(workflowWorld
+    ? {
+        experimental: {
+          workflow: {
+            world: workflowWorld,
+          },
+        },
+      }
+    : {}),
   // 带 native / 动态 require 的包禁止打进 Nitro _libs，否则运行时找不到 .node
   // （典型：@tursodatabase/database → turso.linux-x64-gnu.node）
   build: {
@@ -43,4 +70,3 @@ export default defineAgent({
     ],
   },
 });
-

agent/channels/agentfs.ts

@@ -1,220 +1,198 @@
 /**
  * AgentFS API（前端 / 调试静态页对接）。
  *
- * 路由：
- * - GET    /agentfs/api/sessions
- * - GET    /agentfs/api/sessions/:id/tree?path=
- * - GET    /agentfs/api/sessions/:id/file?path=
- * - GET    /agentfs/api/sessions/:id/checkpoints
- * - POST   /agentfs/api/sessions/:id/checkpoint          body: { name }
- * - POST   /agentfs/api/sessions/:id/restore             body: { checkpoint }
- * - DELETE /agentfs/api/sessions/:id/checkpoint           body: { name }
+ * 读接口（始终注册，需 serviceAuth）：
+ * - GET  /agentfs/api/sessions
+ * - GET  /agentfs/api/sessions/:id/tree?path=
+ * - GET  /agentfs/api/sessions/:id/file?path=
+ * - GET  /agentfs/api/sessions/:id/checkpoints
+ *
+ * 写接口（仅当 AGENTFS_ENABLE_WRITES=1|true|yes 时注册）：
+ * - POST   /agentfs/api/sessions/:id/checkpoint   body: { name }
+ * - POST   /agentfs/api/sessions/:id/restore      body: { checkpoint }
+ * - DELETE /agentfs/api/sessions/:id/checkpoint   body: { name }
  *
  * 鉴权与 /eve 一致：Bearer AGENT_API_KEY，本机回环可走 localDev。
+ * 响应不回传宿主机绝对路径，避免信息泄露。
  * 无内嵌 HTML；本地浏览器见仓库根 `tools/agentfs-browser/index.html`。
  */
 
-import { defineChannel, GET, POST, DELETE } from "eve/channels";
+import { defineChannel, DELETE, GET, POST } from "eve/channels";
 import { routeAuth } from "eve/channels/auth";
 
 import { serviceAuthChain } from "../lib/api-key-auth.js";
 import {
+  createCheckpoint,
+  deleteCheckpoint,
   jsonError,
+  listCheckpoints,
   listSessionDbs,
   listTree,
   readFilePreview,
-  resolveDataDir,
-  resolveSessionsDir,
-  createCheckpoint,
-  listCheckpoints,
   restoreCheckpoint,
-  deleteCheckpoint,
-  type SessionDbInfo,
 } from "../lib/agentfs-debug.js";
 
 const auth = serviceAuthChain();
 
-async function requireAuth(req: Request): Promise<Response | null> {
-  const result = await routeAuth(req, auth);
-  if (result instanceof Response) return result;
-  return null;
+/** checkpoint 写面：必须显式 opt-in，公网默认不暴露。 */
+function checkpointWritesEnabled(): boolean {
+  const v = process.env.AGENTFS_ENABLE_WRITES?.trim().toLowerCase();
+  return v === "1" || v === "true" || v === "yes";
 }
 
-async function sessionIdFromParams(
-  args: { params: Readonly<Record<string, string>> },
-): Promise<string | Response> {
-  const id = args.params.id;
-  if (!id) {
-    return Response.json(
-      { ok: false, error: { code: "missing_id", message: "缺少 session id" } },
-      { status: 400 },
-    );
-  }
-  return id;
+type RouteArgs = { params: Readonly<Record<string, string>> };
+type RouteHandler = (req: Request, args: RouteArgs) => Promise<Response>;
+
+/** 鉴权 → 业务；统一把领域错误转 JSON。 */
+function withAuth(handler: RouteHandler): RouteHandler {
+  return async (req, args) => {
+    const result = await routeAuth(req, auth);
+    if (result instanceof Response) return result;
+    try {
+      return await handler(req, args);
+    } catch (err) {
+      return jsonError(err);
+    }
+  };
 }
 
-async function handleSessions(req: Request): Promise<Response> {
-  const denied = await requireAuth(req);
-  if (denied) return denied;
-  try {
-    const sessions = await listSessionDbs();
-    return Response.json({
-      ok: true,
-      dataDir: resolveDataDir(),
-      sessionsDir: resolveSessionsDir(),
-      sessions: sessions.map((s: SessionDbInfo) => ({
-        id: s.id,
-        sizeBytes: s.sizeBytes,
-        mtimeMs: s.mtimeMs,
-      })),
-    });
-  } catch (err) {
-    return jsonError(err);
-  }
+function badRequest(code: string, message: string): Response {
+  return Response.json({ ok: false, error: { code, message } }, { status: 400 });
 }
 
-async function handleTree(
-  req: Request,
-  args: { params: Readonly<Record<string, string>> },
-): Promise<Response> {
-  const denied = await requireAuth(req);
-  if (denied) return denied;
-  const id = await sessionIdFromParams(args);
-  if (id instanceof Response) return id;
-  try {
-    const url = new URL(req.url);
-    const path = url.searchParams.get("path");
-    const result = await listTree(id, path);
-    return Response.json({ ok: true, ...result });
-  } catch (err) {
-    return jsonError(err);
-  }
+function sessionIdFromParams(args: RouteArgs): string | Response {
+  const id = args.params.id;
+  if (!id) return badRequest("missing_id", "缺少 session id");
+  return id;
 }
 
-async function handleFile(
+/** 从 JSON body 取非空字符串字段；非法 body 视为空对象。 */
+async function requiredBodyString(
   req: Request,
-  args: { params: Readonly<Record<string, string>> },
-): Promise<Response> {
-  const denied = await requireAuth(req);
-  if (denied) return denied;
-  const id = await sessionIdFromParams(args);
-  if (id instanceof Response) return id;
-  try {
-    const url = new URL(req.url);
-    const path = url.searchParams.get("path");
-    if (!path) {
-      return Response.json(
-        { ok: false, error: { code: "missing_path", message: "缺少 path 查询参数" } },
-        { status: 400 },
-      );
-    }
-    const preview = await readFilePreview(id, path);
-    return Response.json({ ok: true, ...preview });
-  } catch (err) {
-    return jsonError(err);
+  field: string,
+  missingCode: string,
+  missingMessage: string,
+): Promise<string | Response> {
+  const body = (await req.json().catch(() => ({}))) as Record<string, unknown>;
+  const value = body[field];
+  if (typeof value !== "string" || value.length === 0) {
+    return badRequest(missingCode, missingMessage);
   }
+  return value;
 }
 
-// ─── Checkpoint ──────────────────────────────────────────────────────
+// ─── 读 ──────────────────────────────────────────────────────────────
 
-async function handleCreateCheckpoint(
-  req: Request,
-  args: { params: Readonly<Record<string, string>> },
-): Promise<Response> {
-  const denied = await requireAuth(req);
-  if (denied) return denied;
-  const id = await sessionIdFromParams(args);
+const handleSessions = withAuth(async (_req, _args) => {
+  const sessions = await listSessionDbs();
+  return Response.json({
+    ok: true,
+    writesEnabled: checkpointWritesEnabled(),
+    sessions: sessions.map((s) => ({
+      id: s.id,
+      sizeBytes: s.sizeBytes,
+      mtimeMs: s.mtimeMs,
+    })),
+  });
+});
+
+const handleTree = withAuth(async (req: Request, args: RouteArgs) => {
+  const id = sessionIdFromParams(args);
   if (id instanceof Response) return id;
-  try {
-    const body: { name?: string } = await req.json().catch(() => ({}));
-    if (!body.name || typeof body.name !== "string" || body.name.length === 0) {
-      return Response.json(
-        { ok: false, error: { code: "missing_name", message: "缺少 name 字段" } },
-        { status: 400 },
-      );
-    }
-    const info = await createCheckpoint(id, body.name);
-    return Response.json({ ok: true, checkpoint: info }, { status: 201 });
-  } catch (err) {
-    return jsonError(err);
-  }
-}
+  const path = new URL(req.url).searchParams.get("path");
+  const result = await listTree(id, path);
+  return Response.json({ ok: true, ...result });
+});
 
-async function handleListCheckpoints(
-  req: Request,
-  args: { params: Readonly<Record<string, string>> },
-): Promise<Response> {
-  const denied = await requireAuth(req);
-  if (denied) return denied;
-  const id = await sessionIdFromParams(args);
+const handleFile = withAuth(async (req: Request, args: RouteArgs) => {
+  const id = sessionIdFromParams(args);
   if (id instanceof Response) return id;
-  try {
+  const path = new URL(req.url).searchParams.get("path");
+  if (!path) return badRequest("missing_path", "缺少 path 查询参数");
+  const preview = await readFilePreview(id, path);
+  return Response.json({ ok: true, ...preview });
+});
+
+const handleListCheckpoints = withAuth(
+  async (_req: Request, args: RouteArgs) => {
+    const id = sessionIdFromParams(args);
+    if (id instanceof Response) return id;
     const checkpoints = await listCheckpoints(id);
     return Response.json({ ok: true, checkpoints });
-  } catch (err) {
-    return jsonError(err);
-  }
-}
+  },
+);
 
-async function handleRestoreCheckpoint(
-  req: Request,
-  args: { params: Readonly<Record<string, string>> },
-): Promise<Response> {
-  const denied = await requireAuth(req);
-  if (denied) return denied;
-  const id = await sessionIdFromParams(args);
-  if (id instanceof Response) return id;
-  try {
-    const body: { checkpoint?: string } = await req.json().catch(() => ({}));
-    if (!body.checkpoint || typeof body.checkpoint !== "string" || body.checkpoint.length === 0) {
-      return Response.json(
-        { ok: false, error: { code: "missing_checkpoint", message: "缺少 checkpoint 字段" } },
-        { status: 400 },
-      );
-    }
-    const result = await restoreCheckpoint(id, body.checkpoint);
+// ─── 写（仅 opt-in 时挂到 routes） ───────────────────────────────────
+
+const handleCreateCheckpoint = withAuth(
+  async (req: Request, args: RouteArgs) => {
+    const id = sessionIdFromParams(args);
+    if (id instanceof Response) return id;
+    const name = await requiredBodyString(
+      req,
+      "name",
+      "missing_name",
+      "缺少 name 字段",
+    );
+    if (name instanceof Response) return name;
+    const info = await createCheckpoint(id, name);
+    return Response.json({ ok: true, checkpoint: info }, { status: 201 });
+  },
+);
+
+const handleRestoreCheckpoint = withAuth(
+  async (req: Request, args: RouteArgs) => {
+    const id = sessionIdFromParams(args);
+    if (id instanceof Response) return id;
+    const checkpoint = await requiredBodyString(
+      req,
+      "checkpoint",
+      "missing_checkpoint",
+      "缺少 checkpoint 字段",
+    );
+    if (checkpoint instanceof Response) return checkpoint;
+    const result = await restoreCheckpoint(id, checkpoint);
     return Response.json({ ok: true, ...result });
-  } catch (err) {
-    return jsonError(err);
-  }
-}
+  },
+);
 
-async function handleDeleteCheckpoint(
-  req: Request,
-  args: { params: Readonly<Record<string, string>> },
-): Promise<Response> {
-  const denied = await requireAuth(req);
-  if (denied) return denied;
-  const id = await sessionIdFromParams(args);
-  if (id instanceof Response) return id;
-  try {
-    const body: { name?: string } = await req.json().catch(() => ({}));
-    if (!body.name || typeof body.name !== "string" || body.name.length === 0) {
-      return Response.json(
-        { ok: false, error: { code: "missing_name", message: "缺少 name 字段" } },
-        { status: 400 },
-      );
-    }
-    await deleteCheckpoint(id, body.name);
+const handleDeleteCheckpoint = withAuth(
+  async (req: Request, args: RouteArgs) => {
+    const id = sessionIdFromParams(args);
+    if (id instanceof Response) return id;
+    const name = await requiredBodyString(
+      req,
+      "name",
+      "missing_name",
+      "缺少 name 字段",
+    );
+    if (name instanceof Response) return name;
+    await deleteCheckpoint(id, name);
     return Response.json({ ok: true });
-  } catch (err) {
-    return jsonError(err);
-  }
-}
+  },
+);
+
+const readRoutes = [
+  GET("/agentfs/api/sessions", handleSessions),
+  GET("/agentfs/api/sessions/:id/tree", handleTree),
+  GET("/agentfs/api/sessions/:id/file", handleFile),
+  GET("/agentfs/api/sessions/:id/checkpoints", handleListCheckpoints),
+] as const;
+
+const writeRoutes = checkpointWritesEnabled()
+  ? ([
+      POST("/agentfs/api/sessions/:id/checkpoint", handleCreateCheckpoint),
+      POST("/agentfs/api/sessions/:id/restore", handleRestoreCheckpoint),
+      DELETE("/agentfs/api/sessions/:id/checkpoint", handleDeleteCheckpoint),
+    ] as const)
+  : [];
 
 export default defineChannel({
+  // 调试页常跨源（file:// / 其它端口）；生产请按域名收紧 origin
   cors: {
     origin: "*",
     methods: ["GET", "POST", "DELETE", "OPTIONS"],
     allowHeaders: ["Authorization", "Content-Type"],
   },
-  routes: [
-    GET("/agentfs/api/sessions", handleSessions),
-    GET("/agentfs/api/sessions/:id/tree", handleTree),
-    GET("/agentfs/api/sessions/:id/file", handleFile),
-    GET("/agentfs/api/sessions/:id/checkpoints", handleListCheckpoints),
-    POST("/agentfs/api/sessions/:id/checkpoint", handleCreateCheckpoint),
-    POST("/agentfs/api/sessions/:id/restore", handleRestoreCheckpoint),
-    DELETE("/agentfs/api/sessions/:id/checkpoint", handleDeleteCheckpoint),
-  ],
+  routes: [...readRoutes, ...writeRoutes],
 });

agent/connections/message.ts

@@ -1,7 +1,37 @@
+/**
+ * 扩展工具中心 MCP 连接。
+ *
+ * URL / 可选 Bearer 一律从环境变量读取，禁止把部署专用端点写死在源码里。
+ * - MESSAGE_MCP_URL   必填（Streamable HTTP / SSE），末尾建议带 `/`
+ * - MESSAGE_MCP_TOKEN 可选；有值时以 Authorization: Bearer 调用上游
+ *
+ * 默认 HF 部署端点见 `.env.example` / PROJECT_RULES（不是 `/spaces/.../mcp`）。
+ */
+
 import { defineMcpClientConnection } from "eve/connections";
 
+/** 规范化 MCP URL：去空白；无尾斜杠时补 `/`（HF Space 路径约定）。 */
+function resolveMessageMcpUrl(): string {
+  const raw = process.env.MESSAGE_MCP_URL?.trim();
+  if (!raw) {
+    throw new Error(
+      "MESSAGE_MCP_URL is required（写入 .env 或部署 Secrets；示例见 .env.example）",
+    );
+  }
+  return raw.endsWith("/") ? raw : `${raw}/`;
+}
+
+const messageMcpToken = process.env.MESSAGE_MCP_TOKEN?.trim() ?? "";
+
 export default defineMcpClientConnection({
-  // HF Space 直连端点（/spaces/.../mcp 会 404；与 PROJECT_RULES 一致）
-  url: "https://hunian003-message.hf.space/mcp",
-  description: "Message 功能中心：浏览器自动化（导航、点击、填表、截图）、沙盒文件操作与命令执行、图片 OCR 文字识别、音频转文字、小红书/微博内容提取。",
+  url: resolveMessageMcpUrl(),
+  description:
+    "扩展工具中心：浏览器自动化（导航、点击、填表、截图）、沙盒文件操作与命令执行、图片 OCR 文字识别、音频转文字、小红书/微博内容提取。",
+  ...(messageMcpToken.length > 0
+    ? {
+        auth: {
+          getToken: async () => ({ token: messageMcpToken }),
+        },
+      }
+    : {}),
 });

agent/lib/agentfs-debug.ts

@@ -1,511 +1,58 @@
 /**
- * AgentFS 调试与存档：列出 session 库、浏览目录、读取文件预览，
- * 以及 session 文件系统存档点（checkpoint 创建 / 列表 / 回退 / 删除）。
- * 供 agentfs channel 与外部前端对接。写操作仅限 checkpoint API。
+ * AgentFS 调试与存档公开 API。
+ *
+ * 实现拆在 `lib/agentfs-debug/`：
+ * - browse：只读树 / 文件预览
+ * - checkpoint：存档创建 / 列表 / 回退 / 删除
+ * - sessions：磁盘 session 库列表
+ *
+ * 供 `channels/agentfs.ts` 与外部前端对接。写操作仅限 checkpoint API。
  */
 
-import { readdir, stat, mkdir, rm } from "node:fs/promises";
-import { basename, dirname, join, resolve } from "node:path";
-
-import { AgentFS } from "agentfs-sdk";
-import type { FileSystem } from "agentfs-sdk";
-
-/** 与 sandbox.ts 一致的后端名与数据布局。 */
-export const AGENTFS_BACKEND_NAME = "agentfs-just-bash";
-
-/** 单文件预览上限（字节），超出只返回 meta + 截断提示。 */
-export const AGENTFS_DEBUG_MAX_FILE_BYTES = 256 * 1024;
-
-/** 存档点名允许字符（中文 + 字母数字 + 部分符号）。 */
-export const CHECKPOINT_NAME_RE = /^[a-zA-Z0-9._\-\u4e00-\u9fff]{1,100}$/;
-
-/** sessionKey 文件名允许的字符（与 eve sanitizeRuntimeSandboxKey 对齐并略放宽）。 */
-const SESSION_ID_RE = /^[a-zA-Z0-9._-]{1,200}$/;
-
-export type SessionDbInfo = {
-  id: string;
-  dbPath: string;
-  sizeBytes: number;
-  mtimeMs: number;
-};
-
-export type TreeEntry = {
-  name: string;
-  path: string;
-  type: "file" | "directory" | "symlink" | "other";
-  size: number;
-  mtime: number;
-};
-
-export type FilePreview = {
-  path: string;
-  size: number;
-  mtime: number;
-  encoding: "utf-8" | "binary";
-  truncated: boolean;
-  content: string;
-  byteLength: number;
-};
-
-/** 数据目录根：EVEAGENT_DATA_DIR 优先，否则 <cwd>/data。 */
-export function resolveDataDir(): string {
-  const fromEnv = process.env.EVEAGENT_DATA_DIR?.trim();
-  if (fromEnv) return resolve(fromEnv);
-  return resolve(process.cwd(), "data");
-}
-
-/** sessions 目录绝对路径。 */
-export function resolveSessionsDir(): string {
-  return join(resolveDataDir(), "agentfs", AGENTFS_BACKEND_NAME, "sessions");
-}
-
-/** 校验 session id，防止路径穿越。 */
-export function assertSessionId(id: string): string {
-  if (!SESSION_ID_RE.test(id)) {
-    throw new AgentFsDebugError(400, "invalid_session_id", "session id 非法");
-  }
-  return id;
-}
-
-/**
- * 解析虚拟 FS 路径：必须为绝对路径、无 `..`、无空字节。
- * 空或 `/` → `/`。
- */
-export function normalizeVirtualPath(raw: string | null | undefined): string {
-  const input = (raw ?? "/").trim() || "/";
-  if (input.includes("\0")) {
-    throw new AgentFsDebugError(400, "invalid_path", "路径含非法字符");
-  }
-  const withSlash = input.startsWith("/") ? input : `/${input}`;
-  const parts = withSlash.split("/").filter((p) => p.length > 0);
-  const out: string[] = [];
-  for (const part of parts) {
-    if (part === ".") continue;
-    if (part === "..") {
-      throw new AgentFsDebugError(400, "invalid_path", "路径不允许包含 ..");
-    }
-    out.push(part);
-  }
-  return out.length === 0 ? "/" : `/${out.join("/")}`;
-}
-
-/** 将 session id 解析为磁盘上的 .db 绝对路径（id 已禁止路径分隔符）。 */
-export function resolveSessionDbPath(sessionId: string): string {
-  const id = assertSessionId(sessionId);
-  const sessionsDir = resolveSessionsDir();
-  const dbPath = resolve(join(sessionsDir, `${id}.db`));
-  if (basename(dbPath) !== `${id}.db`) {
-    throw new AgentFsDebugError(400, "invalid_session_id", "session 路径越界");
-  }
-  return dbPath;
-}
-
-/** 列出 sessions 目录下的 *.db（忽略 -wal/-shm）。 */
-export async function listSessionDbs(): Promise<SessionDbInfo[]> {
-  const sessionsDir = resolveSessionsDir();
-  let names: string[];
-  try {
-    names = await readdir(sessionsDir);
-  } catch (err) {
-    const code = (err as NodeJS.ErrnoException).code;
-    if (code === "ENOENT") return [];
-    throw err;
-  }
-
-  const out: SessionDbInfo[] = [];
-  for (const name of names) {
-    if (!name.endsWith(".db")) continue;
-    if (name.endsWith(".db-wal") || name.endsWith(".db-shm")) continue;
-    const id = name.slice(0, -".db".length);
-    if (!SESSION_ID_RE.test(id)) continue;
-    const dbPath = join(sessionsDir, name);
-    try {
-      const st = await stat(dbPath);
-      if (!st.isFile()) continue;
-      out.push({
-        id,
-        dbPath,
-        sizeBytes: st.size,
-        mtimeMs: st.mtimeMs,
-      });
-    } catch {
-      // 单文件 stat 失败则跳过
-    }
-  }
-  out.sort((a, b) => b.mtimeMs - a.mtimeMs);
-  return out;
-}
-
-/** 打开 AgentFS，执行只读回调后关闭。 */
-export async function withAgentFs<T>(
-  sessionId: string,
-  fn: (agent: Awaited<ReturnType<typeof AgentFS.open>>) => Promise<T>,
-): Promise<T> {
-  const dbPath = resolveSessionDbPath(sessionId);
-  try {
-    await stat(dbPath);
-  } catch (err) {
-    const code = (err as NodeJS.ErrnoException).code;
-    if (code === "ENOENT") {
-      throw new AgentFsDebugError(404, "session_not_found", `session 不存在: ${sessionId}`);
-    }
-    throw err;
-  }
-
-  let agent: Awaited<ReturnType<typeof AgentFS.open>>;
-  try {
-    agent = await AgentFS.open({ path: dbPath });
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    throw new AgentFsDebugError(
-      503,
-      "open_failed",
-      `无法打开 AgentFS（库可能被占用）: ${message}`,
-    );
-  }
-
-  try {
-    return await fn(agent);
-  } finally {
-    try {
-      await agent.close();
-    } catch {
-      // 关闭失败不影响主结果
-    }
-  }
-}
-
-/** 列目录（readdirPlus）。 */
-export async function listTree(
-  sessionId: string,
-  pathRaw: string | null | undefined,
-): Promise<{ path: string; entries: TreeEntry[] }> {
-  const path = normalizeVirtualPath(pathRaw);
-  return withAgentFs(sessionId, async (agent) => {
-    let entries;
-    try {
-      entries = await agent.fs.readdirPlus(path);
-    } catch (err) {
-      throw mapFsError(err, path);
-    }
-    const mapped: TreeEntry[] = entries.map((e) => {
-      const childPath = path === "/" ? `/${e.name}` : `${path}/${e.name}`;
-      let type: TreeEntry["type"] = "other";
-      if (e.stats.isDirectory()) type = "directory";
-      else if (e.stats.isFile()) type = "file";
-      else if (e.stats.isSymbolicLink()) type = "symlink";
-      return {
-        name: e.name,
-        path: childPath,
-        type,
-        size: e.stats.size,
-        mtime: e.stats.mtime,
-      };
-    });
-    mapped.sort((a, b) => {
-      if (a.type === "directory" && b.type !== "directory") return -1;
-      if (a.type !== "directory" && b.type === "directory") return 1;
-      return a.name.localeCompare(b.name);
-    });
-    return { path, entries: mapped };
-  });
-}
-
-/** 读文件预览（限大小）。 */
-export async function readFilePreview(
-  sessionId: string,
-  pathRaw: string | null | undefined,
-): Promise<FilePreview> {
-  const path = normalizeVirtualPath(pathRaw);
-  if (path === "/") {
-    throw new AgentFsDebugError(400, "is_directory", "不能读取根目录为文件");
-  }
-
-  return withAgentFs(sessionId, async (agent) => {
-    let st;
-    try {
-      st = await agent.fs.stat(path);
-    } catch (err) {
-      throw mapFsError(err, path);
-    }
-    if (st.isDirectory()) {
-      throw new AgentFsDebugError(400, "is_directory", "路径是目录，请用 tree 接口");
-    }
-
-    let buf: Buffer;
-    try {
-      buf = await agent.fs.readFile(path);
-    } catch (err) {
-      throw mapFsError(err, path);
-    }
-
-    const truncated = buf.length > AGENTFS_DEBUG_MAX_FILE_BYTES;
-    const slice = truncated ? buf.subarray(0, AGENTFS_DEBUG_MAX_FILE_BYTES) : buf;
-    const encoding = looksLikeText(slice) ? "utf-8" : "binary";
-    const content =
-      encoding === "utf-8"
-        ? slice.toString("utf-8")
-        : slice.toString("base64");
-
-    return {
-      path,
-      size: st.size,
-      mtime: st.mtime,
-      encoding,
-      truncated,
-      content,
-      byteLength: slice.length,
-    };
-  });
-}
-
-function looksLikeText(buf: Buffer): boolean {
-  if (buf.length === 0) return true;
-  let suspicious = 0;
-  const sample = Math.min(buf.length, 4096);
-  for (let i = 0; i < sample; i++) {
-    const c = buf[i]!;
-    if (c === 0) return false;
-    // 允许常见控制符：tab/lf/cr
-    if (c < 32 && c !== 9 && c !== 10 && c !== 13) suspicious++;
-  }
-  return suspicious / sample < 0.05;
-}
-
-function mapFsError(err: unknown, path: string): AgentFsDebugError {
-  const code = (err as NodeJS.ErrnoException)?.code;
-  if (code === "ENOENT") {
-    return new AgentFsDebugError(404, "not_found", `路径不存在: ${path}`);
-  }
-  if (code === "ENOTDIR") {
-    return new AgentFsDebugError(400, "not_directory", `不是目录: ${path}`);
-  }
-  if (code === "EISDIR") {
-    return new AgentFsDebugError(400, "is_directory", `是目录: ${path}`);
-  }
-  const message = err instanceof Error ? err.message : String(err);
-  return new AgentFsDebugError(500, "fs_error", message);
-}
-
-export class AgentFsDebugError extends Error {
-  readonly status: number;
-  readonly code: string;
-
-  constructor(status: number, code: string, message: string) {
-    super(message);
-    this.name = "AgentFsDebugError";
-    this.status = status;
-    this.code = code;
-  }
-}
-
-export function jsonError(err: unknown): Response {
-  if (err instanceof AgentFsDebugError) {
-    return Response.json(
-      { ok: false, error: { code: err.code, message: err.message } },
-      { status: err.status },
-    );
-  }
-  const message = err instanceof Error ? err.message : String(err);
-  return Response.json(
-    { ok: false, error: { code: "internal", message } },
-    { status: 500 },
-  );
-}
-
-// ─── Checkpoint 辅助函数 ────────────────────────────────────────────
-
-/** checkpoints 目录：<sessionsDir>/checkpoints/<sessionId>/ */
-export function resolveCheckpointsDir(sessionId: string): string {
-  return join(resolveSessionsDir(), "checkpoints", assertSessionId(sessionId));
-}
-
-/** 单个存档点 .db 文件路径。 */
-export function resolveCheckpointDbPath(sessionId: string, name: string): string {
-  if (!CHECKPOINT_NAME_RE.test(name)) {
-    throw new AgentFsDebugError(400, "invalid_checkpoint_name", "存档点名非法（允许中文、字母、数字、._-）");
-  }
-  return join(resolveCheckpointsDir(sessionId), `${name}.db`);
-}
-
-/** 递归复制 src 的 dirPath 下所有文件/目录到 dest。 */
-export async function recursiveCopyFs(
-  src: FileSystem,
-  dest: FileSystem,
-  dirPath: string,
-): Promise<void> {
-  const entries = await src.readdirPlus(dirPath);
-  for (const entry of entries) {
-    const child = dirPath === "/" ? `/${entry.name}` : `${dirPath}/${entry.name}`;
-    if (entry.stats.isDirectory()) {
-      try {
-        await dest.mkdir(child);
-      } catch {
-        // 已存在则忽略
-      }
-      await recursiveCopyFs(src, dest, child);
-    } else if (entry.stats.isFile()) {
-      const content = await src.readFile(child);
-      await dest.writeFile(child, content);
-    }
-    // symlink 和其他类型跳过
-  }
-}
-
-export type CheckpointInfo = {
-  name: string;
-  sizeBytes: number;
-  mtimeMs: number;
-};
-
-/** 确认 session .db 已存在，避免 AgentFS.open 对缺失路径静默建空库。 */
-async function assertSessionDbExists(sessionId: string): Promise<string> {
-  const sessionDb = resolveSessionDbPath(sessionId);
-  try {
-    await stat(sessionDb);
-  } catch (err) {
-    const code = (err as NodeJS.ErrnoException).code;
-    if (code === "ENOENT") {
-      throw new AgentFsDebugError(404, "session_not_found", `session 不存在: ${sessionId}`);
-    }
-    throw err;
-  }
-  return sessionDb;
-}
-
-/** 创建存档点：把 session 当前文件状态快照到一个独立 .db。 */
-export async function createCheckpoint(
-  sessionId: string,
-  name: string,
-): Promise<CheckpointInfo> {
-  // 必须先确认 session 存在：AgentFS.open 会对缺失 path 创建空库
-  const sessionDb = await assertSessionDbExists(sessionId);
-  const cpDb = resolveCheckpointDbPath(sessionId, name);
-  await mkdir(dirname(cpDb), { recursive: true });
-
-  let sessionAgent: Awaited<ReturnType<typeof AgentFS.open>>;
-  try {
-    sessionAgent = await AgentFS.open({ path: sessionDb });
-  } catch (err) {
-    throw mapAgentFsOpenError(err, sessionId);
-  }
-  let cpAgent: Awaited<ReturnType<typeof AgentFS.open>> | null = null;
-  try {
-    cpAgent = await AgentFS.open({ path: cpDb });
-    await recursiveCopyFs(sessionAgent.fs, cpAgent.fs, "/");
-  } finally {
-    try { await sessionAgent.close(); } catch { /* ignore */ }
-    if (cpAgent) { try { await cpAgent.close(); } catch { /* ignore */ } }
-  }
-
-  const st = await stat(cpDb);
-  return { name, sizeBytes: st.size, mtimeMs: st.mtimeMs };
-}
-
-/** 列出 session 的所有存档点。 */
-export async function listCheckpoints(sessionId: string): Promise<CheckpointInfo[]> {
-  const dir = resolveCheckpointsDir(sessionId);
-  let names: string[];
-  try {
-    names = await readdir(dir);
-  } catch (err) {
-    const code = (err as NodeJS.ErrnoException).code;
-    if (code === "ENOENT") return [];
-    throw err;
-  }
-
-  const out: CheckpointInfo[] = [];
-  for (const name of names) {
-    if (!name.endsWith(".db")) continue;
-    const label = name.slice(0, -".db".length);
-    if (!CHECKPOINT_NAME_RE.test(label)) continue;
-    const fullPath = join(dir, name);
-    try {
-      const st = await stat(fullPath);
-      if (!st.isFile()) continue;
-      out.push({ name: label, sizeBytes: st.size, mtimeMs: st.mtimeMs });
-    } catch { /* 单文件失败跳过 */ }
-  }
-  out.sort((a, b) => b.mtimeMs - a.mtimeMs);
-  return out;
-}
-
-/** 回退 session 到某个存档点：用存档点文件覆盖 session 文件。 */
-export async function restoreCheckpoint(
-  sessionId: string,
-  name: string,
-): Promise<{ restored: number }> {
-  const cpDb = resolveCheckpointDbPath(sessionId, name);
-  try {
-    await stat(cpDb);
-  } catch (err) {
-    const code = (err as NodeJS.ErrnoException).code;
-    if (code === "ENOENT") {
-      throw new AgentFsDebugError(404, "checkpoint_not_found", `存档点不存在: ${name}`);
-    }
-    throw err;
-  }
-
-  // session 必须已存在；禁止 open 时静默新建空库再写入
-  const sessionDb = await assertSessionDbExists(sessionId);
-  let cpAgent: Awaited<ReturnType<typeof AgentFS.open>>;
-  let sessionAgent: Awaited<ReturnType<typeof AgentFS.open>>;
-  try {
-    cpAgent = await AgentFS.open({ path: cpDb });
-  } catch (err) {
-    throw mapAgentFsOpenError(err, `checkpoint:${name}`);
-  }
-  try {
-    sessionAgent = await AgentFS.open({ path: sessionDb });
-  } catch (err) {
-    try { await cpAgent.close(); } catch { /* ignore */ }
-    throw mapAgentFsOpenError(err, sessionId);
-  }
-
-  try {
-    // 清空 session 根目录下所有内容，再从存档点完整复制
-    const rootEntries = await sessionAgent.fs.readdirPlus("/");
-    for (const e of rootEntries) {
-      const child = `/${e.name}`;
-      try {
-        await sessionAgent.fs.rm(child, { recursive: true, force: true });
-      } catch {
-        // 单个文件/目录删除失败不阻塞整体回退
-      }
-    }
-    await recursiveCopyFs(cpAgent.fs, sessionAgent.fs, "/");
-    return { restored: 1 };
-  } finally {
-    try { await sessionAgent.close(); } catch { /* ignore */ }
-    try { await cpAgent.close(); } catch { /* ignore */ }
-  }
-}
-
-/** 删除单个存档点。 */
-export async function deleteCheckpoint(
-  sessionId: string,
-  name: string,
-): Promise<void> {
-  const cpDb = resolveCheckpointDbPath(sessionId, name);
-  // force:false 才能在缺失时抛 ENOENT → 404（force:true 会静默成功）
-  try {
-    await rm(cpDb, { force: false });
-  } catch (err) {
-    const code = (err as NodeJS.ErrnoException).code;
-    if (code === "ENOENT") {
-      throw new AgentFsDebugError(404, "checkpoint_not_found", `存档点不存在: ${name}`);
-    }
-    throw err;
-  }
-}
-
-function mapAgentFsOpenError(err: unknown, label: string): AgentFsDebugError {
-  const message = err instanceof Error ? err.message : String(err);
-  return new AgentFsDebugError(
-    503,
-    "open_failed",
-    `无法打开 AgentFS（${label}）: ${message}`,
-  );
-}
-
-
+export {
+  AGENTFS_DEBUG_MAX_FILE_BYTES,
+  CHECKPOINT_NAME_RE,
+} from "./agentfs-debug/constants.js";
+
+export {
+  AgentFsDebugError,
+  jsonError,
+  mapAgentFsOpenError,
+  mapFsError,
+} from "./agentfs-debug/errors.js";
+
+export {
+  AGENTFS_BACKEND_NAME,
+  assertSessionId,
+  normalizeVirtualPath,
+  resolveCheckpointDbPath,
+  resolveCheckpointsDir,
+  resolveDataDir,
+  resolveSessionDbPath,
+  resolveSessionsDir,
+} from "./agentfs-debug/paths.js";
+
+export {
+  assertSessionDbExists,
+  withAgentFs,
+  withAgentFsAtPath,
+} from "./agentfs-debug/open.js";
+
+export { listSessionDbs } from "./agentfs-debug/sessions.js";
+
+export { listTree, readFilePreview } from "./agentfs-debug/browse.js";
+
+export {
+  createCheckpoint,
+  deleteCheckpoint,
+  listCheckpoints,
+  recursiveCopyFs,
+  restoreCheckpoint,
+} from "./agentfs-debug/checkpoint.js";
+
+export type {
+  CheckpointInfo,
+  FilePreview,
+  SessionDbInfo,
+  TreeEntry,
+} from "./agentfs-debug/types.js";

agent/lib/agentfs-debug/browse.ts

@@ -0,0 +1,110 @@
+/**
+ * 只读浏览：列目录、读文件预览。
+ */
+
+import { AGENTFS_DEBUG_MAX_FILE_BYTES } from "./constants.js";
+import { AgentFsDebugError, mapFsError } from "./errors.js";
+import { withAgentFs } from "./open.js";
+import { joinVirtualPath, normalizeVirtualPath } from "./paths.js";
+import type { FilePreview, TreeEntry } from "./types.js";
+
+/** 列目录（readdirPlus）。 */
+export async function listTree(
+  sessionId: string,
+  pathRaw: string | null | undefined,
+): Promise<{ path: string; entries: TreeEntry[] }> {
+  const path = normalizeVirtualPath(pathRaw);
+  return withAgentFs(sessionId, async (agent) => {
+    let entries;
+    try {
+      entries = await agent.fs.readdirPlus(path);
+    } catch (err) {
+      throw mapFsError(err, path);
+    }
+    const mapped: TreeEntry[] = entries.map((e) => {
+      let type: TreeEntry["type"] = "other";
+      if (e.stats.isDirectory()) type = "directory";
+      else if (e.stats.isFile()) type = "file";
+      else if (e.stats.isSymbolicLink()) type = "symlink";
+      return {
+        name: e.name,
+        path: joinVirtualPath(path, e.name),
+        type,
+        size: e.stats.size,
+        mtime: e.stats.mtime,
+      };
+    });
+    mapped.sort((a, b) => {
+      if (a.type === "directory" && b.type !== "directory") return -1;
+      if (a.type !== "directory" && b.type === "directory") return 1;
+      return a.name.localeCompare(b.name);
+    });
+    return { path, entries: mapped };
+  });
+}
+
+/** 读文件预览（限大小；文本 utf-8，否则 base64）。 */
+export async function readFilePreview(
+  sessionId: string,
+  pathRaw: string | null | undefined,
+): Promise<FilePreview> {
+  const path = normalizeVirtualPath(pathRaw);
+  if (path === "/") {
+    throw new AgentFsDebugError(400, "is_directory", "不能读取根目录为文件");
+  }
+
+  return withAgentFs(sessionId, async (agent) => {
+    let st;
+    try {
+      st = await agent.fs.stat(path);
+    } catch (err) {
+      throw mapFsError(err, path);
+    }
+    if (st.isDirectory()) {
+      throw new AgentFsDebugError(
+        400,
+        "is_directory",
+        "路径是目录，请用 tree 接口",
+      );
+    }
+
+    let buf: Buffer;
+    try {
+      buf = await agent.fs.readFile(path);
+    } catch (err) {
+      throw mapFsError(err, path);
+    }
+
+    const truncated = buf.length > AGENTFS_DEBUG_MAX_FILE_BYTES;
+    const slice = truncated
+      ? buf.subarray(0, AGENTFS_DEBUG_MAX_FILE_BYTES)
+      : buf;
+    const encoding = looksLikeText(slice) ? "utf-8" : "binary";
+    const content =
+      encoding === "utf-8" ? slice.toString("utf-8") : slice.toString("base64");
+
+    return {
+      path,
+      size: st.size,
+      mtime: st.mtime,
+      encoding,
+      truncated,
+      content,
+      byteLength: slice.length,
+    };
+  });
+}
+
+/** 启发式判断 buffer 是否更像文本（含空字节则否）。 */
+function looksLikeText(buf: Buffer): boolean {
+  if (buf.length === 0) return true;
+  let suspicious = 0;
+  const sample = Math.min(buf.length, 4096);
+  for (let i = 0; i < sample; i++) {
+    const c = buf[i]!;
+    if (c === 0) return false;
+    // 允许常见控制符：tab / lf / cr
+    if (c < 32 && c !== 9 && c !== 10 && c !== 13) suspicious++;
+  }
+  return suspicious / sample < 0.05;
+}

agent/lib/agentfs-debug/checkpoint.ts

@@ -0,0 +1,220 @@
+/**
+ * Session 文件系统存档点：创建 / 列表 / 回退 / 删除。
+ *
+ * 存档库落在 `<sessionsDir>/checkpoints/<sessionId>/<name>.db`，
+ * 与运行中 session 库分离。
+ *
+ * create / restore 会读写「可能正被 sandbox host 占用」的 session 库：
+ * 必须经 HostRegistry.withExclusiveAccess（evict → 独占 open → 不自动重开），
+ * 禁止绕过 host 二次 open 造成锁竞争 / 半写 / 回滚后视图分裂。
+ */
+
+import { readdir, rm, stat } from "node:fs/promises";
+import { join } from "node:path";
+
+import type { FileSystem } from "agentfs-sdk";
+
+import { hostRegistry } from "../agentfs-sandbox/host.js";
+import { CHECKPOINT_NAME_RE } from "./constants.js";
+import { AgentFsDebugError } from "./errors.js";
+import { assertSessionDbExists, withAgentFsAtPath } from "./open.js";
+import {
+  joinVirtualPath,
+  resolveCheckpointDbPath,
+  resolveCheckpointsDir,
+} from "./paths.js";
+import type { CheckpointInfo } from "./types.js";
+
+/** 递归复制 src 的 dirPath 下所有文件/目录到 dest（跳过 symlink 等）。 */
+export async function recursiveCopyFs(
+  src: FileSystem,
+  dest: FileSystem,
+  dirPath: string,
+): Promise<void> {
+  const entries = await src.readdirPlus(dirPath);
+  for (const entry of entries) {
+    const child = joinVirtualPath(dirPath, entry.name);
+    if (entry.stats.isDirectory()) {
+      try {
+        await dest.mkdir(child);
+      } catch {
+        // 已存在则忽略
+      }
+      await recursiveCopyFs(src, dest, child);
+    } else if (entry.stats.isFile()) {
+      const content = await src.readFile(child);
+      await dest.writeFile(child, content);
+    }
+    // symlink 和其他类型跳过
+  }
+}
+
+/** 清空虚拟 FS 根下所有条目（单条失败不阻塞）。 */
+async function clearFsRoot(fs: FileSystem): Promise<void> {
+  const rootEntries = await fs.readdirPlus("/");
+  for (const e of rootEntries) {
+    try {
+      await fs.rm(joinVirtualPath("/", e.name), {
+        recursive: true,
+        force: true,
+      });
+    } catch {
+      // 单个文件/目录删除失败不阻塞整体
+    }
+  }
+}
+
+/** 删除 SQLite 主库及常见旁路文件（-wal / -shm）。 */
+async function removeSqliteFiles(dbPath: string): Promise<void> {
+  for (const p of [dbPath, `${dbPath}-wal`, `${dbPath}-shm`]) {
+    try {
+      await rm(p, { force: true });
+    } catch {
+      // 不存在或瞬时占用：留给后续 open 报错
+    }
+  }
+}
+
+/**
+ * 在 session 库上独占执行：先踢 live host，再 withAgentFsAtPath。
+ * checkpoint 库本身无 host 缓存，仍可在 fn 内独立 open。
+ */
+async function withExclusiveSessionDb<T>(
+  sessionDb: string,
+  fn: () => Promise<T>,
+): Promise<T> {
+  return hostRegistry.withExclusiveAccess(sessionDb, fn);
+}
+
+/** 创建存档点：把 session 当前文件状态完整快照到独立 .db（同名则整体替换）。 */
+export async function createCheckpoint(
+  sessionId: string,
+  name: string,
+): Promise<CheckpointInfo> {
+  // 必须先确认 session 存在：AgentFS.open 会对缺失 path 创建空库
+  const sessionDb = await assertSessionDbExists(sessionId);
+  const cpDb = resolveCheckpointDbPath(sessionId, name);
+
+  // 同名全量替换：先清磁盘文件，再 open 新建，避免旧树残留
+  await removeSqliteFiles(cpDb);
+
+  // exclusive：禁止在 live host 仍占 session 库时二次 open 读快照
+  await withExclusiveSessionDb(sessionDb, async () => {
+    await withAgentFsAtPath(
+      sessionDb,
+      async (sessionAgent) => {
+        await withAgentFsAtPath(
+          cpDb,
+          async (cpAgent) => {
+            await recursiveCopyFs(sessionAgent.fs, cpAgent.fs, "/");
+          },
+          { mustExist: false, label: `checkpoint:${name}` },
+        );
+      },
+      { mustExist: true, label: sessionId },
+    );
+  });
+
+  const st = await stat(cpDb);
+  return { name, sizeBytes: st.size, mtimeMs: st.mtimeMs };
+}
+
+/** 列出 session 的所有存档点。 */
+export async function listCheckpoints(
+  sessionId: string,
+): Promise<CheckpointInfo[]> {
+  // 校验 id；目录不存在视为无存档
+  const dir = resolveCheckpointsDir(sessionId);
+  let names: string[];
+  try {
+    names = await readdir(dir);
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code === "ENOENT") return [];
+    throw err;
+  }
+
+  const out: CheckpointInfo[] = [];
+  for (const name of names) {
+    if (!name.endsWith(".db")) continue;
+    const label = name.slice(0, -".db".length);
+    if (!CHECKPOINT_NAME_RE.test(label)) continue;
+    const fullPath = join(dir, name);
+    try {
+      const st = await stat(fullPath);
+      if (!st.isFile()) continue;
+      out.push({ name: label, sizeBytes: st.size, mtimeMs: st.mtimeMs });
+    } catch {
+      // 单文件失败跳过
+    }
+  }
+  out.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  return out;
+}
+
+/** 回退 session 到某个存档点：清空 session 根后从存档完整复制。 */
+export async function restoreCheckpoint(
+  sessionId: string,
+  name: string,
+): Promise<{ restored: number }> {
+  const cpDb = resolveCheckpointDbPath(sessionId, name);
+  // session 必须已存在；禁止 open 时静默新建空库再写入
+  const sessionDb = await assertSessionDbExists(sessionId);
+
+  // exclusive：evict host → 独占写回滚 → host 失效，避免工具继续看旧盘
+  await withExclusiveSessionDb(sessionDb, async () => {
+    await withAgentFsAtPath(
+      cpDb,
+      async (cpAgent) => {
+        await withAgentFsAtPath(
+          sessionDb,
+          async (sessionAgent) => {
+            await clearFsRoot(sessionAgent.fs);
+            await recursiveCopyFs(cpAgent.fs, sessionAgent.fs, "/");
+          },
+          { mustExist: true, label: sessionId },
+        );
+      },
+      {
+        mustExist: true,
+        label: `checkpoint:${name}`,
+        notFound: {
+          code: "checkpoint_not_found",
+          message: `存档点不存在: ${name}`,
+        },
+      },
+    );
+  });
+
+  return { restored: 1 };
+}
+
+/** 删除单个存档点（含 -wal/-shm）。 */
+export async function deleteCheckpoint(
+  sessionId: string,
+  name: string,
+): Promise<void> {
+  const cpDb = resolveCheckpointDbPath(sessionId, name);
+  // force:false 才能在缺失时抛 ENOENT → 404
+  try {
+    await rm(cpDb, { force: false });
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code === "ENOENT") {
+      throw new AgentFsDebugError(
+        404,
+        "checkpoint_not_found",
+        `存档点不存在: ${name}`,
+      );
+    }
+    throw err;
+  }
+  // 旁路文件尽量清理；主库已删成功即视为删除完成
+  for (const p of [`${cpDb}-wal`, `${cpDb}-shm`]) {
+    try {
+      await rm(p, { force: true });
+    } catch {
+      // ignore
+    }
+  }
+}

agent/lib/agentfs-debug/constants.ts

@@ -0,0 +1,15 @@
+/**
+ * AgentFS 调试与 checkpoint 相关常量。
+ */
+
+/** 单文件预览上限（字节），超出只返回 meta + 截断提示。 */
+export const AGENTFS_DEBUG_MAX_FILE_BYTES = 256 * 1024;
+
+/** 存档点名允许字符（中文 + 字母数字 + 部分符号）。 */
+export const CHECKPOINT_NAME_RE = /^[a-zA-Z0-9._\-\u4e00-\u9fff]{1,100}$/;
+
+/**
+ * sessionKey 文件名允许的字符。
+ * 与 eve `sanitizeRuntimeSandboxKey` 对齐并略放宽长度上限。
+ */
+export const SESSION_ID_RE = /^[a-zA-Z0-9._-]{1,200}$/;

agent/lib/agentfs-debug/errors.ts

@@ -0,0 +1,59 @@
+/**
+ * AgentFS 调试 API 错误类型与 HTTP 映射。
+ */
+
+export class AgentFsDebugError extends Error {
+  readonly status: number;
+  readonly code: string;
+
+  constructor(status: number, code: string, message: string) {
+    super(message);
+    this.name = "AgentFsDebugError";
+    this.status = status;
+    this.code = code;
+  }
+}
+
+/** 把未知错误转成 JSON Response（channel 层统一 catch）。 */
+export function jsonError(err: unknown): Response {
+  if (err instanceof AgentFsDebugError) {
+    return Response.json(
+      { ok: false, error: { code: err.code, message: err.message } },
+      { status: err.status },
+    );
+  }
+  const message = err instanceof Error ? err.message : String(err);
+  return Response.json(
+    { ok: false, error: { code: "internal", message } },
+    { status: 500 },
+  );
+}
+
+/** 虚拟 FS 操作错误 → 调试 API 错误。 */
+export function mapFsError(err: unknown, path: string): AgentFsDebugError {
+  const code = (err as NodeJS.ErrnoException)?.code;
+  if (code === "ENOENT") {
+    return new AgentFsDebugError(404, "not_found", `路径不存在: ${path}`);
+  }
+  if (code === "ENOTDIR") {
+    return new AgentFsDebugError(400, "not_directory", `不是目录: ${path}`);
+  }
+  if (code === "EISDIR") {
+    return new AgentFsDebugError(400, "is_directory", `是目录: ${path}`);
+  }
+  const message = err instanceof Error ? err.message : String(err);
+  return new AgentFsDebugError(500, "fs_error", message);
+}
+
+/** AgentFS.open 失败（常见：库被占用、损坏）。 */
+export function mapAgentFsOpenError(
+  err: unknown,
+  label: string,
+): AgentFsDebugError {
+  const message = err instanceof Error ? err.message : String(err);
+  return new AgentFsDebugError(
+    503,
+    "open_failed",
+    `无法打开 AgentFS（${label}）: ${message}`,
+  );
+}

agent/lib/agentfs-debug/open.ts

@@ -0,0 +1,114 @@
+/**
+ * 短生命周期打开 AgentFS：回调结束即 close，不进入 sandbox host 缓存。
+ *
+ * 适用：
+ * - 只读 browse（tree / file preview）
+ * - checkpoint 库（无 live host）
+ * - 已在 HostRegistry.withExclusiveAccess 保护下的 session 库读写
+ *
+ * 禁止：在 live host 可能仍占用 session .db 时，绕过 exclusive 直接
+ * withAgentFsAtPath(sessionDb) 做 create/restore 等大范围改写。
+ */
+
+import { mkdir, stat } from "node:fs/promises";
+import { dirname } from "node:path";
+
+import { AgentFS } from "agentfs-sdk";
+
+import { AgentFsDebugError, mapAgentFsOpenError } from "./errors.js";
+import { resolveSessionDbPath } from "./paths.js";
+
+export type OpenAgent = Awaited<ReturnType<typeof AgentFS.open>>;
+
+async function closeQuietly(agent: OpenAgent): Promise<void> {
+  try {
+    await agent.close();
+  } catch {
+    // 关闭失败不影响主结果
+  }
+}
+
+/** 确认磁盘上的 .db 已存在，避免 AgentFS.open 对缺失路径静默建空库。 */
+export async function assertDbExists(
+  dbPath: string,
+  notFound: { code: string; message: string },
+): Promise<void> {
+  try {
+    await stat(dbPath);
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code === "ENOENT") {
+      throw new AgentFsDebugError(404, notFound.code, notFound.message);
+    }
+    throw err;
+  }
+}
+
+/** 确认 session .db 已存在。 */
+export async function assertSessionDbExists(sessionId: string): Promise<string> {
+  const sessionDb = resolveSessionDbPath(sessionId);
+  await assertDbExists(sessionDb, {
+    code: "session_not_found",
+    message: `session 不存在: ${sessionId}`,
+  });
+  return sessionDb;
+}
+
+/**
+ * 在指定 db 路径上打开 AgentFS，执行回调后关闭。
+ * @param mustExist 为 true 时禁止 open 静默创建空库；为 false 时会 mkdir 父目录后 open（checkpoint 新建）。
+ * @param notFound  mustExist 时 404 的 code/message；默认 session_not_found。
+ */
+export async function withAgentFsAtPath<T>(
+  dbPath: string,
+  fn: (agent: OpenAgent) => Promise<T>,
+  opts?: {
+    mustExist?: boolean;
+    label?: string;
+    notFound?: { code: string; message: string };
+  },
+): Promise<T> {
+  const mustExist = opts?.mustExist ?? true;
+  const label = opts?.label ?? dbPath;
+
+  if (mustExist) {
+    await assertDbExists(
+      dbPath,
+      opts?.notFound ?? {
+        code: "session_not_found",
+        message: `库不存在: ${label}`,
+      },
+    );
+  } else {
+    await mkdir(dirname(dbPath), { recursive: true });
+  }
+
+  let agent: OpenAgent;
+  try {
+    agent = await AgentFS.open({ path: dbPath });
+  } catch (err) {
+    throw mapAgentFsOpenError(err, label);
+  }
+
+  try {
+    return await fn(agent);
+  } finally {
+    await closeQuietly(agent);
+  }
+}
+
+/** 打开 session 库，执行回调后关闭（要求 session 已存在）。 */
+export async function withAgentFs<T>(
+  sessionId: string,
+  fn: (agent: OpenAgent) => Promise<T>,
+): Promise<T> {
+  const dbPath = resolveSessionDbPath(sessionId);
+  return withAgentFsAtPath(dbPath, fn, {
+    mustExist: true,
+    label: sessionId,
+    notFound: {
+      code: "session_not_found",
+      message: `session 不存在: ${sessionId}`,
+    },
+  });
+}

agent/lib/agentfs-debug/paths.ts

@@ -0,0 +1,93 @@
+/**
+ * 调试 API 的路径解析与校验。
+ *
+ * 数据布局复用 `lib/agentfs/paths.ts`；此处补 session id / 虚拟路径 / checkpoint 校验。
+ */
+
+import { basename, join, resolve } from "node:path";
+
+import {
+  AGENTFS_BACKEND_NAME,
+  resolveDataDir as resolveDataDirFromAppRoot,
+  resolveSessionsDir as resolveSessionsDirFromDataDir,
+} from "../agentfs/paths.js";
+import { CHECKPOINT_NAME_RE, SESSION_ID_RE } from "./constants.js";
+import { AgentFsDebugError } from "./errors.js";
+
+export { AGENTFS_BACKEND_NAME };
+
+/** 数据目录根：`EVEAGENT_DATA_DIR` 优先，否则 `<cwd>/data`。 */
+export function resolveDataDir(): string {
+  return resolveDataDirFromAppRoot();
+}
+
+/** sessions 目录绝对路径。 */
+export function resolveSessionsDir(): string {
+  return resolveSessionsDirFromDataDir(resolveDataDir());
+}
+
+/** 校验 session id，防止路径穿越。 */
+export function assertSessionId(id: string): string {
+  if (!SESSION_ID_RE.test(id)) {
+    throw new AgentFsDebugError(400, "invalid_session_id", "session id 非法");
+  }
+  return id;
+}
+
+/**
+ * 解析虚拟 FS 路径：必须为绝对路径、无 `..`、无空字节。
+ * 空或 `/` → `/`。
+ */
+export function normalizeVirtualPath(raw: string | null | undefined): string {
+  const input = (raw ?? "/").trim() || "/";
+  if (input.includes("\0")) {
+    throw new AgentFsDebugError(400, "invalid_path", "路径含非法字符");
+  }
+  const withSlash = input.startsWith("/") ? input : `/${input}`;
+  const parts = withSlash.split("/").filter((p) => p.length > 0);
+  const out: string[] = [];
+  for (const part of parts) {
+    if (part === ".") continue;
+    if (part === "..") {
+      throw new AgentFsDebugError(400, "invalid_path", "路径不允许包含 ..");
+    }
+    out.push(part);
+  }
+  return out.length === 0 ? "/" : `/${out.join("/")}`;
+}
+
+/** 将 session id 解析为磁盘上的 .db 绝对路径（id 已禁止路径分隔符）。 */
+export function resolveSessionDbPath(sessionId: string): string {
+  const id = assertSessionId(sessionId);
+  const sessionsDir = resolveSessionsDir();
+  const dbPath = resolve(join(sessionsDir, `${id}.db`));
+  if (basename(dbPath) !== `${id}.db`) {
+    throw new AgentFsDebugError(400, "invalid_session_id", "session 路径越界");
+  }
+  return dbPath;
+}
+
+/** checkpoints 目录：`<sessionsDir>/checkpoints/<sessionId>/` */
+export function resolveCheckpointsDir(sessionId: string): string {
+  return join(resolveSessionsDir(), "checkpoints", assertSessionId(sessionId));
+}
+
+/** 单个存档点 .db 文件路径。 */
+export function resolveCheckpointDbPath(
+  sessionId: string,
+  name: string,
+): string {
+  if (!CHECKPOINT_NAME_RE.test(name)) {
+    throw new AgentFsDebugError(
+      400,
+      "invalid_checkpoint_name",
+      "存档点名非法（允许中文、字母、数字、._-）",
+    );
+  }
+  return join(resolveCheckpointsDir(sessionId), `${name}.db`);
+}
+
+/** 拼接虚拟目录下的子路径。 */
+export function joinVirtualPath(dir: string, name: string): string {
+  return dir === "/" ? `/${name}` : `${dir}/${name}`;
+}

agent/lib/agentfs-debug/sessions.ts

@@ -0,0 +1,46 @@
+/**
+ * 列出磁盘上的 session 沙箱库。
+ */
+
+import { readdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+
+import { SESSION_ID_RE } from "./constants.js";
+import { resolveSessionsDir } from "./paths.js";
+import type { SessionDbInfo } from "./types.js";
+
+/** 列出 sessions 目录下的 `*.db`（忽略 -wal/-shm 旁路文件）。 */
+export async function listSessionDbs(): Promise<SessionDbInfo[]> {
+  const sessionsDir = resolveSessionsDir();
+  let names: string[];
+  try {
+    names = await readdir(sessionsDir);
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code === "ENOENT") return [];
+    throw err;
+  }
+
+  const out: SessionDbInfo[] = [];
+  for (const name of names) {
+    // 只认主库文件名：foo.db；foo.db-wal / foo.db-shm 不以 .db 结尾
+    if (!name.endsWith(".db")) continue;
+    const id = name.slice(0, -".db".length);
+    if (!SESSION_ID_RE.test(id)) continue;
+    const dbPath = join(sessionsDir, name);
+    try {
+      const st = await stat(dbPath);
+      if (!st.isFile()) continue;
+      out.push({
+        id,
+        dbPath,
+        sizeBytes: st.size,
+        mtimeMs: st.mtimeMs,
+      });
+    } catch {
+      // 单文件 stat 失败则跳过
+    }
+  }
+  out.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  return out;
+}

agent/lib/agentfs-debug/types.ts

@@ -0,0 +1,34 @@
+/**
+ * AgentFS 调试 API 的公开类型。
+ */
+
+export type SessionDbInfo = {
+  id: string;
+  dbPath: string;
+  sizeBytes: number;
+  mtimeMs: number;
+};
+
+export type TreeEntry = {
+  name: string;
+  path: string;
+  type: "file" | "directory" | "symlink" | "other";
+  size: number;
+  mtime: number;
+};
+
+export type FilePreview = {
+  path: string;
+  size: number;
+  mtime: number;
+  encoding: "utf-8" | "binary";
+  truncated: boolean;
+  content: string;
+  byteLength: number;
+};
+
+export type CheckpointInfo = {
+  name: string;
+  sizeBytes: number;
+  mtimeMs: number;
+};

agent/lib/agentfs-sandbox/backend.ts

@@ -0,0 +1,189 @@
+/**
+ * AgentFS + just-bash 的 `SandboxBackend` 实现。
+ *
+ * 生命周期对齐 eve 官方 just-bash 后端：
+ * - prewarm：按 templateKey 打开/复用模板库；可跑 bootstrap 与 seedFiles
+ * - create ：每个 durable session 独立 .db；优先 existingMetadata / 进程内缓存，
+ *            否则从模板复制，再否则空建
+ * - handle ：captureState 写 metadata v1；shutdown 停解释器并踢出缓存
+ */
+
+import { utimes } from "node:fs/promises";
+
+import {
+  SandboxTemplateNotProvisionedError,
+  type SandboxBackend,
+  type SandboxBackendCreateInput,
+  type SandboxBackendHandle,
+  type SandboxBackendPrewarmInput,
+  type SandboxBackendSessionState,
+  type SandboxSeedFile,
+  type SandboxSession,
+} from "eve/sandbox";
+
+import {
+  AGENTFS_BACKEND_NAME,
+  resolveDataDir,
+  resolveSessionDbPath,
+  resolveTemplateDbPath,
+} from "../agentfs/paths.js";
+import { hostRegistry, pathExists, type AgentFsHost } from "./host.js";
+import {
+  buildSessionMetadata,
+  resolveExistingDbPath,
+} from "./metadata.js";
+import { maybePruneStaleSessions } from "./prune.js";
+import {
+  buildInternalSession,
+  buildPublicSession,
+  setNetworkPolicyUnsupported,
+} from "./session.js";
+
+async function writeSeedFiles(
+  session: SandboxSession,
+  seedFiles: ReadonlyArray<SandboxSeedFile>,
+): Promise<void> {
+  for (const file of seedFiles) {
+    if (typeof file.content === "string") {
+      await session.writeTextFile({ path: file.path, content: file.content });
+    } else {
+      await session.writeBinaryFile({
+        path: file.path,
+        content: file.content,
+      });
+    }
+  }
+}
+
+function buildHandle(opts: {
+  host: AgentFsHost;
+  sessionKey: string;
+}): SandboxBackendHandle {
+  const { host, sessionKey } = opts;
+  const internal = buildInternalSession({
+    id: sessionKey,
+    sandbox: host.sandbox,
+    fs: host.fs,
+  });
+  const session = buildPublicSession(internal, setNetworkPolicyUnsupported);
+
+  return {
+    session,
+    useSessionFn: async () => session,
+    async captureState(): Promise<SandboxBackendSessionState> {
+      return {
+        backendName: AGENTFS_BACKEND_NAME,
+        sessionKey,
+        metadata: buildSessionMetadata(host.dbPath),
+      };
+    },
+    async shutdown(): Promise<void> {
+      // 停 just-bash 解释器并踢缓存；.db 留在磁盘供下次 create 重连
+      await hostRegistry.shutdown(host.dbPath);
+    },
+  };
+}
+
+/**
+ * 解析 create 应打开的 session 库路径，并在需要时从模板复制。
+ *
+ * 优先级：
+ * 1. 进程内同 sessionKey 已登记的 dbPath
+ * 2. existingMetadata.dbPath（持久化重连）
+ * 3. 默认 sessions/<sessionKey>.db；若不存在且有 templateKey，则从模板复制
+ */
+async function resolveSessionDbForCreate(
+  input: SandboxBackendCreateInput,
+): Promise<string> {
+  const { runtimeContext, sessionKey, templateKey } = input;
+  const dataDir = resolveDataDir(runtimeContext.appRoot);
+
+  const inProcess = hostRegistry.getDbPathForSession(sessionKey);
+  if (inProcess) return inProcess;
+
+  const fromMetadata = resolveExistingDbPath(input);
+  if (fromMetadata) return fromMetadata;
+
+  const sessionDbPath = resolveSessionDbPath(dataDir, sessionKey);
+  if (await pathExists(sessionDbPath)) return sessionDbPath;
+
+  // 库尚不存在：有模板则复制派生，无模板则空建（open 时创建文件）
+  if (templateKey !== null) {
+    const templateDbPath = resolveTemplateDbPath(dataDir, templateKey);
+    if (!(await pathExists(templateDbPath))) {
+      throw new SandboxTemplateNotProvisionedError({
+        backendName: AGENTFS_BACKEND_NAME,
+        templateKey,
+      });
+    }
+    await hostRegistry.copyTemplateDb(templateDbPath, sessionDbPath);
+  }
+
+  return sessionDbPath;
+}
+
+/** 构造 agentfs-just-bash SandboxBackend。 */
+export function createAgentFsJustBashBackend(): SandboxBackend {
+  return {
+    name: AGENTFS_BACKEND_NAME,
+
+    async prewarm(
+      input: SandboxBackendPrewarmInput,
+    ): Promise<{ reused: boolean }> {
+      const { runtimeContext, templateKey, bootstrap, seedFiles, log } = input;
+      const dataDir = resolveDataDir(runtimeContext.appRoot);
+      const dbPath = resolveTemplateDbPath(dataDir, templateKey);
+
+      const existing = hostRegistry.getByDbPath(dbPath);
+      if (existing || (await pathExists(dbPath))) {
+        // touch 宿主文件 mtime，给 prune/运维「最近活跃模板」信号
+        try {
+          const now = new Date();
+          await utimes(dbPath, now, now);
+        } catch {
+          // 文件尚被创建中或平台差异——无害
+        }
+        if (!existing) {
+          await hostRegistry.getOrOpen({ dbPath });
+        }
+        return { reused: true };
+      }
+
+      const host = await hostRegistry.getOrOpen({ dbPath });
+      const internal = buildInternalSession({
+        id: templateKey,
+        sandbox: host.sandbox,
+        fs: host.fs,
+      });
+      const session = buildPublicSession(internal, setNetworkPolicyUnsupported);
+
+      if (bootstrap) {
+        log?.("running sandbox bootstrap");
+        await bootstrap({ use: async () => session });
+      }
+      if (seedFiles.length > 0) {
+        await writeSeedFiles(session, seedFiles);
+      }
+
+      return { reused: false };
+    },
+
+    async create(
+      input: SandboxBackendCreateInput,
+    ): Promise<SandboxBackendHandle> {
+      await maybePruneStaleSessions(
+        input.runtimeContext.appRoot,
+        hostRegistry,
+      );
+
+      const dbPath = await resolveSessionDbForCreate(input);
+      const host = await hostRegistry.getOrOpen({
+        dbPath,
+        sessionKey: input.sessionKey,
+      });
+      return buildHandle({ host, sessionKey: input.sessionKey });
+    },
+  };
+}
+
+export { AGENTFS_BACKEND_NAME };

agent/lib/agentfs-sandbox/host.ts

@@ -0,0 +1,246 @@
+/**
+ * AgentFS + just-bash 进程级 host：打开、缓存、派生、独占借用。
+ *
+ * 键用 dbPath（不是 templateKey/sessionKey）——同一路径命中复用，避免重复 open SQLite。
+ * session 另记 sessionKey → dbPath，供 prune 跳过活跃库。
+ *
+ * 生命周期契约：
+ * - getOrOpen / shutdown / withExclusiveAccess 对同一 dbPath 串行
+ * - 任何会大范围改写 live session 库的路径（checkpoint create/restore）必须
+ *   withExclusiveAccess：先 evict（stop sandbox + close AgentFS），再独占 open，
+ *   结束后不自动重开；下次 getOrOpen 以磁盘最新内容重建 host
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+import { access, copyFile, mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+
+import { AgentFS } from "agentfs-sdk";
+import { AgentFsWrapper as JustBashFsWrapper } from "agentfs-sdk/just-bash";
+import {
+  Sandbox as JustBashSandbox,
+  type IFileSystem,
+} from "just-bash";
+
+import { WORKSPACE_ROOT } from "../agentfs/paths.js";
+import { padJustBashFs } from "./pad-fs.js";
+
+export type JustBashSandboxInstance = Awaited<
+  ReturnType<typeof JustBashSandbox.create>
+>;
+
+export type OpenAgentFs = Awaited<ReturnType<typeof AgentFS.open>>;
+
+export interface AgentFsHost {
+  agentFs: OpenAgentFs;
+  sandbox: JustBashSandboxInstance;
+  fs: IFileSystem;
+  dbPath: string;
+}
+
+/** websearch 子 agent 需要的出站前缀；其余默认拒绝。 */
+const NETWORK_ALLOWED_URL_PREFIXES = [
+  "https://api.anysearch.com/",
+  "https://api.firecrawl.dev/",
+] as const;
+
+const NETWORK_ALLOWED_METHODS = ["GET", "HEAD", "POST"] as const;
+
+/** 仅透传检索相关密钥进沙箱 env，不全量开放 process.env。 */
+function buildSandboxEnv(): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const key of ["ANYSEARCH_API_KEY", "FIRECRAWL_API_KEY"] as const) {
+    const v = process.env[key]?.trim();
+    if (v) env[key] = v;
+  }
+  return env;
+}
+
+async function pathExists(path: string): Promise<boolean> {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function closeAgentFsQuietly(agentFs: OpenAgentFs): Promise<void> {
+  try {
+    await agentFs.close();
+  } catch {
+    // 关闭失败不阻塞驱逐
+  }
+}
+
+/**
+ * 进程级 host 注册表。
+ * 对外暴露 open / get / shutdown / withExclusiveAccess；不在模块顶层散落 Map。
+ */
+export class HostRegistry {
+  private readonly hostsByDbPath = new Map<string, AgentFsHost>();
+  private readonly sessionKeyToDbPath = new Map<string, string>();
+  /** 同一 dbPath 上 getOrOpen / shutdown / exclusive 的串行尾。 */
+  private readonly pathChains = new Map<string, Promise<unknown>>();
+  /**
+   * 当前异步上下文正持有串行锁的 dbPath。
+   * 同路径重入（exclusive 内部再调 getOrOpen 等）直接执行，避免自死锁。
+   */
+  private readonly activeDbPath = new AsyncLocalStorage<string>();
+
+  getByDbPath(dbPath: string): AgentFsHost | undefined {
+    return this.hostsByDbPath.get(dbPath);
+  }
+
+  getDbPathForSession(sessionKey: string): string | undefined {
+    return this.sessionKeyToDbPath.get(sessionKey);
+  }
+
+  hasActiveSession(sessionKey: string): boolean {
+    return this.sessionKeyToDbPath.has(sessionKey);
+  }
+
+  /**
+   * 在同一 dbPath 上串行执行。同上下文重入直接跑 fn。
+   * 链上错误不污染后续任务。
+   */
+  private runSerialized<T>(dbPath: string, fn: () => Promise<T>): Promise<T> {
+    if (this.activeDbPath.getStore() === dbPath) {
+      return fn();
+    }
+
+    const prev = this.pathChains.get(dbPath) ?? Promise.resolve();
+    const run = async (): Promise<T> => this.activeDbPath.run(dbPath, fn);
+    // 前序失败也继续本任务
+    const next = prev.then(run, run);
+    this.pathChains.set(
+      dbPath,
+      next.then(
+        () => undefined,
+        () => undefined,
+      ),
+    );
+    return next;
+  }
+
+  /**
+   * 打开（命中复用）一个 session 或 template 的 AgentFS + just-bash 组合。
+   * sessionKey 非空时登记反向索引，供 prune 跳过活跃库。
+   * 与 exclusive / shutdown 同路径串行。
+   */
+  async getOrOpen(opts: {
+    dbPath: string;
+    sessionKey?: string;
+  }): Promise<AgentFsHost> {
+    return this.runSerialized(opts.dbPath, () => this.getOrOpenUnlocked(opts));
+  }
+
+  private async getOrOpenUnlocked(opts: {
+    dbPath: string;
+    sessionKey?: string;
+  }): Promise<AgentFsHost> {
+    const { dbPath, sessionKey } = opts;
+    const cached = this.hostsByDbPath.get(dbPath);
+    if (cached) {
+      if (sessionKey) this.sessionKeyToDbPath.set(sessionKey, dbPath);
+      return cached;
+    }
+
+    await mkdir(dirname(dbPath), { recursive: true });
+    const agentFs = await AgentFS.open({ path: dbPath });
+
+    // 直接构造 AgentFsWrapper：agentfs() 工厂在 Node 24 + pnpm 软链下
+    // 类型守卫会走错兜底分支，触发二次 open 报错。
+    const wrapped = padJustBashFs(
+      new JustBashFsWrapper({ fs: agentFs }) as unknown as IFileSystem,
+    );
+
+    const sandbox = await JustBashSandbox.create({
+      cwd: WORKSPACE_ROOT,
+      env: buildSandboxEnv(),
+      fs: wrapped,
+      network: {
+        allowedUrlPrefixes: [...NETWORK_ALLOWED_URL_PREFIXES],
+        allowedMethods: [...NETWORK_ALLOWED_METHODS],
+      },
+    });
+
+    // Sandbox.create 不会自动建 /workspace
+    try {
+      await sandbox.mkDir(WORKSPACE_ROOT, { recursive: true });
+    } catch {
+      // 已存在可忽略
+    }
+
+    const host: AgentFsHost = { agentFs, sandbox, fs: wrapped, dbPath };
+    this.hostsByDbPath.set(dbPath, host);
+    if (sessionKey) this.sessionKeyToDbPath.set(sessionKey, dbPath);
+    return host;
+  }
+
+  /**
+   * 踢掉缓存中的 host：stop just-bash + close AgentFS，清 session 反向索引。
+   * 磁盘 .db 保留。须在已持有该路径串行锁时调用。
+   */
+  private async evictUnlocked(dbPath: string): Promise<void> {
+    const host = this.hostsByDbPath.get(dbPath);
+    if (!host) return;
+
+    this.hostsByDbPath.delete(dbPath);
+    for (const [key, path] of this.sessionKeyToDbPath) {
+      if (path === dbPath) this.sessionKeyToDbPath.delete(key);
+    }
+
+    try {
+      await host.sandbox.stop();
+    } catch {
+      // stop 失败不阻塞驱逐
+    }
+    // 必须 close：否则 exclusive 二次 open 与残留连接双写 / 视图分裂
+    await closeAgentFsQuietly(host.agentFs);
+  }
+
+  /** 停掉 just-bash 解释器、关闭 AgentFS，并从缓存剔除；磁盘上的 .db 保留以便重连。 */
+  async shutdown(dbPath: string): Promise<void> {
+    return this.runSerialized(dbPath, () => this.evictUnlocked(dbPath));
+  }
+
+  /**
+   * 独占访问某 .db：先 evict live host，再执行 fn（fn 内可安全独立 open 该路径）。
+   * 与 getOrOpen 同路径串行，杜绝「host 占着 + debug 再开」的双开。
+   * fn 结束后不自动重开 host——下次 getOrOpen 以磁盘最新内容重建。
+   *
+   * 注意：已下发的 SandboxBackendHandle 仍持有旧 host 引用；
+   * exclusive 后旧连接会失败或不可用，这是刻意的（避免工具继续看回滚前视图）。
+   * 管理侧 restore 期间中断 mid-flight 工具调用是可接受代价。
+   */
+  async withExclusiveAccess<T>(
+    dbPath: string,
+    fn: () => Promise<T>,
+  ): Promise<T> {
+    return this.runSerialized(dbPath, async () => {
+      await this.evictUnlocked(dbPath);
+      return await fn();
+    });
+  }
+
+  /**
+   * 把模板库文件复制到 session 路径（session 尚不存在时）。
+   * 仅复制主 .db；wal/shm 由后续 open 重建。
+   */
+  async copyTemplateDb(
+    templateDbPath: string,
+    sessionDbPath: string,
+  ): Promise<void> {
+    if (!(await pathExists(templateDbPath))) {
+      throw new Error(`template database missing: ${templateDbPath}`);
+    }
+    await mkdir(dirname(sessionDbPath), { recursive: true });
+    await copyFile(templateDbPath, sessionDbPath);
+  }
+}
+
+/** 进程单例：同一 Node 进程内所有 eve session 共享。 */
+export const hostRegistry = new HostRegistry();
+
+export { pathExists };

agent/lib/agentfs-sandbox/metadata.ts

@@ -0,0 +1,42 @@
+/**
+ * sandbox-backend metadata schema v1 校验。
+ * 持久化字段：`{ version: 1, dbPath: string }`。
+ * 版本不匹配或字段缺失一律丢弃（记 warn），强制按 sessionKey 重建路径。
+ */
+
+import type { SandboxBackendCreateInput } from "eve/sandbox";
+import { AGENTFS_BACKEND_NAME } from "../agentfs/paths.js";
+
+export const METADATA_VERSION = 1 as const;
+
+export type SessionMetadataV1 = {
+  readonly version: typeof METADATA_VERSION;
+  readonly dbPath: string;
+};
+
+export function buildSessionMetadata(dbPath: string): SessionMetadataV1 {
+  return { version: METADATA_VERSION, dbPath };
+}
+
+/** 从 existingMetadata 严格解出 dbPath；不合法返回 null。 */
+export function resolveExistingDbPath(
+  input: SandboxBackendCreateInput,
+): string | null {
+  const m = input.existingMetadata as Record<string, unknown> | undefined;
+  if (!m) return null;
+
+  if (m.version !== METADATA_VERSION) {
+    if (typeof m.dbPath === "string") {
+      console.warn(
+        `[${AGENTFS_BACKEND_NAME}] dropping legacy metadata dbPath=${m.dbPath}; ` +
+          `rebuilding session ${input.sessionKey} from scratch`,
+      );
+    }
+    return null;
+  }
+
+  if (typeof m.dbPath !== "string" || m.dbPath.length === 0) {
+    return null;
+  }
+  return m.dbPath;
+}

agent/lib/agentfs-sandbox/pad-fs.ts

@@ -0,0 +1,30 @@
+/**
+ * 补全 AgentFsWrapper 相对 just-bash `IFileSystem` 缺失的必选方法。
+ *
+ * AgentFsWrapper 已实现 readFileBuffer / appendFile / getAllPaths / chmod 等；
+ * 缺的是 IFileSystem 契约要求的 `realpath` 与 `utimes`。
+ * just-bash 会直接 await 这两个方法（realpath 在 try 里，utimes 在 touch 类命令里），
+ * 未定义会变成 "is not a function"。
+ *
+ * 故意不补半残的 optional 方法（如只有 name 的 readdirWithFileTypes）：
+ * 缺省时 just-bash 会走 readdir + stat 回退，比错误的 type 信息更安全。
+ */
+
+import type { IFileSystem } from "just-bash";
+
+/** AgentFS 不支持真实 symlink 解析与 mtime 写入时的最小 stub。 */
+export function padJustBashFs(inner: IFileSystem): IFileSystem {
+  const realpath = async (path: string): Promise<string> => path;
+  const utimes = async (
+    _path: string,
+    _atime: Date,
+    _mtime: Date,
+  ): Promise<void> => {
+    // AgentFS 不支持 utimes；noop 即可
+  };
+
+  return Object.assign(Object.create(inner) as IFileSystem, {
+    realpath,
+    utimes,
+  });
+}

agent/lib/agentfs-sandbox/process.ts

@@ -0,0 +1,88 @@
+/**
+ * 把 just-bash `Command`（单路 `logs()` 异步迭代）适配为 eve `SandboxProcess`
+ *（独立的 stdout / stderr `ReadableStream`）。
+ *
+ * 与 eve 内部 `adaptMultiplexedCommandToSandboxProcess` 同构：
+ * 只消费一次 logs，边收边 fan-out，避免双消费者竞态，也避免整段缓冲后再吐。
+ */
+
+import type { SandboxProcess } from "eve/sandbox";
+
+export interface MultiplexedCommand {
+  logs(): AsyncIterable<{ type: "stdout" | "stderr"; data: string }>;
+  wait(): PromiseLike<{ exitCode: number }>;
+  kill(): PromiseLike<void> | void;
+}
+
+function createOutputChannel(): {
+  stream: ReadableStream<Uint8Array>;
+  enqueue(chunk: Uint8Array): void;
+  close(): void;
+  error(err: unknown): void;
+} {
+  let cancelled = false;
+  let controller: ReadableStreamDefaultController<Uint8Array> | undefined;
+  return {
+    stream: new ReadableStream<Uint8Array>({
+      start(c) {
+        controller = c;
+      },
+      cancel() {
+        cancelled = true;
+      },
+    }),
+    enqueue(chunk) {
+      if (!cancelled) controller?.enqueue(chunk);
+    },
+    close() {
+      if (!cancelled) controller?.close();
+    },
+    error(err) {
+      if (!cancelled) controller?.error(err);
+    },
+  };
+}
+
+/** 单次消费 logs，按 type 拆到两条流；wait 等日志泵完成后再返回 exitCode。 */
+export function adaptCommandToSandboxProcess(
+  command: MultiplexedCommand,
+): SandboxProcess {
+  const encoder = new TextEncoder();
+  const stdout = createOutputChannel();
+  const stderr = createOutputChannel();
+  const channels = { stdout, stderr } as const;
+
+  const pump = (async () => {
+    try {
+      for await (const msg of command.logs()) {
+        channels[msg.type].enqueue(encoder.encode(msg.data));
+      }
+      stdout.close();
+      stderr.close();
+    } catch (err) {
+      stdout.error(err);
+      stderr.error(err);
+      throw err;
+    }
+  })();
+  // 无消费者时避免未处理 rejection
+  pump.catch(() => undefined);
+
+  let waitPromise: Promise<{ exitCode: number }> | undefined;
+  let killPromise: Promise<void> | undefined;
+
+  return {
+    stdout: stdout.stream,
+    stderr: stderr.stream,
+    wait() {
+      return (waitPromise ??= Promise.resolve().then(async () => {
+        const result = await command.wait();
+        await pump;
+        return { exitCode: result.exitCode };
+      }));
+    },
+    kill() {
+      return (killPromise ??= Promise.resolve().then(() => command.kill()));
+    },
+  };
+}

agent/lib/agentfs-sandbox/prune.ts

@@ -0,0 +1,70 @@
+/**
+ * 清理 sessions 目录下 mtime 超过 AGENTFS_SESSION_MAX_AGE_DAYS 的 .db。
+ * - 跳过 HostRegistry 仍在引用的活跃 session
+ * - 不动 templates/（删错要重 build）
+ * - 第一次 open session 时 lazy 触发一次，避免硬编码 Nitro 启动 hook
+ */
+
+import { readdir, rm, stat } from "node:fs/promises";
+import { join } from "node:path";
+
+import {
+  AGENTFS_BACKEND_NAME,
+  resolveDataDir,
+  resolveSessionsDir,
+} from "../agentfs/paths.js";
+import type { HostRegistry } from "./host.js";
+
+let prunePromise: Promise<void> | null = null;
+
+/** 进程内只跑一轮 stale prune（失败不阻塞 create）。 */
+export function maybePruneStaleSessions(
+  appRoot: string,
+  registry: HostRegistry,
+): Promise<void> {
+  if (prunePromise) return prunePromise;
+  prunePromise = pruneStaleSessions(appRoot, registry).catch((err) => {
+    console.warn(`[${AGENTFS_BACKEND_NAME}] stale-session prune failed:`, err);
+  });
+  return prunePromise;
+}
+
+export async function pruneStaleSessions(
+  appRoot: string,
+  registry: HostRegistry,
+): Promise<void> {
+  const dataDir = resolveDataDir(appRoot);
+  const sessionsDir = resolveSessionsDir(dataDir);
+
+  let entries: import("node:fs").Dirent[];
+  try {
+    entries = await readdir(sessionsDir, { withFileTypes: true });
+  } catch {
+    // 目录不存在（首次启动）
+    return;
+  }
+
+  const maxAgeDays = Number(process.env.AGENTFS_SESSION_MAX_AGE_DAYS ?? 30);
+  if (!Number.isFinite(maxAgeDays) || maxAgeDays <= 0) return;
+
+  const maxAgeMs = maxAgeDays * 86_400_000;
+  const now = Date.now();
+
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith(".db")) continue;
+    // 忽略 wal/shm 旁车（名字以 .db-wal 结尾的不会 match .db 精确后缀之外的情况；
+    // 这里 name.endsWith(".db") 已排除 .db-wal / .db-shm）
+    const sessionKey = entry.name.slice(0, -".db".length);
+    if (registry.hasActiveSession(sessionKey)) continue;
+
+    const dbPath = join(sessionsDir, entry.name);
+    try {
+      const s = await stat(dbPath);
+      if (now - s.mtimeMs > maxAgeMs) {
+        await rm(dbPath, { force: true });
+      }
+    } catch {
+      // 单文件失败不阻塞整体 prune
+    }
+  }
+}

agent/lib/agentfs-sandbox/session.ts

@@ -0,0 +1,369 @@
+/**
+ * InternalSandboxSession 原语 + 公开 SandboxSession 表面。
+ *
+ * 契约对齐 eve 内部 `buildSandboxSession` / `createFileBackedInternalSandboxSession`：
+ * - 后端只实现字节级 read/write、spawn、removePath、resolvePath
+ * - 公开表面负责 encoding、行范围、run 包装、二进制/文本变体
+ * - 公开层在委托前 resolvePath；内部方法收到的 path 已是解析后的绝对路径
+ */
+
+import { dirname } from "node:path";
+
+import type {
+  SandboxProcess,
+  SandboxSession,
+  SandboxNetworkPolicy,
+} from "eve/sandbox";
+import type { IFileSystem } from "just-bash";
+
+import { resolveWorkspacePath } from "../agentfs/paths.js";
+import type { JustBashSandboxInstance } from "./host.js";
+import {
+  adaptCommandToSandboxProcess,
+  type MultiplexedCommand,
+} from "./process.js";
+
+/** 与 AI SDK / eve InternalSandboxSession 对齐的最小原语集。 */
+export interface InternalSandboxSession {
+  readonly id: string;
+  resolvePath(path: string): string;
+  spawn(opts: {
+    command: string;
+    env?: Record<string, string>;
+    abortSignal?: AbortSignal;
+    workingDirectory?: string;
+  }): Promise<SandboxProcess>;
+  readFile(opts: {
+    path: string;
+    abortSignal?: AbortSignal;
+  }): Promise<ReadableStream<Uint8Array> | null>;
+  writeFile(opts: {
+    path: string;
+    content: ReadableStream<Uint8Array>;
+    abortSignal?: AbortSignal;
+  }): Promise<void>;
+  removePath(opts: {
+    path: string;
+    force?: boolean;
+    recursive?: boolean;
+    abortSignal?: AbortSignal;
+  }): Promise<void>;
+}
+
+/** shell 单引号转义（与 eve shell-quote 同构）。 */
+function shellQuote(value: string): string {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+function isNotFound(err: unknown): boolean {
+  const msg = err instanceof Error ? err.message : String(err);
+  return msg.includes("not found") || msg.includes("ENOENT");
+}
+
+async function streamToBytes(
+  stream: ReadableStream<Uint8Array>,
+): Promise<Uint8Array> {
+  const reader = stream.getReader();
+  const parts: Uint8Array[] = [];
+  let total = 0;
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    if (value) {
+      parts.push(value);
+      total += value.length;
+    }
+  }
+  const out = new Uint8Array(total);
+  let pos = 0;
+  for (const part of parts) {
+    out.set(part, pos);
+    pos += part.length;
+  }
+  return out;
+}
+
+function bytesToStream(bytes: Uint8Array): ReadableStream<Uint8Array> {
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      controller.enqueue(bytes);
+      controller.close();
+    },
+  });
+}
+
+async function readBytesFromFs(
+  fs: IFileSystem,
+  path: string,
+): Promise<Uint8Array> {
+  return await fs.readFileBuffer(path);
+}
+
+/**
+ * 从 just-bash Sandbox + 已 pad 的 IFileSystem 构造内部 session。
+ * id 使用 sessionKey（与官方 just-bash 一致，便于跨重连识别）。
+ */
+export function buildInternalSession(opts: {
+  id: string;
+  sandbox: JustBashSandboxInstance;
+  fs: IFileSystem;
+}): InternalSandboxSession {
+  const { id, sandbox, fs } = opts;
+
+  return {
+    id,
+    resolvePath: resolveWorkspacePath,
+
+    async spawn(spawnOpts) {
+      if (spawnOpts.abortSignal?.aborted) {
+        throw new DOMException("The operation was aborted.", "AbortError");
+      }
+      // workingDirectory 用子 shell cd 包住（与 eve just-bash-runtime 一致）
+      const command =
+        spawnOpts.workingDirectory === undefined
+          ? spawnOpts.command
+          : `( cd ${shellQuote(spawnOpts.workingDirectory)} && ${spawnOpts.command} )`;
+
+      const cmd = await sandbox.runCommand({
+        cmd: "eval",
+        args: [command],
+        detached: true,
+        env: spawnOpts.env,
+        signal: spawnOpts.abortSignal,
+      });
+      return adaptCommandToSandboxProcess(cmd as unknown as MultiplexedCommand);
+    },
+
+    async readFile({ path }) {
+      // path 已由公开层 resolvePath
+      try {
+        const bytes = await readBytesFromFs(fs, path);
+        return bytesToStream(bytes);
+      } catch (err) {
+        if (isNotFound(err)) return null;
+        throw err;
+      }
+    },
+
+    async writeFile({ path, content }) {
+      const parent = dirname(path);
+      if (parent && parent !== "/") {
+        try {
+          await fs.mkdir(parent, { recursive: true });
+        } catch {
+          // parent 已存在 / 是文件时，下一行 writeFile 会给出真实错误
+        }
+      }
+      const bytes = await streamToBytes(content);
+      await fs.writeFile(path, bytes);
+    },
+
+    async removePath({ path, force, recursive }) {
+      try {
+        await fs.rm(path, { force, recursive });
+      } catch (err) {
+        if (force && isNotFound(err)) return;
+        throw err;
+      }
+    },
+  };
+}
+
+/** just-bash 不支持运行时改网络策略——与官方后端同语义抛错。 */
+export async function setNetworkPolicyUnsupported(
+  _policy: SandboxNetworkPolicy,
+): Promise<void> {
+  throw new Error(
+    "setNetworkPolicy() is not supported on the agentfs-just-bash backend. " +
+      "just-bash applies its network policy only at sandbox creation " +
+      "(no run-time update) and does not run git or other binaries.",
+  );
+}
+
+function validateReadTextFileOptions(opts: {
+  startLine?: number;
+  endLine?: number;
+}): void {
+  const { startLine, endLine } = opts;
+  if (startLine !== undefined && (!Number.isInteger(startLine) || startLine < 1)) {
+    throw new Error("startLine must be a positive integer (1-based).");
+  }
+  if (endLine !== undefined && (!Number.isInteger(endLine) || endLine < 1)) {
+    throw new Error("endLine must be a positive integer (1-based).");
+  }
+  if (
+    startLine !== undefined &&
+    endLine !== undefined &&
+    startLine > endLine
+  ) {
+    throw new Error("startLine must not be greater than endLine.");
+  }
+}
+
+function splitLinesPreservingEndings(text: string): string[] {
+  const lines: string[] = [];
+  let start = 0;
+  for (let i = 0; i < text.length; i++) {
+    if (text[i] === "\r") {
+      if (i + 1 < text.length && text[i + 1] === "\n") {
+        lines.push(text.slice(start, i + 2));
+        start = i + 2;
+        i++;
+      } else {
+        lines.push(text.slice(start, i + 1));
+        start = i + 1;
+      }
+    } else if (text[i] === "\n") {
+      lines.push(text.slice(start, i + 1));
+      start = i + 1;
+    }
+  }
+  if (start < text.length) lines.push(text.slice(start));
+  return lines;
+}
+
+function applyLineRange(
+  text: string,
+  opts: { startLine?: number; endLine?: number },
+): string {
+  if (opts.startLine === undefined && opts.endLine === undefined) return text;
+  const lines = splitLinesPreservingEndings(text);
+  const total = lines.length;
+  const from = opts.startLine ?? 1;
+  const to = Math.min(opts.endLine ?? total, total);
+  if (from > total) return "";
+  return lines.slice(from - 1, to).join("");
+}
+
+function decodeBytes(bytes: Uint8Array, encoding: string): string {
+  if (encoding === "utf-8" || encoding === "utf8") {
+    return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  }
+  return Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString(
+    encoding as BufferEncoding,
+  );
+}
+
+function encodeString(text: string, encoding: string): Uint8Array {
+  if (encoding === "utf-8" || encoding === "utf8") {
+    return new TextEncoder().encode(text);
+  }
+  return new Uint8Array(Buffer.from(text, encoding as BufferEncoding));
+}
+
+async function collectStreamToString(
+  stream: ReadableStream<Uint8Array>,
+): Promise<string> {
+  return new TextDecoder().decode(await streamToBytes(stream));
+}
+
+/**
+ * 从内部原语构造完整公开 SandboxSession。
+ * 行为对齐 eve `buildSandboxSession`（encoding / 行范围 / run 包装）。
+ */
+export function buildPublicSession(
+  internal: InternalSandboxSession,
+  setNetworkPolicy: (
+    policy: SandboxNetworkPolicy,
+  ) => Promise<void> = setNetworkPolicyUnsupported,
+): SandboxSession {
+  return {
+    id: internal.id,
+    resolvePath: (path) => internal.resolvePath(path),
+
+    async run(opts) {
+      const proc = await internal.spawn({
+        command: opts.command,
+        env: opts.env,
+        abortSignal: opts.abortSignal,
+        workingDirectory: opts.workingDirectory,
+      });
+      const [stdout, stderr, exit] = await Promise.all([
+        collectStreamToString(proc.stdout),
+        collectStreamToString(proc.stderr),
+        proc.wait(),
+      ]);
+      return { exitCode: exit.exitCode, stdout, stderr };
+    },
+
+    async spawn(opts) {
+      return await internal.spawn({
+        command: opts.command,
+        env: opts.env,
+        abortSignal: opts.abortSignal,
+        workingDirectory: opts.workingDirectory,
+      });
+    },
+
+    async readFile(opts) {
+      return await internal.readFile({
+        abortSignal: opts.abortSignal,
+        path: internal.resolvePath(opts.path),
+      });
+    },
+
+    async readBinaryFile(opts) {
+      const stream = await internal.readFile({
+        abortSignal: opts.abortSignal,
+        path: internal.resolvePath(opts.path),
+      });
+      return stream === null ? null : await streamToBytes(stream);
+    },
+
+    async readTextFile(opts) {
+      validateReadTextFileOptions(opts);
+      const stream = await internal.readFile({
+        abortSignal: opts.abortSignal,
+        path: internal.resolvePath(opts.path),
+      });
+      if (stream === null) return null;
+      const text = decodeBytes(
+        await streamToBytes(stream),
+        opts.encoding ?? "utf-8",
+      );
+      return applyLineRange(text, opts);
+    },
+
+    async writeFile(opts) {
+      await internal.writeFile({
+        abortSignal: opts.abortSignal,
+        content: opts.content,
+        path: internal.resolvePath(opts.path),
+      });
+    },
+
+    async writeBinaryFile(opts) {
+      const bytes =
+        opts.content instanceof Uint8Array
+          ? opts.content
+          : new Uint8Array(opts.content);
+      await internal.writeFile({
+        abortSignal: opts.abortSignal,
+        content: bytesToStream(bytes),
+        path: internal.resolvePath(opts.path),
+      });
+    },
+
+    async writeTextFile(opts) {
+      const bytes = encodeString(opts.content, opts.encoding ?? "utf-8");
+      await internal.writeFile({
+        abortSignal: opts.abortSignal,
+        content: bytesToStream(bytes),
+        path: internal.resolvePath(opts.path),
+      });
+    },
+
+    async removePath(opts) {
+      await internal.removePath({
+        abortSignal: opts.abortSignal,
+        force: opts.force,
+        path: internal.resolvePath(opts.path),
+        recursive: opts.recursive,
+      });
+    },
+
+    setNetworkPolicy,
+  };
+}
+
+export { streamToBytes, bytesToStream };

agent/lib/agentfs/paths.ts

@@ -0,0 +1,62 @@
+/**
+ * AgentFS 沙箱数据布局与路径解析。
+ *
+ * 布局（`<dataDir>/agentfs/<backendName>/`）：
+ *   templates/<templateKey>.db   模板库（prewarm 捕获）
+ *   sessions/<sessionKey>.db     每个 eve session 一个独立库
+ *
+ * `dataDir`：`EVEAGENT_DATA_DIR` 优先，否则 `<appRoot>/data`。
+ * sessionKey 已被 eve `sanitizeRuntimeSandboxKey` 限到 `[a-zA-Z0-9._-]{1,120}`，可直接当文件名。
+ */
+
+import { join, resolve } from "node:path";
+
+/** 与 defineSandbox backend.name 一致，参与 cache-key 与 reconnect 校验。 */
+export const AGENTFS_BACKEND_NAME = "agentfs-just-bash";
+
+/** eve sandbox 工作根（所有后端统一命名空间）。 */
+export const WORKSPACE_ROOT = "/workspace";
+
+/** 数据目录根：`EVEAGENT_DATA_DIR` 优先，否则 `<appRoot>/data`（缺省 appRoot 用 cwd）。 */
+export function resolveDataDir(appRoot?: string): string {
+  const fromEnv = process.env.EVEAGENT_DATA_DIR?.trim();
+  if (fromEnv) return resolve(fromEnv);
+  return resolve(appRoot ?? process.cwd(), "data");
+}
+
+/** `<dataDir>/agentfs/<backendName>` */
+export function resolveBackendRoot(dataDir: string): string {
+  return join(dataDir, "agentfs", AGENTFS_BACKEND_NAME);
+}
+
+/** 模板库目录。 */
+export function resolveTemplatesDir(dataDir: string): string {
+  return join(resolveBackendRoot(dataDir), "templates");
+}
+
+/** sessions 库目录。 */
+export function resolveSessionsDir(dataDir: string): string {
+  return join(resolveBackendRoot(dataDir), "sessions");
+}
+
+/** 模板库路径（per-templateKey）。 */
+export function resolveTemplateDbPath(
+  dataDir: string,
+  templateKey: string,
+): string {
+  return join(resolveTemplatesDir(dataDir), `${templateKey}.db`);
+}
+
+/** session 库路径（per-sessionKey）。 */
+export function resolveSessionDbPath(
+  dataDir: string,
+  sessionKey: string,
+): string {
+  return join(resolveSessionsDir(dataDir), `${sessionKey}.db`);
+}
+
+/** 把 eve sandbox 相对路径锚定到 `/workspace/...`；绝对路径原样透传。 */
+export function resolveWorkspacePath(path: string): string {
+  if (!path || path === "/") return WORKSPACE_ROOT;
+  return path.startsWith("/") ? path : `${WORKSPACE_ROOT}/${path}`;
+}

agent/sandbox.ts

@@ -1,681 +1,19 @@
 /**
- * Eve SandboxBackend：把 just-bash 的虚拟文件系统落到 AgentFS 上。
+ * Eve sandbox 定义：AgentFS 持久化 + just-bash 解释器。
  *
- * 单文件后端，无子包依赖。实现 eve 0.22.x 的 `SandboxBackend` 契约：
- * - name          "agentfs-just-bash"（profile 重启识别用）
- * - prewarm       模板级：把 AgentFS 模板库 + just-bash `Sandbox` 缓存到 per-templateKey Map
- * - create        session 级：每个 durable session 一个独立 AgentFS 数据库 + 独立 `Sandbox`，
- *                 通过 `existingMetadata.dbPath` 跨重启命中同一库
+ * 实现细节在 `lib/agentfs-sandbox/`，本文件只做 defineSandbox 入口。
  *
- * 数据目录布局（`<dataDir>/agentfs/<backendName>/`）：
- *   templates/<templateKey>.db   模板库（prewarm 用；当前 evework 无 bootstrap，目录空）
- *   sessions/<sessionKey>.db     每个 eve session 一个独立库
- *
- * 关键事实：
- * - `dataDir` 取自 `EVEAGENT_DATA_DIR`，否则用 `<appRoot>/data`。
- * - sessionKey 由 eve runtime 派生（`runtime/sandbox/keys.js:11-13, 21-22`），
- *   已经被 `sanitizeRuntimeSandboxKey` 限到 `[a-zA-Z0-9._-]{1,120}`，可直接当文件名。
- * - just-bash 没有真后台，`spawn` 通过 `Sandbox.runCommand({ detached: true })`
- *   拿到返回的 `Command`，单次消费 `command.logs()` 再 fan-out 到 stdout/stderr 流，
- *   适配 eve `SandboxProcess` 形状。
- * - `setNetworkPolicy()` just-bash 不支持；按 eve 内部语义抛错，避免误用。
- * - HF Space 容器非持久；务必把 `EVEAGENT_DATA_DIR` 指向持久卷，
- *   否则 per-session 数据库随容器回收即丢。
- */
-
-import { mkdir } from "node:fs/promises";
-import { dirname } from "node:path";
-
-import {
-  defineSandbox,
-  type SandboxBackend,
-  type SandboxBackendCreateInput,
-  type SandboxBackendHandle,
-  type SandboxBackendPrewarmInput,
-  type SandboxBackendRuntimeContext,
-  type SandboxBackendSessionState,
-  type SandboxSession,
-} from "eve/sandbox";
-
-import { AgentFS } from "agentfs-sdk";
-import { AgentFsWrapper as JustBashFsWrapper } from "agentfs-sdk/just-bash";
-import {
-  Sandbox as JustBashSandbox,
-  type IFileSystem,
-} from "just-bash";
-
-const BACKEND_NAME = "agentfs-just-bash";
-const WORKSPACE_ROOT = "/workspace";
-
-/** 数据目录根。`EVEAGENT_DATA_DIR` 优先，否则退到 `<appRoot>/data`。 */
-function resolveDataDir(appRoot: string): string {
-  return process.env.EVEAGENT_DATA_DIR ?? `${appRoot}/data`;
-}
-
-/** AgentFS 模板库路径（per-templateKey）。 */
-function resolveTemplateDbPath(dataDir: string, templateKey: string): string {
-  return `${dataDir}/agentfs/${BACKEND_NAME}/templates/${templateKey}.db`;
-}
-
-/** AgentFS session 库路径（per-sessionKey）。 */
-function resolveSessionDbPath(dataDir: string, sessionKey: string): string {
-  return `${dataDir}/agentfs/${BACKEND_NAME}/sessions/${sessionKey}.db`;
-}
-
-/** Session 库所在目录。prune 用。 */
-function resolveSessionDbDir(dataDir: string): string {
-  return `${dataDir}/agentfs/${BACKEND_NAME}/sessions`;
-}
-
-/** 把 eve sandbox 相对路径锚定到 `/workspace/...`。绝对路径原样透传。 */
-function resolveWorkspacePath(p: string): string {
-  if (!p || p === "/") return WORKSPACE_ROOT;
-  return p.startsWith("/") ? p : `${WORKSPACE_ROOT}/${p}`;
-}
-
-/** 进程级单例：同一进程内所有 eve session 共享同一 AgentFS 数据库与 just-bash 解释器。 */
-interface AgentFsHost {
-  agentFs: Awaited<ReturnType<typeof AgentFS.open>>;
-  // Sandbox 的 constructor 是 private 的，`InstanceType<typeof Sandbox>` 拿不到。
-  // host 持有的就是 `JustBashSandbox.create(...)` 的返回值，按 await 后的类型推。
-  sandbox: Awaited<ReturnType<typeof JustBashSandbox.create>>;
-  fs: IFileSystem;
-  dbPath: string;
-}
-
-/**
- * just-bash 内部 `$a` 函数对 `IFileSystem` 做统一 wrap：
- * 它**不区分** optional methods，对每个属性（如 `realpath`、`utimes`、`readFileBuffer`、
- * `readdirWithFileTypes`）都 `bind` 调用一遍。
- * `AgentFsWrapper` 缺这些方法 -> `undefined.bind` 抛错 -> `eval` 全部命令失败。
- *
- * 这里包装一层把所有 just-bash 期望的 optional 方法补全成最小行为 stub，
- * 行为差异：
- *  - realpath/utimes：不涉及，noop
- *  - readFileBuffer / readFileBytes：调 readFile 后转 Uint8Array
- *  - readdirWithFileTypes：与 readdir 同结果（不返回 types）
- *  - appendFile / writeFileBytes：用 readFile + writeFile 模拟
- *  - getAllPaths：返回 []（AgentFS 不支持列出所有路径）
- */
-function padJustBashFs(inner: IFileSystem): IFileSystem {
-  const readFileBuffer = async (path: string): Promise<Uint8Array> => {
-    const text = await inner.readFile(path, "utf-8");
-    return new TextEncoder().encode(text);
-  };
-  const writeFileBytes = async (
-    path: string,
-    bytes: Uint8Array,
-  ): Promise<void> => {
-    await inner.writeFile(path, bytes);
-  };
-  const appendFile = async (
-    path: string,
-    content: string | Uint8Array,
-  ): Promise<void> => {
-    const next = content instanceof Uint8Array ? content : new TextEncoder().encode(content);
-    let existing: Uint8Array;
-    try {
-      existing = await readFileBuffer(path);
-    } catch {
-      existing = new Uint8Array(0);
-    }
-    const merged = new Uint8Array(existing.length + next.length);
-    merged.set(existing, 0);
-    merged.set(next, existing.length);
-    await inner.writeFile(path, merged);
-  };
-  const readdirWithFileTypes = async (path: string) => {
-    const names = await inner.readdir(path);
-    return names.map((name: string) => ({ name }));
-  };
-  const chmod = async (_path: string, _mode: number): Promise<void> => {
-    // noop: AgentFS 不支持 chmod，AgentFsWrapper 内部已经 no-op，这里再垫一层。
-  };
-  const utimes = async (
-    _path: string,
-    _atime: number | Date,
-    _mtime: number | Date,
-  ): Promise<void> => {
-    // noop: AgentFS 不支持 utimes
-  };
-  const realpath = async (path: string): Promise<string> => path;
-  const getAllPaths = (): string[] => [];
-  return Object.assign(Object.create(inner), {
-    readFileBuffer,
-    writeFileBytes,
-    appendFile,
-    readdirWithFileTypes,
-    chmod,
-    utimes,
-    realpath,
-    getAllPaths,
-  });
-}
-
-/** 进程级 host 缓存。键是 dbPath 而非 templateKey/sessionKey——同一路径命中复用，
- *  不同路径天然分库。prune 时通过 `sessionHostsByDbPath` 反查活跃引用。 */
-const hostsByDbPath = new Map<string, AgentFsHost>();
-/** 反向索引：sessionKey → dbPath，用于 prune 跳过活跃 session。 */
-const sessionHostsBySessionKey = new Map<string, string>();
-
-/** 从 dbPath 拆出 sessionKey。仅识别 `<sessionsDir>/<key>.db` 形状。 */
-function dbPathToSessionKey(sessionsDir: string, dbPath: string): string | null {
-  if (!dbPath.startsWith(sessionsDir + "/")) return null;
-  const rest = dbPath.slice(sessionsDir.length + 1);
-  if (!rest.endsWith(".db")) return null;
-  return rest.slice(0, -".db".length);
-}
-
-/**
- * 打开（命中复用）一个 session 或 template 的 AgentFS + just-bash 组合。
- *
- * - 命中缓存 → 直接返回（避免重复 SQLite open）
- * - 否则 → mkdir parent → `AgentFS.open` → `padJustBashFs` 包装 → `JustBashSandbox.create`
- * - session 还会记录到 `sessionHostsBySessionKey` 供 prune 用
- */
-async function getOrOpenHost(opts: {
-  dbPath: string;
-  isSession: boolean;
-  sessionKey?: string;
-}): Promise<AgentFsHost> {
-  const { dbPath, isSession, sessionKey } = opts;
-  const cached = hostsByDbPath.get(dbPath);
-  if (cached) return cached;
-  await mkdir(dirname(dbPath), { recursive: true });
-  const agentFs = await AgentFS.open({ path: dbPath });
-  // 直接构造 `AgentFsWrapper`：`agentfs()` 工厂的运行时类型守卫
-  // （`handle.fs?.stat === "function"`）在 Node 24 + pnpm 软链下走错兜底分支，
-  // 会触发 `AgentFS.open({ fs: handle })` 二次 open 包成 options 报错。
-  // 我们已经有 typed handle，直接 wrap 没有歧义。
-  // 再用 `padJustBashFs` 把 just-bash `$a` wrap 时一视同仁调到的
-  // optional 方法（realpath/utimes/readFileBuffer/…）补成 stub，
-  // 否则 `eval` 解析时会 `Cannot read properties of undefined (reading 'bind')`。
-  // AgentFsWrapper implements IFileSystem 但缺 realpath/utimes 这两个 optional 方法，
-  // padJustBashFs 会补；类型层 cast 到 IFileSystem 让 TS 不挑刺。
-  const wrapped = padJustBashFs(
-    new JustBashFsWrapper({ fs: agentFs }) as unknown as IFileSystem,
-  );
-  // just-bash 默认无网络、无 curl；websearch 子 agent（anysearch / firecrawl）需要 POST。
-  // 仅放行检索相关 API，不用全网开放。
-  const sandboxEnv: Record<string, string> = {};
-  for (const key of ["ANYSEARCH_API_KEY", "FIRECRAWL_API_KEY"] as const) {
-    const v = process.env[key]?.trim();
-    if (v) sandboxEnv[key] = v;
-  }
-  const sandbox = await JustBashSandbox.create({
-    cwd: WORKSPACE_ROOT,
-    env: sandboxEnv,
-    fs: wrapped,
-    network: {
-      allowedUrlPrefixes: [
-        "https://api.anysearch.com/",
-        "https://api.firecrawl.dev/",
-      ],
-      allowedMethods: ["GET", "HEAD", "POST"],
-    },
-  });
-  // /workspace 是 eve sandbox 的工作根；Sandbox.create 不会自动建该目录
-  try {
-    await sandbox.mkDir(WORKSPACE_ROOT, { recursive: true });
-  } catch {
-    // 已存在 / 不支持递归都可忽略——写文件时 ifs 会按需 mkdir
-  }
-  const host: AgentFsHost = { agentFs, sandbox, fs: wrapped, dbPath };
-  hostsByDbPath.set(dbPath, host);
-  if (isSession && sessionKey) {
-    sessionHostsBySessionKey.set(sessionKey, dbPath);
-  }
-  return host;
-}
-
-/** 把 `ReadableStream<Uint8Array>` 全部读完得到合并后的字节。 */
-async function streamToBytes(stream: ReadableStream<Uint8Array>): Promise<Uint8Array> {
-  const reader = stream.getReader();
-  const parts: Uint8Array[] = [];
-  let total = 0;
-  while (true) {
-    const { done, value } = await reader.read();
-    if (done) break;
-    if (value) {
-      parts.push(value);
-      total += value.length;
-    }
-  }
-  const out = new Uint8Array(total);
-  let pos = 0;
-  for (const part of parts) {
-    out.set(part, pos);
-    pos += part.length;
-  }
-  return out;
-}
-
-/**
- * 把 just-bash `Command`（有 `logs()` 异步迭代 + `wait()` + `kill()`）
- * 适配为 eve `SandboxProcess`（stdout/stderr 是 `ReadableStream<Uint8Array>`）。
- *
- * just-bash 的 `logs()` 在命令结束后才 yield（先 await 完整结果），
- * 因此这里**只消费一次** logs，再按 type 拆到两条流，避免双消费者竞态。
- */
-interface JustBashCommandLike {
-  logs(): AsyncIterable<{ type: "stdout" | "stderr"; data: string }>;
-  wait(): Promise<{ exitCode: number }>;
-  kill(): Promise<void> | void;
-}
-
-function adaptCommandToSandboxProcess(command: JustBashCommandLike) {
-  const encoder = new TextEncoder();
-
-  // 共享一次 collect：stdout/stderr 流都从同一结果分发
-  let collected: Promise<{
-    stdout: Uint8Array[];
-    stderr: Uint8Array[];
-  }> | null = null;
-
-  function collectLogs() {
-    if (!collected) {
-      collected = (async () => {
-        const stdout: Uint8Array[] = [];
-        const stderr: Uint8Array[] = [];
-        for await (const msg of command.logs()) {
-          const chunk = encoder.encode(msg.data);
-          if (msg.type === "stdout") stdout.push(chunk);
-          else stderr.push(chunk);
-        }
-        return { stdout, stderr };
-      })();
-    }
-    return collected;
-  }
-
-  function streamOf(kind: "stdout" | "stderr") {
-    return new ReadableStream<Uint8Array>({
-      async start(controller) {
-        try {
-          const parts = (await collectLogs())[kind];
-          for (const part of parts) controller.enqueue(part);
-          controller.close();
-        } catch (err) {
-          controller.error(err);
-        }
-      },
-    });
-  }
-
-  return {
-    stdout: streamOf("stdout"),
-    stderr: streamOf("stderr"),
-    async wait() {
-      return await command.wait();
-    },
-    async kill() {
-      await Promise.resolve(command.kill());
-    },
-  };
-}
-
-/** InternalSandboxSession 的最小字段集合——只暴露 eve 真正下传的方法。 */
-interface InternalSandboxSession {
-  id: string;
-  resolvePath(p: string): string;
-  spawn(opts: {
-    command: string;
-    env?: Record<string, string>;
-    abortSignal?: AbortSignal;
-  }): Promise<ReturnType<typeof adaptCommandToSandboxProcess>>;
-  readFile(opts: {
-    path: string;
-    abortSignal?: AbortSignal;
-  }): Promise<ReadableStream<Uint8Array> | null>;
-  writeFile(opts: {
-    path: string;
-    content: ReadableStream<Uint8Array>;
-    abortSignal?: AbortSignal;
-  }): Promise<void>;
-  removePath(opts: {
-    path: string;
-    force?: boolean;
-    recursive?: boolean;
-    abortSignal?: AbortSignal;
-  }): Promise<void>;
-}
-
-function buildInternalSession(
-  sandbox: Awaited<ReturnType<typeof JustBashSandbox.create>>,
-  fs: IFileSystem,
-): InternalSandboxSession {
-  return {
-    id: "agentfs-just-bash",
-    resolvePath: resolveWorkspacePath,
-    async spawn(opts) {
-      if (opts.abortSignal?.aborted) {
-        throw new DOMException("The operation was aborted.", "AbortError");
-      }
-      const command = await sandbox.runCommand({
-        cmd: "eval",
-        args: [opts.command],
-        detached: true,
-        env: opts.env,
-        signal: opts.abortSignal,
-      });
-      return adaptCommandToSandboxProcess(command as unknown as JustBashCommandLike);
-    },
-    async readFile({ path }) {
-      const norm = resolveWorkspacePath(path);
-      try {
-        const bytes = await readBytesFromFs(fs, norm);
-        return new ReadableStream<Uint8Array>({
-          start(c) {
-            c.enqueue(bytes);
-            c.close();
-          },
-        });
-      } catch (err) {
-        if (isNotFound(err)) return null;
-        throw err;
-      }
-    },
-    async writeFile({ path, content }) {
-      const norm = resolveWorkspacePath(path);
-      const parent = dirname(norm);
-      if (parent && parent !== "/") {
-        try {
-          await fs.mkdir(parent, { recursive: true });
-        } catch {
-          // parent 可能是文件 / 已存在 / 平台差异——下一行写文件失败时再报错
-        }
-      }
-      const bytes = await streamToBytes(content);
-      await fs.writeFile(norm, bytes);
-    },
-    async removePath({ path, force, recursive }) {
-      const norm = resolveWorkspacePath(path);
-      try {
-        await fs.rm(norm, { force, recursive });
-      } catch (err) {
-        if (force && isNotFound(err)) return;
-        throw err;
-      }
-    },
-  };
-}
-
-/** 优先 `readFileBuffer`（已是 Uint8Array），否则按 utf-8 解码 `readFile`。 */
-async function readBytesFromFs(
-  fs: IFileSystem,
-  norm: string,
-): Promise<Uint8Array> {
-  const maybe = (fs as unknown as {
-    readFileBuffer?: (path: string) => Promise<Uint8Array>;
-  }).readFileBuffer;
-  if (typeof maybe === "function") {
-    return await maybe.call(fs, norm);
-  }
-  const text = await fs.readFile(norm, "utf-8");
-  return new TextEncoder().encode(text);
-}
-
-function isNotFound(err: unknown): boolean {
-  const msg = err instanceof Error ? err.message : String(err);
-  return msg.includes("not found") || msg.includes("ENOENT");
-}
-
-/** just-bash 后端的 network policy 不可中途修改——按 eve 内部语义抛错。 */
-async function setNetworkPolicyUnsupported(): Promise<void> {
-  throw new Error(
-    "setNetworkPolicy() is not supported on the agentfs-just-bash backend. " +
-      "just-bash applies its network policy only at sandbox creation " +
-      "(no run-time update) and does not run git or other binaries.",
-  );
-}
-
-/** 仿 eve 内部 `buildSandboxSession`：把内部 session 包装成公开 surface。 */
-function buildPublicSession(internal: InternalSandboxSession): SandboxSession {
-  async function streamToString(stream: ReadableStream<Uint8Array>): Promise<string> {
-    return new TextDecoder().decode(await streamToBytes(stream));
-  }
-
-  return {
-    id: internal.id,
-    resolvePath: internal.resolvePath,
-
-    async run(opts) {
-      const proc = await internal.spawn({
-        command: opts.command,
-        env: opts.env,
-        abortSignal: opts.abortSignal,
-      });
-      const [stdout, stderr, exit] = await Promise.all([
-        streamToString(proc.stdout),
-        streamToString(proc.stderr),
-        proc.wait(),
-      ]);
-      return { exitCode: exit.exitCode, stdout, stderr };
-    },
-
-    spawn(opts) {
-      return internal.spawn({
-        command: opts.command,
-        env: opts.env,
-        abortSignal: opts.abortSignal,
-      });
-    },
-
-    async readFile(opts) {
-      return internal.readFile({ path: opts.path, abortSignal: opts.abortSignal });
-    },
-    async readBinaryFile(opts) {
-      const s = await internal.readFile({ path: opts.path, abortSignal: opts.abortSignal });
-      return s ? await streamToBytes(s) : null;
-    },
-    async readTextFile(opts) {
-      const s = await internal.readFile({ path: opts.path, abortSignal: opts.abortSignal });
-      if (!s) return null;
-      return new TextDecoder().decode(await streamToBytes(s));
-    },
-
-    async writeFile(opts) {
-      await internal.writeFile({
-        path: opts.path,
-        content: opts.content,
-        abortSignal: opts.abortSignal,
-      });
-    },
-    async writeBinaryFile(opts) {
-      const bytes = opts.content instanceof Uint8Array ? opts.content : new Uint8Array(opts.content);
-      await internal.writeFile({
-        path: opts.path,
-        content: new ReadableStream<Uint8Array>({
-          start(c) {
-            c.enqueue(bytes);
-            c.close();
-          },
-        }),
-        abortSignal: opts.abortSignal,
-      });
-    },
-    async writeTextFile(opts) {
-      const bytes = new TextEncoder().encode(opts.content);
-      await internal.writeFile({
-        path: opts.path,
-        content: new ReadableStream<Uint8Array>({
-          start(c) {
-            c.enqueue(bytes);
-            c.close();
-          },
-        }),
-        abortSignal: opts.abortSignal,
-      });
-    },
-
-    async removePath(opts) {
-      await internal.removePath({
-        path: opts.path,
-        force: opts.force,
-        recursive: opts.recursive,
-        abortSignal: opts.abortSignal,
-      });
-    },
-
-    setNetworkPolicy: setNetworkPolicyUnsupported,
-  };
-}
-
-/**
- * 把 `existingMetadata` 严格解出 dbPath。版本不匹配或字段缺失一律丢弃（记 warn）。
- * 这是 sandbox-backend metadata schema v1 的契约校验点。
+ * 数据布局见 `lib/agentfs/paths.ts`。
+ * HF Space 容器非持久；务必把 `EVEAGENT_DATA_DIR` 指向持久卷。
  */
-function resolveExistingDbPath(
-  input: SandboxBackendCreateInput,
-): string | null {
-  const m = input.existingMetadata as Record<string, unknown> | undefined;
-  if (!m) return null;
-  if (m.version !== 1) {
-    if (typeof m.dbPath === "string") {
-      console.warn(
-        `[${BACKEND_NAME}] dropping legacy metadata dbPath=${m.dbPath}; ` +
-          `rebuilding session ${input.sessionKey} from scratch`,
-      );
-    }
-    return null;
-  }
-  if (typeof m.dbPath !== "string") {
-    return null;
-  }
-  return m.dbPath;
-}
-
-let prunePromise: Promise<void> | null = null;
-/** 第一次 open session host 时 lazy 触发一次 prune，避免硬编码到 Nitro 启动 hook。 */
-function maybePruneStaleSessions(appRoot: string): Promise<void> {
-  if (prunePromise) return prunePromise;
-  prunePromise = pruneStaleSessions(appRoot).catch((err) => {
-    // prune 失败不应阻塞 session 创建；仅记录
-    console.warn(`[${BACKEND_NAME}] stale-session prune failed:`, err);
-  });
-  return prunePromise;
-}
-
-/**
- * 清理 sessions 目录下 mtime 超过 `AGENTFS_SESSION_MAX_AGE_DAYS` 天的 `.db` 文件。
- * - 跳过 `sessionHostsBySessionKey` 仍在引用的活跃 session
- * - 不动 `templates/`（template 是 build plan 派生，删错要重 build）
- */
-async function pruneStaleSessions(appRoot: string): Promise<void> {
-  const { readdir, stat, rm } = await import("node:fs/promises");
-  const dataDir = resolveDataDir(appRoot);
-  const sessionsDir = resolveSessionDbDir(dataDir);
-  let entries: import("node:fs").Dirent[];
-  try {
-    entries = await readdir(sessionsDir, { withFileTypes: true });
-  } catch {
-    // 目录不存在（首次启动）—无需清理
-    return;
-  }
-  const maxAgeDays = Number(
-    process.env.AGENTFS_SESSION_MAX_AGE_DAYS ?? 30,
-  );
-  if (!Number.isFinite(maxAgeDays) || maxAgeDays <= 0) return;
-  const maxAgeMs = maxAgeDays * 86_400_000;
-  const now = Date.now();
-  for (const e of entries) {
-    if (!e.isFile() || !e.name.endsWith(".db")) continue;
-    const dbPath = `${sessionsDir}/${e.name}`;
-    const sessionKey = dbPathToSessionKey(sessionsDir, dbPath);
-    if (sessionKey && sessionHostsBySessionKey.has(sessionKey)) continue;
-    try {
-      const s = await stat(dbPath);
-      if (now - s.mtimeMs > maxAgeMs) {
-        await rm(dbPath, { force: true });
-      }
-    } catch {
-      // 单文件失败不阻塞整体 prune
-    }
-  }
-}
-
-function agentfsJustBashBackend(): SandboxBackend {
-  return {
-    name: BACKEND_NAME,
-
-    async prewarm({
-      runtimeContext,
-      templateKey,
-    }: SandboxBackendPrewarmInput): Promise<{ reused: boolean }> {
-      // 当前 evework 没有 bootstrap / agent/sandbox/workspace/ —— templateKey 始终为 null，
-      // eve runtime 不会调到这个分支（prewarm.js:20 的 `c !== null` 守卫）。
-      // 这里仍然写对以备将来加 bootstrap 时使用。
-      if (templateKey === null) return { reused: false };
-      const dataDir = resolveDataDir(runtimeContext.appRoot);
-      const dbPath = resolveTemplateDbPath(dataDir, templateKey);
-      const cached = hostsByDbPath.get(dbPath);
-      if (cached) {
-        // touch：刷新 mtime，让外部的「最近活跃模板」统计拿到信号
-        try {
-          const now = new Date();
-          await cached.fs.utimes(dbPath, now, now);
-        } catch {
-          // utimes 是 stub（AgentFsWrapper 不支持）—— 失败无害
-        }
-        return { reused: true };
-      }
-      await getOrOpenHost({ dbPath, isSession: false });
-      // TODO: bootstrap / seedFiles 进入时，把 host close，然后
-      // create 阶段用 SQLite `VACUUM INTO` 拿原子快照派生 session。
-      return { reused: false };
-    },
-
-    async create(
-      input: SandboxBackendCreateInput,
-    ): Promise<SandboxBackendHandle> {
-      const { runtimeContext, sessionKey, templateKey } = input;
-      const dataDir = resolveDataDir(runtimeContext.appRoot);
 
-      // 优先级 1：进程内同 sessionKey 命中（防重复 open 同一 DB）
-      const reusedDbPath = sessionHostsBySessionKey.get(sessionKey);
-      // 优先级 2：existingMetadata.dbPath（持久化重连）
-      const existingDbPath = reusedDbPath ?? resolveExistingDbPath(input);
-      // 优先级 3：模板派生（templateKey 非空时，将来用 VACUUM INTO）—— 当前永远 null
-      const templateDbPath =
-        existingDbPath ?? (templateKey !== null
-          ? resolveTemplateDbPath(dataDir, templateKey)
-          : null);
-      // 优先级 4：空建 session 库
-      const dbPath =
-        templateDbPath ?? resolveSessionDbPath(dataDir, sessionKey);
+import { defineSandbox } from "eve/sandbox";
 
-      await maybePruneStaleSessions(runtimeContext.appRoot);
-      const h = await getOrOpenHost({
-        dbPath,
-        isSession: true,
-        sessionKey,
-      });
-      const internal = buildInternalSession(h.sandbox, h.fs);
-      const session = buildPublicSession(internal);
-      return {
-        session,
-        useSessionFn: async () => session,
-        async captureState(): Promise<SandboxBackendSessionState> {
-          return {
-            backendName: BACKEND_NAME,
-            sessionKey,
-            // metadata schema v1：version + dbPath。
-            // 变更前格式 `{ dbPath }`（无 version）会被 resolveExistingDbPath 当作 legacy 丢弃。
-            metadata: { version: 1, dbPath: h.dbPath },
-          };
-        },
-        async shutdown(): Promise<void> {
-          // 不 evict：进程级 Map 让活跃 session 共享 SQLite 连接直到 SIGTERM 回收。
-          // 框架自带 justbash 后端同样 no-op（execution/sandbox/active-handles.js）。
-        },
-      };
-    },
-  };
-}
+import { createAgentFsJustBashBackend } from "./lib/agentfs-sandbox/backend.js";
 
-// 让 `node` 也能 import 此文件——避免 Nitro 把默认导出当函数调用失败
-export { agentfsJustBashBackend };
-export const backendName = BACKEND_NAME;
-export type { SandboxBackendRuntimeContext };
+export { AGENTFS_BACKEND_NAME as backendName } from "./lib/agentfs-sandbox/backend.js";
+export { createAgentFsJustBashBackend as agentfsJustBashBackend } from "./lib/agentfs-sandbox/backend.js";
 
-export default defineSandbox({ backend: agentfsJustBashBackend() });
+export default defineSandbox({
+  backend: createAgentFsJustBashBackend(),
+});

docker-entrypoint.mjs

@@ -9,12 +9,18 @@ function log(msg) {
   process.stdout.write(`[evework-boot] ${msg}\n`);
 }
 
+const workflowWorld = (process.env.WORKFLOW_WORLD ?? "local").trim().toLowerCase();
+const workflowBoot =
+  workflowWorld === "postgres" || workflowWorld === "world-postgres"
+    ? `workflow=postgres url=${process.env.WORKFLOW_POSTGRES_URL ? "set" : "MISSING"}`
+    : `workflow=local data=.workflow-data`;
+
 log(`pid=${process.pid} node=${process.version} cwd=${process.cwd()}`);
 log(
   `env PORT=${process.env.PORT ?? "(unset)"} HOST=${process.env.HOST ?? "(unset)"} NODE_ENV=${process.env.NODE_ENV ?? "(unset)"}`,
 );
 log(
-  `workflow_url=${process.env.WORKFLOW_POSTGRES_URL ? "set" : "MISSING"} custom_base=${process.env.CUSTOM_BASE_URL ? "set" : "MISSING"} custom_model=${process.env.CUSTOM_MODEL ? "set" : "MISSING"} agent_key=${process.env.AGENT_API_KEY ? "set" : "MISSING"}`,
+  `${workflowBoot} custom_base=${process.env.CUSTOM_BASE_URL ? "set" : "MISSING"} custom_model=${process.env.CUSTOM_MODEL ? "set" : "MISSING"} agent_key=${process.env.AGENT_API_KEY ? "set" : "MISSING"}`,
 );
 
 const serverEntry = new URL("./.output/server/index.mjs", import.meta.url);