@sema-agent/server 1.314.0 → 1.316.0

package/dist/http/routes/sessions.js

@@ -0,0 +1,746 @@
+import { materializeMcpTools, sanitizePathComponent, SessionPolicyError } from "@sema-agent/core";
+import { mcpForScenario } from "../../sema-registry.js";
+import { isUuidV7, isUuidShape } from "../../security.js";
+import { windowMessages, truncateMessageBlobs } from "../../audit.js";
+import { redactSecrets } from "../../trace/redact.js";
+import { MAX_SETTINGS_OUTPUT_STYLE_CHARS, MAX_SETTINGS_PERMISSION_RULES, MAX_SETTINGS_ENV_VARS, MAX_SETTINGS_ENV_KEY_CHARS, MAX_SETTINGS_ENV_VALUE_CHARS } from "../../task-settings.js";
+import { workspaceContentType, looksBinary } from "../workspace-content.js";
+import { tarHeader, tarPadding, splitTarPath, TAR_END } from "../tar.js";
+import { sendJson, sendError, sseHeaders } from "../send.js";
+import { gatedPrincipal, explicitOperatorOk } from "../principal-gate.js";
+const MCP_STATUS_TTL_MS = 5_000;
+const MCP_MATERIALIZE_TIMEOUT_MS = 10_000;
+export function createSessionsLocal() {
+    return {
+        sseConnections: 0,
+        sseOwnerLookups: 0,
+        mcpStatusCache: new Map(),
+    };
+}
+export async function handleSessions(req, res, url, ctx) {
+    const miss = { fell: false };
+    await handleSessionsBody(req, res, url, ctx, miss);
+    return !miss.fell;
+}
+async function handleSessionsBody(req, res, url, ctx, miss) {
+    const { deps } = ctx;
+    const { readJson, safeDecode, runOwnerOk, sessionOwnerScope, sessionOwnerScopeForWrite } = ctx.helpers;
+    const sse = ctx.local.sessions;
+    const { mcpStatusCache } = ctx.local.sessions;
+    {
+        const im = /^\/v1\/sessions\/([^/]+)\/init$/.exec(url);
+        if (im && req.method === "GET") {
+            const principal = gatedPrincipal(req, deps.config);
+            if (deps.config.requirePrincipal && !principal) {
+                sendJson(res, 401, { error: `missing principal header '${deps.config.principalHeader}'` });
+                return;
+            }
+            sendJson(res, 200, {
+                sessionId: im[1],
+                model: { provider: deps.config.model.provider, modelId: deps.config.model.id },
+                ...(deps.config.autonomy ? { mode: deps.config.autonomy } : {}),
+            });
+            return;
+        }
+    }
+    {
+        const stm = /^\/v1\/sessions\/([^/]+)\/settings$/.exec(url);
+        if (stm && req.method === "GET") {
+            const principal = gatedPrincipal(req, deps.config);
+            if (deps.config.requirePrincipal && !principal) {
+                sendJson(res, 401, { error: `missing principal header '${deps.config.principalHeader}'` });
+                return;
+            }
+            sendJson(res, 200, {
+                effective: {
+                    model: deps.config.model.id,
+                    ...(deps.config.autonomy ? { mode: deps.config.autonomy } : {}),
+                    approvalRequire: deps.config.approvalRequire,
+                    commandPolicy: deps.config.commandPolicy ?? [],
+                    limits: { maxTaskCostUsd: deps.config.maxTaskCostUsd, maxTaskTokens: deps.config.maxTaskTokens },
+                },
+                applied: { model: deps.config.model.id },
+            });
+            return;
+        }
+    }
+    {
+        const mm = /^\/v1\/sessions\/([^/]+)\/mcp$/.exec(url);
+        if (mm && req.method === "GET") {
+            if (deps.config.requirePrincipal && !gatedPrincipal(req, deps.config)) {
+                sendJson(res, 401, { error: `missing principal header '${deps.config.principalHeader}'` });
+                return;
+            }
+            const specs = mcpForScenario(deps.config.mcpServers, deps.config.defaultScenario);
+            if (!specs || specs.length === 0) {
+                sendJson(res, 200, { servers: [], asOf: new Date().toISOString() });
+                return;
+            }
+            const principal = gatedPrincipal(req, deps.config);
+            const cacheKey = `${deps.config.defaultScenario}::${principal ?? ""}`;
+            const cached = mcpStatusCache.get(cacheKey);
+            if (!cached || Date.now() - cached.at > MCP_STATUS_TTL_MS) {
+                if (mcpStatusCache.size > 1024)
+                    mcpStatusCache.clear();
+                const panel = (async () => {
+                    const matP = materializeMcpTools(specs, principal);
+                    let timer;
+                    const mat = await Promise.race([matP.catch(() => null), new Promise((r) => { timer = setTimeout(() => r(null), MCP_MATERIALIZE_TIMEOUT_MS); })]);
+                    if (timer)
+                        clearTimeout(timer);
+                    if (!mat) {
+                        void matP.then((m) => m?.dispose().catch(() => undefined)).catch(() => undefined);
+                        return { servers: [], asOf: new Date().toISOString(), degraded: true };
+                    }
+                    try {
+                        return {
+                            asOf: new Date().toISOString(),
+                            servers: mat.statuses.map((s) => ({
+                                name: s.name,
+                                status: s.status,
+                                ...(s.serverInfo ? { serverInfo: s.serverInfo } : {}),
+                                ...(s.toolNames ? { toolNames: s.toolNames } : {}),
+                                ...(s.error ? { error: redactSecrets(String(s.error)).slice(0, 200) } : {}),
+                            })),
+                        };
+                    }
+                    finally {
+                        await mat.dispose().catch(() => undefined);
+                    }
+                })();
+                mcpStatusCache.set(cacheKey, { at: Date.now(), panel });
+            }
+            sendJson(res, 200, await mcpStatusCache.get(cacheKey).panel);
+            return;
+        }
+    }
+    {
+        const hm = req.method === "GET" ? /^\/v1\/sessions\/([^/]+)\/head$/.exec(url) : null;
+        if (hm) {
+            const getLeafId = deps.sessionStorage?.getLeafId?.bind(deps.sessionStorage);
+            const ownerOf = deps.sessionStorage?.ownerOf?.bind(deps.sessionStorage);
+            if (!getLeafId || !ownerOf) {
+                sendJson(res, 501, { error: "session head probe requires a durable session store (SESSION_BACKEND=tidb|pg|local)" });
+                return;
+            }
+            const headSession = decodeURIComponent(hm[1]);
+            const getHead = deps.sessionStorage?.getHead?.bind(deps.sessionStorage);
+            let owner;
+            let leafId;
+            if (getHead) {
+                const head = await getHead(headSession);
+                if (head === undefined) {
+                    sendJson(res, 404, { error: "session not found" });
+                    return;
+                }
+                owner = head.owner;
+                if (!runOwnerOk(req, res, owner ?? null))
+                    return;
+                leafId = head.leafId;
+            }
+            else {
+                owner = await ownerOf(headSession);
+                if (owner === undefined) {
+                    sendJson(res, 404, { error: "session not found" });
+                    return;
+                }
+                if (!runOwnerOk(req, res, owner ?? null))
+                    return;
+                leafId = await getLeafId(headSession);
+            }
+            const etag = `"${leafId ?? "empty"}"`;
+            if (req.headers["if-none-match"] === etag) {
+                res.writeHead(304, { etag }).end();
+                return;
+            }
+            res.setHeader("etag", etag);
+            sendJson(res, 200, { sessionId: headSession, leafId });
+            return;
+        }
+    }
+    {
+        const em = req.method === "GET" ? /^\/v1\/sessions\/([^/]+)\/events$/.exec(url) : null;
+        if (em) {
+            const ownerOf = deps.sessionStorage?.ownerOf?.bind(deps.sessionStorage);
+            const watch = deps.sessionWatch;
+            if (!deps.sessionStorage?.getLeafId || !ownerOf || !watch) {
+                sendJson(res, 501, { error: "session events require a durable session store (SESSION_BACKEND=tidb|pg|local)" });
+                return;
+            }
+            const evSession = decodeURIComponent(em[1]);
+            if (sse.sseConnections >= (deps.sessionEventsMaxConnections ?? 256)) {
+                res.writeHead(503, { "retry-after": "5", "content-type": "application/json" });
+                res.end(JSON.stringify({ error: "session-events connection cap reached — fall back to /head polling" }));
+                return;
+            }
+            sse.sseConnections++;
+            let hb;
+            let unsubscribe;
+            let closed = false;
+            const cleanup = () => {
+                if (closed)
+                    return;
+                closed = true;
+                sse.sseConnections--;
+                if (hb)
+                    clearInterval(hb);
+                unsubscribe?.();
+            };
+            res.on("close", cleanup);
+            req.on("close", cleanup);
+            try {
+                const stallBound = deps.sessionEventsStallMs ?? 60_000;
+                if (sse.sseOwnerLookups >= 64) {
+                    cleanup();
+                    res.writeHead(503, { "retry-after": "5", "content-type": "application/json" });
+                    res.end(JSON.stringify({ error: "session-events owner-lookup concurrency cap — retry" }));
+                    return;
+                }
+                sse.sseOwnerLookups++;
+                const ownerP = ownerOf(evSession);
+                void ownerP.catch(() => undefined).then(() => { sse.sseOwnerLookups--; });
+                let stallTimer;
+                let owner;
+                try {
+                    owner = await Promise.race([
+                        ownerP,
+                        new Promise((r) => { stallTimer = setTimeout(() => r("__stall__"), stallBound); stallTimer.unref?.(); }),
+                    ]);
+                }
+                finally {
+                    if (stallTimer)
+                        clearTimeout(stallTimer);
+                }
+                if (closed)
+                    return;
+                if (owner === "__stall__") {
+                    cleanup();
+                    res.writeHead(503, { "retry-after": "5", "content-type": "application/json" });
+                    res.end(JSON.stringify({ error: "session-events owner lookup stalled — retry" }));
+                    return;
+                }
+                if (owner === undefined) {
+                    cleanup();
+                    sendJson(res, 404, { error: "session not found" });
+                    return;
+                }
+                if (!runOwnerOk(req, res, owner ?? null)) {
+                    cleanup();
+                    return;
+                }
+                const q = new URL(req.url ?? url, "http://x").searchParams;
+                const lastLeafId = q.get("lastLeafId");
+                let first = true;
+                let lastAccepted;
+                let lastWritten;
+                let writeBlocked = false;
+                let blockedAt = 0;
+                let pendingHead;
+                const stallMs = deps.sessionEventsStallMs ?? 60_000;
+                const writeRaw = (chunk) => {
+                    if (closed)
+                        return;
+                    try {
+                        const okW = res.write(chunk);
+                        if (!okW && !writeBlocked) {
+                            writeBlocked = true;
+                            blockedAt = Date.now();
+                            res.once("drain", () => {
+                                writeBlocked = false;
+                                const p = pendingHead;
+                                pendingHead = undefined;
+                                if (p && !closed && p.v !== lastWritten)
+                                    doWrite(p.v);
+                            });
+                        }
+                    }
+                    catch { }
+                };
+                const doWrite = (leafId) => {
+                    lastWritten = leafId;
+                    writeRaw(`event: head\ndata: ${JSON.stringify({ sessionId: evSession, leafId })}\n\n`);
+                };
+                const emit = (leafId) => {
+                    if (closed || leafId === lastAccepted)
+                        return;
+                    lastAccepted = leafId;
+                    const suppress = first && lastLeafId !== null && lastLeafId === (leafId ?? "null");
+                    first = false;
+                    if (suppress) {
+                        lastWritten = leafId;
+                        return;
+                    }
+                    if (writeBlocked) {
+                        pendingHead = { v: leafId };
+                        if (Date.now() - blockedAt > stallMs) {
+                            cleanup();
+                            try {
+                                res.end();
+                            }
+                            catch { }
+                        }
+                        return;
+                    }
+                    doWrite(leafId);
+                };
+                let started = false;
+                let preVal;
+                const onHead = (leafId) => {
+                    if (!started)
+                        preVal = { v: leafId };
+                    else
+                        emit(leafId);
+                };
+                const onEnd = () => { cleanup(); try {
+                    res.end();
+                }
+                catch { } };
+                unsubscribe = watch.subscribe(evSession, owner ?? null, onHead, onEnd);
+                if (!unsubscribe) {
+                    cleanup();
+                    res.writeHead(503, { "retry-after": "5", "content-type": "application/json" });
+                    res.end(JSON.stringify({ error: "session-events probe cap reached — fall back to /head polling" }));
+                    return;
+                }
+                res.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-cache, no-transform", connection: "keep-alive", "x-accel-buffering": "no" });
+                writeRaw(": connected\n\n");
+                started = true;
+                if (preVal !== undefined)
+                    emit(preVal.v);
+                const hbMs = deps.sessionEventsHeartbeatMs ?? 25_000;
+                let ownerCheckPending = false;
+                let ownerCheckStartedAt = 0;
+                hb = setInterval(() => {
+                    if (closed)
+                        return;
+                    if (writeBlocked && Date.now() - blockedAt > stallMs) {
+                        onEnd();
+                        return;
+                    }
+                    if (!writeBlocked)
+                        writeRaw(": hb\n\n");
+                    if (ownerCheckPending) {
+                        if (Date.now() - ownerCheckStartedAt > stallMs)
+                            onEnd();
+                        return;
+                    }
+                    ownerCheckPending = true;
+                    ownerCheckStartedAt = Date.now();
+                    void ownerOf(evSession).then((o) => {
+                        ownerCheckPending = false;
+                        if (!closed && o !== owner)
+                            onEnd();
+                    }).catch(() => { ownerCheckPending = false; });
+                }, hbMs);
+                hb.unref?.();
+            }
+            catch (e) {
+                cleanup();
+                if (!res.headersSent)
+                    sendJson(res, 500, { error: `session events failed: ${e instanceof Error ? e.message : "unknown"}` });
+                else
+                    try {
+                        res.end();
+                    }
+                    catch { }
+            }
+            return;
+        }
+    }
+    if (deps.sessionAudit && req.method === "GET") {
+        const sm = /^\/v1\/sessions\/([^/]+)$/.exec(url);
+        if (sm) {
+            const audit = await deps.sessionAudit(sm[1]);
+            if (!audit) {
+                sendJson(res, 404, { error: "session not found" });
+                return;
+            }
+            if (!runOwnerOk(req, res, audit.owner))
+                return;
+            const q = new URL(req.url ?? url, "http://x").searchParams;
+            const qi = (k) => {
+                const v = q.get(k);
+                if (v === null)
+                    return undefined;
+                const n = Number(v);
+                return Number.isFinite(n) && n >= 0 ? n : undefined;
+            };
+            const msgIndex = qi("message");
+            if (msgIndex !== undefined) {
+                const messages = audit.messages;
+                if (msgIndex >= messages.length) {
+                    sendJson(res, 404, { error: "message index out of range", total: messages.length });
+                    return;
+                }
+                sendJson(res, 200, { sessionId: audit.sessionId, floorEntryId: audit.floorEntryId, index: msgIndex, message: messages[msgIndex] });
+                return;
+            }
+            const tail = qi("tail");
+            const before = qi("before");
+            const blobCap = qi("blobCap");
+            if (tail === undefined && before === undefined && blobCap === undefined) {
+                sendJson(res, 200, audit);
+                return;
+            }
+            let messages = audit.messages;
+            let window;
+            if (tail !== undefined || before !== undefined) {
+                const w = windowMessages(messages, { ...(tail !== undefined ? { tail } : {}), ...(before !== undefined ? { before } : {}), ...(qi("limit") !== undefined ? { limit: qi("limit") } : {}) });
+                messages = w.messages;
+                window = w.window;
+            }
+            if (blobCap !== undefined && blobCap > 0)
+                messages = truncateMessageBlobs(messages, blobCap);
+            sendJson(res, 200, { ...audit, messages, ...(window ? { window } : {}) });
+            return;
+        }
+    }
+    {
+        const fm = req.method === "POST" ? /^\/v1\/sessions\/([^/]+)\/fork$/.exec(url) : null;
+        if (fm) {
+            const fork = deps.sessionStorage?.fork?.bind(deps.sessionStorage);
+            const ownerOf = deps.sessionStorage?.ownerOf?.bind(deps.sessionStorage);
+            if (!fork || !ownerOf) {
+                sendJson(res, 501, { error: "session fork requires a durable session store (SESSION_BACKEND=tidb)" });
+                return;
+            }
+            const scope = sessionOwnerScopeForWrite(req);
+            if (!scope.fleetWide && scope.gateOwner === null) {
+                sendJson(res, 401, { error: "unauthorized" });
+                return;
+            }
+            const sourceId = safeDecode(fm[1]);
+            if (sourceId === null || !isUuidV7(sourceId)) {
+                sendJson(res, 400, { error: "invalid session id (must be a uuidv7)" });
+                return;
+            }
+            const owner = await ownerOf(sourceId);
+            if (owner === undefined) {
+                sendJson(res, 404, { error: "session not found" });
+                return;
+            }
+            if (!scope.fleetWide && owner !== scope.gateOwner) {
+                sendJson(res, 404, { error: "session not found" });
+                return;
+            }
+            const newOwner = scope.fleetWide ? (owner ?? null) : scope.gateOwner;
+            const newId = await fork(sourceId, newOwner);
+            if (newId === null) {
+                sendJson(res, 404, { error: "session not found" });
+                return;
+            }
+            sendJson(res, 200, { sessionId: newId });
+            return;
+        }
+    }
+    {
+        const dm = req.method === "DELETE" ? /^\/v1\/sessions\/([^/]+)$/.exec(url) : null;
+        if (dm) {
+            const purge = deps.purgeSession;
+            const ownerOf = deps.sessionStorage?.ownerOf?.bind(deps.sessionStorage);
+            if (!purge || !ownerOf) {
+                sendJson(res, 501, { error: "session delete requires a durable session store (SESSION_BACKEND=tidb)" });
+                return;
+            }
+            const scope = sessionOwnerScopeForWrite(req);
+            if (!scope.fleetWide && scope.gateOwner === null) {
+                sendJson(res, 401, { error: "unauthorized" });
+                return;
+            }
+            const sessionId = safeDecode(dm[1]);
+            if (sessionId === null || !isUuidV7(sessionId)) {
+                sendJson(res, 400, { error: "invalid session id (must be a uuidv7)" });
+                return;
+            }
+            const owner = await ownerOf(sessionId);
+            if (owner === undefined) {
+                sendJson(res, 200, { deleted: false });
+                return;
+            }
+            if (!scope.fleetWide && owner !== scope.gateOwner) {
+                sendJson(res, 200, { deleted: false });
+                return;
+            }
+            const activeTaskId = await deps.runStore?.getActiveTaskId(sessionId);
+            if (activeTaskId) {
+                sendJson(res, 409, { error: "session has an active run; cancel it before deleting", activeTaskId });
+                return;
+            }
+            const result = await purge(sessionId, owner);
+            if ("active" in result) {
+                sendJson(res, 409, { error: "session has an active run; cancel it before deleting", activeTaskId: result.active });
+                return;
+            }
+            sendJson(res, 200, result);
+            return;
+        }
+    }
+    {
+        const pm = req.method === "GET" || req.method === "PUT" ? /^\/v1\/sessions\/([^/]+)\/policy$/.exec(url) : null;
+        if (pm) {
+            const store = deps.sessionPolicyStore;
+            const ownerOf = deps.sessionStorage?.ownerOf?.bind(deps.sessionStorage);
+            if (!store || !ownerOf) {
+                sendJson(res, 501, { error: "session policy requires a session-store backend" });
+                return;
+            }
+            const principal = gatedPrincipal(req, deps.config);
+            if (deps.config.requirePrincipal && principal === undefined) {
+                sendJson(res, 401, { error: "unauthorized" });
+                return;
+            }
+            const sessionId = safeDecode(pm[1]);
+            if (sessionId === null || !isUuidV7(sessionId)) {
+                sendJson(res, 400, { error: "invalid session id (must be a uuidv7)" });
+                return;
+            }
+            const owner = await ownerOf(sessionId);
+            if (owner === undefined) {
+                sendJson(res, 404, { error: "session not found" });
+                return;
+            }
+            if (owner === null) {
+                sendJson(res, 409, { error: "session policy requires an owned session (set REQUIRE_PRINCIPAL / attach a principal); this session is ownerless" });
+                return;
+            }
+            const operator = explicitOperatorOk(principal, deps.config.operatorPrincipals);
+            if (!operator && owner !== (principal ?? null)) {
+                sendJson(res, 404, { error: "session not found" });
+                return;
+            }
+            const target = owner;
+            if (req.method === "GET") {
+                sendJson(res, 200, { rules: (await store.getRules(sessionId, target)) ?? { rev: 0 } });
+                return;
+            }
+            let body;
+            try {
+                body = (await readJson(req));
+            }
+            catch {
+                sendJson(res, 400, { error: "invalid JSON body" });
+                return;
+            }
+            if (typeof body.rules !== "object" || body.rules === null || Array.isArray(body.rules)) {
+                sendJson(res, 400, { error: "rules must be a SessionPermissionRules object" });
+                return;
+            }
+            if (body.expectedRev !== undefined && (typeof body.expectedRev !== "number" || !Number.isInteger(body.expectedRev) || body.expectedRev < 0)) {
+                sendJson(res, 400, { error: "expectedRev must be a non-negative integer" });
+                return;
+            }
+            const raw = body.rules;
+            const rules = {};
+            for (const f of ["toolAllow", "toolDeny", "allowDirs", "commandAllow", "commandDeny"]) {
+                if (raw[f] === undefined)
+                    continue;
+                if (!Array.isArray(raw[f]) || !raw[f].every((x) => typeof x === "string")) {
+                    sendJson(res, 400, { error: `${f} must be an array of strings` });
+                    return;
+                }
+                rules[f] = raw[f];
+            }
+            try {
+                const stored = await store.putRules(sessionId, target, rules, { ...(typeof body.expectedRev === "number" ? { expectedRev: body.expectedRev } : {}), operator });
+                sendJson(res, 200, { rules: stored });
+            }
+            catch (e) {
+                if (e instanceof SessionPolicyError) {
+                    sendError(res, e.code === "conflict" ? 409 : 403, e.code, e.message);
+                    return;
+                }
+                throw e;
+            }
+            return;
+        }
+    }
+    {
+        const wm = req.method === "GET" ? /^\/v1\/sessions\/([^/]+)\/workspace(?:\/([^/]+)(?:\/(tree|file|archive))?)?$/.exec(url) : null;
+        if (wm) {
+            const fs = deps.fileSnapshotStore;
+            const ownerOf = deps.sessionStorage?.ownerOf?.bind(deps.sessionStorage);
+            if (!fs || typeof fs.listKeys !== "function" || typeof fs.exportManifest !== "function" || typeof fs.getBlob !== "function" || !ownerOf) {
+                sendJson(res, 501, { error: "workspace browse requires a durable snapshot store (rewindFiles wiring) and a durable session store" });
+                return;
+            }
+            const scope = sessionOwnerScope(req);
+            if (!scope.fleetWide && scope.gateOwner === null) {
+                sendJson(res, 401, { error: "unauthorized" });
+                return;
+            }
+            const wsSession = safeDecode(wm[1]);
+            if (wsSession === null || !isUuidShape(wsSession)) {
+                sendJson(res, 400, { error: "invalid session id (must be a canonical uuid)" });
+                return;
+            }
+            const wsOwner = await ownerOf(wsSession);
+            if (wsOwner === undefined || (!scope.fleetWide && wsOwner !== scope.gateOwner)) {
+                sendJson(res, 404, { error: "session not found" });
+                return;
+            }
+            const q = new URL(req.url ?? "", "http://x").searchParams;
+            const keys = (await fs.listKeys(wsSession)).sort().reverse();
+            const sub = wm[3];
+            if (wm[2] === undefined) {
+                const limRaw = q.get("limit");
+                if (limRaw !== null && !(/^[0-9]+$/.test(limRaw) && Number(limRaw) >= 1 && Number(limRaw) <= 100)) {
+                    sendJson(res, 400, { error: "limit must be a decimal integer in 1..100" });
+                    return;
+                }
+                const lim = limRaw === null ? 20 : Number(limRaw);
+                const page = keys.slice(0, lim);
+                const snapshots = [];
+                for (const k of page) {
+                    const m = await fs.exportManifest(wsSession, k);
+                    if (m === null)
+                        continue;
+                    let bytes;
+                    if (typeof fs.blobSizes === "function") {
+                        const sizes = await fs.blobSizes([...new Set(m.values())]);
+                        bytes = 0;
+                        for (const h of m.values())
+                            bytes += sizes.get(h) ?? 0;
+                    }
+                    snapshots.push({ key: k, files: m.size, ...(bytes !== undefined ? { bytes } : {}) });
+                }
+                sendJson(res, 200, {
+                    sessionId: wsSession,
+                    snapshots,
+                    ...(snapshots.length > 0 ? { latest: snapshots[0].key } : {}),
+                    total: snapshots.length,
+                });
+                return;
+            }
+            const keyRaw = safeDecode(wm[2]);
+            if (keyRaw === null) {
+                sendJson(res, 400, { error: "malformed snapshot key" });
+                return;
+            }
+            const key = keyRaw === "latest" ? keys[0] : keyRaw;
+            const manifest = key !== undefined ? await fs.exportManifest(wsSession, key) : null;
+            if (key === undefined || manifest === null) {
+                sendJson(res, 404, { error: "snapshot not found" });
+                return;
+            }
+            if (sub === "tree") {
+                const limRaw = q.get("limit");
+                if (limRaw !== null && !(/^[0-9]+$/.test(limRaw) && Number(limRaw) >= 1 && Number(limRaw) <= 2000)) {
+                    sendJson(res, 400, { error: "limit must be a decimal integer in 1..2000" });
+                    return;
+                }
+                const offRaw = q.get("offset");
+                if (offRaw !== null && !/^[0-9]+$/.test(offRaw)) {
+                    sendJson(res, 400, { error: "offset must be a non-negative integer" });
+                    return;
+                }
+                const lim = limRaw === null ? 500 : Number(limRaw);
+                const off = offRaw === null ? 0 : Number(offRaw);
+                const all = [...manifest.entries()].sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+                const page = all.slice(off, off + lim);
+                const sizes = typeof fs.blobSizes === "function" ? await fs.blobSizes([...new Set(page.map(([, h]) => h))]) : undefined;
+                sendJson(res, 200, {
+                    sessionId: wsSession,
+                    key,
+                    entries: page.map(([path, hash]) => ({ path, hash, ...(sizes?.get(hash) !== undefined ? { size: sizes.get(hash) } : {}) })),
+                    total: all.length,
+                    ...(off + lim < all.length ? { nextOffset: off + lim } : {}),
+                });
+                return;
+            }
+            if (sub === "file") {
+                const pathParam = q.get("path");
+                if (!pathParam) {
+                    sendJson(res, 400, { error: "missing ?path=<relPath from the tree>" });
+                    return;
+                }
+                const hash = manifest.get(pathParam);
+                if (hash === undefined) {
+                    sendJson(res, 404, { error: "no such file in this snapshot (paths are the tree's relPaths, verbatim)" });
+                    return;
+                }
+                const cap = deps.config.workspaceFileMaxBytes ?? 8 * 1024 * 1024;
+                if (typeof fs.blobSizes === "function") {
+                    const known = (await fs.blobSizes([hash])).get(hash);
+                    if (known !== undefined && known > cap) {
+                        sendError(res, 413, "workspace_file_too_large", "file exceeds the single-file read limit — download it via the archive endpoint", { code: "workspace_file_too_large", sizeBytes: known, limit: cap });
+                        return;
+                    }
+                }
+                const bytes = await fs.getBlob(hash);
+                if (bytes === undefined) {
+                    sendJson(res, 404, { error: "file content no longer available (snapshot raced a reap)" });
+                    return;
+                }
+                if (bytes.byteLength > cap) {
+                    sendError(res, 413, "workspace_file_too_large", "file exceeds the single-file read limit — download it via the archive endpoint", { code: "workspace_file_too_large", sizeBytes: bytes.byteLength, limit: cap });
+                    return;
+                }
+                const ct = workspaceContentType(pathParam);
+                const bin = looksBinary(bytes);
+                res.writeHead(200, {
+                    "content-type": ct,
+                    "content-length": bytes.byteLength,
+                    "x-content-type-options": "nosniff",
+                    "x-sema-content-binary": bin ? "true" : "false",
+                });
+                res.end(Buffer.from(bytes));
+                return;
+            }
+            if (sub === "archive") {
+                const entries = [...manifest.entries()].sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+                const bad = entries.filter(([p]) => splitTarPath(p) === null).map(([p]) => p);
+                if (bad.length > 0) {
+                    sendJson(res, 422, { error: `snapshot contains ${bad.length} path(s) not representable in ustar (>255 bytes or unsplittable)`, paths: bad.slice(0, 5) });
+                    return;
+                }
+                if (typeof fs.hasBlobs === "function") {
+                    const present = await fs.hasBlobs([...new Set(entries.map(([, h]) => h))]);
+                    const missing = entries.filter(([, h]) => !present.has(h)).length;
+                    if (missing > 0) {
+                        sendJson(res, 502, { error: `snapshot is missing ${missing} blob(s) (raced a reap or a partial import) — retry, or pick another snapshot` });
+                        return;
+                    }
+                }
+                res.writeHead(200, {
+                    "content-type": "application/x-tar",
+                    "content-disposition": `attachment; filename="workspace-${key}.tar"`,
+                    "x-content-type-options": "nosniff",
+                });
+                const write = async (buf) => {
+                    if (res.writableEnded || res.destroyed)
+                        throw new Error("client gone");
+                    if (!res.write(buf)) {
+                        await new Promise((resolve, reject) => {
+                            const onDrain = () => { cleanup(); resolve(); };
+                            const onGone = () => { cleanup(); reject(new Error("client gone (closed while draining)")); };
+                            const cleanup = () => { res.off("drain", onDrain); res.off("close", onGone); res.off("error", onGone); };
+                            res.once("drain", onDrain);
+                            res.once("close", onGone);
+                            res.once("error", onGone);
+                        });
+                    }
+                };
+                try {
+                    for (const [p, h] of entries) {
+                        const bytes = await fs.getBlob(h);
+                        if (bytes === undefined)
+                            throw new Error(`blob vanished mid-stream: ${h}`);
+                        await write(tarHeader(p, bytes.byteLength, 0));
+                        await write(Buffer.from(bytes));
+                        await write(tarPadding(bytes.byteLength));
+                    }
+                    await write(TAR_END);
+                    res.end();
+                }
+                catch {
+                    res.destroy();
+                }
+                return;
+            }
+            sendJson(res, 404, { error: "unknown workspace verb — use /tree, /file?path=, or /archive" });
+            return;
+        }
+    }
+    miss.fell = true;
+}
+//# sourceMappingURL=sessions.js.map