@sema-agent/server 1.298.0 → 1.299.0

package/dist/config.d.ts

@@ -164,6 +164,7 @@ export interface ServiceConfig {
     };
     snapshotBlobSqlMaxBytes?: number;
     snapshotBlobAllowSql: boolean;
+    workspaceFileMaxBytes: number;
     sendUserFile?: {
         endpoint: string;
         publicEndpoint?: string;

package/dist/config.js

@@ -538,6 +538,7 @@ export function loadConfig() {
             : undefined,
         snapshotBlobSqlMaxBytes: optFinitePositiveEnv("SNAPSHOT_BLOB_SQL_MAX_BYTES"),
         snapshotBlobAllowSql: process.env.SNAPSHOT_BLOB_ALLOW_SQL_BYTES === "true",
+        workspaceFileMaxBytes: optFinitePositiveEnv("WORKSPACE_FILE_MAX_BYTES") ?? 8 * 1024 * 1024,
         sendUserFile: (process.env.MINIO_ENDPOINT || process.env.S3_ENDPOINT) && process.env.MINIO_ACCESS_KEY && process.env.MINIO_SECRET_KEY
             ? {
                 endpoint: (process.env.MINIO_ENDPOINT || process.env.S3_ENDPOINT),

package/dist/http/server.js

@@ -3,6 +3,7 @@ import { once } from "node:events";
 import { timingSafeEqual, createHash, randomBytes } from "node:crypto";
 import { sessionLogDigest, sessionLogDigestsComparable, uuidv7, sanitizePathComponent, callKeyOrdinal, isThinkingLevel, DEFAULT_EFFORT_LEVELS, expandTiers, materializeMcpTools, runWithVerification, resumeWithVerification, runCascade, CheckpointError, mintCheckpointToken, SessionPolicyError, SessionError, HAND_TOOL_EFFECTS, canonicalToolName, formatUserScope, defaultTaskRegistry, validatePendingSteer, StreamingImportValidator, getWorkflowRun, subscribeWorkflow, deriveAgentDisplayStatus } from "@sema-agent/core";
 import { decideParkedAgent, findParkedAgentForCheckpoint } from "../parked-decide.js";
+import { tarHeader, tarPadding, splitTarPath, TAR_END } from "./tar.js";
 import { matchCatalogModel } from "../model-select.js";
 import { mcpForScenario } from "../sema-registry.js";
 import { HttpError, principalFrom, verifiedPrincipal, setSsoPrincipal, ssoVerifiedPrincipal, setSsoScope, isUuidV7, isUuidShape, verifyDirectDoorProof, MAX_APPROVAL_REASON_CHARS } from "../security.js";
@@ -671,6 +672,12 @@ export function createHttpServer(deps) {
                 fleet: deps.fleetBus
                     ? { stream: true, sessionScope: true, observe: true, resume: "snapshot", bgNotifyFailClosed: true, steerPriority: "advisory" }
                     : false,
+                workspace: (() => {
+                    const wfs = deps.fileSnapshotStore;
+                    return wfs && typeof wfs.listKeys === "function" && typeof wfs.exportManifest === "function" && typeof wfs.getBlob === "function" && Boolean(deps.sessionStorage?.ownerOf)
+                        ? { browse: true, archive: true, maxFileBytes: deps.config.workspaceFileMaxBytes ?? 8 * 1024 * 1024 }
+                        : false;
+                })(),
                 leader: Boolean(deps.leaderEndpoint),
                 memory: false,
                 memoryWrite: false,
@@ -3932,6 +3939,180 @@ export function createHttpServer(deps) {
                 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, ...(keys.length > 0 ? { latest: keys[0] } : {}), total: keys.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) {
+                            sendJson(res, 413, { error: "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) {
+                        sendJson(res, 413, { error: "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((r) => res.once("drain", r));
+                    };
+                    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;
+            }
+        }
         {
             const sm = /^\/v1\/sessions\/([^/]+)\/sync\/(manifest|entries|import|plan|blobs(?:\/([^/]+))?|snapshots\/([^/]+)\/blobs\/([^/]+)|import\/([^/]+)\/entries)$/.exec(url);
             if (sm) {
@@ -6625,6 +6806,23 @@ function routeLabel(_method, url) {
         return url;
     return "other";
 }
+function workspaceContentType(relPath) {
+    const ext = relPath.slice(relPath.lastIndexOf(".") + 1).toLowerCase();
+    const TABLE = {
+        txt: "text/plain; charset=utf-8", md: "text/plain; charset=utf-8", log: "text/plain; charset=utf-8",
+        json: "application/json; charset=utf-8", csv: "text/csv; charset=utf-8",
+        png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg", gif: "image/gif", webp: "image/webp",
+        pdf: "application/pdf",
+    };
+    return TABLE[ext] ?? "application/octet-stream";
+}
+function looksBinary(bytes) {
+    const n = Math.min(bytes.byteLength, 8192);
+    for (let i = 0; i < n; i++)
+        if (bytes[i] === 0)
+            return true;
+    return false;
+}
 function authorized(req, token) {
     const h = req.headers.authorization ?? "";
     return safeEqual(h, `Bearer ${token}`) || safeEqual(h, `token ${token}`);

package/dist/http/tar.d.ts

@@ -0,0 +1,8 @@
+export declare function splitTarPath(relPath: string): {
+    prefix: string;
+    name: string;
+} | null;
+export declare function tarHeader(relPath: string, sizeBytes: number, mtimeSec: number): Buffer;
+export declare function tarPadding(sizeBytes: number): Buffer;
+export declare const TAR_END: Buffer<ArrayBuffer>;
+//# sourceMappingURL=tar.d.ts.map

package/dist/http/tar.js

@@ -0,0 +1,49 @@
+const BLOCK = 512;
+function octal(n, width) {
+    const s = n.toString(8).padStart(width - 1, "0");
+    return Buffer.from(s + "\0", "ascii");
+}
+export function splitTarPath(relPath) {
+    const bytes = Buffer.byteLength(relPath, "utf8");
+    if (bytes <= 100)
+        return { prefix: "", name: relPath };
+    if (bytes > 255)
+        return null;
+    for (let i = relPath.length - 1; i > 0; i--) {
+        if (relPath[i] !== "/")
+            continue;
+        const prefix = relPath.slice(0, i);
+        const name = relPath.slice(i + 1);
+        if (Buffer.byteLength(name, "utf8") <= 100 && Buffer.byteLength(prefix, "utf8") <= 155 && name.length > 0)
+            return { prefix, name };
+    }
+    return null;
+}
+export function tarHeader(relPath, sizeBytes, mtimeSec) {
+    const split = splitTarPath(relPath);
+    if (split === null)
+        throw new Error(`tar: path not representable in ustar (must be ≤255 bytes and splittable at "/"): ${relPath}`);
+    const h = Buffer.alloc(BLOCK, 0);
+    h.write(split.name, 0, 100, "utf8");
+    octal(0o644, 8).copy(h, 100);
+    octal(0, 8).copy(h, 108);
+    octal(0, 8).copy(h, 116);
+    octal(sizeBytes, 12).copy(h, 124);
+    octal(Math.max(0, Math.floor(mtimeSec)), 12).copy(h, 136);
+    h.fill(0x20, 148, 156);
+    h.write("0", 156, 1, "ascii");
+    h.write("ustar\0", 257, 6, "ascii");
+    h.write("00", 263, 2, "ascii");
+    h.write(split.prefix, 345, 155, "utf8");
+    let sum = 0;
+    for (const b of h)
+        sum += b;
+    Buffer.from(sum.toString(8).padStart(6, "0") + "\0 ", "ascii").copy(h, 148);
+    return h;
+}
+export function tarPadding(sizeBytes) {
+    const rem = sizeBytes % BLOCK;
+    return Buffer.alloc(rem === 0 ? 0 : BLOCK - rem, 0);
+}
+export const TAR_END = Buffer.alloc(BLOCK * 2, 0);
+//# sourceMappingURL=tar.js.map

package/dist/plugins/blob-backend.d.ts

@@ -21,6 +21,7 @@ export declare class SqlBlobBackend implements BlobBackend {
     hasBlobs(hashes: string[]): Promise<Set<string>>;
     deleteBlobs(hashes: string[]): Promise<number>;
 }
+export declare function sqlBlobSizes(dialect: "tidb" | "pg", pool: MysqlPool | PgPool, hashes: string[]): Promise<Map<string, number>>;
 export interface MinioBlobBackendConfig {
     endpoint: string;
     bucket: string;

package/dist/plugins/blob-backend.js

@@ -71,6 +71,19 @@ async function sqlHasBlobs(dialect, pool, hashes) {
     const r = await pool.query(`SELECT blob_hash FROM snapshot_blob WHERE blob_hash IN (${ph})`, distinct);
     return new Set(r.rows.map((row) => row.blob_hash));
 }
+export async function sqlBlobSizes(dialect, pool, hashes) {
+    if (hashes.length === 0)
+        return new Map();
+    const distinct = [...new Set(hashes)];
+    if (dialect === "tidb") {
+        const ph = distinct.map(() => "?").join(",");
+        const [rows] = await pool.query(`SELECT blob_hash, byte_len FROM snapshot_blob WHERE blob_hash IN (${ph})`, distinct);
+        return new Map(rows.map((r) => [String(r.blob_hash), Number(r.byte_len)]));
+    }
+    const ph = distinct.map((_, i) => `$${i + 1}`).join(",");
+    const r = await pool.query(`SELECT blob_hash, byte_len FROM snapshot_blob WHERE blob_hash IN (${ph})`, distinct);
+    return new Map(r.rows.map((row) => [row.blob_hash, Number(row.byte_len)]));
+}
 async function sqlDeleteIndexRowsPastGrace(dialect, pool, hashes) {
     if (hashes.length === 0)
         return [];

package/dist/plugins/pg-file-snapshot-store.d.ts

@@ -18,6 +18,7 @@ export declare class PgFileSnapshotStore implements FileSnapshotStore {
     exportManifest(scope: string, key: string): Promise<Map<string, string> | null>;
     getBlob(hash: string): Promise<Uint8Array | undefined>;
     hasBlobs(hashes: string[]): Promise<Set<string>>;
+    blobSizes(hashes: string[]): Promise<Map<string, number>>;
     reap(scope: string, keepKeys: string[]): Promise<number>;
     deleteBySession(scope: string): Promise<number>;
     private gcOrphanBlobs;

package/dist/plugins/pg-file-snapshot-store.js

@@ -1,6 +1,6 @@
 import { captureManifest, applyManifest, DEFAULT_SNAPSHOT_BOUNDS } from "@sema-agent/core";
 import { createHash } from "node:crypto";
-import { SqlBlobBackend } from "./blob-backend.js";
+import { SqlBlobBackend, sqlBlobSizes } from "./blob-backend.js";
 export class PgFileSnapshotStore {
     pool;
     bounds;
@@ -141,6 +141,9 @@ export class PgFileSnapshotStore {
     async hasBlobs(hashes) {
         return this.blobs.hasBlobs(hashes);
     }
+    async blobSizes(hashes) {
+        return sqlBlobSizes("pg", this.pool, hashes);
+    }
     async reap(scope, keepKeys) {
         return this.tx(async (c) => {
             const keys = await c.query("SELECT DISTINCT snap_key FROM snapshot_manifest WHERE scope = $1", [scope]);

package/dist/plugins/tidb-file-snapshot-store.d.ts

@@ -18,6 +18,7 @@ export declare class TiDBFileSnapshotStore implements FileSnapshotStore {
     exportManifest(scope: string, key: string): Promise<Map<string, string> | null>;
     getBlob(hash: string): Promise<Uint8Array | undefined>;
     hasBlobs(hashes: string[]): Promise<Set<string>>;
+    blobSizes(hashes: string[]): Promise<Map<string, number>>;
     reap(scope: string, keepKeys: string[]): Promise<number>;
     deleteBySession(scope: string): Promise<number>;
     private gcOrphanBlobs;

package/dist/plugins/tidb-file-snapshot-store.js

@@ -1,6 +1,6 @@
 import { captureManifest, applyManifest, DEFAULT_SNAPSHOT_BOUNDS } from "@sema-agent/core";
 import { createHash } from "node:crypto";
-import { SqlBlobBackend } from "./blob-backend.js";
+import { SqlBlobBackend, sqlBlobSizes } from "./blob-backend.js";
 export class TiDBFileSnapshotStore {
     pool;
     bounds;
@@ -141,6 +141,9 @@ export class TiDBFileSnapshotStore {
     async hasBlobs(hashes) {
         return this.blobs.hasBlobs(hashes);
     }
+    async blobSizes(hashes) {
+        return sqlBlobSizes("tidb", this.pool, hashes);
+    }
     async reap(scope, keepKeys) {
         return this.tx(async (conn) => {
             const [keys] = await conn.query("SELECT DISTINCT snap_key FROM snapshot_manifest WHERE scope = ?", [scope]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/server",
-  "version": "1.298.0",
+  "version": "1.299.0",
   "description": "Sema Server — the server/API implementation layer for Sema, wiring core, registry, model providers, and cloud agent execution. Built on @sema-agent/core.",
   "type": "module",
   "license": "BUSL-1.1",