session-steward 0.1.1 → 0.2.0

package/lib/server.mjs

@@ -11,10 +11,12 @@ import { classifyInstalledVersion } from "./version-support.mjs";
 
 const {
   assertDeepCleanupSupported,
+  deleteSessionDeletionBackup,
   formatSessionForJson,
   executeSessionDeletion,
   fingerprintSessionDeletion,
   diagnoseStorageCompatibility,
+  getSessionOverview,
   getSessionRecord,
   listSessions,
   loadDeletionStore,
@@ -32,6 +34,9 @@ const MAX_SAVED_PLANS = 20;
 const MAX_SAVED_OPERATIONS = 50;
 const PLAN_RECORD_SAMPLE_LIMIT = 20;
 const PLAN_REVIEW_REQUIRED = "DELETION_PLAN_REVIEW_REQUIRED";
+const SESSION_OVERVIEW_TTL_MS = 45 * 1000;
+const ALLOWED_INACTIVE_DAYS = new Set([30, 60, 90]);
+const ALLOWED_ARCHIVE_STATUSES = new Set(["all", "active", "archived"]);
 const publicDirectory = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "dist");
 const staticAssets = new Map([
   ["/", { fileName: "index.html", contentType: "text/html; charset=utf-8" }],
@@ -164,6 +169,30 @@ function getPositiveInteger(value, fallback, maximum = Number.MAX_SAFE_INTEGER)
   return Math.min(parsed, maximum);
 }
 
+function getInactiveBeforeMs(value) {
+  if (value === null || value === "") {
+    return null;
+  }
+
+  const days = Number(value);
+
+  if (!ALLOWED_INACTIVE_DAYS.has(days)) {
+    throw new Error("Last activity must be 30, 60, or 90 days.");
+  }
+
+  return Date.now() - days * 24 * 60 * 60 * 1000;
+}
+
+function getArchiveStatus(value) {
+  const status = value || "all";
+
+  if (!ALLOWED_ARCHIVE_STATUSES.has(status)) {
+    throw new Error("Session status must be all, active, or archived.");
+  }
+
+  return status;
+}
+
 function getLocalRequestOrigin({ hostHeader, server }) {
   if (typeof hostHeader !== "string") {
     return null;
@@ -196,7 +225,15 @@ function requireMutationAuthorization({ request, requestUrl, token }) {
   }
 }
 
-function summarizePlan(plan, preflight) {
+function summarizePlan(plan, preflight, scope) {
+  const relatedRecordCount = plan.historyMatchCount
+    + plan.sessionIndexMatchCount
+    + plan.logRowCount
+    + plan.spawnEdgeCount
+    + (scope === "deep"
+      ? plan.goalRowCount + plan.memoryRowCount + preflight.desktopStateMatchCount
+      : 0);
+
   return {
     availableDiskBytes: preflight.availableDiskBytes,
     childCount: plan.childCount,
@@ -208,6 +245,7 @@ function summarizePlan(plan, preflight) {
     logRowCount: plan.logRowCount,
     memoryRowCount: plan.memoryRowCount,
     missingTranscriptCount: plan.missingTranscriptPaths.length,
+    newestLinkedActivityAtMs: plan.newestLinkedActivityAtMs,
     recordSamples: plan.records.slice(0, PLAN_RECORD_SAMPLE_LIMIT).map((record) => ({
       displayName: record.displayName,
       id: record.id,
@@ -215,7 +253,9 @@ function summarizePlan(plan, preflight) {
     sessionIndexMatchCount: plan.sessionIndexMatchCount,
     sessionCount: plan.ids.length,
     spawnEdgeCount: plan.spawnEdgeCount,
-    transcriptCount: plan.transcriptPaths.length,
+    relatedRecordCount,
+    transcriptBytes: plan.transcriptBytes,
+    transcriptCount: plan.transcriptFileCount,
   };
 }
 
@@ -235,9 +275,9 @@ function summarizeVerification(verification) {
 
 function summarizeDeletionResult(result) {
   return {
-    backupDirectory: result.backupDirectory,
     deletedSessionCount: result.deletedIds.length,
     deletedTranscriptCount: result.deletedTranscriptPaths.length,
+    recoveryBackupDeleted: false,
     skippedTranscriptCount: result.skippedTranscriptPaths.length,
   };
 }
@@ -245,7 +285,9 @@ function summarizeDeletionResult(result) {
 function publicOperation(operation) {
   return {
     backupDirectory: operation.backupDirectory ?? null,
+    backupDeleteError: operation.backupDeleteError ?? null,
     canCancel: Boolean(operation.canCancel),
+    canDeleteBackup: Boolean(operation.canDeleteBackup),
     canRestore: Boolean(operation.canRestore),
     cancelRequested: Boolean(operation.cancelRequested),
     error: operation.error ?? null,
@@ -291,6 +333,57 @@ export async function startLocalServer({ codexHome, configDirectory, port = 0 })
   const deletionPlans = new Map();
   const operations = new Map();
   const activeTasks = new Set();
+  let overviewCache = null;
+
+  function invalidateSessionOverview() {
+    overviewCache = null;
+  }
+
+  async function readSessionOverview({ refresh = false } = {}) {
+    const activeCodexHome = settings.getHome("codex");
+
+    if (
+      !refresh
+      && overviewCache?.codexHome === activeCodexHome
+      && overviewCache.expiresAtMs > Date.now()
+    ) {
+      return overviewCache.overview;
+    }
+
+    const overview = await getSessionOverview({ codexHome: activeCodexHome });
+    overviewCache = {
+      codexHome: activeCodexHome,
+      expiresAtMs: Date.now() + SESSION_OVERVIEW_TTL_MS,
+      overview,
+    };
+    return overview;
+  }
+
+  async function removeOperationBackups(operation, additionalDirectories = []) {
+    const candidates = [...new Set([
+      ...(operation.backupDirectories ?? []),
+      operation.backupDirectory,
+      ...additionalDirectories,
+    ].filter(Boolean))]
+      .sort((left, right) => right.length - left.length);
+    const remaining = [];
+
+    for (const backupDirectory of candidates) {
+      try {
+        await deleteSessionDeletionBackup({
+          backupDirectory,
+          codexHome: operation.codexHome,
+        });
+      } catch {
+        remaining.push(backupDirectory);
+      }
+    }
+
+    operation.backupDirectories = remaining;
+    operation.backupDirectory = remaining[0] ?? null;
+    operation.canDeleteBackup = remaining.length > 0;
+    return remaining.length === 0;
+  }
 
   function getDeletionPlan(planId) {
     const savedPlan = typeof planId === "string" ? deletionPlans.get(planId) : null;
@@ -380,6 +473,7 @@ export async function startLocalServer({ codexHome, configDirectory, port = 0 })
         store: currentStore,
       });
       operation.backupDirectory = result.backupDirectory;
+      operation.backupDirectories = [result.backupDirectory];
       operation.result = summarizeDeletionResult(result);
       operation.canCancel = false;
       operation.message = "Checking that cleanup completed";
@@ -395,8 +489,14 @@ export async function startLocalServer({ codexHome, configDirectory, port = 0 })
 
       if (verification.complete) {
         operation.message = "Cleanup completed";
+        if (await removeOperationBackups(operation)) {
+          operation.result.recoveryBackupDeleted = true;
+        } else {
+          operation.backupDeleteError = "Cleanup completed, but its recovery backup could not be removed.";
+        }
         operation.status = "completed";
       } else {
+        operation.canDeleteBackup = true;
         operation.canRestore = true;
         operation.error = "Cleanup finished, but some selected items remain. You can restore the recovery backup.";
         operation.message = "Cleanup needs attention";
@@ -404,6 +504,7 @@ export async function startLocalServer({ codexHome, configDirectory, port = 0 })
       }
     } catch (error) {
       operation.backupDirectory = error?.backupDirectory ?? null;
+      operation.backupDirectories = operation.backupDirectory ? [operation.backupDirectory] : [];
       operation.canCancel = false;
       operation.errorCode = error?.code ?? null;
       operation.progress = error?.cancelled ? operation.progress : 100;
@@ -411,14 +512,19 @@ export async function startLocalServer({ codexHome, configDirectory, port = 0 })
       if (error?.cancelled) {
         operation.error = null;
         operation.message = "Cleanup cancelled before session data changed";
+        if (!(await removeOperationBackups(operation))) {
+          operation.backupDeleteError = "Cleanup was cancelled, but its temporary backup could not be removed.";
+        }
         operation.status = "cancelled";
       } else {
+        operation.canDeleteBackup = Boolean(operation.backupDirectory);
         operation.canRestore = Boolean(operation.backupDirectory);
         operation.error = error instanceof Error ? error.message : "Cleanup could not be completed.";
         operation.message = "Cleanup could not be completed";
         operation.status = "failed";
       }
     } finally {
+      invalidateSessionOverview();
       savedPlan.consumed = true;
       deletionPlans.delete(savedPlan.id);
       operation.finishedAtMs = Date.now();
@@ -431,7 +537,10 @@ export async function startLocalServer({ codexHome, configDirectory, port = 0 })
     const id = randomBytes(18).toString("base64url");
     const operation = {
       backupDirectory: null,
+      backupDirectories: [],
+      backupDeleteError: null,
       canCancel: true,
+      canDeleteBackup: false,
       canRestore: false,
       cancelRequested: false,
       codexHome: savedPlan.codexHome,
@@ -457,7 +566,9 @@ export async function startLocalServer({ codexHome, configDirectory, port = 0 })
 
   function startRestoreOperation(operation) {
     operation.canCancel = false;
+    operation.canDeleteBackup = false;
     operation.canRestore = false;
+    operation.backupDeleteError = null;
     operation.error = null;
     operation.errorCode = null;
     operation.message = "Restore queued";
@@ -467,20 +578,38 @@ export async function startLocalServer({ codexHome, configDirectory, port = 0 })
     activeOperationId = operation.id;
     const task = (async () => {
       try {
-        operation.restoreResult = await restoreSessionDeletionBackup({
+        const restoreResult = await restoreSessionDeletionBackup({
           backupDirectory: operation.backupDirectory,
           codexHome: operation.codexHome,
           onProgress: (update) => Object.assign(operation, update),
         });
+        operation.restoreResult = restoreResult;
         operation.message = "Recovery backup restored";
         operation.progress = 100;
+        if (await removeOperationBackups(operation, [restoreResult.safetyBackupDirectory])) {
+          operation.restoreResult = {
+            ...restoreResult,
+            recoveryBackupsDeleted: true,
+            safetyBackupDirectory: null,
+          };
+        } else {
+          operation.backupDeleteError = "The sessions were restored, but temporary recovery files could not be removed.";
+        }
         operation.status = "restored";
       } catch (error) {
+        if (error?.safetyBackupDirectory) {
+          operation.backupDirectories = [...new Set([
+            ...(operation.backupDirectories ?? []),
+            error.safetyBackupDirectory,
+          ])];
+        }
+        operation.canDeleteBackup = true;
         operation.canRestore = true;
         operation.error = error instanceof Error ? error.message : "The recovery backup could not be restored.";
         operation.message = "Restore could not be completed";
         operation.status = "restore-failed";
       } finally {
+        invalidateSessionOverview();
         operation.finishedAtMs = Date.now();
         if (activeOperationId === operation.id) activeOperationId = null;
       }
@@ -552,6 +681,7 @@ export async function startLocalServer({ codexHome, configDirectory, port = 0 })
             ? await settings.resetProviderHome(providerId)
             : await settings.setProviderHome(providerId, (await readJsonBody(request)).home);
           deletionPlans.clear();
+          invalidateSessionOverview();
           sendJson(response, 200, { provider });
         } finally {
           mutationInProgress = false;
@@ -576,15 +706,28 @@ export async function startLocalServer({ codexHome, configDirectory, port = 0 })
         return;
       }
 
+      if (request.method === "GET" && requestUrl.pathname === "/api/session-overview") {
+        const overview = await readSessionOverview({
+          refresh: requestUrl.searchParams.get("refresh") === "true",
+        });
+        sendJson(response, 200, { overview });
+        return;
+      }
+
       if (request.method === "GET" && requestUrl.pathname === "/api/sessions") {
         const result = await listSessions({
+          archiveStatus: getArchiveStatus(requestUrl.searchParams.get("archiveStatus")),
           codexHome: settings.getHome("codex"),
+          inactiveBeforeMs: getInactiveBeforeMs(requestUrl.searchParams.get("inactiveDays")),
           includeInternals: requestUrl.searchParams.get("includeInternals") === "true",
           includeSupporting: requestUrl.searchParams.get("includeSupporting") === "true",
           page: getPositiveInteger(requestUrl.searchParams.get("page"), 1),
           pageSize: getPositiveInteger(requestUrl.searchParams.get("pageSize"), 25, 100),
           search: requestUrl.searchParams.get("search"),
           sort: requestUrl.searchParams.get("sort"),
+          workspace: requestUrl.searchParams.has("workspace")
+            ? requestUrl.searchParams.get("workspace")
+            : undefined,
         });
         sendJson(response, 200, {
           ...result,
@@ -640,7 +783,7 @@ export async function startLocalServer({ codexHome, configDirectory, port = 0 })
         deletionPlans.set(id, savedPlan);
         sendJson(response, 200, {
           plan: {
-            ...summarizePlan(plan, preflight),
+            ...summarizePlan(plan, preflight, scope),
             expiresAtMs,
             id,
           },
@@ -674,18 +817,20 @@ export async function startLocalServer({ codexHome, configDirectory, port = 0 })
         return;
       }
 
-      const operationRoute = /^\/api\/deletions\/([^/]+)(\/restore)?$/u.exec(requestUrl.pathname);
+      const operationRoute = /^\/api\/deletions\/([^/]+)(\/restore|\/backup)?$/u.exec(requestUrl.pathname);
 
       if (operationRoute) {
         const operation = getOperation(decodeURIComponent(operationRoute[1]));
-        const restoreRoute = Boolean(operationRoute[2]);
+        const operationAction = operationRoute[2] ?? "";
+        const restoreRoute = operationAction === "/restore";
+        const backupRoute = operationAction === "/backup";
 
-        if (request.method === "GET" && !restoreRoute) {
+        if (request.method === "GET" && !operationAction) {
           sendJson(response, 200, { operation: publicOperation(operation) });
           return;
         }
 
-        if (request.method === "DELETE" && !restoreRoute) {
+        if (request.method === "DELETE" && !operationAction) {
           requireMutationAuthorization({ request, requestUrl, token: mutationToken });
           const cancelAccepted = operation.status === "queued" || (
             operation.status === "running" && operation.canCancel
@@ -698,6 +843,33 @@ export async function startLocalServer({ codexHome, configDirectory, port = 0 })
           return;
         }
 
+        if (request.method === "DELETE" && backupRoute) {
+          requireMutationAuthorization({ request, requestUrl, token: mutationToken });
+
+          if (!operation.canDeleteBackup || !operation.backupDirectory) {
+            throw new Error("A recovery backup is not available for deletion.");
+          }
+
+          if (mutationInProgress || activeOperationId) {
+            sendJson(response, 409, { error: "Wait for the current cleanup to finish before deleting its backup." });
+            return;
+          }
+
+          mutationInProgress = true;
+          try {
+            if (!(await removeOperationBackups(operation))) {
+              throw new Error("The recovery backup could not be deleted.");
+            }
+            operation.backupDeleteError = null;
+            operation.canRestore = false;
+            if (operation.result) operation.result.recoveryBackupDeleted = true;
+            sendJson(response, 200, { operation: publicOperation(operation) });
+          } finally {
+            mutationInProgress = false;
+          }
+          return;
+        }
+
         if (request.method === "POST" && restoreRoute) {
           requireMutationAuthorization({ request, requestUrl, token: mutationToken });
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "session-steward",
-  "version": "0.1.1",
-  "description": "Safely review, back up, and remove local Codex sessions with a browser UI or terminal CLI.",
+  "version": "0.2.0",
+  "description": "A local Codex session manager for safely reviewing and deleting old sessions with a browser UI or terminal CLI.",
   "license": "MIT",
   "author": "Mallik Cheripally",
   "type": "module",
@@ -18,23 +18,24 @@
   "keywords": [
     "codex",
     "codex-cli",
-    "codex-sessions",
     "openai-codex",
-    "openai",
-    "chatgpt",
+    "codex-sessions",
+    "codex-session-manager",
+    "codex-session-cleanup",
+    "codex-cleanup",
+    "codex-history",
+    "delete-codex-sessions",
     "session-manager",
     "session-cleanup",
+    "chatgpt-desktop",
+    "chatgpt-history",
     "ai-coding-agent",
-    "cli",
-    "backup",
-    "privacy",
-    "local-first"
+    "chatgpt-app-cleanup"
   ],
   "os": ["darwin", "linux"],
   "files": [
     "bin",
     "dist",
-    "docs",
     "lib",
     "LICENSE",
     "README.md"
@@ -48,6 +49,7 @@
   "scripts": {
     "build": "vite build",
     "benchmark:discovery": "node --expose-gc test/benchmarks/codex-discovery.mjs",
+    "benchmark:overview": "node --expose-gc test/benchmarks/codex-overview.mjs",
     "benchmark:scale": "node --expose-gc test/benchmarks/codex-list.mjs",
     "benchmark:transcripts": "node --expose-gc test/benchmarks/codex-transcripts.mjs",
     "prepack": "npm run build",