@botlearn-course/daemon 0.0.20-beta.5 → 0.0.20-beta.6

package/README.md

@@ -47,6 +47,13 @@ daemon，由 root-owned 固定 launcher 清空附加组后直接降权为 `user`
 `agent-service session --bootstrap-stdin` 同样属于受 supervisor 保护的内部协议，不应直接暴露给
 课程任务或 workspace shell。
 
+veFaaS Origin 的托管 workspace 使用用户级 NAS backing image。root bootstrap 完成 NFS、marker、
+ext4、loop mount 和固定 3 GiB 校验后，daemon 才发送 `sandbox.ready`。RuntimeSession 使用稳定路径
+`/workspace/sessions/{runtime_session_id}/workspace`，Sandbox generation 只参与写入隔离。磁盘写满
+统一上报 `workspace_user_quota_exceeded`。pause 和 cleanup 进入 drain 后，daemon 先停止 runtime
+writer，再通过 root launcher 执行 ext4 sync、loop unmount、backing image 和 NFS parent fsync；完成后
+才发送 `sandbox.drained` 并退出。
+
 ## 支持的 runtime
 
 run 的 `runtime.id` 决定用哪个 adapter 执行；未指定时默认 `codex`。runtime 不可用时 run 会

package/dist/agent-service-sandbox.d.ts

@@ -78,6 +78,7 @@ export declare class AgentServiceSandboxClient implements RunReportingClient, Pe
     run(): Promise<void>;
     stop(): void;
     stopGracefully(): Promise<void>;
+    private drainWorkspace;
     postEvent(agentRunId: string, event: RunEvent): Promise<RunEventReceipt>;
     postFile(agentRunId: string, file: RunFileCandidate): Promise<RunFileRecord>;
     recordWorkspaceScanMeasurement(agentRunId: string, measurement: WorkspaceScanMeasurement): Promise<void>;

package/dist/agent-service-sandbox.js

@@ -20,7 +20,8 @@ import { validateWorkspaceEntrySet, WorkspaceEntrySetError, } from "./workspace-
 import { WORKSPACE_SNAPSHOT_POLICY_V1, workspaceSnapshotPolicyCapability, } from "./workspace-snapshot-policy.js";
 import { assertWorkspaceRestoreCapacity, restoreWorkspaceSnapshot, WorkspaceRestoreError, } from "./workspace-restore.js";
 import { readWorkspaceMaterializationMarker } from "./workspace-materialization.js";
-import { applyRuntimeWorkspaceQuota, assertRuntimeWorkspaceQuota } from "./workspace-quota.js";
+import { assertWorkspaceFilesystem, flushWorkspaceFilesystem, nasWorkspaceEnabled, } from "./workspace-filesystem.js";
+import { applyRuntimeWorkspaceQuota } from "./workspace-quota.js";
 import { WebSocketClient, } from "./websocket-client.js";
 const RECONNECT_DELAYS_MS = [1_000, 2_000, 4_000, 8_000, 16_000, 30_000];
 const MAX_SPOOL_FRAMES = 1024;
