@botlearn-course/daemon 0.0.19 → 0.0.20-beta.10

package/dist/workspace-filesystem.js

@@ -0,0 +1,120 @@
+import { execFile } from "node:child_process";
+import { readFileSync, statfsSync, statSync } 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);
+const defaultCapacityProbes = {
+    statfsBytes(workspaceRoot) {
+        const filesystem = statfsSync(workspaceRoot, { bigint: true });
+        return filesystem.blocks * filesystem.bsize;
+    },
+    backingFileBytes(imagePath) {
+        return BigInt(statSync(imagePath).size);
+    },
+};
+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],
+            source: decodeMountInfoPath(filesystem[1]),
+            mountOptions: new Set(fields[5].split(",")),
+            superOptions: new Set(filesystem[2].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, capacityProbes) {
+    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);
+    const validFilesystem = mount?.filesystemType === "ext4" || (mount?.filesystemType === "fuse.ext4"
+        && mount.source === "/mnt/botlearn-workspace-store/workspace.ext4"
+        && mount.superOptions.has("allow_other"));
+    if (!mount
+        || !validFilesystem
+        || !mount.mountOptions.has("rw")
+        || !mount.mountOptions.has("nodev")
+        || !mount.mountOptions.has("nosuid")) {
+        throw new Error("workspace_loop_mount_failed");
+    }
+    if (env.NODE_ENV === "test" && capacityProbes === undefined)
+        return;
+    const probes = capacityProbes ?? defaultCapacityProbes;
+    // fuse2fs reports a zero-sized statfs view in veFaaS even though the exact backing
+    // image is mounted and enforces the filesystem boundary. The mount proof above pins
+    // that image, so its validated file size is the authoritative capacity for FUSE.
+    const boundedBytes = mount.filesystemType === "fuse.ext4"
+        ? probes.backingFileBytes(mount.source)
+        : probes.statfsBytes(workspaceRoot);
+    if (boundedBytes !== BigInt(WORKSPACE_IMAGE_LOGICAL_BYTES)) {
+        throw new Error("workspace_quota_mismatch");
+    }
+}

package/dist/workspace-materialization.d.ts

@@ -0,0 +1,16 @@
+export declare const WORKSPACE_MATERIALIZATION_SCHEMA: "agent-workspace-materialization/1";
+export interface WorkspaceMaterializationMarker {
+    schemaVersion: typeof WORKSPACE_MATERIALIZATION_SCHEMA;
+    sandboxId: string;
+    sandboxGeneration: number;
+    runtimeSessionId: string;
+    workspaceContinuityState: "healthy" | "degraded";
+    snapshotId: string | null;
+    revision: number;
+    contentSha256: string | null;
+    writtenAt: string;
+}
+export declare function workspaceMaterializationMarkerPath(sandboxId: string, runtimeSessionId: string): string;
+export declare function writeWorkspaceMaterializationMarker(marker: WorkspaceMaterializationMarker): void;
+export declare function readWorkspaceMaterializationMarker(sandboxId: string, runtimeSessionId: string): WorkspaceMaterializationMarker | null;
+export declare function removeWorkspaceMaterializationMarker(sandboxId: string, runtimeSessionId: string): boolean;

package/dist/workspace-materialization.js

