@sema-agent/server 1.316.0 → 1.317.0

package/dist/http/routes/session-sync.js

@@ -40,35 +40,35 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
         if (sm) {
             const ownerOf = deps.sessionStorage?.ownerOf?.bind(deps.sessionStorage);
             if (!deps.backend || !ownerOf) {
-                sendJson(res, 501, { error: "session sync requires a durable session store" });
+                sendError(res, 501, "capability.session_store_required", "session sync requires a durable session store");
                 return;
             }
             const scope = sessionOwnerScopeForWrite(req);
             if (!scope.fleetWide && scope.gateOwner === null) {
-                sendJson(res, 401, { error: "unauthorized" });
+                sendError(res, 401, "auth.unauthorized", "unauthorized");
                 return;
             }
             const sessionId = safeDecode(sm[1]);
             if (sessionId === null || !isUuidShape(sessionId)) {
-                sendJson(res, 400, { error: "invalid session id (must be a canonical uuid)" });
+                sendError(res, 400, "request.id_invalid", "invalid session id (must be a canonical uuid)");
                 return;
             }
             const owner = await ownerOf(sessionId);
             const ownsOrFleet = (o) => scope.fleetWide || o === scope.gateOwner;
             const pullGateOk = () => {
                 if (owner === undefined) {
-                    sendJson(res, 404, { error: "session not found" });
+                    sendError(res, 404, "not_found.session", "session not found");
                     return false;
                 }
                 if (!ownsOrFleet(owner)) {
-                    sendJson(res, 404, { error: "session not found" });
+                    sendError(res, 404, "not_found.session", "session not found");
                     return false;
                 }
                 return true;
             };
             const pushGateOk = () => {
                 if (owner !== undefined && !ownsOrFleet(owner)) {
-                    sendJson(res, 404, { error: "session not found" });
+                    sendError(res, 404, "not_found.session", "session not found");
                     return false;
                 }
                 return true;
@@ -78,7 +78,7 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                     return;
                 const out = await exportSessionManifest(sessionId, deps.backend);
                 if (out === null) {
-                    sendJson(res, 404, { error: "session not found" });
+                    sendError(res, 404, "not_found.session", "session not found");
                     return;
                 }
                 sendJson(res, 200, { manifest: out.manifest });
@@ -92,19 +92,19 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                 if (afterSeqRaw !== null) {
                     const n = Number(afterSeqRaw);
                     if (!Number.isInteger(n) || n < 0) {
-                        sendJson(res, 400, { error: "afterSeq must be a non-negative integer" });
+                        sendError(res, 400, "request.query_invalid", "afterSeq must be a non-negative integer");
                         return;
                     }
                     afterSeq = n;
                 }
                 const stream = deps.sessionStorage?.exportEntriesStream?.bind(deps.sessionStorage);
                 if (!stream) {
-                    sendJson(res, 501, { error: "session entry streaming requires a durable session store" });
+                    sendError(res, 501, "capability.session_store_required", "session entry streaming requires a durable session store");
                     return;
                 }
                 const it = await stream(sessionId, afterSeq === undefined ? undefined : { afterSeq });
                 if (it === null) {
-                    sendJson(res, 404, { error: "session not found" });
+                    sendError(res, 404, "not_found.session", "session not found");
                     return;
                 }
                 res.writeHead(200, { "content-type": "application/x-ndjson", "transfer-encoding": "chunked" });
@@ -132,22 +132,22 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                 const key = safeDecode(sm[4]);
                 const hash = safeDecode(sm[5]);
                 if (key === null || hash === null) {
-                    sendJson(res, 400, { error: "invalid snapshot key or blob hash" });
+                    sendError(res, 400, "request.path_malformed", "invalid snapshot key or blob hash");
                     return;
                 }
                 if (!SHA256_HEX_RE.test(hash)) {
-                    sendJson(res, 400, { error: "blob hash must be 64 lowercase-hex chars" });
+                    sendError(res, 400, "request.id_invalid", "blob hash must be 64 lowercase-hex chars");
                     return;
                 }
                 const fs = deps.fileSnapshotStore;
                 const manifest = await fs?.exportManifest?.(sessionId, key);
                 if (!manifest || ![...manifest.values()].includes(hash)) {
-                    sendJson(res, 404, { error: "blob not found" });
+                    sendError(res, 404, "not_found.blob", "blob not found");
                     return;
                 }
                 const bytes = await fs?.getBlob?.(hash);
                 if (!bytes) {
-                    sendJson(res, 404, { error: "blob not found" });
+                    sendError(res, 404, "not_found.blob", "blob not found");
                     return;
                 }
                 res.writeHead(200, { "content-type": "application/octet-stream" });
@@ -159,12 +159,12 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                     return;
                 const hash = safeDecode(sm[3]);
                 if (hash === null || !SHA256_HEX_RE.test(hash)) {
-                    sendJson(res, 400, { error: "blob hash must be 64 lowercase-hex chars" });
+                    sendError(res, 400, "request.id_invalid", "blob hash must be 64 lowercase-hex chars");
                     return;
                 }
                 const fs = deps.fileSnapshotStore;
                 if (typeof fs?.putBlob !== "function") {
-                    sendJson(res, 501, { error: "blob upload requires a durable snapshot store" });
+                    sendError(res, 501, "capability.snapshot_store_required", "blob upload requires a durable snapshot store");
                     return;
                 }
                 const body = await readRawBody(req, SYNC_BLOB_MAX_BYTES);
@@ -173,7 +173,7 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                     return;
                 }
                 if (createHash("sha256").update(body).digest("hex") !== hash) {
-                    sendJson(res, 400, { error: "blob hash mismatch" });
+                    sendError(res, 400, "request.hash_mismatch", "blob hash mismatch");
                     return;
                 }
                 const put = await fs.putBlob(hash, new Uint8Array(body));
@@ -197,7 +197,7 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                     }).catch(() => { });
                 }
                 if (!deps.sessionStorage?.beginImportStaging) {
-                    sendJson(res, 501, { error: "staged session import requires a durable session store" });
+                    sendError(res, 501, "capability.session_store_required", "staged session import requires a durable session store");
                     return;
                 }
                 let body;