@@ -601,6 +602,18 @@ export class AgentServiceSandboxClient {
     async stopGracefully() {
         this.dispatcher.cancelAll();
         await quiesceRuntimeWriters(null);
+        await flushWorkspaceFilesystem();
+        this.stop();
+    }
+    async drainWorkspace(fence) {
+        if (!(await this.dispatcher.drain(10_000)) || !this.isCurrentLifecycleFence(fence)) {
+            return;
+        }
+        await quiesceRuntimeWriters(null);
+        await flushWorkspaceFilesystem();
+        if (!this.isCurrentLifecycleFence(fence))
+            return;
+        await this.sendControlFrame("sandbox.drained", {});
         this.stop();
     }
     async postEvent(agentRunId, event) {
@@ -823,7 +836,7 @@ export class AgentServiceSandboxClient {
             this.rejectPending(new Error("Agent Service sandbox generation changed"));
             for (const sessionId of Object.keys(this.state.sessions)) {
                 revokeRuntimeSessionWorkspace(sessionId, this.state.sandboxGeneration);
-                removeRuntimeSessionWorkspace(sessionId, this.state.sandboxGeneration);
+                removeRuntimeSessionWorkspace(sessionId, this.state.sandboxGeneration, nasWorkspaceEnabled());
             }
             this.state.sessions = {};
             this.state.sandboxGeneration = frame.sandbox_generation;
@@ -853,7 +866,7 @@ export class AgentServiceSandboxClient {
         this.runtimeLogPolicy = runtimeLogPolicy(frame.payload.runtime_log_policy);
         await cleanupRuntimeSessionWorkspaceCopyStaging();
         this.persist();
-        assertRuntimeWorkspaceQuota(process.env.BOTLEARN_AGENT_SERVICE_WORKSPACE_ROOT ?? "");
+        assertWorkspaceFilesystem(process.env.BOTLEARN_AGENT_SERVICE_WORKSPACE_ROOT ?? "");
         assertWorkspaceWriterFreezeSupported();
         await this.sendControlFrame("sandbox.ready", {
             protocol_versions: [AGENT_SERVICE_WS_SCHEMA],
@@ -862,6 +875,7 @@ export class AgentServiceSandboxClient {
                 "workspace_writer_freeze_v1",
                 "workspace_snapshot_v2",
                 "workspace_restore_v1",
+                ...(nasWorkspaceEnabled() ? ["workspace_nas_v1"] : []),
                 ...(workspaceCopyV1Supported() ? ["workspace_copy_v1"] : []),
             ],
             workspace_snapshot_policy: workspaceSnapshotPolicyCapability(),
@@ -1008,11 +1022,7 @@ export class AgentServiceSandboxClient {
                 return;
             case "sandbox.drain":
                 await this.sendCommandAck(frame, "ok");
-                this.scheduleLifecycle("sandbox.drain", async (fence) => {
-                    if (await this.dispatcher.drain(10_000) && this.isCurrentLifecycleFence(fence)) {
-                        await this.sendControlFrame("sandbox.drained", {});
-                    }
-                });
+                this.scheduleLifecycle("sandbox.drain", (fence) => this.drainWorkspace(fence));
                 return;
             case "protocol.error":
                 throw new Error(`server protocol error: ${String(frame.payload.code ?? "unknown")}`);
@@ -1038,11 +1048,7 @@ export class AgentServiceSandboxClient {
             return;
         }
         if (state === "drain") {
-            this.scheduleLifecycle("sandbox.sync.drain", async (fence) => {
-                if (await this.dispatcher.drain(10_000) && this.isCurrentLifecycleFence(fence)) {
-                    await this.sendControlFrame("sandbox.drained", {});
-                }
-            });
+            this.scheduleLifecycle("sandbox.sync.drain", (fence) => this.drainWorkspace(fence));
         }
         // idle/run/cancel：实际工作全部由显式命令帧下发（合同 §1.3）。
     }
@@ -1317,7 +1323,9 @@ export class AgentServiceSandboxClient {
             await finalizeRuntimeSessionWorkspaceCopy(markerPath);
         }
         try {
-            await applyRuntimeWorkspaceQuota(sessionId, this.sandboxGeneration);
+            if (!nasWorkspaceEnabled()) {
+                await applyRuntimeWorkspaceQuota(sessionId, this.sandboxGeneration);
+            }
         }
         catch (error) {
             if (requestedRestore) {

package/dist/run-dispatcher.js

@@ -13,6 +13,7 @@ import { buildToolObservation } from "./tool-observation.js";
 import { buildReasoningTracePayload, extractReasoningText, REASONING_TRACE_MAX_CHARS, } from "./trace-projection.js";
 import { RuntimeExecutionError, } from "./types.js";
 import { ensureRunWorkspace, transcriptPath } from "./workspace.js";
+import { isWorkspaceQuotaExceededError } from "./workspace-filesystem.js";
 // 与 runtimes/index.ts 的 DEFAULT_RUNTIME_ID 保持一致（此处不 import registry，避免拉入全部 adapter）。
 const DEFAULT_RUNTIME_ID = "codex";
 const DEFAULT_TIMEOUT_SECONDS = 900;
@@ -951,13 +952,15 @@ export class RunDispatcher {
                 }
                 else {
                     const info = errorInfo(err);
-                    const errorType = err instanceof RuntimeProfileApplyError
-                        ? err.code
-                        : err instanceof InputAttachmentMaterializationError
+                    const errorType = isWorkspaceQuotaExceededError(err)
+                        ? "workspace_user_quota_exceeded"
+                        : err instanceof RuntimeProfileApplyError
                             ? err.code
-                            : err instanceof RuntimeExecutionError
-                                ? err.errorType
-                                : "runtime_error";
+                            : err instanceof InputAttachmentMaterializationError
+                                ? err.code
+                                : err instanceof RuntimeExecutionError
+                                    ? err.errorType
+                                    : "runtime_error";
                     await sendFailure(errorType, info.error_message, err, err instanceof RuntimeProfileApplyError
                         ? { code: err.code, profile_apply_status: "failed" }
                         : {});

package/dist/types.d.ts

@@ -233,9 +233,9 @@ export interface CourseRuntime {
 }
 /** runtime 执行失败（dispatcher 折叠为 run.failed）。 */
 export declare class RuntimeExecutionError extends Error {
-    readonly errorType: "runtime_error" | "runtime_unavailable" | "timeout";
+    readonly errorType: "runtime_error" | "runtime_unavailable" | "timeout" | "workspace_user_quota_exceeded";
     readonly failure?: Partial<RuntimeFailureSummary> | undefined;
-    constructor(message: string, errorType?: "runtime_error" | "runtime_unavailable" | "timeout", failure?: Partial<RuntimeFailureSummary> | undefined);
+    constructor(message: string, errorType?: "runtime_error" | "runtime_unavailable" | "timeout" | "workspace_user_quota_exceeded", failure?: Partial<RuntimeFailureSummary> | undefined);
 }
 /**
  * 本地诊断用的失败摘要。完整结构只进脱敏日志/transcript；wire 仅允许

package/dist/workspace-filesystem.d.ts

@@ -0,0 +1,14 @@
+export declare const WORKSPACE_IMAGE_FORMAT: "botlearn-workspace-image/1";
+export declare const WORKSPACE_IMAGE_LOGICAL_BYTES: number;
+interface MountInfoEntry {
+    target: string;
+    filesystemType: string;
+    mountOptions: Set<string>;
+}
+export declare function parseWorkspaceMountInfo(text: string): MountInfoEntry[];
+export declare function nasWorkspaceEnabled(env?: NodeJS.ProcessEnv): boolean;
+export declare function workspaceFilesystemFlushCommand(env?: NodeJS.ProcessEnv): [string, string[]] | null;
+export declare function flushWorkspaceFilesystem(env?: NodeJS.ProcessEnv): Promise<void>;
+export declare function isWorkspaceQuotaExceededError(error: unknown): boolean;
+export declare function assertWorkspaceFilesystem(workspaceRoot: string, env?: NodeJS.ProcessEnv, mountInfo?: string): void;
+export {};

package/dist/workspace-filesystem.js

@@ -0,0 +1,100 @@
+import { execFile } from "node:child_process";
+import { readFileSync, statfsSync } from "node:fs";
+import { promisify } from "node:util";
+import { assertRuntimeWorkspaceQuota } from "./workspace-quota.js";
+export const WORKSPACE_IMAGE_FORMAT = "botlearn-workspace-image/1";
+export const WORKSPACE_IMAGE_LOGICAL_BYTES = 3 * 1024 * 1024 * 1024;
+const RUNTIME_LAUNCHER = "/opt/botlearn/bin/botlearn-runtime-launcher";
+const execFileAsync = promisify(execFile);
+function decodeMountInfoPath(value) {
+    return value.replace(/\\([0-7]{3})/gu, (_match, octal) => String.fromCharCode(Number.parseInt(octal, 8)));
+}
+export function parseWorkspaceMountInfo(text) {
+    return text.split("\n").filter(Boolean).map((line) => {
+        const [left, right] = line.split(" - ", 2);
+        const fields = left?.split(" ") ?? [];
+        const filesystem = right?.split(" ") ?? [];
+        if (fields.length < 6 || filesystem.length < 3) {
+            throw new Error("workspace_mount_proof_invalid");
+        }
+        return {
+            target: decodeMountInfoPath(fields[4]),
+            filesystemType: filesystem[0],
+            mountOptions: new Set(fields[5].split(",")),
+        };
+    });
+}
+export function nasWorkspaceEnabled(env = process.env) {
+    return env.BOTLEARN_WORKSPACE_IMAGE_FORMAT !== undefined;
+}
+export function workspaceFilesystemFlushCommand(env = process.env) {
+    if (!nasWorkspaceEnabled(env))
+        return null;
+    if (env.BOTLEARN_RUNTIME_LAUNCH_MODE === "direct-uid") {
+        return [RUNTIME_LAUNCHER, ["--workspace-filesystem-flush"]];
+    }
+    if (env.BOTLEARN_RUNTIME_LAUNCH_MODE === "sudo") {
+        return [
+            "/usr/bin/sudo",
+            ["-n", "--", RUNTIME_LAUNCHER, "--workspace-filesystem-flush"],
+        ];
+    }
+    if (env.BOTLEARN_DAEMON_ENABLE_FAKE_RUNTIME === "1" || env.NODE_ENV === "test") {
+        return null;
+    }
+    throw new Error("workspace_nas_flush_failed");
+}
+export async function flushWorkspaceFilesystem(env = process.env) {
+    const command = workspaceFilesystemFlushCommand(env);
+    if (command === null)
+        return;
+    try {
+        await execFileAsync(command[0], command[1], { timeout: 30_000 });
+    }
+    catch {
+        throw new Error("workspace_nas_flush_failed");
+    }
+}
+export function isWorkspaceQuotaExceededError(error) {
+    if (!(error instanceof Error))
+        return false;
+    const candidate = error;
+    const code = String(candidate.code ?? candidate.failure?.error_code ?? "");
+    const detail = [
+        candidate.message,
+        candidate.failure?.error_message,
+        candidate.failure?.stderr_tail,
+    ].map((value) => String(value ?? "")).join(" ");
+    return code === "ENOSPC"
+        || code === "EDQUOT"
+        || /\b(?:ENOSPC|EDQUOT|no space left on device|disk quota exceeded)\b/iu.test(detail)
+        || (candidate.cause !== undefined && isWorkspaceQuotaExceededError(candidate.cause));
+}
+export function assertWorkspaceFilesystem(workspaceRoot, env = process.env, mountInfo) {
+    if (!nasWorkspaceEnabled(env)) {
+        assertRuntimeWorkspaceQuota(workspaceRoot);
+        return;
+    }
+    if (env.BOTLEARN_WORKSPACE_IMAGE_FORMAT !== WORKSPACE_IMAGE_FORMAT
+        || env.BOTLEARN_WORKSPACE_LOGICAL_BYTES !== String(WORKSPACE_IMAGE_LOGICAL_BYTES)
+        || !/^[0-9a-f]{64}$/u.test(env.BOTLEARN_WORKSPACE_SCOPE_DIGEST ?? "")) {
+        throw new Error("workspace_quota_mismatch");
+    }
+    if (env.NODE_ENV === "test" && mountInfo === undefined)
+        return;
+    const mount = parseWorkspaceMountInfo(mountInfo ?? readFileSync("/proc/self/mountinfo", "utf8"))
+        .find((candidate) => candidate.target === workspaceRoot);
+    if (!mount
+        || mount.filesystemType !== "ext4"
+        || !mount.mountOptions.has("rw")
+        || !mount.mountOptions.has("nodev")
+        || !mount.mountOptions.has("nosuid")) {
+        throw new Error("workspace_loop_mount_failed");
+    }
+    if (env.NODE_ENV === "test")
+        return;
+    const filesystem = statfsSync(workspaceRoot, { bigint: true });
+    if (filesystem.blocks * filesystem.bsize !== BigInt(WORKSPACE_IMAGE_LOGICAL_BYTES)) {
+        throw new Error("workspace_quota_mismatch");
+    }
+}

package/dist/workspace.d.ts

@@ -20,9 +20,9 @@ export declare function runtimeProfileDir(agentRunId: string): string;
 export declare function runtimeProfileRunRootDir(agentRunId: string): string;
 export declare function runtimeSessionRootDir(runtimeSessionId: string, sandboxGeneration: number): string;
 /**
- * per-session workspace（ADR-015 §7）：managed sandbox 下为
- * `<BOTLEARN_AGENT_SERVICE_WORKSPACE_ROOT>/<runtime_session_id>/generation-<sandbox_generation>`，
- * 由 daemon 在 session.open 时创建。
+ * per-session workspace（ADR-015 §7）：NAS managed sandbox 使用稳定路径
+ * `<root>/sessions/<runtime_session_id>/workspace`；旧 provider 保留 generation 路径。
+ * 两种路径都由 daemon 在 session.open 时创建。
  */
 export declare function runtimeSessionWorkspaceDir(runtimeSessionId: string, sandboxGeneration: number): string;
 export declare function runtimeSessionTranscriptPath(runtimeSessionId: string, sandboxGeneration: number, agentRunId: string): string;
@@ -102,7 +102,7 @@ export declare function exposeRuntimeSessionWorkspace(runtimeSessionId: string,
 /** Revoke a managed workspace without deleting the session's durable local materialization. */
 export declare function revokeRuntimeSessionWorkspace(runtimeSessionId: string, sandboxGeneration: number): void;
 /** session.close 时删除 workspace 与本地 session 物化状态（transcripts 等）。幂等。 */
-export declare function removeRuntimeSessionWorkspace(runtimeSessionId: string, sandboxGeneration: number): void;
+export declare function removeRuntimeSessionWorkspace(runtimeSessionId: string, sandboxGeneration: number, preserveManagedWorkspace?: boolean): void;
 export declare function ensureRuntimeSessionWorkspace(runtimeSessionId: string, sandboxGeneration: number, agentRunId: string): {
     rootDir: string;
     workspaceDir: string;

package/dist/workspace.js

@@ -4,6 +4,7 @@ import { createHash, randomUUID } from "node:crypto";
 import path from "node:path";
 import { TextDecoder } from "node:util";
 import { daemonHome } from "./auth-store.js";
+import { nasWorkspaceEnabled } from "./workspace-filesystem.js";
 /**
  * 每 run 隔离工作区（spec §4）：
  *
@@ -53,9 +54,9 @@ export function runtimeSessionRootDir(runtimeSessionId, sandboxGeneration) {
     return path.join(daemonHome(), "agent-service-sessions", runtimeSessionId, `generation-${sandboxGeneration}`);
 }
 /**
- * per-session workspace（ADR-015 §7）：managed sandbox 下为
- * `<BOTLEARN_AGENT_SERVICE_WORKSPACE_ROOT>/<runtime_session_id>/generation-<sandbox_generation>`，
- * 由 daemon 在 session.open 时创建。
+ * per-session workspace（ADR-015 §7）：NAS managed sandbox 使用稳定路径
+ * `<root>/sessions/<runtime_session_id>/workspace`；旧 provider 保留 generation 路径。
+ * 两种路径都由 daemon 在 session.open 时创建。
  */
 export function runtimeSessionWorkspaceDir(runtimeSessionId, sandboxGeneration) {
     assertSafeId(runtimeSessionId, "runtime_session_id");
@@ -64,6 +65,9 @@ export function runtimeSessionWorkspaceDir(runtimeSessionId, sandboxGeneration)
     }
     const managedRoot = process.env.BOTLEARN_AGENT_SERVICE_WORKSPACE_ROOT?.trim();
     if (managedRoot) {
+        if (nasWorkspaceEnabled()) {
+            return path.join(managedRoot, "sessions", runtimeSessionId, "workspace");
+        }
         return path.join(managedRoot, runtimeSessionId, `generation-${sandboxGeneration}`);
     }
     return path.join(runtimeSessionRootDir(runtimeSessionId, sandboxGeneration), "workspace");
@@ -71,7 +75,11 @@ export function runtimeSessionWorkspaceDir(runtimeSessionId, sandboxGeneration)
 function managedRuntimeSessionParentDir(runtimeSessionId) {
     assertSafeId(runtimeSessionId, "runtime_session_id");
     const managedRoot = process.env.BOTLEARN_AGENT_SERVICE_WORKSPACE_ROOT?.trim();
-    return managedRoot ? path.join(managedRoot, runtimeSessionId) : null;
+    if (!managedRoot)
+        return null;
+    return nasWorkspaceEnabled()
+        ? path.join(managedRoot, "sessions", runtimeSessionId)
+        : path.join(managedRoot, runtimeSessionId);
 }
 export function runtimeSessionTranscriptPath(runtimeSessionId, sandboxGeneration, agentRunId) {
     assertSafeId(agentRunId, "agent_run_id");
@@ -228,12 +236,16 @@ async function childDirectories(root) {
 export async function cleanupRuntimeSessionWorkspaceCopyStaging() {
     const managedRoot = process.env.BOTLEARN_AGENT_SERVICE_WORKSPACE_ROOT?.trim();
     if (managedRoot) {
-        for (const sessionName of await childDirectories(managedRoot)) {
+        const sessionRoot = nasWorkspaceEnabled()
+            ? path.join(managedRoot, "sessions")
+            : managedRoot;
+        for (const sessionName of await childDirectories(sessionRoot)) {
             if (!SAFE_ID_PATTERN.test(sessionName))
                 continue;
-            const sessionParent = path.join(managedRoot, sessionName);
+            const sessionParent = path.join(sessionRoot, sessionName);
             for (const name of await childDirectories(sessionParent)) {
-                if (MANAGED_COPY_STAGING_PATTERN.test(name)) {
+                if (MANAGED_COPY_STAGING_PATTERN.test(name)
+                    || LOCAL_COPY_STAGING_PATTERN.test(name)) {
                     await fs.rm(path.join(sessionParent, name), { recursive: true, force: true });
                 }
             }
@@ -700,16 +712,19 @@ export function revokeRuntimeSessionWorkspace(runtimeSessionId, sandboxGeneratio
     }
 }
 /** session.close 时删除 workspace 与本地 session 物化状态（transcripts 等）。幂等。 */
-export function removeRuntimeSessionWorkspace(runtimeSessionId, sandboxGeneration) {
-    // 校验路径段安全后按 session 整体删除（含全部 generation 与 transcripts）。
+export function removeRuntimeSessionWorkspace(runtimeSessionId, sandboxGeneration, preserveManagedWorkspace = false) {
+    // 校验路径段安全后删除本地物化状态；generation 换代可保留 NAS 正文。
     runtimeSessionRootDir(runtimeSessionId, sandboxGeneration);
     rmSync(path.join(daemonHome(), "agent-service-sessions", runtimeSessionId), {
         recursive: true,
         force: true,
     });
     const managedRoot = process.env.BOTLEARN_AGENT_SERVICE_WORKSPACE_ROOT?.trim();
-    if (managedRoot) {
-        rmSync(path.join(managedRoot, runtimeSessionId), { recursive: true, force: true });
+    if (managedRoot && !preserveManagedWorkspace) {
+        const sessionRoot = nasWorkspaceEnabled()
+            ? path.join(managedRoot, "sessions", runtimeSessionId)
+            : path.join(managedRoot, runtimeSessionId);
+        rmSync(sessionRoot, { recursive: true, force: true });
     }
 }
 export function ensureRuntimeSessionWorkspace(runtimeSessionId, sandboxGeneration, agentRunId) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botlearn-course/daemon",
-  "version": "0.0.20-beta.5",
+  "version": "0.0.20-beta.6",
   "description": "Lightweight BotLearn Course daemon: run course tasks on your own machine with your own agent runtime (BYOA).",
   "type": "module",
   "bin": {