@wangxiaocuo/dsh-session-trash 0.0.0-stage → 0.6.0

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: session-trash
+      name: '@wangxiaocuo/dsh-session-trash'

package/icon.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="64" height="64" viewBox="0 0 64 64" role="img" aria-label="Session trash">
+  <rect width="64" height="64" rx="14" fill="#2A6FF0"/>
+  <g transform="translate(14 14) scale(2.25)" fill="none" stroke="#FFFFFF" stroke-width="1">
+    <path d="M1.28149 3.88831H14.7187"/>
+    <path d="M5.41602 3.88833V2.47962C5.41602 2.29282 5.52492 2.11366 5.71876 1.98157C5.9126 1.84948 6.17551 1.77527 6.44964 1.77527H9.55053C9.82466 1.77527 10.0876 1.84948 10.2814 1.98157C10.4753 2.11366 10.5842 2.29282 10.5842 2.47962V3.88833"/>
+    <path d="M2.57349 3.88831L3.19366 13.2943C3.21937 13.5502 3.33952 13.7872 3.53065 13.9593C3.72178 14.1313 3.97016 14.2259 4.22729 14.2246H11.7728C12.0299 14.2259 12.2783 14.1313 12.4694 13.9593C12.6605 13.7872 12.7807 13.5502 12.8064 13.2943L13.4266 3.88831"/>
+    <path d="M6.44946 6.98926V11.1238"/>
+    <path d="M9.55054 6.98926V11.1238"/>
+  </g>
+</svg>

package/index.js

@@ -0,0 +1,129 @@
+import z from '@deepseek-ai/schemastery'
+import { resolveTrashPaths } from './lib/paths.js'
+import { TrashStore } from './lib/store.js'
+import { createEligibility } from './lib/eligibility.js'
+import { createStateService } from './lib/state.js'
+import { createTrashService } from './lib/trash-service.js'
+import { createCleanupService } from './lib/cleanup.js'
+import { registerApi } from './lib/http.js'
+
+/** Host services this plugin cannot work without. */
+export const inject = ['sessionPersistence', 'webServer', 'connection', 'sessions', 'agents']
+
+/** Validated plugin configuration; ordinary fields restart the plugin when changed. */
+export const Config = z.object({
+  retentionDays: z.natural().min(1).max(3650).default(30).description('Days a trashed session is kept before automatic deletion.'),
+  sweepIntervalHours: z
+    .natural()
+    .min(1)
+    .max(168)
+    .default(6)
+    .description('Hours between automatic cleanup sweeps.'),
+  enableAutoCleanup: z.boolean().default(true).description('Automatically delete sessions past the retention period.'),
+  debug: z.boolean().default(false).description('Emit detailed trash diagnostics.'),
+})
+
+/**
+ * Build a plain diagnostics sink that never depends on the shape of the
+ * harness logger service.
+ *
+ * @param {import('@deepseek-ai/cordis').Context} ctx plugin context.
+ * @returns {{ info: Function, warn: Function, error: Function, debug: Function }} a prefixed diagnostics sink.
+ */
+function createLogger(ctx) {
+  const prefix = 'dsh-session-trash'
+  let sink = null
+  try {
+    const factory = ctx.get('logger')
+    if (typeof factory === 'function') {
+      const instance = factory(prefix)
+      if (instance !== null && instance !== undefined && typeof instance.info === 'function') sink = instance
+    } else if (factory !== null && factory !== undefined && typeof factory.info === 'function') {
+      sink = factory
+    }
+  } catch {
+    sink = null
+  }
+  const emit = (level, args) => {
+    if (sink !== null && typeof sink[level] === 'function') {
+      sink[level](...args)
+      return
+    }
+    const method = level === 'debug' ? 'log' : level
+    console[method](`[${prefix}]`, ...args)
+  }
+  return {
+    info: (...args) => emit('info', args),
+    warn: (...args) => emit('warn', args),
+    error: (...args) => emit('error', args),
+    debug: (...args) => emit('debug', args),
+  }
+}
+
+/**
+ * Register the trash services, its state projection, the HTTP API, crash
+ * recovery, and the retention sweep.
+ *
+ * @param {import('@deepseek-ai/cordis').Context} ctx plugin context.
+ * @param {object} config validated plugin configuration.
+ * @returns {void}
+ */
+export function apply(ctx, config) {
+  const logger = createLogger(ctx)
+  const scoped = config.debug ? logger : { ...logger, debug: () => {} }
+  const paths = resolveTrashPaths()
+  const store = new TrashStore({ root: paths.root, logger: scoped })
+  const eligibility = createEligibility({ ctx, store, logger: scoped })
+  const trashService = createTrashService({
+    ctx,
+    store,
+    eligibility,
+    config,
+    logger: scoped,
+    paths,
+  })
+  const cleanupService = createCleanupService({
+    ctx,
+    trashService,
+    config,
+    logger: scoped,
+  })
+  const stateService = createStateService({
+    store,
+    config,
+    trashRootDisplay: paths.display,
+    nextSweepAt: () => cleanupService.nextSweepAt(),
+    cleanup: () => cleanupService.diagnostics(),
+  })
+
+  ctx.effect(() => () => cleanupService.stop(), 'session-trash: cleanup disposal')
+
+  const ready = store
+    .init()
+    .then(async (summary) => {
+      logger.info(
+        `trash root ready at ${paths.display}; retention ${config.retentionDays}d, sweep every ${config.sweepIntervalHours}h; index ${summary.status}, ${store.entries().length} entries`,
+      )
+      try {
+        const recovery = await trashService.recover()
+        if (recovery.changed > 0) {
+          logger.info(
+            `startup recovery settled ${recovery.changed} entries (${recovery.completed} completed, ${recovery.rolledBack} rolled back, ${recovery.missing} missing)`,
+          )
+        }
+      } catch (error) {
+        logger.error(
+          `startup trash recovery failed: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}`,
+        )
+      }
+      cleanupService.start()
+      return summary
+    })
+    .catch((error) => {
+      logger.error(`trash root initialization failed at ${paths.display}: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}`)
+      throw error
+    })
+  ready.catch(() => {})
+
+  registerApi({ ctx, eligibility, stateService, trashService, cleanupService, ready, config, logger: scoped })
+}