@@ -205,20 +205,20 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                     body = (await readJson(req));
                 }
                 catch {
-                    sendJson(res, 400, { error: "invalid JSON body" });
+                    sendError(res, 400, "request.invalid_json", "invalid JSON body");
                     return;
                 }
                 if (!Array.isArray(body.entryIds) || !body.entryIds.every((x) => typeof x === "string")) {
-                    sendJson(res, 400, { error: "entryIds must be an array of strings" });
+                    sendError(res, 400, "request.field_invalid", "entryIds must be an array of strings");
                     return;
                 }
                 const snapshotsOk = Array.isArray(body.snapshots) && body.snapshots.every((s) => typeof s === "object" && s !== null && typeof s.key === "string" && Array.isArray(s.manifest));
                 if (!snapshotsOk || !Array.isArray(body.policy) || !Array.isArray(body.anchors)) {
-                    sendJson(res, 400, { error: "malformed import metadata" });
+                    sendError(res, 400, "request.body_shape", "malformed import metadata");
                     return;
                 }
                 if (body.resolution !== undefined && body.resolution !== "overwrite-dst") {
-                    sendJson(res, 400, { error: "resolution must be 'overwrite-dst'" });
+                    sendError(res, 400, "request.field_invalid", "resolution must be 'overwrite-dst'");
                     return;
                 }
                 const resolution = body.resolution;
