dsh-plugin-session-cleaner 0.0.0-stage → 0.3.2

package/src/contract.cjs

@@ -0,0 +1,96 @@
+/**
+ * The Remote contract, shared verbatim by both halves.
+ *
+ * The Host's typert manifest and the Web client's mounted descriptors are both
+ * built from this file, so the two halves cannot drift.
+ *
+ * Written as CommonJS on purpose: the Web client bundles this file into a
+ * single self-contained `client.js`, and Node's ESM interop exposes these
+ * `exports.*` assignments to the Host half as named imports, so one file
+ * serves both without a build-time transform.
+ *
+ * dsh-typert-loader requires EVERY codec — parameters and results — to be
+ * `strict` (a string typeSymbol plus a create() factory), and the gateway's
+ * boundary check only calls `codec.create().parse(value)`. A pass-through
+ * parser therefore satisfies the wire contract exactly: the payloads are plain
+ * JSON projection data, and the gateway's own assertJsonValue still guards the
+ * boundary, so hand-rolling one line of validation beats shipping a schema
+ * library inside the client bundle.
+ */
+
+/** Pass-through boundary schema: whatever crosses is already lossless JSON. */
+const passthrough = () => ({ parse: (value) => value })
+
+/** The one schema entry both halves register for their codecs. */
+const SESSION_CLEANER_JSON_SCHEMA = Object.freeze({
+  name: 'SessionCleanerJson',
+  create: passthrough,
+})
+
+/** Strict JSON codec, valid on both the Host manifest and the client mount. */
+const JSON_CODEC = Object.freeze({
+  mode: 'strict',
+  typeSymbol: 'dsh-plugin-session-cleaner#SessionCleanerJson',
+  create: passthrough,
+})
+
+/** One ordered business parameter. */
+const param = (name, wire = name) => Object.freeze({
+  name,
+  wire,
+  source: 'json',
+  codec: JSON_CODEC,
+})
+
+const SESSION_CLEANER_LIST = Object.freeze({
+  id: 'dsh-plugin-session-cleaner#sessionCleaner/list',
+  service: 'sessionCleaner',
+  namespace: 'sessionCleaner',
+  method: 'list',
+  invocation: { kind: 'direct' },
+  parameters: [],
+  result: JSON_CODEC,
+})
+
+const SESSION_CLEANER_PREVIEW = Object.freeze({
+  id: 'dsh-plugin-session-cleaner#sessionCleaner/preview',
+  service: 'sessionCleaner',
+  namespace: 'sessionCleaner',
+  method: 'preview',
+  invocation: { kind: 'direct' },
+  parameters: [param('sessionIds')],
+  result: JSON_CODEC,
+})
+
+const SESSION_CLEANER_READ = Object.freeze({
+  id: 'dsh-plugin-session-cleaner#sessionCleaner/read',
+  service: 'sessionCleaner',
+  namespace: 'sessionCleaner',
+  method: 'read',
+  invocation: { kind: 'direct' },
+  parameters: [param('sessionId'), param('options')],
+  result: JSON_CODEC,
+})
+
+const SESSION_CLEANER_DELETE = Object.freeze({
+  id: 'dsh-plugin-session-cleaner#sessionCleaner/delete',
+  service: 'sessionCleaner',
+  namespace: 'sessionCleaner',
+  method: 'delete',
+  invocation: { kind: 'direct' },
+  parameters: [param('sessionIds'), param('options')],
+  result: JSON_CODEC,
+})
+
+const TYPERT_REMOTE = Object.freeze({
+  package: 'dsh-plugin-session-cleaner',
+  descriptors: [SESSION_CLEANER_LIST, SESSION_CLEANER_PREVIEW, SESSION_CLEANER_READ, SESSION_CLEANER_DELETE],
+})
+
+exports.SESSION_CLEANER_JSON_SCHEMA = SESSION_CLEANER_JSON_SCHEMA
+exports.SESSION_CLEANER_LIST = SESSION_CLEANER_LIST
+exports.SESSION_CLEANER_PREVIEW = SESSION_CLEANER_PREVIEW
+exports.SESSION_CLEANER_READ = SESSION_CLEANER_READ
+exports.SESSION_CLEANER_DELETE = SESSION_CLEANER_DELETE
+exports.TYPERT_REMOTE = TYPERT_REMOTE
+exports.default = TYPERT_REMOTE

