@botlearn-course/daemon 0.0.20-beta.1 → 0.0.20-beta.3

package/dist/workspace-snapshot-control.js

@@ -0,0 +1,169 @@
+import { createReadStream, rmSync } from "node:fs";
+import path from "node:path";
+import { ensureDaemonHome } from "./auth-store.js";
+import { writeWorkspaceMaterializationMarker } from "./workspace-materialization.js";
+import { WORKSPACE_SNAPSHOT_POLICY_V1 } from "./workspace-snapshot-policy.js";
+import { stageWorkspaceSnapshot } from "./workspace-snapshot-staging.js";
+export class WorkspaceSnapshotControlError extends Error {
+    code;
+    retryable;
+    constructor(code, retryable) {
+        super(code);
+        this.code = code;
+        this.retryable = retryable;
+        this.name = "WorkspaceSnapshotControlError";
+    }
+}
+function controlBase(wsUrl) {
+    const url = new URL(wsUrl);
+    url.protocol = url.protocol === "wss:" ? "https:" : "http:";
+    url.pathname = "/internal/v1/workspace-checkpoints";
+    url.search = "";
+    url.hash = "";
+    return url.toString().replace(/\/$/, "");
+}
+async function requestJson(url, token, body, signal) {
+    const response = await fetch(url, {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${token}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify(body),
+        signal,
+    });
+    if (!response.ok) {
+        let code = `workspace_snapshot_control_${response.status}`;
+        let explicitRetryable;
+        try {
+            const payload = await response.json();
+            const detail = payload.detail;
+            if (detail && typeof detail === "object" && !Array.isArray(detail)) {
+                const stable = detail.code;
+                if (typeof stable === "string" && /^workspace_[a-z0-9_]+$/u.test(stable))
+                    code = stable;
+                const retryable = detail.retryable;
+                if (typeof retryable === "boolean")
+                    explicitRetryable = retryable;
+            }
+        }
+        catch {
+            // Content-free HTTP fallback remains stable and retry classification stays status-based.
+        }
+        throw new WorkspaceSnapshotControlError(code, explicitRetryable ?? (response.status >= 500 || response.status === 408 || response.status === 429 ||
+            response.status === 409));
+    }
+    return await response.json();
+}
+function fence(scope) {
+    return {
+        sandbox_id: scope.sandboxId,
+        sandbox_generation: scope.sandboxGeneration,
+        connection_epoch: scope.connectionEpoch,
+        runtime_session_id: scope.runtimeSessionId,
+        ...(scope.agentRunId ? { agent_run_id: scope.agentRunId } : {}),
+        ...(scope.workerAttempt ? { worker_attempt: scope.workerAttempt } : {}),
+        ...(scope.activationId ? { activation_id: scope.activationId } : {}),
+    };
+}
+export async function checkpointWorkspace(options) {
+    const { scope } = options;
+    const signal = AbortSignal.timeout(WORKSPACE_SNAPSHOT_POLICY_V1.checkpointAttemptDeadlineMs);
+    const checkpointUrl = `${controlBase(options.wsUrl)}/${scope.checkpointId}`;
+    const controlDirectory = path.join(ensureDaemonHome(), "agent-service-sandboxes", scope.sandboxId, "workspace-control");
+    const staged = stageWorkspaceSnapshot({
+        workspaceDirectory: options.workspaceDirectory,
+        controlDirectory,
+        checkpointId: scope.checkpointId,
+        limits: WORKSPACE_SNAPSHOT_POLICY_V1.limits,
+        maxStabilityRetries: WORKSPACE_SNAPSHOT_POLICY_V1.maxStabilityRetries,
+        freezeProof: options.freezeProof,
+    });
+    try {
+        const entrySet = {
+            schemaVersion: "agent-workspace-entry-set/1",
+            entries: staged.entrySet.entries,
+        };
+        const proposal = await requestJson(`${checkpointUrl}/proposal`, options.reconnectToken, {
+            fence: fence(scope),
+            policy_id: WORKSPACE_SNAPSHOT_POLICY_V1.policyId,
+            base_revision: scope.baseRevision,
+            entry_count: staged.entrySet.entries.length,
+            file_count: staged.entrySet.fileCount,
+            total_bytes: staged.entrySet.totalBytes,
+            content_sha256: staged.entrySet.contentSha256,
+            entry_set: entrySet,
+        }, signal);
+        if (proposal.unchanged) {
+            if (proposal.revision === 0 && proposal.snapshot_id === null) {
+                writeWorkspaceMaterializationMarker({
+                    schemaVersion: "agent-workspace-materialization/1",
+                    sandboxId: scope.sandboxId,
+                    sandboxGeneration: scope.sandboxGeneration,
+                    runtimeSessionId: scope.runtimeSessionId,
+                    workspaceContinuityState: "healthy",
+                    snapshotId: null,
+                    revision: 0,
+                    contentSha256: null,
+                    writtenAt: new Date().toISOString(),
+                });
+            }
+            return {
+                revision: proposal.revision,
+                snapshotId: proposal.snapshot_id,
+                contentSha256: proposal.content_sha256,
+            };
+        }
+        for (let offset = 0; offset < proposal.missing_blob_ids.length; offset += 25) {
+            const requestedBlobIds = proposal.missing_blob_ids.slice(offset, offset + 25);
+            const grants = await requestJson(`${checkpointUrl}/upload-grants`, options.reconnectToken, { fence: fence(scope), blob_ids: requestedBlobIds }, signal);
+            if (grants.length !== requestedBlobIds.length) {
+                throw new Error("workspace_snapshot_upload_grant_count_mismatch");
+            }
+            for (const item of grants) {
+                const source = staged.files.find((file) => file.sha256 === item.sha256 && file.sizeBytes === item.size_bytes);
+                if (!source)
+                    throw new Error("workspace_snapshot_upload_source_missing");
+                const response = await fetch(item.grant.url, {
+                    method: item.grant.method,
+                    headers: item.grant.headers,
+                    body: createReadStream(source.stagingPath),
+                    duplex: "half",
+                    signal,
+                });
+                if (!response.ok)
+                    throw new Error(`workspace_snapshot_upload_${response.status}`);
+            }
+        }
+        let committed = await requestJson(`${checkpointUrl}/complete`, options.reconnectToken, { fence: fence(scope), policy_id: WORKSPACE_SNAPSHOT_POLICY_V1.policyId }, signal);
+        while (committed.status === "pending") {
+            await new Promise((resolve) => setTimeout(resolve, 500));
+            committed = await requestJson(`${checkpointUrl}/status`, options.reconnectToken, { fence: fence(scope) }, signal);
+        }
+        if (committed.status !== "committed" ||
+            committed.snapshot_id === null ||
+            committed.revision === null ||
+            committed.content_sha256 === null) {
+            throw new WorkspaceSnapshotControlError(committed.error_code || "workspace_snapshot_verification_failed", false);
+        }
+        writeWorkspaceMaterializationMarker({
+            schemaVersion: "agent-workspace-materialization/1",
+            sandboxId: scope.sandboxId,
+            sandboxGeneration: scope.sandboxGeneration,
+            runtimeSessionId: scope.runtimeSessionId,
+            workspaceContinuityState: "healthy",
+            snapshotId: committed.snapshot_id,
+            revision: committed.revision,
+            contentSha256: committed.content_sha256,
+            writtenAt: new Date().toISOString(),
+        });
+        return {
+            revision: committed.revision,
+            snapshotId: committed.snapshot_id,
+            contentSha256: committed.content_sha256,
+        };
+    }
+    finally {
+        rmSync(staged.stagingDirectory, { recursive: true, force: true });
+    }
+}