@@ -338,16 +338,16 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
             if (sm[6] !== undefined && req.method === "POST") {
                 const stagingId = safeDecode(sm[6]);
                 if (stagingId === null) {
-                    sendJson(res, 400, { error: "invalid staging id" });
+                    sendError(res, 400, "request.id_invalid", "invalid staging id");
                     return;
                 }
                 const pending = pendingStagings.get(stagingId);
                 if (!pending || pending.realSessionId !== sessionId) {
-                    sendJson(res, 404, { error: "staging not found" });
+                    sendError(res, 404, "not_found.staging", "staging not found");
                     return;
                 }
                 if (!pending.openedFleetWide && !scope.fleetWide && pending.openedBy !== scope.gateOwner) {
-                    sendJson(res, 404, { error: "staging not found" });
+                    sendError(res, 404, "not_found.staging", "staging not found");
                     return;
                 }
                 const getBlob = (h) => deps.fileSnapshotStore.getBlob(h);
@@ -492,11 +492,11 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                     body = (await readJson(req));
                 }
                 catch {
-                    sendJson(res, 400, { error: "invalid JSON body" });
+                    sendError(res, 400, "request.invalid_json", "invalid JSON body");
                     return;
                 }
                 if (!Array.isArray(body.entryIds) || !body.entryIds.every((x) => typeof x === "string")) {
-                    sendJson(res, 400, { error: "entryIds must be an array of strings" });
+                    sendError(res, 400, "request.field_invalid", "entryIds must be an array of strings");
                     return;
                 }
                 const dst = await deps.sessionStorage?.exportEntries?.(sessionId);
@@ -504,7 +504,7 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                 sendJson(res, 200, relation);
                 return;
             }
-            sendJson(res, 404, { error: "not found" });
+            sendError(res, 404, "not_found.route", "not found");
             return;
         }
     }

package/dist/http/routes/sessions-list.js

@@ -1,5 +1,5 @@
 import { isUuidV7 } from "../../security.js";
