@sema-agent/server 7.115.0 → 7.116.0

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

@@ -2,7 +2,8 @@ import { once } from "node:events";
 import { randomBytes, createHash } from "node:crypto";
 import { sessionLogDigest, sessionLogDigestsComparable, StreamingImportValidator, validateFileHistoryExport } from "@sema-agent/core";
 import { StringDecoder } from "node:string_decoder";
-import { exportSessionManifest, fileHistoryImportFace, replayFileHistory, replayPolicyRecords, overwriteWipeIncapable, wipeSessionAttendants } from "../../session-sync.js";
+import { exportSessionManifest, fileHistoryImportFace, replayFileHistory, replayPolicyRecords, wipeSessionAttendants } from "../../session-sync.js";
+import * as facts from "../../capability-facts.js";
 import { classifySyncRelationshipByIds, SyncConflictError } from "../../session-sync-kernel.js";
 import { isUuidShape } from "../../security.js";
 import { sendJson, sendError, sendSessionError, sendSessionPolicyError, msg } from "../send.js";
@@ -36,16 +37,13 @@ export async function handleSessionSync(req, res, match, ctx) {
     const { pendingStagings, importLeases, touchImportLease, cleanupStaging } = ctx.local.sessionSync;
     {
         {
-            const ownerOf = deps.sessionStorage?.ownerOf?.bind(deps.sessionStorage);
-            if (!deps.backend || !ownerOf) {
-                sendError(res, 501, "capability.session_store_required", "session sync requires a durable session store");
-                return;
-            }
-            const historyStore = deps.fileHistoryStore;
-            if (historyStore === undefined) {
-                sendError(res, 501, "capability.snapshot_store_required", "session sync is not available on this deployment: no file-history store is wired, so there is no file history to export or import");
+            const sync = facts.sessionSync(deps);
+            if (!sync.available) {
+                sendSessionSyncUnavailable(res, sync.why);
                 return;
             }
+            const { backend, sessionStorage, historyStore } = sync;
+            const ownerOf = sessionStorage.ownerOf.bind(sessionStorage);
             const scope = sessionOwnerScopeForWrite(req);
             if (!scope.fleetWide && scope.gateOwner === null) {
                 sendUnauthorized(res, "identity");
@@ -81,7 +79,7 @@ export async function handleSessionSync(req, res, match, ctx) {
                     return;
                 let out;
                 try {
-                    out = await exportSessionManifest(sessionId, deps.backend, historyStore);
+                    out = await exportSessionManifest(sessionId, backend, historyStore);
                 }
                 catch (e) {
                     if (sendSessionPolicyError(res, e))
@@ -108,12 +106,7 @@ export async function handleSessionSync(req, res, match, ctx) {
                     }
                     afterSeq = n;
                 }
-                const stream = deps.sessionStorage?.exportEntriesStream?.bind(deps.sessionStorage);
-                if (!stream) {
-                    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 });
+                const it = await sessionStorage.exportEntriesStream(sessionId, afterSeq === undefined ? undefined : { afterSeq });
                 if (it === null) {
                     sendError(res, 404, "not_found.session", SESSION_NOT_FOUND_MESSAGE);
                     return;
@@ -138,6 +131,11 @@ export async function handleSessionSync(req, res, match, ctx) {
                 return;
             }
             if (match.decl.id === "session-sync-history-blob") {
+                const blobs = facts.sessionSyncFileHistory(deps);
+                if (!blobs.available) {
+                    sendSessionSyncUnavailable(res, blobs.why);
+                    return;
+                }
                 if (!pullGateOk())
                     return;
                 const hash = safeDecode(match.params.hash);
@@ -149,18 +147,14 @@ export async function handleSessionSync(req, res, match, ctx) {
                     sendError(res, 400, "request.id_invalid", "blob hash must be 64 lowercase-hex chars");
                     return;
                 }
-                const fs = deps.fileHistoryStore;
-                if (fs?.syncBlobFaces !== true) {
-                    sendError(res, 404, "not_found.blob", "blob not found");
-                    return;
-                }
+                const fs = blobs.historyStore;
                 const envelope = typeof fs.exportHistory === "function" ? await fs.exportHistory(sessionId) : null;
                 const referenced = envelope !== null && envelope !== undefined && envelope.tracked.some((t) => t.versions.some((v) => v.blobHash === hash));
                 if (!referenced) {
                     sendError(res, 404, "not_found.blob", "blob not found");
                     return;
                 }
-                const bytes = await fs.getBlob?.(hash);
+                const bytes = await fs.getBlob(hash);
                 if (!bytes) {
                     sendError(res, 404, "not_found.blob", "blob not found");
                     return;
@@ -172,6 +166,11 @@ export async function handleSessionSync(req, res, match, ctx) {
             if (match.decl.id === "session-sync-blob-put") {
                 if (rateLimited(req, res))
                     return;
+                const blobs = facts.sessionSyncFileHistory(deps);
+                if (!blobs.available) {
+                    sendSessionSyncUnavailable(res, blobs.why);
+                    return;
+                }
                 if (!pushGateOk())
                     return;
                 const hash = safeDecode(match.params.hash);
@@ -179,11 +178,7 @@ export async function handleSessionSync(req, res, match, ctx) {
                     sendError(res, 400, "request.id_invalid", "blob hash must be 64 lowercase-hex chars");
                     return;
                 }
-                const fs = deps.fileHistoryStore;
-                if (fs?.syncBlobFaces !== true || typeof fs.putBlob !== "function") {
-                    sendError(res, 501, "capability.snapshot_store_required", "blob upload requires a durable file-history store");
-                    return;
-                }
+                const fs = blobs.historyStore;
                 const body = await readRawBody(req, SYNC_BLOB_MAX_BYTES);
                 if (deps.snapshotBlobSqlCapBytes !== undefined && body.byteLength > deps.snapshotBlobSqlCapBytes) {
                     sendError(res, 413, "blob_too_large_for_sql", `blob of ${body.byteLength} bytes exceeds this deployment's SQL snapshot-blob cap (${deps.snapshotBlobSqlCapBytes} bytes — TiDB's txn-entry-size-limit is the low wall at 6MiB by default; the mysql-protocol packet limit sits above it) — configure MinIO object storage (MINIO_ENDPOINT/MINIO_ACCESS_KEY/MINIO_SECRET_KEY) for large snapshot blobs, or raise SNAPSHOT_BLOB_SQL_MAX_BYTES if your deployment lifted those limits`);
@@ -213,10 +208,6 @@ export async function handleSessionSync(req, res, match, ctx) {
                         }
                     }).catch(() => { });
                 }
-                if (!deps.sessionStorage?.beginImportStaging) {
-                    sendError(res, 501, "capability.session_store_required", "staged session import requires a durable session store");
-                    return;
-                }
                 let body;
                 try {
                     body = (await readJson(req));
@@ -237,7 +228,7 @@ export async function handleSessionSync(req, res, match, ctx) {
                 if (policyRead.problem !== undefined) {
                     const legacy = legacyToolNameProblemOf(policyRead.problem);
                     if (legacy !== undefined) {
-                        sendError(res, 400, "rules.legacy_tool_name", `policy: ${describeSessionRulesRecordProblem(policyRead.problem)}`, { field: legacy.field, name: legacy.name });
+                        sendError(res, 400, "rules.legacy_tool_name", `policy: ${describeSessionRulesRecordProblem(policyRead.problem)}`, { ...legacy });
                         return;
                     }
                     sendError(res, 400, "request.field_invalid", `policy: ${describeSessionRulesRecordProblem(policyRead.problem)}`);
@@ -261,7 +252,7 @@ export async function handleSessionSync(req, res, match, ctx) {
                 const entryIds = body.entryIds;
                 const policy = policyRead.records;
                 const anchors = body.anchors;
-                const dstIds = (await deps.sessionStorage.listEntryIds?.(sessionId)) ?? null;
+                const dstIds = (await sessionStorage.listEntryIds?.(sessionId)) ?? null;
                 const relA = classifySyncRelationshipByIds(entryIds, dstIds);
                 if ((relA.relation === "fork" || relA.relation === "stale") && resolution !== "overwrite-dst") {
                     sendError(res, 409, "conflict", "sync conflict", { relation: relA });
@@ -270,7 +261,7 @@ export async function handleSessionSync(req, res, match, ctx) {
                 let payloadVerified = false;
                 let digestSaysDiffer = false;
                 if (relA.relation === "identical" && srcLogDigest !== undefined) {
-                    const dstEntries = await deps.sessionStorage.exportEntries?.(sessionId).catch(() => null) ?? null;
+                    const dstEntries = await sessionStorage.exportEntries(sessionId).catch(() => null) ?? null;
                     const dstDigest = dstEntries === null ? undefined : sessionLogDigest(dstEntries);
                     if (sessionLogDigestsComparable(srcLogDigest, dstDigest)) {
                         if (srcLogDigest === dstDigest)
@@ -282,7 +273,8 @@ export async function handleSessionSync(req, res, match, ctx) {
                         digestSaysDiffer = true;
                 }
                 if (relA.relation === "identical" && !digestSaysDiffer) {
-                    if (fileHistory !== null && deps.fileHistoryStore?.syncBlobFaces === true && fileHistoryImportFace(deps.fileHistoryStore) && deps.fileHistoryStore.getBlob) {
+                    const blobFaces = facts.sessionSyncFileHistory(deps);
+                    if (fileHistory !== null && blobFaces.available && fileHistoryImportFace(blobFaces.historyStore)) {
                         if (resolution === "overwrite-dst") {
                             const activeNow = await deps.runStore?.getActiveTaskId(sessionId);
                             if (activeNow) {
@@ -290,8 +282,8 @@ export async function handleSessionSync(req, res, match, ctx) {
                                 return;
                             }
                         }
-                        const getBlobA = (h) => deps.fileHistoryStore.getBlob(h);
-                        const r = await replayFileHistory(deps.fileHistoryStore, sessionId, fileHistory, getBlobA, { allowReplace: resolution === "overwrite-dst" });
+                        const getBlobA = (h) => blobFaces.historyStore.getBlob(h);
+                        const r = await replayFileHistory(blobFaces.historyStore, sessionId, fileHistory, getBlobA, { allowReplace: resolution === "overwrite-dst" });
                         const failCode = r.ok ? undefined : r.error.code === "not_found" ? "missing_blob" : r.error.code;
                         if (!r.ok) {
                             sendError(res, 422, failCode, `file history import failed (${r.error.code})`);
@@ -343,7 +335,7 @@ export async function handleSessionSync(req, res, match, ctx) {
                         return;
                     }
                 }
-                const fss = deps.fileHistoryStore;
+                const fss = historyStore;
                 if (fileHistory !== null && fileHistoryImportFace(fss) !== undefined) {
                     const distinct = new Set();
                     for (const t of fileHistory.tracked)
@@ -351,7 +343,7 @@ export async function handleSessionSync(req, res, match, ctx) {
                             if (v.blobHash !== null)
                                 distinct.add(v.blobHash);
                     const all = [...distinct];
-                    if (typeof fss?.hasBlobs === "function") {
+                    if (typeof fss.hasBlobs === "function") {
                         const present = await fss.hasBlobs(all);
                         const missing = all.find((h) => !present.has(h));
                         if (missing !== undefined) {
@@ -359,7 +351,7 @@ export async function handleSessionSync(req, res, match, ctx) {
                             return;
                         }
                     }
-                    else if (typeof fss?.getBlob === "function") {
+                    else if (typeof fss.getBlob === "function") {
                         for (const hash of all) {
                             if (!(await fss.getBlob(hash))) {
                                 sendError(res, 422, "missing_blob", "missing blob; PUT all referenced blobs before import");
@@ -371,7 +363,7 @@ export async function handleSessionSync(req, res, match, ctx) {
                 const importingPrincipal = scope.fleetWide ? (owner ?? null) : scope.gateOwner;
                 const operatorOk = explicitOperatorOk(gatedPrincipal(req, deps.config), deps.config.operatorPrincipals);
                 const token = randomBytes(8).toString("hex");
-                const handle = deps.sessionStorage.beginImportStaging(sessionId, token);
+                const handle = sessionStorage.beginImportStaging(sessionId, token);
                 const stagingId = handle.stagingId;
                 importLeases.set(sessionId, { at: Date.now(), stagingId });
                 pendingStagings.set(stagingId, {
@@ -396,7 +388,7 @@ export async function handleSessionSync(req, res, match, ctx) {
                     sendError(res, 404, "not_found.staging", "staging not found");
                     return;
                 }
-                const getBlob = (h) => deps.fileHistoryStore?.getBlob ? deps.fileHistoryStore.getBlob(h) : Promise.resolve(undefined);
+                const getBlob = (h) => historyStore.getBlob ? historyStore.getBlob(h) : Promise.resolve(undefined);
                 const validator = new StreamingImportValidator();
                 let lineBuf = "";
                 let pendingBatch = [];
@@ -481,19 +473,13 @@ export async function handleSessionSync(req, res, match, ctx) {
                     sendError(res, 409, "session_active", "session started an active run while the import streamed; sync after it settles", { activeTaskId: activeAtCommit });
                     return;
                 }
-                if (pending.resolution !== undefined && overwriteWipeIncapable(deps.sessionPolicyStore)) {
-                    await pending.handle.abort().catch(() => undefined);
-                    cleanupStaging(stagingId);
-                    sendError(res, 501, "capability.policy_purge_required", "overwrite-dst cannot proceed: this deployment's session-policy store has no deleteBySession purge verb, so the destination's stale policy rows cannot be wiped and the import would land a MIXED state (the source's conversation plus the destination's leftover policy rows, which keep gating). Upgrade the policy store (every in-tree store carries deleteBySession since core 1.423), or re-run without resolution overwrite-dst");
-                    return;
-                }
                 try {
                     const committed = await pending.handle.commit(pending.owner, pending.resolution ? { resolution: pending.resolution } : undefined);
                     if (pending.resolution === "overwrite-dst" && (committed.relation === "fork" || committed.relation === "stale")) {
-                        await wipeSessionAttendants({ fileHistoryStore: deps.fileHistoryStore, sessionPolicyStore: deps.sessionPolicyStore, resumeAnchorStore: deps.resumeAnchorStore }, sessionId);
+                        await wipeSessionAttendants({ fileHistoryStore: historyStore, sessionPolicyStore: deps.sessionPolicyStore, resumeAnchorStore: deps.resumeAnchorStore }, sessionId);
                     }
-                    if (pending.fileHistory !== null && deps.fileHistoryStore && fileHistoryImportFace(deps.fileHistoryStore)) {
-                        const r = await replayFileHistory(deps.fileHistoryStore, sessionId, pending.fileHistory, getBlob, { allowReplace: pending.resolution === "overwrite-dst" });
+                    if (pending.fileHistory !== null && fileHistoryImportFace(historyStore)) {
+                        const r = await replayFileHistory(historyStore, sessionId, pending.fileHistory, getBlob, { allowReplace: pending.resolution === "overwrite-dst" });
                         const failCode = r.ok ? undefined : r.error.code === "not_found" ? "missing_blob" : r.error.code;
                         if (!r.ok) {
                             sendError(res, 422, failCode, `file history import failed (${r.error.code})`);
@@ -508,7 +494,7 @@ export async function handleSessionSync(req, res, match, ctx) {
                     if (anchorStore)
                         for (const a of pending.anchors)
                             await anchorStore.put(sessionId, a.eventId, a.entryId, pending.owner);
-                    deps.sessionStorage.evict?.(sessionId);
+                    sessionStorage.evict?.(sessionId);
                     cleanupStaging(stagingId);
                     sendJson(res, 200, { relation: committed.relation });
                 }
@@ -541,7 +527,7 @@ export async function handleSessionSync(req, res, match, ctx) {
                     sendError(res, 400, "request.field_invalid", "entryIds must be an array of strings");
                     return;
                 }
-                const dst = await deps.sessionStorage?.exportEntries?.(sessionId);
+                const dst = await sessionStorage.exportEntries(sessionId);
                 const relation = classifySyncRelationshipByIds(body.entryIds, dst ? dst.map((e) => e.id) : null);
                 sendJson(res, 200, relation);
                 return;
@@ -550,6 +536,31 @@ export async function handleSessionSync(req, res, match, ctx) {
         }
     }
 }
+function sendSessionSyncUnavailable(res, why) {
+    switch (why) {
+        case "store_backend_absent":
+        case "session_owner_face_absent":
+            sendError(res, 501, "capability.session_store_required", "session sync requires a durable session store");
+            return;
+        case "session_export_absent":
+            sendError(res, 501, "capability.session_store_required", "session entry streaming requires a durable session store");
+            return;
+        case "session_import_staging_absent":
+            sendError(res, 501, "capability.session_store_required", "staged session import requires a durable session store");
+            return;
+        case "file_history_store_absent":
+            sendError(res, 501, "capability.snapshot_store_required", "session sync is not available on this deployment: no file-history store is wired, so there is no file history to export or import");
+            return;
+        case "policy_purge_absent":
+            sendError(res, 501, "capability.policy_purge_required", "session sync is not available on this deployment: the session-policy store has no deleteBySession purge verb, so an overwrite-dst import could not wipe the destination's stale policy rows. Every in-tree policy store carries it since core 1.423 — upgrade the policy store");
+            return;
+        case "sync_blob_faces_absent":
+            sendError(res, 501, "capability.snapshot_store_required", "file-history blob transfer is not available on this deployment: its file-history store has no blob faces (SQL backends only; capabilities.sessionSyncFileHistory is false here). Sync the conversation without fileHistory");
+            return;
+        default:
+            return assertNever(why);
+    }
+}
 export const SESSION_SYNC_ROUTES = [
     { id: "session-sync-manifest", pattern: /^\/v1\/sessions\/(?<sessionId>[^/]+)\/sync\/manifest$/, label: "/v1/sessions/:id/sync/$verb", methods: ["GET"] },
     { id: "session-sync-entries", pattern: /^\/v1\/sessions\/(?<sessionId>[^/]+)\/sync\/entries$/, label: "/v1/sessions/:id/sync/$verb", methods: ["GET"] },

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

@@ -4,6 +4,7 @@ import { sendUnauthorized } from "../principal-gate.js";
 import { filterFingerprint } from "../cursor-fingerprint.js";
 import { sessionTempoOfRunStatus } from "../../plugins/store-contracts.js";
 import { assertNever } from "../route-ctx.js";
+import * as facts from "../../capability-facts.js";
 export async function handleSessionsList(req, res, match, ctx) {
     const { deps } = ctx;
     const { isFleetWide, sessionOwnerScope } = ctx.helpers;
@@ -14,11 +15,12 @@ export async function handleSessionsList(req, res, match, ctx) {
                 sendUnauthorized(res, "identity");
                 return;
             }
-            const lister = deps.sessionStorage?.listSessions?.bind(deps.sessionStorage) ?? deps.runStore?.listSessions?.bind(deps.runStore);
-            if (!lister) {
+            const listing = facts.sessionList(deps);
+            if (!listing.available) {
                 sendError(res, 501, "capability.session_store_required", "session list requires a durable session store (DB_BACKEND=mysql|pg|local)");
                 return;
             }
+            const lister = listing.lister;
             const includeUnowned = !fleetWide && legacyUnownedAmnestyOpen(deps.config.requirePrincipal, gateOwner);
             await handleSessionList(res, lister, new URLSearchParams(match.search), gateOwner, includeUnowned);
             return;
@@ -29,7 +31,8 @@ export async function handleSessionsList(req, res, match, ctx) {
                 sendUnauthorized(res, "identity");
                 return;
             }
-            if (!deps.sendFileLedger) {
+            const ledger = facts.sendFileLedger(deps);
+            if (!ledger.available) {
                 sendError(res, 501, "capability.store_required", "sendfile ledger requires a store backend (DB_BACKEND=mysql|pg|local) and the SendUserFile issuer configured");
                 return;
             }
@@ -64,7 +67,7 @@ export async function handleSessionsList(req, res, match, ctx) {
                     scope = s;
                 }
             }
-            const rows = await deps.sendFileLedger.listByScope(scope, limit + 1, before);
+            const rows = await ledger.ledger.listByScope(scope, limit + 1, before);
             const hasMore = rows.length > limit;
             const page = hasMore ? rows.slice(0, limit) : rows;
             sendJson(res, 200, {
@@ -117,7 +120,7 @@ async function handleSessionList(res, lister, query, forceOwner, includeUnowned
         sendError(res, 400, "request.cursor_filter_mismatch", "cursor was issued under a different filter (owner/q) — restart from the first page without a cursor");
         return;
     }
-    const rows = await lister({ ...(owner ? { owner } : {}), ...(includeUnowned ? { includeUnowned: true } : {}), ...(cursor ? { cursor } : {}), limit: limit + 1, ...(q ? { q } : {}) });
+    const rows = await lister({ ...(owner !== undefined ? { owner } : {}), ...(includeUnowned ? { includeUnowned: true } : {}), ...(cursor ? { cursor } : {}), limit: limit + 1, ...(q ? { q } : {}) });
     const hasMore = rows.length > limit;
     const page = hasMore ? rows.slice(0, limit) : rows;
     const last = page[page.length - 1];

package/dist/http/routes/sessions.js

@@ -10,6 +10,7 @@ import { readWritableSessionPermissionRules, describeSessionPermissionRulesProbl
 import { sendJson, sendError, sendSessionError, sendSessionPolicyError, sseHeaders } from "../send.js";
 import { gatedPrincipal, explicitOperatorOk, runOwnerReadable, sendPrincipalRefusal, sendUnauthorized } from "../principal-gate.js";
 import { assertNever, SESSION_NOT_FOUND_MESSAGE } from "../route-ctx.js";
+import * as facts from "../../capability-facts.js";
 import { rosterAgentId } from "./agents-roster.js";
 const MCP_STATUS_TTL_MS = 5_000;
 const MCP_MATERIALIZE_TIMEOUT_MS = 10_000;
@@ -291,12 +292,13 @@ export async function handleSessions(req, res, match, ctx) {
     }
     {
         if (match.decl.id === "session-events") {
-            const ownerOf = deps.sessionStorage?.ownerOf?.bind(deps.sessionStorage);
-            const watch = deps.sessionWatch;
-            if (!deps.sessionStorage?.getLeafId || !ownerOf || !watch) {
+            const evFact = facts.sessionEventStream(deps);
+            if (!evFact.available) {
                 sendError(res, 501, "capability.session_store_required", "session events require a durable session store (DB_BACKEND=mysql|pg|local)");
                 return;
             }
+            const ownerOf = evFact.sessionStorage.ownerOf.bind(evFact.sessionStorage);
+            const watch = evFact.watch;
             const evSession = safeDecode(match.params.sessionId);
             if (evSession === null) {
                 sendError(res, 400, "request.path_malformed", "session id segment is not valid percent-encoding");
@@ -494,11 +496,12 @@ export async function handleSessions(req, res, match, ctx) {
                 sendPrincipalRefusal(res, req, deps.config);
                 return;
             }
-            if (!deps.sessionAudit) {
+            const auditFact = facts.sessionAuditView(deps);
+            if (!auditFact.available) {
                 sendError(res, 501, "capability.memory_engine_required", "memory provenance and erasure are not available on this deployment — they require a wired memory engine (MEMORY_ENGINE=on) whose backend owns the engine control plane (controlPlaneRoot); the file memory backend does, the pg/tidb memory backends do not (their control plane would land on a replica's local disk)");
                 return;
             }
-            if ((await readOwnedSessionView(deps.sessionAudit, sessionId)) === undefined)
+            if ((await readOwnedSessionView(auditFact.sessionAudit, sessionId)) === undefined)
                 return;
             const faces = deps.memoryCompliance;
             if (faces === undefined) {
@@ -546,11 +549,12 @@ export async function handleSessions(req, res, match, ctx) {
                 sendPrincipalRefusal(res, req, deps.config);
                 return;
             }
-            if (!deps.sessionAudit) {
+            const auditFact = facts.sessionAuditView(deps);
+            if (!auditFact.available) {
                 sendError(res, 501, "capability.memory_engine_required", "session memory status is not available on this deployment — it requires a wired memory engine (MEMORY_ENGINE=on) whose backend owns the engine control plane (controlPlaneRoot); the file memory backend does, the pg/tidb memory backends do not (their control plane would land on a replica's local disk)");
                 return;
             }
-            if ((await readOwnedSessionView(deps.sessionAudit, sessionId)) === undefined)
+            if ((await readOwnedSessionView(auditFact.sessionAudit, sessionId)) === undefined)
                 return;
             const face = deps.sessionMemoryStatus;
             if (face === undefined) {
@@ -590,11 +594,12 @@ export async function handleSessions(req, res, match, ctx) {
     }
     if (match.decl.id === "session-detail") {
         {
-            if (!deps.sessionAudit) {
-                sendError(res, 404, "not_found.route", "not found");
+            const auditFact = facts.sessionAuditView(deps);
+            if (!auditFact.available) {
+                sendError(res, 501, "capability.session_store_required", "the session audit view requires a durable session store (DB_BACKEND=mysql|pg|local)");
                 return;
             }
-            const audit = await readOwnedSessionView(deps.sessionAudit, match.params.sessionId);
+            const audit = await readOwnedSessionView(auditFact.sessionAudit, match.params.sessionId);
             if (audit === undefined)
                 return;
             const q = new URLSearchParams(match.search);
@@ -647,12 +652,13 @@ export async function handleSessions(req, res, match, ctx) {
     }
     {
         if (match.decl.id === "session-fork") {
-            const fork = deps.sessionStorage?.fork?.bind(deps.sessionStorage);
-            const ownerOf = deps.sessionStorage?.ownerOf?.bind(deps.sessionStorage);
-            if (!fork || !ownerOf) {
+            const forkFact = facts.sessionFork(deps);
+            if (!forkFact.available) {
                 sendError(res, 501, "capability.session_store_required", "session fork requires a durable session store (DB_BACKEND=mysql|pg|local)");
                 return;
             }
+            const fork = forkFact.sessionStorage.fork.bind(forkFact.sessionStorage);
+            const ownerOf = forkFact.sessionStorage.ownerOf.bind(forkFact.sessionStorage);
             const scope = sessionOwnerScopeForWrite(req);
             if (!scope.fleetWide && scope.gateOwner === null) {
                 sendUnauthorized(res, "identity");
@@ -684,12 +690,13 @@ export async function handleSessions(req, res, match, ctx) {
     }
     {
         if (match.decl.id === "session-delete") {
-            const purge = deps.purgeSession;
-            const ownerOf = deps.sessionStorage?.ownerOf?.bind(deps.sessionStorage);
-            if (!purge || !ownerOf) {
+            const deleteFact = facts.sessionDelete(deps);
+            if (!deleteFact.available) {
                 sendError(res, 501, "capability.session_store_required", "session delete requires a durable session store (DB_BACKEND=mysql|pg|local)");
                 return;
             }
+            const purge = deleteFact.purge;
+            const ownerOf = deleteFact.sessionStorage.ownerOf.bind(deleteFact.sessionStorage);
             const scope = sessionOwnerScopeForWrite(req);
             if (!scope.fleetWide && scope.gateOwner === null) {
                 sendUnauthorized(res, "identity");
@@ -729,12 +736,13 @@ export async function handleSessions(req, res, match, ctx) {
     }
     {
         if (match.decl.id === "session-policy-get" || match.decl.id === "session-policy-put") {
-            const store = deps.sessionPolicyStore;
-            const ownerOf = deps.sessionStorage?.ownerOf?.bind(deps.sessionStorage);
-            if (!store || !ownerOf) {
+            const policyFact = facts.sessionPolicy(deps);
+            if (!policyFact.available) {
                 sendError(res, 501, "capability.session_store_required", "session policy requires a session-store backend");
                 return;
             }
+            const store = policyFact.policyStore;
+            const ownerOf = policyFact.sessionStorage.ownerOf.bind(policyFact.sessionStorage);
             const principal = gatedPrincipal(req, deps.config);
             if (deps.config.requirePrincipal && principal === undefined) {
                 sendUnauthorized(res, "identity");
@@ -789,7 +797,10 @@ export async function handleSessions(req, res, match, ctx) {
                         sendError(res, 400, "request.field_invalid", describeSessionPermissionRulesProblem(read.problem));
                         return;
                     case "legacy-tool-name":
-                        sendError(res, 400, "rules.legacy_tool_name", describeSessionPermissionRulesProblem(read.problem), { field: read.problem.field, name: read.problem.name });
+                        sendError(res, 400, "rules.legacy_tool_name", describeSessionPermissionRulesProblem(read.problem), { ...read.problem.refusal });
+                        return;
+                    case "unreachable-tool-name":
+                        sendError(res, 400, "request.field_invalid", describeSessionPermissionRulesProblem(read.problem));
                         return;
                     default: {
                         const unhandled = read.problem;
@@ -814,10 +825,14 @@ export async function handleSessions(req, res, match, ctx) {
             return;
         }
     }
-    {
-        if (match.decl.id === "session-workspace") {
-            sendError(res, 501, "capability.workspace_retired", "workspace browse is retired: the whole-tree snapshot epoch it projected was replaced by per-edited-file rewind history (which holds only files the agent edited, not the workspace). There is no whole-tree manifest to browse anymore.");
-            return;
+    if (match.decl.id === "session-workspace") {
+        const workspace = facts.workspaceBrowse();
+        switch (workspace.why) {
+            case "workspace_retired":
+                sendError(res, 501, "capability.workspace_retired", "workspace browse is retired: the whole-tree snapshot epoch it projected was replaced by per-edited-file rewind history (which holds only files the agent edited, not the workspace). There is no whole-tree manifest to browse anymore.");
+                return;
+            default:
+                return assertNever(workspace.why);
         }
     }
     return assertNever(match.decl.id);

package/dist/http/routes/shared-memory.js

@@ -2,6 +2,7 @@ import { SHARED_MEMORY_READ_CAP_BYTES, SharedMemoryStoreError } from "@sema-agen
 import { sendJson, sendError } from "../send.js";
 import { gatedPrincipal, sendUnauthorized } from "../principal-gate.js";
 import { assertNever } from "../route-ctx.js";
+import * as facts from "../../capability-facts.js";
 const RETRY_AFTER_SEC = 10;
 const HTTP_LIST_LIMIT = 100;
 const FORBIDDEN_PATH_CHARS = /[\p{Cc}\p{Cf}\p{Co}\p{Cn}\p{Default_Ignorable_Code_Point}\u2028\u2029\\]/u;
@@ -32,11 +33,12 @@ async function bindSnapshot(req, res, ctx) {
         sendUnauthorized(res, "identity");
         return undefined;
     }
-    const provider = deps.sharedMemoryStore;
-    if (!provider) {
-        refuseStore(res);
+    const fact = facts.sharedMemoryRead(deps);
+    if (!fact.available) {
+        sendError(res, 501, "capability.shared_memory_required", "org shared memory is not available on this deployment (it needs both a shared memory store provider and an org membership directory)");
         return undefined;
     }
+    const provider = fact.provider;
     const snapshot = await provider.snapshot({ sessionId: `http:${principal ?? "anonymous"}`, taskId: "http-read", ...(principal ? { principal } : {}) }, {});
     if (snapshot.state === "unavailable") {
         refuseUnavailable(res, snapshot.message);

package/dist/http/routes/tasks.js

@@ -27,6 +27,7 @@ import { headerStr, gatedPrincipal, explicitOperatorOk } from "../principal-gate
 import { failOpenTagForDroppedFrame, recordFailOpen } from "../../observability/fail-open.js";
 import { buildSyncSubmitBody } from "../sync-submit-body.js";
 import { assertNever } from "../route-ctx.js";
+import * as facts from "../../capability-facts.js";
 import { buildCheckpointCtx } from "../checkpoint-ctx.js";
 import { withModelReachScope } from "../../model-reach-scope.js";
 import { createInstructionSelectionLeg } from "../../instruction-selection.js";
@@ -123,7 +124,7 @@ export async function handleTasks(req, res, match, ctx) {
                 sendError(res, 400, "request.field_conflict", "verify / cascade are not supported on /v1/tasks/stream (both are multi-attempt, not a single stream) — use /v1/tasks or /v1/runs");
                 return;
             }
-            const earlyDurableTid = deps.runStore && prepared.spec.sessionId ? uuidv7() : undefined;
+            const earlyDurableTid = facts.durableRuns(deps).available && prepared.spec.sessionId ? uuidv7() : undefined;
             const streamLegStartedAt = Date.now();
             const detachOnDisconnect = headerStr(req.headers["x-detach-on-disconnect"]) === "true";
             if (detachOnDisconnect && earlyDurableTid === undefined) {

package/dist/http/routes/trace-usage.js

@@ -8,6 +8,7 @@ import { sendJson, sendError, sseHeaders, SSE_MAX_STREAM_MS, SSE_HEARTBEAT_IDLE_
 import { filterFingerprint } from "../cursor-fingerprint.js";
 import { gatedPrincipal, sendUnauthorized } from "../principal-gate.js";
 import { assertNever } from "../route-ctx.js";
+import * as facts from "../../capability-facts.js";
 const TOOL_RESULT_LIMIT_CAP = 262_144;
 const TOOL_RESULT_OFFSET_CAP = 2_147_483_646;
 export async function handleTraceUsage(req, res, match, ctx) {
@@ -18,13 +19,15 @@ export async function handleTraceUsage(req, res, match, ctx) {
             sendUnauthorized(res, "operator");
             return;
         }
-        if (!deps.runStore) {
+        const runs = facts.durableRuns(deps);
+        if (!runs.available) {
             sendError(res, 501, "capability.run_store_required", "trace API requires a durable run store (DB_BACKEND=mysql|pg|local)");
             return;
         }
+        const runStore = runs.runStore;
         const q = new URLSearchParams(match.search);
         const sinceSec = Math.min(30 * 86_400, Math.max(60, Number(q.get("sinceSec") ?? 86_400) || 86_400));
-        sendJson(res, 200, { sinceSec, rows: await deps.runStore.sourceSummary(Date.now() - sinceSec * 1000) });
+        sendJson(res, 200, { sinceSec, rows: await runStore.sourceSummary(Date.now() - sinceSec * 1000) });
         return;
     }
     if (match.decl.id === "task-trace-list" ||
@@ -38,15 +41,17 @@ export async function handleTraceUsage(req, res, match, ctx) {
             sendUnauthorized(res, "identity");
             return;
         }
-        if (!deps.runStore) {
+        const runs = facts.durableRuns(deps);
+        if (!runs.available) {
             sendError(res, 501, "capability.run_store_required", "trace API requires a durable run store (DB_BACKEND=mysql|pg|local)");
             return;
         }
+        const runStore = runs.runStore;
         const query = new URLSearchParams(match.search);
         const taskId = match.params.taskId;
         let ownedRun;
         if (taskId && gateOwner !== null) {
-            const run = await deps.runStore.getRun(taskId);
+            const run = await runStore.getRun(taskId);
             if (!run || (run.owner !== null && run.owner !== gateOwner)) {
                 sendError(res, 404, "not_found.run", "task not found");
                 return;
@@ -55,19 +60,19 @@ export async function handleTraceUsage(req, res, match, ctx) {
         }
         switch (match.decl.id) {
             case "task-trace-list":
-                await handleTaskList(res, deps.runStore, query, gateOwner);
+                await handleTaskList(res, runStore, query, gateOwner);
                 return;
             case "task-trace-turns":
-                await handleTaskTurns(res, deps.runStore, taskId, query);
+                await handleTaskTurns(res, runStore, taskId, query);
                 return;
             case "task-trace-stream":
-                await streamTaskTrace(req, res, deps.runStore, taskId, deps.config.runStaleSec * 1000, match.search);
+                await streamTaskTrace(req, res, runStore, taskId, deps.config.runStaleSec * 1000, match.search);
                 return;
             case "task-trace-artifacts":
-                await handleTaskArtifacts(res, deps.runStore, taskId);
+                await handleTaskArtifacts(res, runStore, taskId);
                 return;
             case "task-tool-result":
-                await handleToolResult(res, deps.toolResultStore, deps.runStore, taskId, ownedRun, safeDecode(match.params.ref), query);
+                await handleToolResult(res, deps.toolResultStore, runStore, taskId, ownedRun, safeDecode(match.params.ref), query);
                 return;
             default:
                 return assertNever(match.decl.id);
@@ -78,10 +83,12 @@ export async function handleTraceUsage(req, res, match, ctx) {
     {
         const sub = match.params.sub;
         {
-            if (!deps.runStore) {
+            const runs = facts.durableRuns(deps);
+            if (!runs.available) {
                 sendError(res, 501, "capability.run_store_required", "usage analytics requires a run store");
                 return;
             }
+            const runStore = runs.runStore;
             const fleetWide = isFleetWide(req);
             const jwtOwner = fleetWide ? undefined : gatedPrincipal(req, deps.config);
             if (!fleetWide && !jwtOwner) {
@@ -104,7 +111,7 @@ export async function handleTraceUsage(req, res, match, ctx) {
             }
             const owner = jwtOwner ?? (q.get("principal") ?? undefined);
             try {
-                const scan = await deps.runStore.usageScan(from, to, owner !== undefined ? { owner } : undefined);
+                const scan = await runStore.usageScan(from, to, owner !== undefined ? { owner } : undefined);
                 const base = { from: new Date(from).toISOString(), to: new Date(to).toISOString(), ...(scan.truncated ? { truncated: true } : {}) };
                 if (sub === "summary") {
                     sendJson(res, 200, { ...base, ...usageSummary(scan.rows) });