package/dist/workspace-snapshot-policy.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Protocol limits frozen with Course Service's WorkspaceSnapshotPolicyV1.
+ * Deployment may enable the capability, but must never override these values.
+ */
+export declare const WORKSPACE_SNAPSHOT_POLICY_V1: {
+    readonly policyId: "WorkspaceSnapshotPolicyV1";
+    readonly limits: {
+        maxPathSegmentBytes: number;
+        maxPathBytes: number;
+        maxDepth: number;
+        maxFileBytes: number;
+        maxFileCount: number;
+        maxTotalBytes: number;
+        maxEntrySetBytes: number;
+    };
+    readonly maxStabilityRetries: 2;
+    readonly checkpointAttemptDeadlineMs: 30000;
+    readonly requiredRestoreFreeBytes: number;
+    readonly sessionRetainedHardLimitBytes: number;
+    readonly checkpointReservationBytes: number;
+    readonly restorePageEntries: 25;
+};
+/** Wire representation validated exactly by Agent Service during the v0.3 handshake. */
+export declare function workspaceSnapshotPolicyCapability(): Record<string, unknown>;

package/dist/workspace-snapshot-policy.js

@@ -0,0 +1,45 @@
+import { RUNTIME_WORKSPACE_INODE_QUOTA, RUNTIME_WORKSPACE_QUOTA_BYTES, } from "./workspace-quota.js";
+/**
+ * Protocol limits frozen with Course Service's WorkspaceSnapshotPolicyV1.
+ * Deployment may enable the capability, but must never override these values.
+ */
+export const WORKSPACE_SNAPSHOT_POLICY_V1 = {
+    policyId: "WorkspaceSnapshotPolicyV1",
+    limits: {
+        maxPathSegmentBytes: 255,
+        maxPathBytes: 1024,
+        maxDepth: 32,
+        maxFileBytes: 50 * 1024 * 1024,
+        maxFileCount: 2_000,
+        maxTotalBytes: 512 * 1024 * 1024,
+        maxEntrySetBytes: 1024 * 1024,
+    },
+    maxStabilityRetries: 2,
+    checkpointAttemptDeadlineMs: 30_000,
+    requiredRestoreFreeBytes: 1024 * 1024,
+    sessionRetainedHardLimitBytes: 2 * 1024 * 1024 * 1024,
+    checkpointReservationBytes: 512 * 1024 * 1024,
+    restorePageEntries: 25,
+};
+/** Wire representation validated exactly by Agent Service during the v0.3 handshake. */
+export function workspaceSnapshotPolicyCapability() {
+    return {
+        policy_id: WORKSPACE_SNAPSHOT_POLICY_V1.policyId,
+        max_path_segment_bytes: WORKSPACE_SNAPSHOT_POLICY_V1.limits.maxPathSegmentBytes,
+        max_path_bytes: WORKSPACE_SNAPSHOT_POLICY_V1.limits.maxPathBytes,
+        max_depth: WORKSPACE_SNAPSHOT_POLICY_V1.limits.maxDepth,
+        max_file_bytes: WORKSPACE_SNAPSHOT_POLICY_V1.limits.maxFileBytes,
+        max_file_count: WORKSPACE_SNAPSHOT_POLICY_V1.limits.maxFileCount,
+        max_total_bytes: WORKSPACE_SNAPSHOT_POLICY_V1.limits.maxTotalBytes,
+        max_entry_set_bytes: WORKSPACE_SNAPSHOT_POLICY_V1.limits.maxEntrySetBytes,
+        required_restore_free_bytes: WORKSPACE_SNAPSHOT_POLICY_V1.requiredRestoreFreeBytes,
+        session_retained_hard_limit_bytes: WORKSPACE_SNAPSHOT_POLICY_V1.sessionRetainedHardLimitBytes,
+        checkpoint_reservation_bytes: WORKSPACE_SNAPSHOT_POLICY_V1.checkpointReservationBytes,
+        restore_page_entries: WORKSPACE_SNAPSHOT_POLICY_V1.restorePageEntries,
+        max_stability_retries: WORKSPACE_SNAPSHOT_POLICY_V1.maxStabilityRetries,
+        checkpoint_attempt_deadline_ms: WORKSPACE_SNAPSHOT_POLICY_V1.checkpointAttemptDeadlineMs,
+        prepare_deadline_seconds: 15 * 60,
+        runtime_filesystem_quota_bytes: RUNTIME_WORKSPACE_QUOTA_BYTES,
+        runtime_inode_quota: RUNTIME_WORKSPACE_INODE_QUOTA,
+    };
+}