-import { sendJson } from "../send.js";
+import { sendJson, sendError } from "../send.js";
 export async function handleSessionsList(req, res, url, ctx) {
     const miss = { fell: false };
     await handleSessionsListBody(req, res, url, ctx, miss);
@@ -11,12 +11,12 @@ async function handleSessionsListBody(req, res, url, ctx, miss) {
     if (req.method === "GET" && url === "/v1/sessions") {
         const { fleetWide, gateOwner } = sessionOwnerScope(req);
         if (!fleetWide && gateOwner === null) {
-            sendJson(res, 401, { error: "unauthorized" });
+            sendError(res, 401, "auth.unauthorized", "unauthorized");
             return;
         }
         const lister = deps.sessionStorage?.listSessions?.bind(deps.sessionStorage) ?? deps.runStore?.listSessions?.bind(deps.runStore);
         if (!lister) {
-            sendJson(res, 501, { error: "session list requires a durable session store (SESSION_BACKEND=tidb)" });
+            sendError(res, 501, "capability.session_store_required", "session list requires a durable session store (SESSION_BACKEND=tidb)");
             return;
         }
         await handleSessionList(res, lister, new URL(req.url ?? "", "http://x").searchParams, gateOwner);
@@ -25,23 +25,23 @@ async function handleSessionsListBody(req, res, url, ctx, miss) {
     if (req.method === "GET" && url === "/v1/sendfile-links") {
         const { fleetWide, gateOwner } = sessionOwnerScope(req);
         if (!fleetWide && gateOwner === null) {
-            sendJson(res, 401, { error: "unauthorized" });
+            sendError(res, 401, "auth.unauthorized", "unauthorized");
             return;
         }
         if (!deps.sendFileLedger) {
-            sendJson(res, 501, { error: "sendfile ledger requires a store backend (DB_BACKEND=tidb|pg|local) and the SendUserFile issuer configured" });
+            sendError(res, 501, "capability.store_required", "sendfile ledger requires a store backend (DB_BACKEND=tidb|pg|local) and the SendUserFile issuer configured");
             return;
         }
         const query = new URL(req.url ?? "", "http://x").searchParams;
         const limitRaw = query.get("limit");
         if (limitRaw !== null && !(/^[0-9]+$/.test(limitRaw) && Number(limitRaw) >= 1 && Number(limitRaw) <= 100)) {
-            sendJson(res, 400, { error: "limit must be a decimal integer in 1..100" });
+            sendError(res, 400, "request.query_invalid", "limit must be a decimal integer in 1..100");
             return;
         }
         const limit = limitRaw === null ? 50 : Number(limitRaw);
         const beforeRaw = query.get("before");
         if (beforeRaw !== null && !isUuidV7(beforeRaw)) {
-            sendJson(res, 400, { error: "before must be a uuidv7 link id (the `id`/`nextBefore` of a previous page)" });
+            sendError(res, 400, "request.id_invalid", "before must be a uuidv7 link id (the `id`/`nextBefore` of a previous page)");
             return;
         }
         const before = beforeRaw ?? undefined;
@@ -57,7 +57,7 @@ async function handleSessionsListBody(req, res, url, ctx, miss) {
             else {
                 const s = scopeRaw.trim();
                 if (s === "" || s.length > 190) {
-                    sendJson(res, 400, { error: "scope must be a non-blank tenant principal of at most 190 characters (the sendfile_link.scope column width)" });
+                    sendError(res, 400, "request.query_invalid", "scope must be a non-blank tenant principal of at most 190 characters (the sendfile_link.scope column width)");
                     return;
                 }
                 scope = s;

package/dist/http/routes/sessions.js

@@ -32,7 +32,7 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
         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}'` });
+                sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
                 return;
             }
             sendJson(res, 200, {
@@ -48,7 +48,7 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
         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}'` });
+                sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
                 return;
             }
             sendJson(res, 200, {
@@ -68,7 +68,7 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
         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}'` });
+                sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
                 return;
             }
             const specs = mcpForScenario(deps.config.mcpServers, deps.config.defaultScenario);
@@ -120,7 +120,7 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
             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)" });
+                sendError(res, 501, "capability.session_store_required", "session head probe requires a durable session store (SESSION_BACKEND=tidb|pg|local)");
                 return;
             }
             const headSession = decodeURIComponent(hm[1]);
@@ -130,7 +130,7 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
             if (getHead) {
                 const head = await getHead(headSession);
                 if (head === undefined) {
-                    sendJson(res, 404, { error: "session not found" });
+                    sendError(res, 404, "not_found.session", "session not found");
                     return;
                 }
                 owner = head.owner;
@@ -141,7 +141,7 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
             else {
                 owner = await ownerOf(headSession);
                 if (owner === undefined) {
-                    sendJson(res, 404, { error: "session not found" });
+                    sendError(res, 404, "not_found.session", "session not found");
                     return;
                 }
                 if (!runOwnerOk(req, res, owner ?? null))
@@ -164,7 +164,7 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
             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)" });
+                sendError(res, 501, "capability.session_store_required", "session events require a durable session store (SESSION_BACKEND=tidb|pg|local)");
                 return;
             }
             const evSession = decodeURIComponent(em[1]);
@@ -221,7 +221,7 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
                 }
                 if (owner === undefined) {
                     cleanup();
-                    sendJson(res, 404, { error: "session not found" });
+                    sendError(res, 404, "not_found.session", "session not found");
                     return;
                 }
                 if (!runOwnerOk(req, res, owner ?? null)) {
@@ -337,7 +337,7 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
             catch (e) {
                 cleanup();
                 if (!res.headersSent)
-                    sendJson(res, 500, { error: `session events failed: ${e instanceof Error ? e.message : "unknown"}` });
+                    sendError(res, 500, "internal.error", `session events failed: ${e instanceof Error ? e.message : "unknown"}`);
                 else
                     try {
                         res.end();
@@ -352,7 +352,7 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
         if (sm) {
             const audit = await deps.sessionAudit(sm[1]);
             if (!audit) {
-                sendJson(res, 404, { error: "session not found" });
+                sendError(res, 404, "not_found.session", "session not found");
                 return;
             }
             if (!runOwnerOk(req, res, audit.owner))
@@ -369,7 +369,7 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
             if (msgIndex !== undefined) {
                 const messages = audit.messages;
                 if (msgIndex >= messages.length) {
-                    sendJson(res, 404, { error: "message index out of range", total: messages.length });
+                    sendError(res, 404, "not_found.message_index", "message index out of range", { total: messages.length });
                     return;
                 }
                 sendJson(res, 200, { sessionId: audit.sessionId, floorEntryId: audit.floorEntryId, index: msgIndex, message: messages[msgIndex] });
@@ -401,32 +401,32 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
             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)" });
+                sendError(res, 501, "capability.session_store_required", "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" });
+                sendError(res, 401, "auth.unauthorized", "unauthorized");
                 return;
             }
             const sourceId = safeDecode(fm[1]);
             if (sourceId === null || !isUuidV7(sourceId)) {
-                sendJson(res, 400, { error: "invalid session id (must be a uuidv7)" });
+                sendError(res, 400, "request.id_invalid", "invalid session id (must be a uuidv7)");
                 return;
             }
             const owner = await ownerOf(sourceId);
             if (owner === undefined) {
-                sendJson(res, 404, { error: "session not found" });
+                sendError(res, 404, "not_found.session", "session not found");
                 return;
             }
             if (!scope.fleetWide && owner !== scope.gateOwner) {
-                sendJson(res, 404, { error: "session not found" });
+                sendError(res, 404, "not_found.session", "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" });
+                sendError(res, 404, "not_found.session", "session not found");
                 return;
             }
             sendJson(res, 200, { sessionId: newId });
@@ -439,17 +439,17 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
             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)" });
+                sendError(res, 501, "capability.session_store_required", "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" });
+                sendError(res, 401, "auth.unauthorized", "unauthorized");
                 return;
             }
             const sessionId = safeDecode(dm[1]);
             if (sessionId === null || !isUuidV7(sessionId)) {
-                sendJson(res, 400, { error: "invalid session id (must be a uuidv7)" });
+                sendError(res, 400, "request.id_invalid", "invalid session id (must be a uuidv7)");
                 return;
             }
             const owner = await ownerOf(sessionId);
