session-steward 0.4.0 → 0.5.1

package/lib/providers/codex/index.mjs

@@ -1,3 +1,4 @@
+import { readSessionEvents } from "./events.mjs";
 import {
   assertDeepCleanupSupported,
   diagnoseStorageCompatibility,
@@ -38,6 +39,7 @@ export const codexProvider = Object.freeze({
   loadSessionStore,
   planSessionDeletion,
   preflightSessionDeletion,
+  readSessionEvents,
   restoreSessionDeletionBackup,
   verifySessionDeletion,
 });

package/lib/providers/codex/store.mjs

@@ -460,6 +460,7 @@ export function getCodexPaths(codexHomeInput, { refresh = false } = {}) {
 
   return {
     archivedSessionsDirectory,
+    attachmentsDirectory: path.join(codexHome, "attachments"),
     codexHome,
     desktopStateBackupPath: path.join(codexHome, ".codex-global-state.json.bak"),
     desktopStatePath: path.join(codexHome, ".codex-global-state.json"),
@@ -477,6 +478,7 @@ export function getCodexPaths(codexHomeInput, { refresh = false } = {}) {
     stateDatabasePath,
     stateDatabases: allValidDatabases(state),
     stateDatabasePaths: allValidDatabases(state).map((database) => database.path),
+    threadWriterLocksDirectory: path.join(codexHome, "thread-writer-locks"),
     transcriptDirectories: [sessionsDirectory, archivedSessionsDirectory],
   };
 }
@@ -768,6 +770,7 @@ export async function loadSessionStore({ codexHome }) {
   });
 
   return {
+    attachmentsDirectory: paths.attachmentsDirectory,
     childIdsByParentId,
     codexHome: paths.codexHome,
     desktopStateBackupPath: paths.desktopStateBackupPath,
@@ -787,6 +790,7 @@ export async function loadSessionStore({ codexHome }) {
     stateDatabasePath: paths.stateDatabasePath,
     stateDatabasePaths: paths.stateDatabasePaths,
     stateDatabases: paths.stateDatabases,
+    threadWriterLocksDirectory: paths.threadWriterLocksDirectory,
     resolvedDatabases: paths.resolvedDatabases,
     logsDatabasePaths: paths.logsDatabasePaths,
     memoryDatabasePaths: paths.memoryDatabasePaths,
@@ -850,6 +854,16 @@ export async function diagnoseStorageCompatibility({ codexHome }) {
     .filter((entry) => entry.isFile() && entry.name.endsWith(".sqlite") && !recognizedDatabases.has(entry.name))
     .map((entry) => `Other local database found: ${entry.name}`)
     .sort();
+  try {
+    const attachmentEntries = await fs.readdir(paths.attachmentsDirectory, { withFileTypes: true });
+    if (attachmentEntries.some((entry) => entry.name !== ".DS_Store")) {
+      newlyDiscovered.push("Session attachments are kept because their ownership cannot be verified safely.");
+    }
+  } catch (error) {
+    if (error?.code !== "ENOENT") {
+      newlyDiscovered.push("The session attachments folder could not be examined.");
+    }
+  }
   const status = missing.length > 0 || changed.length > 0
     ? "unsupported"
     : newlyDiscovered.length > 0
@@ -906,7 +920,14 @@ function stateSchema(database) {
   const spawn = database.tables?.thread_spawn_edges?.exists !== undefined
     ? database.tables.thread_spawn_edges
     : inspectSqliteTable(database.path, "thread_spawn_edges");
-  const schema = { columns, hasSpawnEdges: Boolean(spawn?.exists) };
+  const dynamicTools = database.tables?.thread_dynamic_tools?.exists !== undefined
+    ? database.tables.thread_dynamic_tools
+    : inspectSqliteTable(database.path, "thread_dynamic_tools");
+  const schema = {
+    columns,
+    hasDynamicTools: Boolean(dynamicTools?.exists),
+    hasSpawnEdges: Boolean(spawn?.exists),
+  };
   stateSchemaCache.set(database, schema);
   return schema;
 }
@@ -1935,6 +1956,10 @@ export async function planSessionDeletion({ recordIds, store }) {
 
     return count;
   }, 0);
+  const dynamicToolRowCount = (store.stateDatabases ?? [{ path: store.stateDatabasePath }])
+    .reduce((total, database) => total + (stateSchema(database).hasDynamicTools
+      ? countRowsForIds(database.path, "thread_dynamic_tools", "thread_id", deletionIds)
+      : 0), 0);
   const logRowCount = (store.logsDatabasePaths ?? [store.logsDatabasePath].filter(Boolean))
     .reduce((total, databasePath) => total + countRowsForIds(databasePath, "logs", "thread_id", deletionIds), 0);
   const memoryRowCount = (store.memoryDatabasePaths ?? [store.memoryDatabasePath].filter(Boolean))
@@ -1953,6 +1978,7 @@ export async function planSessionDeletion({ recordIds, store }) {
       backup: store.hasDesktopStateBackup ? "pending" : "absent",
       current: store.hasDesktopState ? "pending" : "absent",
     },
+    dynamicToolRowCount,
     goalRowCount,
     historyMatchCount: historyMatches.count,
     ids: deletionIds,
@@ -2016,6 +2042,7 @@ export async function fingerprintSessionDeletion({ plan, scope, store }) {
   hash.update(`${store.codexHome}\0${scope}\0`);
 
   const counts = [
+    plan.dynamicToolRowCount,
     plan.historyMatchCount,
     plan.logRowCount,
     plan.sessionIndexMatchCount,
@@ -2053,6 +2080,9 @@ export async function fingerprintSessionDeletion({ plan, scope, store }) {
 
   for (const database of store.stateDatabases ?? [{ path: store.stateDatabasePath }]) {
     fingerprintRowsForIds(hash, database.path, "threads", "id", plan.ids);
+    if (stateSchema(database).hasDynamicTools) {
+      fingerprintRowsForIds(hash, database.path, "thread_dynamic_tools", "thread_id", plan.ids);
+    }
     if (stateSchema(database).hasSpawnEdges) {
       fingerprintRowsForIds(hash, database.path, "thread_spawn_edges", "parent_thread_id", plan.ids);
       fingerprintRowsForIds(hash, database.path, "thread_spawn_edges", "child_thread_id", plan.ids);
@@ -2129,6 +2159,36 @@ async function getAvailableDiskBytes(directoryPath) {
   return stats.bavail * stats.bsize;
 }
 
+async function findActiveThreadIds(store, ids) {
+  if (!store.threadWriterLocksDirectory) return { available: false, ids: [] };
+
+  let entries;
+  try {
+    entries = await fs.readdir(store.threadWriterLocksDirectory, { withFileTypes: true });
+  } catch (error) {
+    if (error?.code === "ENOENT") return { available: false, ids: [] };
+    throw error;
+  }
+
+  const lockedIds = new Set(entries
+    .filter((entry) => entry.isFile() && entry.name.endsWith(".lock"))
+    .map((entry) => entry.name.slice(0, -5)));
+  return {
+    available: true,
+    ids: ids.filter((id) => lockedIds.has(id)),
+  };
+}
+
+function activeThreadError(ids) {
+  const error = new Error(
+    ids.length === 1
+      ? "Close the selected Codex session before cleanup."
+      : `Close the ${ids.length} selected Codex sessions that are still open before cleanup.`,
+  );
+  error.activeThreadIds = ids;
+  return error;
+}
+
 function formatBytes(bytes) {
   if (bytes < 1024) {
     return `${bytes} bytes`;
@@ -2164,6 +2224,9 @@ export async function preflightSessionDeletion({ availableDiskBytes, plan, scope
     throw new Error("The selected Codex home is missing a required session store.");
   }
 
+  const activeThreads = await findActiveThreadIds(store, plan.ids);
+  if (activeThreads.ids.length > 0) throw activeThreadError(activeThreads.ids);
+
   const deletedIdSet = new Set(plan.ids);
   const desktopStates = await Promise.all([
     store.hasDesktopState ? readJsonFile(store.desktopStatePath) : null,
@@ -2192,7 +2255,7 @@ export async function preflightSessionDeletion({ availableDiskBytes, plan, scope
       backup: store.hasDesktopStateBackup ? "supported" : "absent",
       current: store.hasDesktopState ? "supported" : "absent",
     },
-    activeThreadDetection: "unavailable",
+    activeThreadDetection: activeThreads.available ? "writer-locks" : "unavailable",
     missingRequiredPaths,
   };
 }
@@ -2384,6 +2447,11 @@ export async function executeSessionDeletion({
     throw cleanupCancelled(backupDirectory);
   }
 
+  const activeThreads = await findActiveThreadIds(store, plan.ids);
+  if (activeThreads.ids.length > 0) {
+    throw cleanupErrorWithBackup(activeThreadError(activeThreads.ids), backupDirectory);
+  }
+
   await reportProgress(onProgress, {
     canCancel: false,
     message: "Removing selected session data",
@@ -2413,10 +2481,14 @@ export async function executeSessionDeletion({
     }
     for (const { database, ids } of plan.stateTargets ?? (store.stateDatabases ?? [{ path: store.stateDatabasePath }]).map((database) => ({ database, ids: plan.ids }))) {
       const stateStatements = [];
-      const hasSpawnEdges = stateSchema(database).hasSpawnEdges;
+      const schema = stateSchema(database);
       for (const idBatch of batches(ids)) {
         const idPlaceholders = placeholders(idBatch);
-        if (hasSpawnEdges) stateStatements.push({
+        if (schema.hasDynamicTools) stateStatements.push({
+          parameters: idBatch,
+          sql: `delete from thread_dynamic_tools where thread_id in (${idPlaceholders})`,
+        });
+        if (schema.hasSpawnEdges) stateStatements.push({
           parameters: [...idBatch, ...idBatch],
           sql: `delete from thread_spawn_edges where parent_thread_id in (${idPlaceholders}) or child_thread_id in (${idPlaceholders})`,
         });
@@ -2749,6 +2821,10 @@ export async function verifySessionDeletion({ plan, scope = "deep", store }) {
   const deletedIdSet = new Set(plan.ids);
   const remainingThreads = (store.stateDatabasePaths ?? [store.stateDatabasePath])
     .flatMap((databasePath) => findRowsForIds(databasePath, "threads", "id", plan.ids));
+  const remainingDynamicTools = (store.stateDatabases ?? [{ path: store.stateDatabasePath }])
+    .flatMap((database) => stateSchema(database).hasDynamicTools
+      ? findRowsForIds(database.path, "thread_dynamic_tools", "thread_id", plan.ids)
+      : []);
   const remainingMemoryRecords = scope === "deep" && store.hasMemoryDatabase
     ? (store.memoryDatabasePaths ?? [store.memoryDatabasePath]).flatMap((databasePath) =>
       findRowsForIds(databasePath, "stage1_outputs", "thread_id", plan.ids))
@@ -2804,6 +2880,7 @@ export async function verifySessionDeletion({ plan, scope = "deep", store }) {
   return {
     complete:
       remainingThreads.length === 0 &&
+      remainingDynamicTools.length === 0 &&
       remainingMemoryRecords.length === 0 &&
       remainingGoalRecords.length === 0 &&
       remainingLogRecords.length === 0 &&
@@ -2812,6 +2889,7 @@ export async function verifySessionDeletion({ plan, scope = "deep", store }) {
       remainingTranscriptPaths.length === 0 &&
       remainingDesktopStateReferences.length === 0,
     remainingDesktopStateReferences,
+    remainingDynamicTools,
     remainingGoalRecords,
     remainingHistoryEntries,
     remainingHistoryEntryCount: historyMatches.count,

package/lib/server.mjs

@@ -6,6 +6,10 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { getProvider, listProviders } from "./providers/index.mjs";
+import {
+  DEFAULT_SESSION_EVENT_LIMIT,
+  MAX_SESSION_EVENT_LIMIT,
+} from "./session-event-reader.mjs";
 import { createProviderSettings } from "./settings.mjs";
 import { classifyInstalledVersion } from "./version-support.mjs";
 
@@ -174,6 +178,35 @@ function getPositiveInteger(value, fallback, maximum = Number.MAX_SAFE_INTEGER)
   return Math.min(parsed, maximum);
 }
 
+function getSessionEventLimit(value) {
+  if (value === null) return DEFAULT_SESSION_EVENT_LIMIT;
+  if (!/^\d+$/u.test(value)) {
+    throw new Error(`limit must be between 1 and ${MAX_SESSION_EVENT_LIMIT}.`);
+  }
+
+  const limit = Number(value);
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > MAX_SESSION_EVENT_LIMIT) {
+    throw new Error(`limit must be between 1 and ${MAX_SESSION_EVENT_LIMIT}.`);
+  }
+
+  return limit;
+}
+
+function getSessionId(value) {
+  if (
+    typeof value !== "string"
+    || value.length === 0
+    || value.length > 512
+    || value.trim() !== value
+    || value.includes("\0")
+    || /[\\/]/u.test(value)
+  ) {
+    throw new Error("Enter a valid session ID.");
+  }
+
+  return value;
+}
+
 function getInactiveBeforeMs(value) {
   if (value === null || value === "") {
     return null;
@@ -811,10 +844,38 @@ export async function startLocalServer({ claudeHome, codexHome, configDirectory,
         return;
       }
 
+      if (request.method === "GET" && requestUrl.pathname === "/api/session-events") {
+        const controller = new AbortController();
+        const abortRead = () => controller.abort();
+        request.once("aborted", abortRead);
+        response.once("close", () => {
+          if (!response.writableEnded) abortRead();
+        });
+        const providerId = resolveProviderId(requestUrl.searchParams.get("provider"));
+        const provider = getProvider(providerId);
+        const id = getSessionId(requestUrl.searchParams.get("id"));
+        const result = await provider.readSessionEvents({
+          ...providerOptions(providerId, settings.getHome(providerId)),
+          id,
+          limit: getSessionEventLimit(requestUrl.searchParams.get("limit")),
+          signal: controller.signal,
+        });
+
+        if (controller.signal.aborted) return;
+
+        if (!result) {
+          sendJson(response, 404, { error: "Session not found." });
+          return;
+        }
+
+        sendJson(response, 200, result);
+        return;
+      }
+
       if (request.method === "GET" && requestUrl.pathname.startsWith("/api/sessions/")) {
         const providerId = resolveProviderId(requestUrl.searchParams.get("provider"));
         const provider = getProvider(providerId);
-        const id = decodeURIComponent(requestUrl.pathname.slice("/api/sessions/".length));
+        const id = getSessionId(decodeURIComponent(requestUrl.pathname.slice("/api/sessions/".length)));
         const record = await provider.getSessionRecord({
           ...providerOptions(providerId, settings.getHome(providerId)),
           id,

package/lib/session-event-reader.mjs

@@ -0,0 +1,126 @@
+import {
+  SESSION_EVENT_READ_MODE,
+  SESSION_EVENT_WINDOW_END,
+} from "./session-events.mjs";
+
+export const DEFAULT_SESSION_EVENT_LIMIT = 100;
+export const MAX_SESSION_EVENT_LIMIT = 1_000;
+
+const MAX_PENDING_SESSION_EVENTS = 2_048;
+const MAX_UNMAPPED_SESSION_EVENT_TYPES = 128;
+const SESSION_EVENT_READ_MODES = new Set(Object.values(SESSION_EVENT_READ_MODE));
+const WRAPPED_CONTEXT_PATTERN = /^<([A-Za-z][\w:.-]*[_-][\w:.-]*)(?:\s[^>]*)?>[\s\S]*?<\/\1>\s*/u;
+
+export function isInjectedSessionAsk(value) {
+  if (typeof value !== "string") return false;
+  let remaining = value.trim();
+  if (!remaining) return false;
+  if (/^#{1,6}\s+[^\n]*\binstructions?\b/iu.test(remaining)) return true;
+  let matched = false;
+
+  while (remaining) {
+    const match = WRAPPED_CONTEXT_PATTERN.exec(remaining);
+    if (!match) return false;
+    matched = true;
+    remaining = remaining.slice(match[0].length).trimStart();
+  }
+
+  return matched;
+}
+
+export function createSessionEventReadState({
+  limit = DEFAULT_SESSION_EVENT_LIMIT,
+  mode = SESSION_EVENT_READ_MODE.RECENT,
+} = {}) {
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > MAX_SESSION_EVENT_LIMIT) {
+    throw new TypeError(`limit must be between 1 and ${MAX_SESSION_EVENT_LIMIT}.`);
+  }
+
+  if (!SESSION_EVENT_READ_MODES.has(mode)) {
+    throw new TypeError(`Unsupported session event read mode: ${mode}`);
+  }
+
+  const events = new Array(limit);
+  const pending = new Map();
+  const pendingIds = new WeakMap();
+  let length = 0;
+  let start = 0;
+
+  function untrack(event) {
+    const pendingId = pendingIds.get(event);
+    if (pendingId && pending.get(pendingId) === event) pending.delete(pendingId);
+  }
+
+  return {
+    add(event, { pendingId = null } = {}) {
+      if (pendingId) {
+        pending.delete(pendingId);
+        pending.set(pendingId, event);
+        pendingIds.set(event, pendingId);
+
+        while (pending.size > MAX_PENDING_SESSION_EVENTS) {
+          pending.delete(pending.keys().next().value);
+        }
+      }
+
+      if (length < limit) {
+        events[(start + length) % limit] = event;
+        length += 1;
+      } else if (mode === SESSION_EVENT_READ_MODE.RECENT) {
+        untrack(events[start]);
+        events[start] = event;
+        start = (start + 1) % limit;
+      }
+
+      return mode === SESSION_EVENT_READ_MODE.PREVIEW && length === limit;
+    },
+    resolve(pendingId, update, { consume = true } = {}) {
+      const event = pending.get(pendingId);
+      if (!event) return false;
+      if (consume) pending.delete(pendingId);
+      update(event);
+      return true;
+    },
+    values() {
+      return Array.from({ length }, (_, index) => events[(start + index) % limit]);
+    },
+    window({ complete, stoppedEarly }) {
+      return {
+        complete,
+        end: stoppedEarly
+          ? SESSION_EVENT_WINDOW_END.OLDEST
+          : complete
+            ? SESSION_EVENT_WINDOW_END.NEWEST
+            : SESSION_EVENT_WINDOW_END.PARTIAL,
+        outcomesMayBeUnresolved: stoppedEarly || !complete,
+      };
+    },
+  };
+}
+
+export function createUnmappedSessionEventTracker() {
+  const counts = new Map();
+  let other = 0;
+
+  return {
+    add(type) {
+      const normalizedType = typeof type === "string" && type.trim()
+        ? type.trim()
+        : "unknown";
+      if (counts.has(normalizedType)) {
+        counts.set(normalizedType, counts.get(normalizedType) + 1);
+      } else if (counts.size < MAX_UNMAPPED_SESSION_EVENT_TYPES) {
+        counts.set(normalizedType, 1);
+      } else {
+        other += 1;
+      }
+    },
+    values(limit = 5) {
+      const entries = [...counts].map(([type, count]) => ({ count, type }));
+      if (other > 0) entries.push({ count: other, type: "other unmapped types" });
+      return entries
+        .sort((left, right) => right.count - left.count || left.type.localeCompare(right.type))
+        .slice(0, limit);
+    },
+  };
+}