@@ -0,0 +1,136 @@
+import { randomBytes } from "node:crypto";
+import { chmodSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
+import path from "node:path";
+import { ensureDaemonHome } from "./auth-store.js";
+export const WORKSPACE_MATERIALIZATION_SCHEMA = "agent-workspace-materialization/1";
+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 SHA256 = /^[0-9a-f]{64}$/;
+function assertUuid(value, label) {
+    if (!UUID.test(value))
+        throw new Error(label + " must be a UUID");
+}
+function markerDirectory(sandboxId) {
+    assertUuid(sandboxId, "sandboxId");
+    return path.join(ensureDaemonHome(), "agent-service-sandboxes", sandboxId, "workspace-materializations");
+}
+export function workspaceMaterializationMarkerPath(sandboxId, runtimeSessionId) {
+    assertUuid(runtimeSessionId, "runtimeSessionId");
+    return path.join(markerDirectory(sandboxId), runtimeSessionId + ".json");
+}
+function validateMarker(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new Error("workspace materialization marker must be an object");
+    }
+    const marker = raw;
+    const expectedKeys = [
+        "schemaVersion",
+        "sandboxId",
+        "sandboxGeneration",
+        "runtimeSessionId",
+        "workspaceContinuityState",
+        "snapshotId",
+        "revision",
+        "contentSha256",
+        "writtenAt",
+    ].sort();
+    if (Object.keys(marker).sort().some((key, index) => key !== expectedKeys[index]) ||
+        Object.keys(marker).length !== expectedKeys.length)
+        throw new Error("workspace materialization marker fields are invalid");
+    if (marker.schemaVersion !== WORKSPACE_MATERIALIZATION_SCHEMA) {
+        throw new Error("workspace materialization marker schema is unsupported");
+    }
+    if (typeof marker.sandboxId !== "string")
+        throw new Error("sandboxId is required");
+    if (typeof marker.runtimeSessionId !== "string") {
+        throw new Error("runtimeSessionId is required");
+    }
+    assertUuid(marker.sandboxId, "sandboxId");
+    assertUuid(marker.runtimeSessionId, "runtimeSessionId");
+    if (!Number.isSafeInteger(marker.sandboxGeneration) ||
+        marker.sandboxGeneration < 1 ||
+        !Number.isSafeInteger(marker.revision) ||
+        marker.revision < 0 ||
+        typeof marker.writtenAt !== "string" ||
+        Number.isNaN(Date.parse(marker.writtenAt)))
+        throw new Error("workspace materialization marker values are invalid");
+    if (marker.workspaceContinuityState !== "healthy" &&
+        marker.workspaceContinuityState !== "degraded")
+        throw new Error("workspace materialization continuity is invalid");
+    if (marker.snapshotId !== null) {
+        if (typeof marker.snapshotId !== "string")
+            throw new Error("snapshotId is invalid");
+        assertUuid(marker.snapshotId, "snapshotId");
+    }
+    const revisionZero = marker.revision === 0;
+    if (revisionZero !== (marker.snapshotId === null) ||
+        revisionZero !== (marker.contentSha256 === null) ||
+        (!revisionZero &&
+            (typeof marker.contentSha256 !== "string" || !SHA256.test(marker.contentSha256)))) {
+        throw new Error("workspace materialization marker pointer is inconsistent");
+    }
+    return marker;
+}
+export function writeWorkspaceMaterializationMarker(marker) {
+    validateMarker(marker);
+    const directory = markerDirectory(marker.sandboxId);
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    try {
+        chmodSync(directory, 0o700);
+    }
+    catch {
+        // Windows best effort.
+    }
+    const target = workspaceMaterializationMarkerPath(marker.sandboxId, marker.runtimeSessionId);
+    const staging = target + ".tmp-" + process.pid + "-" + randomBytes(4).toString("hex");
+    try {
+        writeFileSync(staging, JSON.stringify(marker), { encoding: "utf8", mode: 0o600 });
+        const file = openSync(staging, "r");
+        try {
+            fsyncSync(file);
+        }
+        finally {
+            closeSync(file);
+        }
+        renameSync(staging, target);
+        try {
+            chmodSync(target, 0o600);
+        }
+        catch {
+            // Windows best effort.
+        }
+        try {
+            const parent = openSync(directory, "r");
+            try {
+                fsyncSync(parent);
+            }
+            finally {
+                closeSync(parent);
+            }
+        }
+        catch {
+            // Some platforms cannot fsync a directory.
+        }
+    }
+    catch (error) {
+        try {
+            unlinkSync(staging);
+        }
+        catch {
+            // Staging may not have been created.
+        }
+        throw error;
+    }
+}
+export function readWorkspaceMaterializationMarker(sandboxId, runtimeSessionId) {
+    const file = workspaceMaterializationMarkerPath(sandboxId, runtimeSessionId);
+    if (!existsSync(file))
+        return null;
+    return validateMarker(JSON.parse(readFileSync(file, "utf8")));
+}
+export function removeWorkspaceMaterializationMarker(sandboxId, runtimeSessionId) {
+    const file = workspaceMaterializationMarkerPath(sandboxId, runtimeSessionId);
+    if (!existsSync(file))
+        return false;
+    unlinkSync(file);
+    return true;
+}

package/dist/workspace-quota.d.ts

@@ -0,0 +1,4 @@
+export declare const RUNTIME_WORKSPACE_QUOTA_BYTES: number;
+export declare const RUNTIME_WORKSPACE_INODE_QUOTA = 2000;
+export declare function assertRuntimeWorkspaceQuota(workspaceRoot: string): void;
+export declare function applyRuntimeWorkspaceQuota(runtimeSessionId: string, sandboxGeneration: number): Promise<void>;

package/dist/workspace-quota.js