@@ -463,12 +463,12 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
             }
             const activeTaskId = await deps.runStore?.getActiveTaskId(sessionId);
             if (activeTaskId) {
-                sendJson(res, 409, { error: "session has an active run; cancel it before deleting", activeTaskId });
+                sendError(res, 409, "conflict.session_active_run", "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 });
+                sendError(res, 409, "conflict.session_active_run", "session has an active run; cancel it before deleting", { activeTaskId: result.active });
                 return;
             }
             sendJson(res, 200, result);
@@ -481,31 +481,31 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
             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" });
+                sendError(res, 501, "capability.session_store_required", "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" });
+                sendError(res, 401, "auth.unauthorized", "unauthorized");
                 return;
             }
             const sessionId = safeDecode(pm[1]);
             if (sessionId === null || !isUuidV7(sessionId)) {
-                sendJson(res, 400, { error: "invalid session id (must be a uuidv7)" });
+                sendError(res, 400, "request.id_invalid", "invalid session id (must be a uuidv7)");
                 return;
             }
             const owner = await ownerOf(sessionId);
             if (owner === undefined) {
-                sendJson(res, 404, { error: "session not found" });
+                sendError(res, 404, "not_found.session", "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" });
+                sendError(res, 409, "conflict.session_ownerless", "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" });
+                sendError(res, 404, "not_found.session", "session not found");
                 return;
             }
             const target = owner;