package/src/index.js

@@ -0,0 +1,437 @@
+/**
+ * session-cleaner Host half.
+ *
+ * DSH ships no way to delete a session: `sessionPersistence` exposes only
+ * create/open/stat/list, `sessionController` has no delete, and the sidebar
+ * menu offers pin/rename/fork/archive. This plugin adds the missing operation
+ * and performs it completely — session log, projection cache, workspace
+ * registry references, and derived search indexes.
+ *
+ * The service is the single authority for deletion; the Web UI and the model
+ * Tool are two callers of it.
+ *
+ * This module deliberately imports NO DSH package: the profile's
+ * `@deepseek-ai/*` entries are partly unresolved links, so a static dependency
+ * on any of them would turn a load-time resolution failure into a plugin that
+ * never activates. Everything it needs arrives through the Cordis context.
+ */
+
+import { executeDeletion, findSearchIndexes, isValidSessionId, planDeletion, readSessionTranscript, resolveDshHome, rootsFor, scanSessions } from './cleaner.js'
+
+export const name = 'sessionCleaner'
+export const inject = ['tools', 'agents']
+
+const SERVICE = 'sessionCleaner'
+const RESTORE_NOTE = 'Deletion is permanent: DSH has no recycle bin and no soft-delete layer.'
+const DEFAULT_STOP_TIMEOUT_MS = 8000
+
+/** One human-readable line describing a byte count. */
+function formatBytes(bytes) {
+  if (!Number.isFinite(bytes) || bytes <= 0) return '0 B'
+  const units = ['B', 'KiB', 'MiB', 'GiB', 'TiB']
+  let value = bytes
+  let unit = 0
+  while (value >= 1024 && unit < units.length - 1) {
+    value /= 1024
+    unit += 1
+  }
+  return `${value >= 10 || unit === 0 ? Math.round(value) : value.toFixed(1)} ${units[unit]}`
+}
+
+/** Resolve the stop timeout, allowing an environment override for testing. */
+function stopTimeoutMs() {
+  const raw = Number(process.env.DSH_SESSION_CLEANER_STOP_MS)
+  if (Number.isFinite(raw) && raw >= 500 && raw <= 60000) return raw
+  return DEFAULT_STOP_TIMEOUT_MS
+}
+
+/** JSON-serializable projection of a deletion plan. */
+function planToWire(plan) {
+  return {
+    targetCount: plan.targets.length,
+    bytes: plan.totals.bytes,
+    humanBytes: formatBytes(plan.totals.bytes),
+    targets: plan.targets.map((target) => ({
+      id: target.id,
+      depth: target.depth,
+      isRoot: target.isRoot,
+      workspaceKey: target.workspaceKey,
+      logFile: target.logFile,
+      bytes: target.bytes,
+      title: target.title,
+      cwd: target.cwd,
+    })),
+    registryChanges: plan.registryChanges,
+    searchIndexes: plan.searchIndexes,
+    rejected: plan.rejectedIds,
+    missing: plan.missing,
+    skipped: plan.skipped,
+  }
+}
+
+/** JSON-serializable projection of a deletion result. */
+function resultToWire(result) {
+  return {
+    aborted: result.aborted === true,
+    stopped: result.stopped,
+    deleted: result.deleted.map((entry) => ({ id: entry.id, kind: entry.kind, bytes: entry.bytes ?? 0 })),
+    registryChanges: result.registryChanges,
+    searchIndexesRemoved: result.searchIndexesRemoved.map((entry) => entry.path),
+    failed: result.failed,
+    warnings: result.warnings,
+    summary: result.summary,
+    humanBytes: formatBytes(result.summary?.bytesDeleted ?? 0),
+  }
+}
+
+/**
+ * Build the deletion service over the live Cordis context.
+ * @param ctx - the plugin context, carrying `agents`.
+ */
+function createService(ctx) {
+  const roots = rootsFor(resolveDshHome())
+  const timeoutMs = stopTimeoutMs()
+
+  /**
+   * The live workspace registry, when the running DSH publishes one. Present,
+   * it becomes the single write authority over `workspace.json`: deleting ids
+   * through it updates the in-memory registry and pushes follow increments to
+   * the client, so deleted rows disappear from the sidebar without a restart.
+   * Writing the file ourselves beside it would race the registry's own
+   * read-modify-write and resurrect detached ids on its next change.
+   */
+  let liveRegistry
+
+  /** Resolve a live agent for a session, if one is registered. */
+  const liveAgent = (sessionId) => {
+    try {
+      return ctx.agents?.get(sessionId)
+    } catch {
+      return undefined
+    }
+  }
+
+  /** Wait until an agent reports `idle`, or the timeout expires. */
+  const awaitIdle = async (agent, limitMs) => {
+    const deadline = Date.now() + limitMs
+    while (Date.now() < deadline) {
+      if (agent.status !== 'running') return true
+      await new Promise((resolve) => setTimeout(resolve, 120))
+    }
+    return agent.status !== 'running'
+  }
+
+  /**
+   * Stop one session before its files are removed: a running agent would keep
+   * appending to a log we just deleted, leaving a half session behind.
+   *
+   * `ctx.agents.get()` returns a bare Agent — the AgentHandle disposer is a
+   * capability held only by whoever created it — so cancellation is the
+   * correct lever here, not disposal.
+   */
+  const stopSession = async (sessionId) => {
+    const agent = liveAgent(sessionId)
+    if (agent === undefined) return { wasRunning: false, stillRunning: false }
+    if (agent.status !== 'running') return { wasRunning: false, stillRunning: false }
+
+    try {
+      if (typeof agent.cancel === 'function') {
+        agent.cancel({ kind: 'user' }, { keepInbox: false })
+      } else if (typeof agent.abort === 'function') {
+        agent.abort()
+      } else if (typeof agent.interrupt === 'function') {
+        agent.interrupt()
+      } else {
+        return { wasRunning: true, stillRunning: true, reason: 'the live agent exposes no cancellation method' }
+      }
+    } catch (error) {
+      return { wasRunning: true, stillRunning: true, reason: String(error?.message ?? error) }
+    }
+
+    const idle = await awaitIdle(agent, timeoutMs)
+    return {
+      wasRunning: true,
+      stillRunning: !idle,
+      ...(idle ? {} : { reason: `still running after ${timeoutMs} ms` }),
+    }
+  }
+
+  /**
+   * Detach deleted sessions through the LIVE registry service, so the running
+   * app updates its workspace projection immediately instead of on next start.
+   *
+   * Every call is idempotent on the registry side: unarchiving an id that is
+   * not archived resolves without writing, and `detachSession` filters a list
+   * that no longer carries the id. Pin and archive are mutually exclusive and
+   * archiving drops the pin, but both sets are checked anyway — belt against
+   * a registry whose invariants drifted. Failures are collected per id and
+   * reported as warnings: the files are already deleted at this point, and a
+   * stale accounting entry heals on the next start.
+   */
+  const detachViaRegistry = async (ids) => {
+    const registry = liveRegistry
+    const changes = []
+    const failures = []
+    if (registry === undefined) return { changes, failures }
+
+    let entities
+    try {
+      entities = registry.list()
+    } catch (error) {
+      return { changes, failures: [{ id: '*', reason: `registry list() failed: ${String(error?.message ?? error)}` }] }
+    }
+
+    for (const id of ids) {
+      // Remove the row from the client BEFORE the accounting detach. The
+      // detach pushes a follow increment that re-roots a still-snapshotted
+      // row into Ungrouped, where it lingers until the list refresh lands —
+      // the event makes the client drop the row locally first, with no RPC
+      // round trip. It is the same event the shipped controller emits when it
+      // disposes a session; if the gateway does not relay it, behavior falls
+      // back to the brief Ungrouped flash, never worse.
+      try { ctx.emit?.('api-session/removed', id) } catch { /* advisory */ }
+      try {
+        if (Array.isArray(registry.archivedSessionIds) && registry.archivedSessionIds.includes(id)) {
+          await registry.unarchiveSession(id)
+          changes.push({ where: 'global.archivedSessionIds', removed: 1 })
+        }
+        if (Array.isArray(registry.pinnedSessionIds) && registry.pinnedSessionIds.includes(id)) {
+          await registry.unpinSession(id)
+          changes.push({ where: 'global.pinnedSessionIds', removed: 1 })
+        }
+        for (const entity of entities) {
+          if (!Array.isArray(entity?.sessionIds) || !entity.sessionIds.includes(id)) continue
+          await entity.detachSession(id)
+          changes.push({ where: `workspaces[${String(entity.id)}].sessionIds`, removed: 1 })
+        }
+      } catch (error) {
+        failures.push({ id, reason: String(error?.message ?? error) })
+      }
+    }
+    return { changes, failures }
+  }
+
+  return {
+    dshHome: roots.dshHome,
+
+    /** Attach or detach the live registry service (see apply). */
+    bindRegistry(registry) {
+      liveRegistry = registry && typeof registry === 'object' ? registry : undefined
+    },
+
+    /** Every session on disk with lightweight metadata, largest first. */
+    async list() {
+      const { records, skipped } = await scanSessions(roots)
+      const searchIndexes = await findSearchIndexes(roots)
+      const sessions = [...records.values()].map((record) => ({
+        id: record.id,
+        workspaceKey: record.workspaceKey,
+        bytes: record.bytes,
+        humanBytes: formatBytes(record.bytes),
+        parent: record.parent,
+        cwd: record.cwd,
+        title: record.title,
+        createdAt: record.createdAt,
+      }))
+      sessions.sort((left, right) => right.bytes - left.bytes)
+      return { sessions, skipped, searchIndexes, dshHome: roots.dshHome }
+    },
+
+    /** Preview exactly what deleting these sessions would remove. */
+    async preview(sessionIds) {
+      const planned = await planDeletion(roots, Array.isArray(sessionIds) ? sessionIds : [])
+      return { ...planToWire(planned), note: RESTORE_NOTE }
+    },
+
+    /**
+     * Read one session's conversation as a read-only transcript preview.
+     * Locating the log reuses the scan, so the id grammar and path
+     * containment checks guarding deletion guard the read too.
+     */
+    async read(sessionId, options = {}) {
+      if (!isValidSessionId(sessionId)) {
+        return { ok: false, error: 'not a valid session id' }
+      }
+      const { records } = await scanSessions(roots)
+      const record = records.get(sessionId)
+      if (record === undefined) {
+        return { ok: false, error: 'session not found on disk' }
+      }
+      try {
+        const transcript = await readSessionTranscript(record.logFile, options)
+        return {
+          ok: true,
+          id: record.id,
+          workspaceKey: record.workspaceKey,
+          cwd: record.cwd,
+          bytes: record.bytes,
+          humanBytes: formatBytes(record.bytes),
+          title: transcript.title ?? record.title,
+          createdAt: transcript.createdAt,
+          messages: transcript.messages,
+          totalMessages: transcript.totalMessages,
+          truncated: transcript.truncated,
+        }
+      } catch (error) {
+        return { ok: false, error: `failed to read the session log: ${String(error?.message ?? error)}` }
+      }
+    },
+
+    /**
+     * Permanently delete sessions and their descendants.
+     * @param sessionIds - root session ids to remove.
+     * @param options.guard - a session id that must NOT be deleted (the open one).
+     * @param options.cascade - reserved; descendants are always included.
+     */
+    async delete(sessionIds, options = {}) {
+      const requested = Array.isArray(sessionIds) ? sessionIds.filter(isValidSessionId) : []
+      if (requested.length === 0) {
+        return { ok: false, error: 'no valid session ids were supplied' }
+      }
+      if (typeof options?.guard === 'string' && requested.includes(options.guard)) {
+        return {
+          ok: false,
+          error: 'refused: the requested set contains the session that is currently open',
+          guard: options.guard,
+        }
+      }
+
+      const planned = await planDeletion(roots, requested)
+      if (typeof options?.guard === 'string' && planned.targets.some((target) => target.id === options.guard)) {
+        return {
+          ok: false,
+          error: 'refused: a descendant of the requested set is the session that is currently open',
+          guard: options.guard,
+        }
+      }
+
+      const hasLiveRegistry = liveRegistry !== undefined
+      const result = await executeDeletion(roots, planned, {
+        stop: stopSession,
+        ...(hasLiveRegistry ? { detachRegistry: detachViaRegistry } : {}),
+      })
+      return {
+        ok: result.failed.length === 0 && result.aborted !== true,
+        // Which authority detached the registry references: 'live-registry'
+        // means the running app's projection was updated in place (the client
+        // re-pulls its session list right after this), 'registry-file' is the
+        // offline fallback that edits workspace.json on disk.
+        registrySync: hasLiveRegistry ? 'live-registry' : 'registry-file',
+        ...resultToWire(result),
+      }
+    },
+  }
+}
+
+/**
+ * The model-facing definition. `parameters` is a JSON Schema root; the registry
+ * validates it and requires `output.schema` plus `output.render`.
+ * @param service - the deletion service.
+ * @param currentSessionId - the session running the call, refused as a target.
+ */
+function deletionTool(service, currentSessionId) {
+  return {
+    name: 'session_delete',
+    description: [
+      'Permanently delete DeepSeek Harness sessions: their logs, projection caches,',
+      'workspace-registry references and derived search indexes. Descendant subagent',
+      'sessions are removed together with their parent, and a running session is stopped first.',
+      'There is NO undo and no recycle bin. Always preview first with dryRun: true (the default),',
+      'show the user the sessions and total size, and only then re-run with dryRun: false.',
+    ].join(' '),
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        sessionIds: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Session ids to delete. Descendant subagent sessions are included automatically.',
+        },
+        dryRun: {
+          type: 'boolean',
+          description: 'When true (the default) only report what would be deleted. Set false to actually delete.',
+        },
+      },
+      // Canonical JSON Schema: `required` is a TOP-LEVEL array of property
+      // names. A per-property `required: true` is a DSL-only spelling; the
+      // registry does not validate `parameters` at registration, and the model
+      // provider then rejects it — failing EVERY conversation carrying this
+      // tool (`Invalid schema for function 'session_delete': true is not of
+      // type "array"`).
+      required: ['sessionIds'],
+    },
+    output: {
+      // A permissive OBJECT root: the registry validates this as strict JSON
+      // Schema, so `type: 'json'` (a DSL-only spelling) is rejected. Every
+      // branch this tool returns is an object, so an open object is exact.
+      schema: { type: 'object', additionalProperties: true },
+      render(_args, value) {
+        return [{ type: 'text', text: JSON.stringify(value, null, 2) }]
+      },
+    },
+    async execute(args) {
+      const ids = Array.isArray(args?.sessionIds) ? args.sessionIds : []
+      if (typeof currentSessionId === 'string' && ids.includes(currentSessionId)) {
+        return {
+          ok: false,
+          error: 'refused: that is the session running this tool call; deleting it would destroy the active conversation',
+        }
+      }
+
+      if (args?.dryRun !== false) {
+        const preview = await service.preview(ids)
+        return {
+          ok: true,
+          dryRun: true,
+          ...preview,
+          message: `Would delete ${preview.targetCount} session(s) and free ${preview.humanBytes}. Re-run with dryRun: false to confirm.`,
+        }
+      }
+
+      const result = await service.delete(ids, { guard: currentSessionId })
+      return {
+        ...result,
+        ...(result.ok === true
+          ? { message: `Deleted ${result.summary?.sessionsDeleted ?? 0} session(s), freed ${result.humanBytes}.` }
+          : {}),
+      }
+    },
+  }
+}
+
+export function apply(ctx) {
+  const service = createService(ctx)
+
+  // Public Cordis service plus its Remote binding, so the Web UI reaches the
+  // same deletion authority the Tool uses. The typert contribution itself is
+  // loaded by dsh-typert-loader from this package's `./typert` export; the
+  // consumer-side descriptors are mounted by the Web client — the Host half
+  // never mounts them itself.
+  service.typertRemote = Object.freeze({ service, serviceKey: name, namespace: name })
+  ctx.provide(name, service)
+
+  // Dynamic — NOT part of `inject` — so a composition without the workspace
+  // registry still activates this plugin and keeps the file-based fallback.
+  // While the service is up it is the only writer of workspace.json during
+  // deletions (see createService). The disposable is kept for symmetry with
+  // Cordis' effect semantics but the plugin lives as long as the host.
+  try {
+    if (typeof ctx.inject === 'function') {
+      ctx.inject(['workspaceRegistry'], (scope) => {
+        service.bindRegistry(scope?.workspaceRegistry)
+        return () => { service.bindRegistry(undefined) }
+      })
+    }
+  } catch { /* the composition publishes no workspace registry */ }
+
+  ctx.effect(() => {
+    const holder = ctx.agents?.currentInitiator?.()
+    const currentSessionId = typeof holder?.id === 'string' ? holder.id : undefined
+    const dispose = ctx.tools.register(deletionTool(service, currentSessionId))
+    return () => dispose()
+  }, 'session-cleaner.tool')
+}
+
+// Re-exported so a host (and the tests) can compose the core directly.
+export { planDeletion, executeDeletion, rootsFor, resolveDshHome }