package/dist/workspace-snapshot-staging.d.ts

@@ -1,3 +1,4 @@
+import { type WorkspaceWriterFreezeProof } from "./runtime-quiescence.js";
 import { type CanonicalWorkspaceEntrySet, type WorkspaceEntrySetLimits } from "./workspace-entry-set.js";
 export declare class WorkspaceSnapshotStagingError extends Error {
     readonly code: string;
@@ -21,14 +22,6 @@ export interface WorkspaceSnapshotStagingOptions {
     checkpointId: string;
     limits: WorkspaceEntrySetLimits;
     maxStabilityRetries: number;
-    quiescenceProof: WorkspaceQuiescenceProof;
-}
-export interface WorkspaceQuiescenceProof {
-    proofVersion: "workspace-quiescence-proof/1";
-    sandboxId: string;
-    sandboxGeneration: number;
-    runtimeSessionId: string;
-    checkpointId: string;
-    allWritersStopped: true;
+    freezeProof: WorkspaceWriterFreezeProof;
 }
 export declare function stageWorkspaceSnapshot(options: WorkspaceSnapshotStagingOptions): StagedWorkspaceSnapshot;

package/dist/workspace-snapshot-staging.js

@@ -1,6 +1,7 @@
 import { createHash, randomUUID } from "node:crypto";
-import { chmodSync, closeSync, constants, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readdirSync, readSync, realpathSync, rmSync, writeSync, } from "node:fs";
+import { chmodSync, closeSync, constants, existsSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readdirSync, readSync, realpathSync, rmSync, writeSync, } from "node:fs";
 import path from "node:path";
+import { isWorkspaceWriterFreezeProof, } from "./runtime-quiescence.js";
 import { defaultCaseFold, validateWorkspaceEntrySet, WORKSPACE_ENTRY_SET_SCHEMA, } from "./workspace-entry-set.js";
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 const EXCLUDED_NAMES = new Set(["node_modules"]);
@@ -107,30 +108,52 @@ function fsyncDirectory(directory) {
         closeSync(handle);
     }
 }