package/lib/cleanup.js

@@ -0,0 +1,342 @@
+/** Delay before the first automatic sweep after activation. */
+export const ACTIVATION_SWEEP_DELAY_MS = 10_000
+
+/** How long a page-open sweep waits before triggering another one. */
+export const PAGE_OPEN_THROTTLE_MS = 60 * 60 * 1000
+
+/** First delay after a failed sweep; doubled on every further consecutive failure. */
+export const CLEANUP_RETRY_BASE_MS = 60 * 1000
+
+/** Upper bound for the automatic retry delay. */
+export const CLEANUP_RETRY_MAX_MS = 60 * 60 * 1000
+
+/** Result returned after the service was stopped. */
+const STOPPED_RESULT = Object.freeze({ purged: 0, failed: 0, settled: 0 })
+
+/**
+ * @param {unknown} error arbitrary failure.
+ * @returns {string} a concise message.
+ */
+function messageOf(error) {
+  return error instanceof Error ? error.message : String(error)
+}
+
+/**
+ * @param {unknown} error arbitrary failure.
+ * @returns {string} a bounded diagnostic message for `/state`.
+ */
+function errorText(error) {
+  const message = messageOf(error)
+  return message.length > 500 ? `${message.slice(0, 497)}...` : message
+}
+
+/**
+ * @param {import('@deepseek-ai/cordis').Context} ctx plugin context.
+ * @returns {{ interval: Function, timeout: Function } | undefined} the timer service, when composed.
+ */
+function resolveTimer(ctx) {
+  let timer
+  try {
+    timer = typeof ctx.get === 'function' ? ctx.get('timer') : undefined
+  } catch {
+    timer = undefined
+  }
+  if (timer !== null && timer !== undefined && typeof timer.interval === 'function' && typeof timer.timeout === 'function') {
+    return timer
+  }
+  if (typeof ctx.interval === 'function' && typeof ctx.timeout === 'function') {
+    return { interval: ctx.interval.bind(ctx), timeout: ctx.timeout.bind(ctx) }
+  }
+  return undefined
+}
+
+/**
+ * Schedule the retention sweep. Automatic cleanup runs once shortly after
+ * activation and then every `sweepIntervalHours`; when the timer service is
+ * absent it degrades to activation + trash-page open. A scheduled sweep that
+ * fails, or that reports failed purges, is retried with exponential backoff so
+ * a transient sharing violation does not wait for the next full interval.
+ * Manual cleanup is always available and never gated by `enableAutoCleanup`.
+ *
+ * @param {{
+ *   ctx: import('@deepseek-ai/cordis').Context,
+ *   trashService: { sweep: (options: { allowPurge: boolean, now: number, reason: string }) => Promise<object> },
+ *   config: { sweepIntervalHours: number, enableAutoCleanup: boolean },
+ *   logger: { info: Function, warn: Function, error: Function, debug: Function },
+ * }} deps host services and the configured cadence.
+ * @returns {{
+ *   start: () => void,
+ *   stop: () => void,
+ *   runNow: (options?: { manual?: boolean, reason?: string }) => Promise<object>,
+ *   maybeSweepOnPageOpen: () => void,
+ *   nextSweepAt: () => number | null,
+ *   lastSweepAt: () => number,
+ *   diagnostics: () => object,
+ * }} the cleanup service.
+ */
+export function createCleanupService({ ctx, trashService, config, logger }) {
+  const intervalMs = config.sweepIntervalHours * 60 * 60 * 1000
+  const timer = resolveTimer(ctx)
+  let lastAttemptAt = 0
+  let lastSuccessAt = 0
+  let lastRun = null
+  let scheduledAt = null
+  let retryAt = null
+  let consecutiveFailures = 0
+  let inFlight = null
+  let started = false
+  let stopped = false
+  let disposeActivation = null
+  let disposeInterval = null
+  let disposeRetry = null
+
+  /**
+   * @param {unknown} error sweep failure.
+   * @returns {void}
+   */
+  function report(error) {
+    logger.warn(`automatic trash cleanup failed: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}`)
+  }
+
+  /**
+   * @returns {void}
+   */
+  function clearRetry() {
+    const dispose = disposeRetry
+    disposeRetry = null
+    retryAt = null
+    if (typeof dispose !== 'function') return
+    try {
+      dispose()
+    } catch (error) {
+      logger.debug(`cannot dispose the trash cleanup retry timer: ${messageOf(error)}`)
+    }
+  }
+
+  /**
+   * Schedule one backoff retry after a failed automatic sweep.
+   *
+   * @param {string} reason failure trigger for diagnostics.
+   * @returns {void}
+   */
+  function scheduleRetry(reason) {
+    if (stopped || !config.enableAutoCleanup) return
+    clearRetry()
+    const exponent = Math.min(Math.max(consecutiveFailures - 1, 0), 8)
+    const delay = Math.min(CLEANUP_RETRY_BASE_MS * 2 ** exponent, CLEANUP_RETRY_MAX_MS)
+    retryAt = Date.now() + delay
+    const fire = () => {
+      retryAt = null
+      disposeRetry = null
+      void runNow({ reason: 'retry' }).catch(report)
+    }
+    if (timer !== undefined) {
+      disposeRetry = ctx.effect(() => timer.timeout(fire, delay), 'session-trash: cleanup retry')
+    } else {
+      const handle = setTimeout(fire, delay)
+      handle.unref?.()
+      disposeRetry = () => clearTimeout(handle)
+    }
+    logger.warn(
+      `trash cleanup (${reason}) will retry in ${Math.round(delay / 1000)}s after ${consecutiveFailures} consecutive failure(s)`,
+    )
+  }
+
+  /**
+   * Run one sweep, joining an in-flight sweep instead of queuing another. A
+   * manual request waits for the in-flight sweep and then runs its own purge,
+   * because an automatic sweep may have been started with `allowPurge: false`.
+   *
+   * @param {{ manual?: boolean, reason?: string }} [options] manual trigger and diagnostic label.
+   * @returns {Promise<object>} the sweep summary.
+   */
+  async function runNow(options = {}) {
+    if (stopped) return { ...STOPPED_RESULT }
+    const manual = options.manual === true
+    while (inFlight !== null) {
+      if (!manual) return inFlight
+      await inFlight.catch(() => {})
+    }
+    const reason = options.reason ?? (manual ? 'manual' : 'scheduled')
+    const startedAt = Date.now()
+    inFlight = (async () => {
+      const allowPurge = manual || config.enableAutoCleanup
+      try {
+        let result
+        try {
+          result = await trashService.sweep({ allowPurge, now: Date.now(), reason })
+        } catch (error) {
+          lastAttemptAt = Date.now()
+          lastRun = {
+            at: lastAttemptAt,
+            reason,
+            purged: 0,
+            failed: 0,
+            settled: 0,
+            allowPurge,
+            durationMs: lastAttemptAt - startedAt,
+            error: errorText(error),
+          }
+          consecutiveFailures += 1
+          logger.error(`trash cleanup (${reason}) failed after ${lastRun.durationMs}ms: ${messageOf(error)}`)
+          if (!manual) scheduleRetry(reason)
+          throw error
+        }
+        lastAttemptAt = Date.now()
+        lastSuccessAt = lastAttemptAt
+        lastRun = {
+          at: lastAttemptAt,
+          reason,
+          purged: typeof result.purged === 'number' ? result.purged : 0,
+          failed: typeof result.failed === 'number' ? result.failed : 0,
+          settled: typeof result.changed === 'number' ? result.changed : 0,
+          allowPurge,
+          durationMs: lastAttemptAt - startedAt,
+          error: null,
+        }
+        if (lastRun.failed > 0) {
+          consecutiveFailures += 1
+          logger.warn(
+            `trash cleanup (${reason}) finished with ${lastRun.failed} failed purge(s) after ${lastRun.durationMs}ms`,
+          )
+          if (!manual) scheduleRetry(reason)
+        } else {
+          consecutiveFailures = 0
+          clearRetry()
+          if (lastRun.purged > 0 || lastRun.settled > 0) {
+            logger.info(
+              `trash cleanup (${reason}) purged ${lastRun.purged} expired sessions, settled ${lastRun.settled} entries in ${lastRun.durationMs}ms`,
+            )
+          } else {
+            logger.debug(`trash cleanup (${reason}) found nothing to do in ${lastRun.durationMs}ms`)
+          }
+        }
+        return result
+      } finally {
+        inFlight = null
+      }
+    })()
+    return inFlight
+  }
+
+  /**
+   * @returns {void}
+   */
+  function scheduleInterval() {
+    if (stopped || timer === undefined || !config.enableAutoCleanup) return
+    if (disposeInterval !== null) return
+    disposeInterval = ctx.effect(
+      () =>
+        timer.interval(() => {
+          scheduledAt = Date.now() + intervalMs
+          void runNow({ reason: 'interval' }).catch(report)
+        }, intervalMs),
+      'session-trash: retention sweep',
+    )
+  }
+
+  /**
+   * @returns {number | null} the soonest scheduled automatic sweep, preferring a retry.
+   */
+  function computeNextSweepAt() {
+    if (!config.enableAutoCleanup) return null
+    if (retryAt !== null) return retryAt
+    return timer === undefined ? null : scheduledAt
+  }
+
+  return {
+    /**
+     * Schedule the activation sweep. Automatic cleanup is skipped when disabled;
+     * crash recovery has already run by this point either way.
+     *
+     * @returns {void}
+     */
+    start() {
+      if (started || stopped) return
+      started = true
+      if (!config.enableAutoCleanup) {
+        scheduledAt = null
+        return
+      }
+      scheduledAt = timer === undefined ? null : Date.now() + ACTIVATION_SWEEP_DELAY_MS
+      const fire = () => {
+        void runNow({ reason: 'activation' })
+          .catch(report)
+          .finally(() => {
+            if (stopped || !config.enableAutoCleanup) return
+            scheduledAt = timer === undefined ? null : Date.now() + intervalMs
+            scheduleInterval()
+          })
+      }
+      if (timer !== undefined) {
+        disposeActivation = ctx.effect(() => timer.timeout(fire, ACTIVATION_SWEEP_DELAY_MS), 'session-trash: activation sweep')
+      } else {
+        const handle = setTimeout(fire, ACTIVATION_SWEEP_DELAY_MS)
+        handle.unref?.()
+        disposeActivation = () => clearTimeout(handle)
+      }
+    },
+
+    /**
+     * Stop every scheduled sweep and retry, and ignore later triggers.
+     *
+     * @returns {void}
+     */
+    stop() {
+      stopped = true
+      if (typeof disposeActivation === 'function') disposeActivation()
+      if (typeof disposeInterval === 'function') disposeInterval()
+      clearRetry()
+      disposeActivation = null
+      disposeInterval = null
+    },
+
+    runNow,
+
+    /**
+     * Trigger a throttled background sweep when the trash page opens. The
+     * timer-backed composition uses a one-hour throttle; without a timer the
+     * configured sweep interval throttles instead.
+     *
+     * @returns {void}
+     */
+    maybeSweepOnPageOpen() {
+      if (stopped) return
+      const throttle = timer === undefined || !config.enableAutoCleanup ? intervalMs : PAGE_OPEN_THROTTLE_MS
+      if (lastAttemptAt !== 0 && Date.now() - lastAttemptAt <= throttle) return
+      void runNow({ reason: 'page-open' }).catch(report)
+    },
+
+    /**
+     * @returns {number | null} the next scheduled automatic sweep, when one exists.
+     */
+    nextSweepAt() {
+      return computeNextSweepAt()
+    },
+
+    /**
+     * @returns {number} the last succeeded sweep timestamp, or zero.
+     */
+    lastSweepAt() {
+      return lastSuccessAt
+    },
+
+    /**
+     * Read-only cleanup diagnostics for `/state` and the settings page.
+     *
+     * @returns {object} a JSON-safe diagnostic snapshot.
+     */
+    diagnostics() {
+      return {
+        enabled: config.enableAutoCleanup,
+        timerBacked: timer !== undefined,
+        lastAttemptAt: lastAttemptAt === 0 ? null : lastAttemptAt,
+        lastSuccessAt: lastSuccessAt === 0 ? null : lastSuccessAt,
+        nextSweepAt: computeNextSweepAt(),
+        retryAt,
+        consecutiveFailures,
+        lastRun: lastRun === null ? null : { ...lastRun },
+      }
+    },
+  }
+}