@@ -518,15 +518,15 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
                 body = (await readJson(req));
             }
             catch {
-                sendJson(res, 400, { error: "invalid JSON body" });
+                sendError(res, 400, "request.invalid_json", "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" });
+                sendError(res, 400, "request.body_shape", "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" });
+                sendError(res, 400, "request.field_invalid", "expectedRev must be a non-negative integer");
                 return;
             }
             const raw = body.rules;
@@ -535,7 +535,7 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
                 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` });
+                    sendError(res, 400, "request.field_invalid", `${f} must be an array of strings`);
                     return;
                 }
                 rules[f] = raw[f];
@@ -560,22 +560,22 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
             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" });
+                sendError(res, 501, "capability.snapshot_store_required", "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" });
+                sendError(res, 401, "auth.unauthorized", "unauthorized");
                 return;
             }
             const wsSession = safeDecode(wm[1]);
             if (wsSession === null || !isUuidShape(wsSession)) {
-                sendJson(res, 400, { error: "invalid session id (must be a canonical uuid)" });
+                sendError(res, 400, "request.id_invalid", "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" });
+                sendError(res, 404, "not_found.session", "session not found");
                 return;
             }
             const q = new URL(req.url ?? "", "http://x").searchParams;
@@ -584,7 +584,7 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
             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" });
+                    sendError(res, 400, "request.query_invalid", "limit must be a decimal integer in 1..100");
                     return;
                 }
                 const lim = limRaw === null ? 20 : Number(limRaw);
@@ -613,24 +613,24 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
             }
             const keyRaw = safeDecode(wm[2]);
             if (keyRaw === null) {
-                sendJson(res, 400, { error: "malformed snapshot key" });
+                sendError(res, 400, "request.path_malformed", "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" });
+                sendError(res, 404, "not_found.snapshot", "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" });
+                    sendError(res, 400, "request.query_invalid", "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" });
+                    sendError(res, 400, "request.query_invalid", "offset must be a non-negative integer");
                     return;
                 }
                 const lim = limRaw === null ? 500 : Number(limRaw);
@@ -650,12 +650,12 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
             if (sub === "file") {
                 const pathParam = q.get("path");
                 if (!pathParam) {
-                    sendJson(res, 400, { error: "missing ?path=<relPath from the tree>" });
+                    sendError(res, 400, "request.query_invalid", "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)" });
+                    sendError(res, 404, "not_found.file", "no such file in this snapshot (paths are the tree's relPaths, verbatim)");
                     return;
                 }
                 const cap = deps.config.workspaceFileMaxBytes ?? 8 * 1024 * 1024;
@@ -668,7 +668,7 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
                 }
                 const bytes = await fs.getBlob(hash);
                 if (bytes === undefined) {
-                    sendJson(res, 404, { error: "file content no longer available (snapshot raced a reap)" });
+                    sendError(res, 404, "not_found.file", "file content no longer available (snapshot raced a reap)");
                     return;
                 }
                 if (bytes.byteLength > cap) {
@@ -690,14 +690,14 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
                 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) });
+                    sendError(res, 422, "request.content_unrepresentable", `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` });
+                        sendError(res, 502, "internal.snapshot_blobs_missing", `snapshot is missing ${missing} blob(s) (raced a reap or a partial import) — retry, or pick another snapshot`);
                         return;
                     }
                 }
@@ -737,7 +737,7 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
                 }
                 return;
             }
-            sendJson(res, 404, { error: "unknown workspace verb — use /tree, /file?path=, or /archive" });
+            sendError(res, 404, "request.route_unsupported", "unknown workspace verb — use /tree, /file?path=, or /archive");
             return;
         }
     }

package/dist/http/routes/side-query.d.ts

@@ -0,0 +1,4 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { RouteCtx } from "../route-ctx.js";
+export declare function handleSideQuery(req: IncomingMessage, res: ServerResponse, url: string, ctx: RouteCtx): Promise<boolean>;
+//# sourceMappingURL=side-query.d.ts.map