@@ -0,0 +1,42 @@
+import { execFile } from "node:child_process";
+import { readFileSync, statfsSync, statSync } from "node:fs";
+import { promisify } from "node:util";
+export const RUNTIME_WORKSPACE_QUOTA_BYTES = 512 * 1024 * 1024;
+export const RUNTIME_WORKSPACE_INODE_QUOTA = 2_000;
+const WORKSPACE_BACKING_BYTES = 3 * 1024 * 1024 * 1024;
+const QUOTA_MARKER = "/var/lib/botlearn-runtime/workspace-quota.ready";
+const RUNTIME_LAUNCHER = "/opt/botlearn/bin/botlearn-runtime-launcher";
+const execFileAsync = promisify(execFile);
+export function assertRuntimeWorkspaceQuota(workspaceRoot) {
+    if (process.env.BOTLEARN_DAEMON_ENABLE_FAKE_RUNTIME === "1" || process.env.NODE_ENV === "test") {
+        return;
+    }
+    if (process.env.BOTLEARN_RUNTIME_WORKSPACE_QUOTA_BYTES !== String(RUNTIME_WORKSPACE_QUOTA_BYTES) ||
+        process.env.BOTLEARN_RUNTIME_WORKSPACE_INODE_QUOTA !== String(RUNTIME_WORKSPACE_INODE_QUOTA)) {
+        throw new Error("workspace_runtime_quota_unverified");
+    }
+    const filesystem = statfsSync(workspaceRoot, { bigint: true });
+    const marker = statSync(QUOTA_MARKER);
+    if (filesystem.blocks * filesystem.bsize < BigInt(WORKSPACE_BACKING_BYTES) ||
+        marker.uid !== 0 || (marker.mode & 0o777) !== 0o600 ||
+        readFileSync(QUOTA_MARKER, "utf8") !== "workspace-filesystem-quota/1\n") {
+        throw new Error("workspace_runtime_quota_probe_failed");
+    }
+}
+export async function applyRuntimeWorkspaceQuota(runtimeSessionId, sandboxGeneration) {
+    if (process.env.BOTLEARN_DAEMON_ENABLE_FAKE_RUNTIME === "1" || process.env.NODE_ENV === "test") {
+        return;
+    }
+    const args = ["--workspace-quota-apply", runtimeSessionId, String(sandboxGeneration)];
+    if (process.env.BOTLEARN_RUNTIME_LAUNCH_MODE === "sudo") {
+        await execFileAsync("/usr/bin/sudo", ["-n", "--", RUNTIME_LAUNCHER, ...args], {
+            timeout: 10_000,
+        });
+        return;
+    }
+    if (process.env.BOTLEARN_RUNTIME_LAUNCH_MODE === "direct-uid") {
+        await execFileAsync(RUNTIME_LAUNCHER, args, { timeout: 10_000 });
+        return;
+    }
+    throw new Error("workspace_runtime_quota_helper_unavailable");
+}

package/dist/workspace-restore.d.ts

@@ -0,0 +1,42 @@
+import { type WorkspaceEntry, type WorkspaceEntrySetLimits } from "./workspace-entry-set.js";
+export declare class WorkspaceRestoreError extends Error {
+    readonly code: string;
+    readonly retryable: boolean;
+    constructor(code: string, retryable?: boolean);
+}
+export interface WorkspaceRestoreDescriptor {
+    sandboxId: string;
+    sandboxGeneration: number;
+    runtimeSessionId: string;
+    continuityState: "healthy" | "degraded";
+    continuityErrorCode: string | null;
+    snapshotId: string | null;
+    revision: number;
+    contentSha256: string | null;
+    expectedFileCount: number;
+    expectedEntryCount: number;
+    expectedTotalBytes: number;
+}
+export interface WorkspaceRestoreOptions {
+    workspaceDirectory: string;
+    controlDirectory: string;
+    descriptor: WorkspaceRestoreDescriptor;
+    entrySet: unknown;
+    limits: WorkspaceEntrySetLimits;
+    requiredFreeBytes: number;
+    downloadFile(entry: WorkspaceEntry, partPath: string): Promise<void>;
+}
+export interface WorkspaceRestoreCapacityOptions {
+    workspaceDirectory: string;
+    descriptor: WorkspaceRestoreDescriptor;
+    requiredFreeBytes: number;
+    entryCopies?: 1 | 2;
+}
+export declare function workspaceRestoreJournalPath(controlDirectory: string, runtimeSessionId: string): string;
+export declare function recoverWorkspaceRestoreSwap(options: {
+    workspaceDirectory: string;
+    controlDirectory: string;
+    descriptor: WorkspaceRestoreDescriptor;
+}): boolean;
+export declare function restoreWorkspaceSnapshot(options: WorkspaceRestoreOptions): Promise<void>;
+export declare function assertWorkspaceRestoreCapacity(options: WorkspaceRestoreCapacityOptions): void;