openmausbot 0.1.70 → 0.1.72

package/dist-server/server/usage-ledger.js

@@ -0,0 +1,239 @@
+// The USAGE ledger: one row per settled turn, append-only, month by month
+// under <data>/usage/, so "what did this workspace spend, by bot, by model,
+// by person, by day" is answerable after a restart and exportable for an
+// invoice. The per-task tally (store.ts addTaskUsage) is a running total
+// that lives and dies with the task; this is the durable record.
+//
+// Same discipline as the decision log: 0600 files, serialized appends per
+// directory, fire-and-forget. Bookkeeping must never fail the turn it is
+// booking. Rows carry who asked and what it cost, never message text.
+import { readFileSync } from "node:fs";
+import { appendFile, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { billableFor } from "./prices.js";
+export const USAGE_GROUPINGS = ["bot", "model", "user", "day", "engine"];
+const DIR = "usage";
+const MAX_RANGE_DAYS = 366;
+const DAY_MS = 24 * 60 * 60_000;
+const writeQueues = new Map();
+const clean = (value) => typeof value === "number" && Number.isFinite(value) ? Math.max(0, Math.trunc(value)) : 0;
+const finiteOrNull = (value) => typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : null;
+function monthKey(at) {
+    return `${at.getUTCFullYear()}-${String(at.getUTCMonth() + 1).padStart(2, "0")}`;
+}
+export function usageFileFor(dataDir, at) {
+    return join(dataDir, DIR, `${monthKey(at)}.jsonl`);
+}
+/** Append one settled turn. Fire-and-forget; see the module comment. */
+export function appendUsage(dataDir, row) {
+    const record = {
+        ...row,
+        at: row.at ?? new Date().toISOString(),
+        input: clean(row.input),
+        output: clean(row.output),
+        ...(typeof row.cachedInput === "number" ? { cachedInput: clean(row.cachedInput) } : {}),
+        costUsd: finiteOrNull(row.costUsd),
+    };
+    const previous = writeQueues.get(dataDir) ?? Promise.resolve();
+    const queued = previous
+        .then(() => write(dataDir, record))
+        .catch(() => {
+        /* bookkeeping must never take down the turn */
+    });
+    writeQueues.set(dataDir, queued);
+    void queued.finally(() => {
+        if (writeQueues.get(dataDir) === queued)
+            writeQueues.delete(dataDir);
+    });
+}
+async function write(dataDir, record) {
+    await mkdir(join(dataDir, DIR), { recursive: true, mode: 0o700 });
+    await appendFile(usageFileFor(dataDir, new Date(record.at)), JSON.stringify(record) + "\n", { mode: 0o600 });
+}
+/** Test/shutdown seam: wait until everything queued for this directory is on disk. */
+export async function flushUsageLedger(dataDir) {
+    await writeQueues.get(dataDir);
+}
+const isTrigger = (value) => typeof value === "object" && value !== null && typeof value.kind === "string";
+const isUsageRow = (value) => typeof value === "object" &&
+    value !== null &&
+    typeof value.at === "string" &&
+    typeof value.botId === "string" &&
+    typeof value.model === "string" &&
+    typeof value.input === "number" &&
+    typeof value.output === "number" &&
+    isTrigger(value.trigger);
+function monthsBetween(from, to) {
+    const keys = [];
+    const cursor = new Date(Date.UTC(from.getUTCFullYear(), from.getUTCMonth(), 1));
+    while (cursor.getTime() <= to.getTime()) {
+        keys.push(monthKey(cursor));
+        cursor.setUTCMonth(cursor.getUTCMonth() + 1);
+    }
+    return keys;
+}
+/** Every row whose time falls inside the range, oldest first. */
+export function readUsage(dataDir, range) {
+    const rows = [];
+    const from = range.from.getTime();
+    const to = range.to.getTime();
+    for (const key of monthsBetween(range.from, range.to)) {
+        let text;
+        try {
+            text = readFileSync(join(dataDir, DIR, `${key}.jsonl`), "utf8");
+        }
+        catch {
+            continue;
+        }
+        for (const line of text.split("\n")) {
+            if (!line)
+                continue;
+            try {
+                const value = JSON.parse(line);
+                if (!isUsageRow(value))
+                    continue;
+                const at = Date.parse(value.at);
+                if (at >= from && at <= to)
+                    rows.push(value);
+            }
+            catch {
+                /* a line torn mid-write: skip the fragment, keep the rest */
+            }
+        }
+    }
+    return rows;
+}
+/** A date range from query strings: `YYYY-MM-DD` each, `to` inclusive to
+ * the end of its day (UTC). Defaults to the current month to date. Null
+ * for anything malformed, reversed, or longer than a year. */
+export function parseUsageRange(from, to, now = new Date()) {
+    const day = /^(\d{4})-(\d{2})-(\d{2})$/;
+    const parse = (value, endOfDay) => {
+        const match = day.exec(value);
+        if (!match)
+            return null;
+        const date = new Date(Date.UTC(Number(match[1]), Number(match[2]) - 1, Number(match[3]), endOfDay ? 23 : 0, endOfDay ? 59 : 0, endOfDay ? 59 : 0, endOfDay ? 999 : 0));
+        // Reject 2026-02-31 style rollovers.
+        return date.getUTCMonth() === Number(match[2]) - 1 && date.getUTCDate() === Number(match[3]) ? date : null;
+    };
+    const start = from ? parse(from, false) : new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), 1));
+    const end = to ? parse(to, true) : now;
+    if (!start || !end || start.getTime() > end.getTime())
+        return null;
+    if (end.getTime() - start.getTime() > MAX_RANGE_DAYS * DAY_MS)
+        return null;
+    return { from: start, to: end };
+}
+/** A stable key and a display label for who asked. Labels for the
+ * non-person kinds are English fallbacks; the app localizes by key. */
+export function triggerKey(trigger) {
+    switch (trigger.kind) {
+        case "user":
+            return `user:${(trigger.email ?? trigger.label ?? "").toLowerCase() || "unknown"}`;
+        case "owner":
+            return "owner";
+        case "routine":
+            return `routine:${trigger.routineId ?? trigger.label ?? "unknown"}`;
+        default:
+            return "bot";
+    }
+}
+export function triggerLabel(trigger) {
+    switch (trigger.kind) {
+        case "user":
+            return trigger.email ?? trigger.label ?? "Signed-in user";
+        case "owner":
+            return "This computer";
+        case "routine":
+            return `Routine: ${trigger.label ?? trigger.routineId ?? "unknown"}`;
+        default:
+            return "Bot to bot";
+    }
+}
+function groupOf(row, groupBy) {
+    switch (groupBy) {
+        case "bot":
+            return { key: `bot:${row.botId}`, label: row.botName || row.botId };
+        case "model":
+            return { key: `model:${row.driverKind}/${row.model}`, label: row.model };
+        case "user":
+            return { key: triggerKey(row.trigger), label: triggerLabel(row.trigger) };
+        case "day":
+            return { key: `day:${row.at.slice(0, 10)}`, label: row.at.slice(0, 10) };
+        default:
+            return { key: `engine:${row.driverKind}`, label: row.driverKind };
+    }
+}
+function emptyGroup(key, label) {
+    return { key, label, turns: 0, input: 0, output: 0, cachedInput: 0, costUsd: null, unpriced: 0, billableUsd: null };
+}
+function add(group, row, prices) {
+    group.turns += 1;
+    group.input += clean(row.input);
+    group.output += clean(row.output);
+    group.cachedInput += clean(row.cachedInput);
+    const cost = finiteOrNull(row.costUsd);
+    if (cost === null)
+        group.unpriced += 1;
+    else
+        group.costUsd = (group.costUsd ?? 0) + cost;
+    const billable = prices ? billableFor(row, prices) : null;
+    if (billable !== null)
+        group.billableUsd = (group.billableUsd ?? 0) + billable;
+}
+/** Totals per group, money first then volume; days stay chronological. */
+export function summarizeUsage(rows, groupBy, prices = null) {
+    const groups = new Map();
+    const total = emptyGroup("total", "total");
+    for (const row of rows) {
+        const { key, label } = groupOf(row, groupBy);
+        let group = groups.get(key);
+        if (!group) {
+            group = emptyGroup(key, label);
+            groups.set(key, group);
+        }
+        add(group, row, prices);
+        add(total, row, prices);
+    }
+    const ordered = [...groups.values()];
+    if (groupBy === "day")
+        ordered.sort((a, b) => a.key.localeCompare(b.key));
+    else {
+        ordered.sort((a, b) => {
+            const costA = a.costUsd ?? Number.NEGATIVE_INFINITY;
+            const costB = b.costUsd ?? Number.NEGATIVE_INFINITY;
+            return costB - costA || b.input + b.output - (a.input + a.output);
+        });
+    }
+    return { groups: ordered, total };
+}
+function csvCell(value) {
+    if (value === null)
+        return "";
+    const text = String(value);
+    // A leading formula character is neutralised so a spreadsheet never
+    // executes a bot name or an email address.
+    const safe = /^[=+\-@\t\r]/.test(text) ? `'${text}` : text;
+    return /[",\n\r]/.test(safe) ? `"${safe.replaceAll('"', '""')}"` : safe;
+}
+/** One line per turn, spreadsheet-ready; a billable column when a price list is given. */
+export function usageCsv(rows, prices = null) {
+    const header = ["time", "bot", "model", "engine", "triggered_by", "input_tokens", "output_tokens", "cached_input_tokens", "cost_usd", ...(prices ? ["billable_usd"] : []), "thread"];
+    const lines = [header.join(",")];
+    for (const row of rows) {
+        lines.push([
+            row.at,
+            row.botName || row.botId,
+            row.model,
+            row.driverKind,
+            triggerLabel(row.trigger),
+            clean(row.input),
+            clean(row.output),
+            clean(row.cachedInput),
+            finiteOrNull(row.costUsd),
+            ...(prices ? [billableFor(row, prices)] : []),
+            row.threadId,
+        ].map(csvCell).join(","));
+    }
+    return lines.join("\n") + "\n";
+}

package/dist-server/server/webhook-ingress.js

@@ -70,7 +70,7 @@ function eventName(req) {
         header(req, "x-event-type") ??
         header(req, "ce-type"))?.trim() || undefined;
 }