package/src/remote.js

@@ -0,0 +1,12 @@
+/**
+ * Remote contract entry point for the Host half.
+ * The descriptors live in `contract.cjs` because the Web client bundles that
+ * same file, so both halves are guaranteed to agree on the wire shape.
+ */
+export {
+  SESSION_CLEANER_DELETE,
+  SESSION_CLEANER_LIST,
+  SESSION_CLEANER_PREVIEW,
+  TYPERT_REMOTE,
+} from './contract.cjs'
+export { default } from './contract.cjs'

package/src/typert.host.js

@@ -0,0 +1,38 @@
+/**
+ * Strict reflection for the session-cleaner service.
+ *
+ * dsh-typert-loader imports this file for every bundle that declares the
+ * `./typert` export, so it MUST exist and MUST load cleanly — a missing or
+ * throwing contributor fails the plugin's activation entirely. The invocations
+ * are the same descriptors the Web client mounts, imported from the shared
+ * contract so the two halves cannot drift.
+ */
+
+import { SESSION_CLEANER_DELETE, SESSION_CLEANER_JSON_SCHEMA, SESSION_CLEANER_LIST, SESSION_CLEANER_PREVIEW, SESSION_CLEANER_READ } from './contract.cjs'
+
+export const TYPERT = {
+  package: 'dsh-plugin-session-cleaner',
+  face: 'host',
+  schemas: [SESSION_CLEANER_JSON_SCHEMA],
+  invocations: [SESSION_CLEANER_LIST, SESSION_CLEANER_PREVIEW, SESSION_CLEANER_READ, SESSION_CLEANER_DELETE],
+  model: {
+    services: [{
+      key: 'sessionCleaner',
+      exportName: 'SessionCleanerService',
+      description: 'Complete session deletion: session logs, projection caches, workspace-registry references and derived search indexes.',
+      summary: 'Session cleanup service',
+      tags: [],
+      members: [
+        { kind: 'method', name: 'list', signature: 'list(): Promise<{ sessions: SessionCleanupRecord[]; skipped: unknown[]; searchIndexes: string[]; dshHome: string }>' },
+        { kind: 'method', name: 'preview', signature: 'preview(sessionIds: string[]): Promise<SessionCleanupPlan>' },
+        { kind: 'method', name: 'read', signature: 'read(sessionId: string, options?: { maxMessages?: number; maxCharsPerMessage?: number }): Promise<SessionTranscriptResult>' },
+        { kind: 'method', name: 'delete', signature: 'delete(sessionIds: string[], options?: { guard?: string }): Promise<SessionCleanupResult>' },
+      ],
+      types: [],
+    }],
+    events: [],
+    objects: [],
+  },
+}
+
+export default TYPERT