+function descriptorPath(handle, fallback) {
+    if (existsSync("/proc/self/fd")) {
+        const value = path.join("/proc/self/fd", String(handle));
+        if (!existsSync(value))
+            fail("workspace_snapshot_fd_traversal_unavailable");
+        return value;
+    }
+    // Darwin has no procfs open-file path that supports relative child lookup. It is used
+    // only by local tests/BYOA; managed durable sandboxes are Linux and fail closed above.
+    return fallback;
+}
 function stageOnce(options, paths) {
     const stagingDirectory = path.join(paths.checkpointRoot, randomUUID());
     mkdirSync(stagingDirectory, { mode: 0o700 });
     chmodSync(stagingDirectory, 0o700);
     try {
-        const rootStats = lstatSync(paths.workspace, { bigint: true });
-        if (!rootStats.isDirectory())
+        const rootHandle = openSync(paths.workspace, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+        const rootStats = fstatSync(rootHandle, { bigint: true });
+        if (!rootStats.isDirectory()) {
+            closeSync(rootHandle);
             fail("workspace_snapshot_root_invalid");
+        }
         const entries = [];
         const files = [];
         let fileCount = 0;
         let totalBytes = 0;
-        function walk(sourceDirectory, destinationDirectory, segments) {
-            const directoryBefore = lstatSync(sourceDirectory, { bigint: true });
+        let estimatedEntrySetBytes = Buffer.byteLength('{"schemaVersion":"agent-workspace-entry-set/1","entries":[]}', "utf8");
+        function appendEntry(entry) {
+            estimatedEntrySetBytes += Buffer.byteLength(JSON.stringify(entry), "utf8") + 1;
+            if (estimatedEntrySetBytes > options.limits.maxEntrySetBytes) {
+                fail("workspace_snapshot_limit_exceeded");
+            }
+            entries.push(entry);
+        }
+        function walk(sourceHandle, sourceFallback, destinationDirectory, segments) {
+            const directoryBefore = fstatSync(sourceHandle, { bigint: true });
             assertSourceNode(directoryBefore, {
                 rootDevice: rootStats.dev,
                 expected: "directory",
             });
+            const sourceDirectory = descriptorPath(sourceHandle, sourceFallback);
             const children = readdirSync(sourceDirectory, {
-                withFileTypes: true,
                 encoding: "buffer",
-            }).sort((left, right) => Buffer.compare(left.name, right.name));
+            }).sort((left, right) => Buffer.compare(left, right));
             for (const child of children) {
-                const name = decodeName(child.name);
+                const name = decodeName(child);
                 if (excludedName(name))
                     continue;
                 const relativeSegments = [...segments, name];
@@ -145,13 +168,21 @@ function stageOnce(options, paths) {
                     fail("workspace_snapshot_unsupported_file_type");
                 if (stats.isDirectory()) {
                     assertSourceNode(stats, { rootDevice: rootStats.dev, expected: "directory" });
+                    const childHandle = openSync(source, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+                    const openedDirectory = fstatSync(childHandle, { bigint: true });
+                    if (!sameIdentity(stats, openedDirectory)) {
+                        closeSync(childHandle);
+                        fail("workspace_snapshot_source_changed", true);
+                    }
                     mkdirSync(destination, { mode: 0o700 });
                     chmodSync(destination, 0o700);
-                    entries.push({ type: "directory", path: relativePath, mode: "0700" });
-                    if (entries.length > options.limits.maxEntrySetBytes) {
-                        fail("workspace_snapshot_limit_exceeded");
+                    appendEntry({ type: "directory", path: relativePath, mode: "0700" });
+                    try {
+                        walk(childHandle, source, destination, relativeSegments);
+                    }
+                    finally {
+                        closeSync(childHandle);
                     }
-                    walk(source, destination, relativeSegments);
                     continue;
                 }
                 const copied = copyStableFile(source, destination, {
@@ -163,7 +194,7 @@ function stageOnce(options, paths) {
                 if (fileCount > options.limits.maxFileCount ||
                     totalBytes > options.limits.maxTotalBytes)
                     fail("workspace_snapshot_limit_exceeded");
-                entries.push({
+                appendEntry({
                     type: "file",
                     path: relativePath,
                     mode: copied.mode,
@@ -176,17 +207,19 @@ function stageOnce(options, paths) {
                     sizeBytes: copied.sizeBytes,
                     sha256: copied.sha256,
                 });
-                if (entries.length > options.limits.maxEntrySetBytes) {
-                    fail("workspace_snapshot_limit_exceeded");
-                }
             }
-            const directoryAfter = lstatSync(sourceDirectory, { bigint: true });
+            const directoryAfter = fstatSync(sourceHandle, { bigint: true });
             if (!sameIdentity(directoryBefore, directoryAfter)) {
                 fail("workspace_snapshot_source_changed", true);
             }
             fsyncDirectory(destinationDirectory);
         }
-        walk(paths.workspace, stagingDirectory, []);
+        try {
+            walk(rootHandle, paths.workspace, stagingDirectory, []);
+        }
+        finally {
+            closeSync(rootHandle);
+        }
         entries.sort((left, right) => Buffer.compare(Buffer.from(left.path, "utf8"), Buffer.from(right.path, "utf8")));
         files.sort((left, right) => Buffer.compare(Buffer.from(left.path, "utf8"), Buffer.from(right.path, "utf8")));
         const entrySet = validateWorkspaceEntrySet({ schemaVersion: WORKSPACE_ENTRY_SET_SCHEMA, entries }, options.limits);
@@ -200,13 +233,14 @@ function stageOnce(options, paths) {
 export function stageWorkspaceSnapshot(options) {
     if (!UUID.test(options.checkpointId))
         fail("workspace_snapshot_checkpoint_invalid");
-    if (options.quiescenceProof.proofVersion !== "workspace-quiescence-proof/1" ||
-        !UUID.test(options.quiescenceProof.sandboxId) ||
-        !UUID.test(options.quiescenceProof.runtimeSessionId) ||
-        options.quiescenceProof.checkpointId !== options.checkpointId ||
-        !Number.isSafeInteger(options.quiescenceProof.sandboxGeneration) ||
-        options.quiescenceProof.sandboxGeneration < 1 ||
-        options.quiescenceProof.allWritersStopped !== true)
+    if (!isWorkspaceWriterFreezeProof(options.freezeProof) ||
+        options.freezeProof.proofVersion !== "workspace-writer-freeze-proof/1" ||
+        !UUID.test(options.freezeProof.sandboxId) ||
+        !UUID.test(options.freezeProof.runtimeSessionId) ||
+        options.freezeProof.checkpointId !== options.checkpointId ||
+        !Number.isSafeInteger(options.freezeProof.sandboxGeneration) ||
+        options.freezeProof.sandboxGeneration < 1 ||
+        options.freezeProof.allWritersFrozen !== true)
         fail("workspace_snapshot_writer_isolation_unproven");
     if (!Number.isSafeInteger(options.maxStabilityRetries) || options.maxStabilityRetries < 0) {
         fail("workspace_snapshot_retry_limit_invalid");

package/package.json

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