-export function createWebhookIngressHandler(manager) {
+export function createWebhookIngressHandler(manager, claimRequest) {
     return async (req, res) => {
         const url = new URL(req.url ?? "/", "http://localhost");
         if (req.method === "GET" && url.pathname === "/health") {
@@ -81,7 +81,9 @@ export function createWebhookIngressHandler(manager) {
             return json(res, 404, { error: "Unknown webhook endpoint" });
         if (req.method !== "POST")
             return json(res, 405, { error: "Webhooks accept POST requests" });
+        let release;
         try {
+            release = claimRequest?.();
             const pathSecret = match[2] ? decodeURIComponent(match[2]) : "";
             const secret = pathSecret || bearerSecret(req);
             // Reject bad capability URLs before buffering or parsing attacker input.
@@ -121,6 +123,9 @@ export function createWebhookIngressHandler(manager) {
             }
             return json(res, status, { error: message });
         }
+        finally {
+            release?.();
+        }
     };
 }
 /** The base senders are told to use. Behind a proxy or tunnel the listening
@@ -142,7 +147,7 @@ export function advertisedWebhookBase(raw) {
 export async function listenWebhookIngress(manager, options) {
     const host = options.host ?? "127.0.0.1";
     const advertised = options.publicBaseUrl === undefined ? undefined : advertisedWebhookBase(options.publicBaseUrl);
-    const server = createServer(createWebhookIngressHandler(manager));
+    const server = createServer(createWebhookIngressHandler(manager, options.claimRequest));
     await new Promise((resolve, reject) => {
         const onError = (error) => reject(error);
         server.once("error", onError);

package/dist-server/server/workspace-backup-http.js

@@ -0,0 +1,264 @@
+import { randomUUID } from "node:crypto";
+import { createReadStream, createWriteStream, existsSync, lstatSync, mkdirSync, readdirSync, statSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { z } from "zod";
+import { WORKSPACE_BACKUP_CLIENT_KEYS } from "../shared/workspace-backup-client.js";
+import { createWorkspaceBackup, stageWorkspaceBackup, commitPendingWorkspaceRestore, MAX_WORKSPACE_BACKUP_UPLOAD_BYTES, removeWorkspaceBackupJob, } from "./workspace-backup.js";
+const PREFIX = "/api/workspace-backup";
+const MAX_UPLOAD_BYTES = MAX_WORKSPACE_BACKUP_UPLOAD_BYTES;
+const MAX_CLIENT_STATE_BYTES = 2 * 1024 ** 2;
+const EXPIRES_MS = 60 * 60_000;
+const passwordSchema = z.string().min(12, "Use a password of at least 12 characters.").max(1024);
+const failure = (message, status = 400) => Object.assign(new Error(message), { status });
+/** Session-only controls remain usable while the workspace is locked. Their
+ * excluded session file is not part of the snapshot or replacement. */
+export function isWorkspaceBackupSessionControl(method, path) {
+    return (method === "GET" && path === "/api/auth/sessions") ||
+        (method === "POST" && path === "/api/auth/logout") ||
+        (method === "DELETE" && /^\/api\/auth\/sessions\/[\w-]+$/.test(path));
+}
+/** All routes remain admin-only in request-auth. Passwords and raw credential
+ * metadata never appear in URLs, responses, logs, or event broadcasts. */
+export function createWorkspaceBackupRoutes(options) {
+    // ponytail: one bounded set per server; transfers expire after an hour.
+    const artifacts = new Map();
+    let operating = false;
+    const json = (res, status, body) => {
+        res.writeHead(status, { "content-type": "application/json", "cache-control": "no-store" });
+        res.end(JSON.stringify(body));
+    };
+    const owner = (auth) => auth.kind === "session" ? auth.session.id : "local-owner";
+    const check = (req, auth) => {
+        if (!options.authorized(req, auth))
+            throw failure("Your session changed. Reopen Backups and try again.", 403);
+    };
+    function remove(id, artifact) {
+        if (artifact.path) {
+            try {
+                unlinkSync(artifact.path);
+            }
+            catch { }
+        }
+        if (artifact.kind !== "upload") {
+            try {
+                removeWorkspaceBackupJob(options.dataDir, id);
+            }
+            catch { /* Recovery jobs are deliberately protected. */ }
+        }
+        artifacts.delete(id);
+    }
+    // A crashed process has no in-memory transfer map. Reclaim only its old,
+    // app-named jobs; never safety copies or pending/committed recovery state.
+    function reclaimAbandoned() {
+        const root = join(options.dataDir, ".backups");
+        if (!existsSync(root) || lstatSync(root).isSymbolicLink())
+            return;
+        for (const entry of readdirSync(root, { withFileTypes: true })) {
+            if (!entry.isDirectory() || !/^[a-f0-9-]{36}$/.test(entry.name))
+                continue;
+            if (statSync(join(root, entry.name)).mtimeMs + EXPIRES_MS > Date.now())
+                continue;
+            try {
+                removeWorkspaceBackupJob(options.dataDir, entry.name);
+            }
+            catch { /* May belong to a recoverable restore. */ }
+        }
+        const uploads = join(root, "uploads");
+        if (!existsSync(uploads) || lstatSync(uploads).isSymbolicLink())
+            return;
+        for (const entry of readdirSync(uploads, { withFileTypes: true })) {
+            if (!entry.isFile() || !/^[a-f0-9-]{36}\.ombbackup$/.test(entry.name))
+                continue;
+            const file = join(uploads, entry.name);
+            if (statSync(file).mtimeMs + EXPIRES_MS <= Date.now()) {
+                try {
+                    unlinkSync(file);
+                }
+                catch { }
+            }
+        }
+    }
+    try {
+        reclaimAbandoned();
+    }
+    catch { /* Temporary-file cleanup must not prevent normal server startup. */ }
+    function expire() {
+        for (const [id, artifact] of artifacts) {
+            if (artifact.expires > Date.now())
+                continue;
+            remove(id, artifact);
+        }
+    }
+    function replacePrevious(auth, kinds) {
+        expire();
+        for (const [id, artifact] of artifacts)
+            if (artifact.owner === owner(auth) && kinds.includes(artifact.kind))
+                remove(id, artifact);
+    }
+    const get = (id, auth, kind) => {
+        expire();
+        const artifact = typeof id === "string" ? artifacts.get(id) : undefined;
+        if (!artifact || artifact.owner !== owner(auth) || artifact.kind !== kind) {
+            throw failure("This backup has expired or belongs to another session. Select the file again.", 404);
+        }
+        return artifact;
+    };
+    async function operate(work) {
+        if (operating)
+            throw failure("Another backup operation is in progress. Wait for it to finish.", 409);
+        operating = true;
+        try {
+            return await work();
+        }
+        finally {
+            operating = false;
+        }
+    }
+    return async (req, res, path, auth) => {
+        if (!path.startsWith(`${PREFIX}/`))
+            return false;
+        res.setHeader("cache-control", "no-store");
+        const method = req.method;
+        try {
+            check(req, auth);
+            if (method === "GET" && path === `${PREFIX}/status`) {
+                json(res, 200, {
+                    ...options.status(),
+                    lastRestoreId: options.restored.restored ? options.restored.id : null,
+                    safetyCopyPath: options.restored.safetyCopyPath ?? null,
+                });
+                return true;
+            }
+            if (method === "POST" && path === `${PREFIX}/client-state`) {
+                const body = z.object({ restoreId: z.string().uuid() }).parse(await options.readBody(req));
+                check(req, auth);
+                if (!options.restored.restored || body.restoreId !== options.restored.id)
+                    throw failure("This restore has not completed. Restart OpenMausBot first.", 409);
+                json(res, 200, { clientState: options.restored.clientState ?? {} });
+                return true;
+            }
+            if (method === "POST" && path === `${PREFIX}/export`) {
+                // Allow the full preference budget plus the JSON envelope/password.
+                const body = z.object({ password: passwordSchema, clientState: z.record(z.string(), z.string()).default({}) }).parse(await options.readBody(req, MAX_CLIENT_STATE_BYTES + 8 * 1024));
+                if (Buffer.byteLength(JSON.stringify(body.clientState)) > MAX_CLIENT_STATE_BYTES)
+                    throw failure("Saved drafts exceed the 2 MB backup preference limit.", 413);
+                const clientState = Object.fromEntries(Object.entries(body.clientState).filter(([key]) => WORKSPACE_BACKUP_CLIENT_KEYS.includes(key)));
+                const result = await operate(() => options.exclusive(async () => {
+                    check(req, auth);
+                    replacePrevious(auth, ["download"]);
+                    if (artifacts.size >= 4)
+                        throw failure("There are already four backup files in progress. Restart or wait an hour before creating another.", 409);
+                    return createWorkspaceBackup(options.dataDir, { password: body.password, clientState, appVersion: options.appVersion });
+                }));
+                try {
+                    check(req, auth);
+                }
+                catch (error) {
+                    removeWorkspaceBackupJob(options.dataDir, result.id);
+                    throw error;
+                }
+                artifacts.set(result.id, { owner: owner(auth), kind: "download", path: result.path, summary: result.summary, expires: Date.now() + EXPIRES_MS });
+                json(res, 200, { id: result.id, filename: `OpenMausBot-${result.summary.createdAt.slice(0, 10)}.ombbackup`, bytes: statSync(result.path).size, summary: result.summary });
+                return true;
+            }
+            const download = /^\/api\/workspace-backup\/download\/([\w-]+)$/.exec(path);
+            if (method === "GET" && download) {
+                const artifact = get(download[1], auth, "download");
+                const file = artifact.path;
+                res.writeHead(200, {
+                    "content-type": "application/octet-stream",
+                    "content-length": statSync(file).size,
+                    "content-disposition": `attachment; filename="OpenMausBot-${artifact.summary.createdAt.slice(0, 10)}.ombbackup"`,
+                    "x-content-type-options": "nosniff",
+                });
+                await pipeline(createReadStream(file), res);
+                return true;
+            }
+            if (method === "POST" && path === `${PREFIX}/upload`) {
+                await operate(async () => {
+                    const length = Number(req.headers["content-length"]);
+                    if (!Number.isSafeInteger(length) || length <= 0 || length > MAX_UPLOAD_BYTES)
+                        throw failure("Select a backup containing no more than 10 GB of workspace data.", 413);
+                    replacePrevious(auth, ["upload", "staged"]);
+                    if (artifacts.size >= 4)
+                        throw failure("There are already four backup files in progress. Restart or wait an hour before uploading another.", 409);
+                    const root = join(options.dataDir, ".backups");
+                    mkdirSync(root, { recursive: true, mode: 0o700 });
+                    if (lstatSync(root).isSymbolicLink())
+                        throw failure("Backup storage must not be a symbolic link.");
+                    const directory = join(root, "uploads");
+                    mkdirSync(directory, { recursive: true, mode: 0o700 });
+                    if (lstatSync(directory).isSymbolicLink())
+                        throw failure("Backup storage must not be a symbolic link.");
+                    const id = randomUUID();
+                    const file = join(directory, `${id}.ombbackup`);
+                    let bytes = 0;
+                    try {
+                        const limit = new Transform({ transform(chunk, _encoding, callback) {
+                                bytes += chunk.length;
+                                callback(bytes > MAX_UPLOAD_BYTES ? failure("The backup is too large.", 413) : null, chunk);
+                            } });
+                        await pipeline(req.iterator({ destroyOnReturn: false }), limit, createWriteStream(file, { flags: "wx", mode: 0o600 }));
+                        if (bytes !== length)
+                            throw failure("The upload was incomplete. Select the file again.");
+                        check(req, auth);
+                        artifacts.set(id, { owner: owner(auth), kind: "upload", path: file, expires: Date.now() + EXPIRES_MS });
+                        json(res, 200, { id });
+                    }
+                    catch (error) {
+                        try {
+                            unlinkSync(file);
+                        }
+                        catch { }
+                        throw error;
+                    }
+                });
+                return true;
+            }
+            if (method === "POST" && path === `${PREFIX}/preview`) {
+                const body = z.object({ id: z.string().uuid(), password: passwordSchema }).parse(await options.readBody(req));
+                const artifact = get(body.id, auth, "upload");
+                const result = await operate(() => stageWorkspaceBackup(options.dataDir, artifact.path, { password: body.password, currentAppVersion: options.appVersion }));
+                try {
+                    check(req, auth);
+                }
+                catch (error) {
+                    removeWorkspaceBackupJob(options.dataDir, result.id);
+                    throw error;
+                }
+                try {
+                    unlinkSync(artifact.path);
+                }
+                catch { }
+                artifacts.delete(body.id);
+                artifacts.set(result.id, { owner: owner(auth), kind: "staged", summary: result.summary, expires: Date.now() + EXPIRES_MS });
+                json(res, 200, { id: result.id, summary: result.summary });
+                return true;
+            }
+            if (method === "POST" && path === `${PREFIX}/restore`) {
+                const body = z.object({ id: z.string().uuid(), confirmation: z.literal("REPLACE") }).parse(await options.readBody(req));
+                get(body.id, auth, "staged");
+                const result = await operate(() => options.exclusive(async () => {
+                    check(req, auth);
+                    return commitPendingWorkspaceRestore(options.dataDir, body.id);
+                }, true));
+                artifacts.delete(body.id);
+                json(res, 200, { ...result, restoreId: body.id });
+                return true;
+            }
+            json(res, 404, { error: "Unknown backup operation." });
+        }
+        catch (error) {
+            if (res.headersSent) {
+                res.destroy();
+                return true;
+            }
+            json(res, error instanceof z.ZodError ? 400 : error.status ?? 400, {
+                error: error instanceof z.ZodError ? error.issues[0]?.message ?? "Invalid backup request." : error instanceof Error ? error.message : "Backup failed.",
+            });
+        }
+        return true;
+    };
+}

package/dist-server/server/workspace-backup-maintenance.js

@@ -0,0 +1,40 @@
+/** A backup owns one quiet workspace. Never interrupt a turn to obtain it. */
+export class WorkspaceBackupMaintenance {
+    active = false;
+    pendingRestore = false;
+    requests = 0;
+    assertAvailable() {
+        if (this.active)
+            throw Object.assign(new Error(this.pendingRestore
+                ? "A workspace restore is ready. Fully quit and reopen OpenMausBot (or restart the hosted server) to finish."
+                : "A workspace backup is in progress. Try again when it finishes."), { status: 503 });
+    }
+    request() {
+        this.assertAvailable();
+        this.requests++;
+        return () => { this.requests--; };
+    }
+    async run(work, hooks, keepLocked = false) {
+        this.assertAvailable();
+        if (this.requests || !hooks.idle())
+            throw Object.assign(new Error("Wait for bot turns, approvals, sign-ins, and computer actions to finish before backing up or restoring."), { status: 409 });
+        this.active = true;
+        let committed = false;
+        try {
+            hooks.pause();
+            await hooks.flush();
+            if (!hooks.idle())
+                throw Object.assign(new Error("The workspace is still finishing background work. Try again shortly."), { status: 409 });
+            const result = await work();
+            committed = keepLocked;
+            this.pendingRestore = keepLocked;
+            return result;
+        }
+        finally {
+            if (!committed) {
+                this.active = false;
+                hooks.resume();
+            }
+        }
+    }
+}

package/dist-server/server/workspace-backup-policy.js

@@ -0,0 +1,28 @@
+import { parseStoredConfig } from "./config.js";
+// Connection sections deliberately stay on the destination as a whole: a
+// restored URL must never redirect an API key retained from that device.
+// Allowlisting ordinary settings also keeps future/unknown auth fields out.
+const PORTABLE_CONFIG_KEYS = [
+    "profile", "language", "budgets", "billing", "rooms", "threads",
+    "localVm", "features", "browserProfiles",
+];
+export function portableWorkspaceConfig(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("Invalid workspace configuration in backup.");
+    const config = parseStoredConfig(value);
+    return Object.fromEntries(PORTABLE_CONFIG_KEYS.filter((key) => config[key] !== undefined).map((key) => [key, config[key]]));
+}
+export function restoredWorkspaceConfig(portable, destination) {
+    if (!destination || typeof destination !== "object" || Array.isArray(destination))
+        throw new Error("Invalid destination workspace configuration; connections were not changed.");
+    const merged = { ...destination };
+    for (const key of PORTABLE_CONFIG_KEYS)
+        delete merged[key];
+    return { ...merged, ...portableWorkspaceConfig(portable) };
+}
+/** Exact app-owned authentication paths, not a scan of user document text. */
+export function excludedWorkspaceAuthPath(path) {
+    return /^(?:(?:providers|caddy|chrome-profile|\.agent-browser)(?:\/|$)|workspace-credentials\.json$|browser-engine-key$)/.test(path) ||
+        /^(?:config\.json|webhooks\.json|workspace-credentials\.json|browser-engine-key|sessions\.json|tunnel-account\.json)\.\d+(?:\.[0-9a-f-]+)?\.tmp$/.test(path) ||
+        /^(?:vm-home|vm-homes\/[^/]+)\/\.browser-profiles(?:\/|$)/.test(path);
+}