@anionex/dsh-turn-rewind 0.1.2 → 0.2.1

package/src/engine.ts

@@ -49,6 +49,8 @@ import {
   type RestoreResult,
   type SnapshotEntry,
   type WorkspaceChange,
+  type WorkspaceOverview,
+  type WorkspacePurgeReport,
 } from './types.js'
 
 const DEFAULTS = {
@@ -67,7 +69,7 @@ const DEFAULTS = {
 
 /** Persistent workspace change-set engine, independent of the DSH tool adapter. */
 export class ChangeLedgerEngine {
-  readonly config: ResolvedChangeLedgerConfig
+  private readonly currentConfig: ResolvedChangeLedgerConfig
   readonly store: LedgerStore
   private readonly plans = new Map<string, RestorePlan>()
   private readonly activePlans = new Set<string>()
@@ -75,11 +77,28 @@ export class ChangeLedgerEngine {
 
   /** Build an engine and start crash-journal reconciliation. */
   constructor(config: ChangeLedgerConfig = {}) {
-    this.config = resolveConfig(config)
-    this.store = new LedgerStore(this.config)
+    this.currentConfig = resolveConfig(config)
+    this.store = new LedgerStore(this.currentConfig)
     this.ready = this.initializeStore()
   }
 
+  /** Currently resolved configuration; runtime-tunable fields update in place. */
+  get config(): ResolvedChangeLedgerConfig {
+    return this.currentConfig
+  }
+
+  /**
+   * Swap runtime-tunable configuration (limits, modes, timeouts, trust) in place.
+   * The storage root must never move once the engine owns locks and journals.
+   */
+  updateConfig(config: ChangeLedgerConfig): void {
+    const resolved = resolveConfig(config)
+    if (resolved.storageDir !== this.currentConfig.storageDir) {
+      throw new ChangeLedgerError('INVALID_CONFIG', 'storageDir cannot change while the engine is running')
+    }
+    Object.assign(this.currentConfig as WritableResolvedConfig, resolved)
+  }
+
   /** Wait for startup reconciliation and return the number of interrupted journals found. */
   async initialize(): Promise<number> {
     return this.ready
@@ -743,6 +762,135 @@ export class ChangeLedgerEngine {
     }
   }
 
+  /** Inventory every workspace this storage root has ever persisted state for. */
+  async listWorkspaces(options: { readonly signal?: AbortSignal } = {}): Promise<WorkspaceOverview[]> {
+    await this.ready
+    const groups = new Map<string, { restorePoints: RestorePointSummary[]; recoveryCount: number }>()
+    const groupOf = (workspace: string): { restorePoints: RestorePointSummary[]; recoveryCount: number } => {
+      const existing = groups.get(workspace)
+      if (existing !== undefined) return existing
+      const created = { restorePoints: [], recoveryCount: 0 }
+      groups.set(workspace, created)
+      return created
+    }
+    for (const workspaceDir of await this.store.listWorkspaceDirs(options.signal)) {
+      for (const manifest of await this.store.listManifestsInDir(workspaceDir, options.signal)) {
+        groupOf(manifest.workspace).restorePoints.push(summarize(manifest))
+      }
+      for (const operation of await this.store.listOperationsInDir(workspaceDir, options.signal)) {
+        if (operation.state === 'interrupted' || operation.state === 'recovery-required') {
+          groupOf(operation.workspace).recoveryCount += 1
+        }
+      }
+    }
+    return [...groups.entries()]
+      .map(([workspace, group]) => ({
+        workspace,
+        restorePoints: [...group.restorePoints].sort(
+          (left, right) => right.createdAt - left.createdAt || right.id.localeCompare(left.id),
+        ),
+        totalBytes: group.restorePoints.reduce((total, point) => total + point.totalBytes, 0),
+        recoveryCount: group.recoveryCount,
+      }))
+      .sort((left, right) => left.workspace.localeCompare(right.workspace))
+  }
+
+  /** Delete unprotected restore points recorded for one workspace and collect unused blobs. */
+  async purgeWorkspace(options: {
+    readonly workspace: string
+    /** Restrict the purge to these restore points; protection rules still apply. */
+    readonly restorePointIds?: readonly string[]
+    readonly signal?: AbortSignal
+  }): Promise<WorkspacePurgeReport> {
+    await this.ready
+    const restorePointIds = options.restorePointIds === undefined ? undefined : new Set(options.restorePointIds)
+    const targetDirs = new Set<string>()
+    for (const workspaceDir of await this.store.listWorkspaceDirs(options.signal)) {
+      for (const manifest of await this.store.listManifestsInDir(workspaceDir, options.signal)) {
+        if (manifest.workspace === options.workspace
+          && (restorePointIds === undefined || restorePointIds.has(manifest.id))) {
+          targetDirs.add(workspaceDir)
+        }
+      }
+      for (const operation of await this.store.listOperationsInDir(workspaceDir, options.signal)) {
+        if (operation.workspace === options.workspace) targetDirs.add(workspaceDir)
+      }
+    }
+    let deletedRestorePoints = 0
+    let retainedRestorePoints = 0
+    let deletedBlobs = 0
+    let retainedBlobs = 0
+    for (const workspaceDir of targetDirs) {
+      const result = await this.purgeWorkspaceDir(workspaceDir, options.workspace, restorePointIds, options.signal)
+      deletedRestorePoints += result.deletedRestorePoints
+      retainedRestorePoints += result.retainedRestorePoints
+      deletedBlobs += result.deletedBlobs
+      retainedBlobs += result.retainedBlobs
+    }
+    return { workspace: options.workspace, deletedRestorePoints, retainedRestorePoints, deletedBlobs, retainedBlobs }
+  }
+
+  private async purgeWorkspaceDir(
+    workspaceDir: string,
+    workspace: string,
+    restorePointIds: ReadonlySet<string> | undefined,
+    signal?: AbortSignal,
+  ): Promise<{ deletedRestorePoints: number; retainedRestorePoints: number; deletedBlobs: number; retainedBlobs: number }> {
+    // A live repository needs both its shared Git lock and durable directory lock.
+    // A missing path, or one now nested under a different repository, cannot expose
+    // its old Git namespace but still takes the durable lock before storage cleanup.
+    let liveRepository = false
+    let release: () => Promise<void>
+    try {
+      const root = await discoverRepositoryRoot(workspace, signal)
+      if (root === workspace) {
+        await this.assertStorageSeparated(root)
+        release = await this.acquireWorkspace(root, signal)
+        liveRepository = true
+      } else {
+        release = await this.store.acquireWorkspaceDir(workspaceDir, workspace, signal)
+      }
+    } catch (error) {
+      if (!(error instanceof ChangeLedgerError) || error.code !== 'WORKSPACE_NOT_FOUND') throw error
+      release = await this.store.acquireWorkspaceDir(workspaceDir, workspace, signal)
+    }
+    let deletedRestorePoints = 0
+    let retainedRestorePoints = 0
+    try {
+      const manifests = (await this.store.listManifestsInDir(workspaceDir, signal))
+        .filter((manifest) => manifest.workspace === workspace
+          && (restorePointIds === undefined || restorePointIds.has(manifest.id)))
+      const protectedIds = new Set<string>()
+      for (const operation of await this.store.listOperationsInDir(workspaceDir, signal)) {
+        if (operation.state === 'running' || operation.state === 'rollback-running'
+          || operation.state === 'interrupted' || operation.state === 'recovery-required') {
+          protectedIds.add(operation.restorePointId)
+          protectedIds.add(operation.rescuePointId)
+        }
+      }
+      for (const journal of await this.store.listGitCheckpointJournalsInDir(workspaceDir, signal)) {
+        protectedIds.add(journal.restorePointId)
+      }
+      for (const manifest of manifests) {
+        if (protectedIds.has(manifest.id)) {
+          retainedRestorePoints += 1
+          continue
+        }
+        if (liveRepository) {
+          await this.deleteManifestWithGit(manifest, signal)
+        } else {
+          await this.store.deleteManifestInDir(workspaceDir, manifest.id)
+        }
+        deletedRestorePoints += 1
+      }
+      if (restorePointIds === undefined) await this.store.clearTurnOutcomesInDir(workspaceDir)
+      const gc = await this.store.collectGarbageInDir(workspaceDir, signal)
+      return { deletedRestorePoints, retainedRestorePoints, ...gc }
+    } finally {
+      await release()
+    }
+  }
+
   private async createLocked(options: {
     readonly cwd: string
     readonly kind: RestorePointKind
@@ -943,6 +1091,9 @@ export class ChangeLedgerEngine {
   }
 }
 
+/** Mutable view used only by `updateConfig` to swap fields on the shared resolved object. */
+type WritableResolvedConfig = { -readonly [K in keyof ResolvedChangeLedgerConfig]: ResolvedChangeLedgerConfig[K] }
+
 /** Resolve and validate every deployment-varying configuration value. */
 export function resolveConfig(config: ChangeLedgerConfig): ResolvedChangeLedgerConfig {
   const home = homedir()

package/src/index.ts

@@ -4,12 +4,14 @@
  */
 import type { Context } from '@deepseek-ai/cordis'
 import { ChangeLedgerEngine } from './engine.js'
-import { installRewindHttp, TurnCheckpointCoordinator } from './rewind-host.js'
+import { installManageHttp, installRewindHttp, TurnCheckpointCoordinator } from './rewind-host.js'
+import { installTurnRewindSettings } from './settings.js'
 import type { ChangeLedgerConfig } from './types.js'
 
 export * from './engine.js'
 export * from './errors.js'
 export * from './rewind-host.js'
+export * from './settings.js'
 export * from './types.js'
 
 declare module '@deepseek-ai/cordis' {
@@ -30,7 +32,9 @@ export class ChangeLedgerService {
     ctx.inject(['agents'], (scope: Context) => { checkpoints.install(scope) })
     ctx.inject(['webServer', 'sessions', 'sessionQuery', 'apiProxy', 'agents'], (scope: Context) => {
       installRewindHttp(scope, this.engine, checkpoints)
+      installManageHttp(scope, this.engine)
     })
+    installTurnRewindSettings(ctx, config, this.engine)
     void this.engine.initialize().then((reconciled) => {
       if (reconciled > 0) {
         ctx.logger.warn(`[change-ledger] reconciled ${reconciled} interrupted durable operation(s)`)
@@ -95,6 +99,21 @@ export class ChangeLedgerService {
   listRecovery(options: Parameters<ChangeLedgerEngine['listRecovery']>[0]): ReturnType<ChangeLedgerEngine['listRecovery']> {
     return this.engine.listRecovery(options)
   }
+
+  /** Inventory every workspace this storage root has persisted state for. */
+  listWorkspaces(options?: Parameters<ChangeLedgerEngine['listWorkspaces']>[0]): ReturnType<ChangeLedgerEngine['listWorkspaces']> {
+    return this.engine.listWorkspaces(options)
+  }
+
+  /** Delete unprotected restore points recorded for one workspace. */
+  purgeWorkspace(options: Parameters<ChangeLedgerEngine['purgeWorkspace']>[0]): ReturnType<ChangeLedgerEngine['purgeWorkspace']> {
+    return this.engine.purgeWorkspace(options)
+  }
+
+  /** Swap runtime-tunable configuration; the storage root must stay fixed. */
+  updateConfig(config: ChangeLedgerConfig): void {
+    this.engine.updateConfig(config)
+  }
 }
 
 export default ChangeLedgerService

package/src/rewind-host.ts

@@ -29,6 +29,12 @@ interface AgentLike {
   readonly session: SessionLike
 }
 
+interface ToolExecutionLike {
+  readonly agent?: AgentLike
+  readonly parent?: symbol
+  readonly signal: AbortSignal
+}
+
 interface AgentsLike {
   list(): AgentLike[]
 }
@@ -102,6 +108,10 @@ declare module '@deepseek-ai/cordis' {
       },
       next: () => Promise<unknown>,
     ): Promise<unknown>
+    'tools/execute'(
+      exec: ToolExecutionLike,
+      next: () => Promise<unknown>,
+    ): Promise<unknown>
   }
 }
 
@@ -110,7 +120,7 @@ const BODY_LIMIT = 64 * 1024
 const INITIAL_CHANGE_PREVIEW_LIMIT = 8
 const MAX_CHANGE_PAGE_SIZE = 200
 
-/** Capture each turn before its opening user message can trigger model or tool work. */
+/** Capture each turn beside model work and gate root tool side effects on its bounded outcome. */
 export class TurnCheckpointCoordinator {
   private readonly captures = new Map<string, Promise<void>>()
   private readonly pending = new Set<string>()
@@ -120,10 +130,17 @@ export class TurnCheckpointCoordinator {
 
   constructor(private readonly engine: ChangeLedgerEngine) {}
 
-  /** Install the first-step gate; checkpoint failures are recorded but never reject the user turn. */
+  /** Keep sidecar checkpoint work out of the Agent response waterfall. */
   install(ctx: Context): void {
     ctx.on('agent/pre-step', async ({ agent, turn, step, signal }, next) => {
-      if (step === 1) await this.capture(ctx, agent, turn, signal)
+      if (step === 1) this.startCapture(ctx, agent, turn, signal)
+      return next()
+    }, { prepend: true })
+
+    ctx.on('tools/execute', async (exec, next) => {
+      if (exec.agent !== undefined && exec.parent === undefined) {
+        await this.waitForOpenTurn(exec.agent, exec.signal)
+      }
       return next()
     }, { prepend: true })
   }
@@ -138,6 +155,20 @@ export class TurnCheckpointCoordinator {
     return error === undefined ? { status: 'missing' } : { status: 'failed', error }
   }
 
+  private startCapture(
+    ctx: Pick<Context, 'logger'>,
+    agent: AgentLike,
+    turn: number,
+    signal: AbortSignal,
+  ): void {
+    const key = checkpointKey(agent.id, turn)
+    if (this.captures.has(key)) return
+    const capture = this.capture(ctx, agent, turn, signal).catch(async (error: unknown) => {
+      await this.recordFailure(ctx, agent.id, turn, error)
+    })
+    this.captures.set(key, capture)
+  }
+
   private async capture(
     ctx: Pick<Context, 'logger'>,
     agent: AgentLike,
@@ -159,11 +190,6 @@ export class TurnCheckpointCoordinator {
     const captureDeadline = createDeadline(Math.max(1, timeoutMs - reserveMs))
     const captureSignal = AbortSignal.any([signal, captureDeadline.signal])
     try {
-      const existing = this.captures.get(key)
-      if (existing !== undefined) {
-        await waitWithSignal(existing, captureSignal).catch(() => undefined)
-        return
-      }
       this.pending.add(key)
       this.failures.delete(key)
       this.skips.delete(key)
@@ -201,7 +227,6 @@ export class TurnCheckpointCoordinator {
           this.pending.delete(key)
         }
       })()
-      this.captures.set(key, capture)
       try {
         await waitWithSignal(capture, outcomeSignal)
       } catch (error) {
@@ -220,6 +245,24 @@ export class TurnCheckpointCoordinator {
     }
   }
 
+  /** Wait only for the bounded checkpoint outcome of the Agent's open turn. */
+  private async waitForOpenTurn(agent: AgentLike, signal: AbortSignal): Promise<void> {
+    if (signal.aborted) return
+    const boundary = agent.session.events.findLast(event => event.type === 'turn/start' || event.type === 'turn/end')
+    if (boundary?.type !== 'turn/start') return
+    const turn = boundary.data.turn
+    if (!Number.isSafeInteger(turn) || (turn as number) < 0) return
+    const capture = this.captures.get(checkpointKey(agent.id, turn as number))
+    if (capture === undefined) return
+    try {
+      await waitWithSignal(capture, signal)
+    } catch (error) {
+      // Delegate caller cancellation so the DSH tool runtime preserves its
+      // canonical ABORTED_BEFORE_DISPATCH result instead of a wrapper error.
+      if (!signal.aborted) throw error
+    }
+  }
+
   private async serializeWorkspace(workspace: string, signal: AbortSignal, task: () => Promise<void>): Promise<void> {
     const previous = this.workspaceTails.get(workspace) ?? Promise.resolve()
     const current = (async () => {
@@ -686,3 +729,73 @@ function json(response: HttpResponseLike, status: number, value: unknown): void
   response.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' })
   response.end(`${JSON.stringify(value)}\n`)
 }
+
+export const MANAGE_HTTP_PATH = '/turn-rewind/manage'
+
+/** Register the same-origin storage-management endpoint consumed by the settings card. */
+export function installManageHttp(ctx: Context, engine: ChangeLedgerEngine): void {
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: MANAGE_HTTP_PATH,
+    handler: createManageHttpHandler(engine),
+  }), 'change-ledger.manageHttp')
+}
+
+/** Build the storage-management route as a testable unit. */
+export function createManageHttpHandler(
+  engine: ChangeLedgerEngine,
+): (request: HttpRequestLike, response: HttpResponseLike) => Promise<void> {
+  return async (request, response) => {
+    try {
+      if (request.method === 'GET') {
+        const workspaces = await engine.listWorkspaces()
+        json(response, 200, {
+          storageDir: engine.config.storageDir,
+          totalBytes: workspaces.reduce((total, workspace) => total + workspace.totalBytes, 0),
+          workspaces: workspaces.map((workspace) => ({
+            workspace: workspace.workspace,
+            totalBytes: workspace.totalBytes,
+            recoveryCount: workspace.recoveryCount,
+            restorePoints: workspace.restorePoints.map((point) => ({
+              id: point.id,
+              kind: point.kind,
+              format: point.format,
+              createdAt: point.createdAt,
+              totalBytes: point.totalBytes,
+              fileCount: point.fileCount,
+              ...(point.sessionId === undefined ? {} : { sessionId: point.sessionId }),
+              ...(point.turn === undefined ? {} : { turn: point.turn }),
+              ...(point.label === undefined ? {} : { label: point.label }),
+            })),
+          })),
+        })
+        return
+      }
+      if (request.method === 'POST') {
+        const body = objectBody(await readBody(request))
+        const action = requiredText(body.action, 'action')
+        if (action === 'delete') {
+          const workspace = requiredText(body.workspace, 'workspace')
+          const restorePointId = requiredText(body.restorePointId, 'restorePointId')
+          const report = await engine.purgeWorkspace({ workspace, restorePointIds: [restorePointId] })
+          if (report.deletedRestorePoints === 0) {
+            throw new ChangeLedgerError(
+              report.retainedRestorePoints > 0 ? 'RECOVERY_REFERENCE' : 'RESTORE_POINT_NOT_FOUND',
+              report.retainedRestorePoints > 0
+                ? 'restore point is required by an incomplete recovery journal'
+                : `restore point ${restorePointId} does not exist`,
+            )
+          }
+          json(response, 200, { status: 'completed', action, ...report })
+          return
+        }
+        throw new ChangeLedgerError('INVALID_ARGUMENTS', `unsupported manage action ${action}`)
+      }
+      response.writeHead(405, { allow: 'GET, POST' })
+      response.end()
+    } catch (error) {
+      const status = error instanceof ChangeLedgerError && error.code === 'RESTORE_POINT_NOT_FOUND' ? 404 : 409
+      json(response, status, { error: errorMessage(error), code: error instanceof ChangeLedgerError ? error.code : 'MANAGE_FAILED' })
+    }
+  }
+}

package/src/settings.ts

@@ -0,0 +1,93 @@
+/**
+ * Runtime settings surface for Turn Rewind on the DSH web settings page.
+ * @module @anionex/dsh-turn-rewind
+ */
+import type { Context } from '@deepseek-ai/cordis'
+import { installSettingsSection, settingsNamespace } from '@deepseek-ai/dsh-settings'
+import z from '@deepseek-ai/schemastery'
+import { resolveConfig, type ChangeLedgerEngine } from './engine.js'
+import type { ChangeLedgerConfig, ResolvedChangeLedgerConfig } from './types.js'
+
+/** Namespace join key shared by the host section and the browser settings card. */
+export const TURN_REWIND_SETTINGS_NAMESPACE = settingsNamespace('turn-rewind')
+
+/** Every runtime-tunable field of {@link ChangeLedgerConfig}; `storageDir` stays config-layer only. */
+export interface TurnRewindSettings {
+  /** Maximum user and rescue restore points retained per workspace. */
+  maxRestorePoints: number
+  /** Maximum automatic turn checkpoints retained per session. */
+  maxTurnCheckpointsPerSession: number
+  /** Maximum number of files in one restore point. */
+  maxFiles: number
+  /** Maximum bytes read from one regular file. */
+  maxFileBytes: number
+  /** Maximum aggregate regular-file bytes in one restore point. */
+  maxSnapshotBytes: number
+  /** Restore-plan lifetime in milliseconds. */
+  planTtlMs: number
+  /** Age after which a lock whose owner is gone may be reclaimed. */
+  staleLockMs: number
+  /** Automatic turn-checkpoint implementation; `off` records durable skips instead. */
+  turnCheckpointMode: 'off' | 'git-native' | 'legacy'
+  /** Maximum time one automatic checkpoint may block the first Agent step. */
+  turnCheckpointTimeoutMs: number
+  /** Maximum uncached worktree bytes read by one automatic Git-native checkpoint. */
+  turnCheckpointMaxNewBytes: number
+  /** Fast trusts fenced Git/stat metadata; strict rereads every eligible path. */
+  turnCheckpointTrust: 'fast' | 'strict'
+}
+
+/** Schemastery schema for the `turn-rewind` settings namespace. */
+export const TurnRewindSettingsSchema: z<TurnRewindSettings> = (() => {
+  const defaults = tunableSettings(resolveConfig({}))
+  return z.object({
+    maxRestorePoints: z.number().step(1).min(1).default(defaults.maxRestorePoints),
+    maxTurnCheckpointsPerSession: z.number().step(1).min(1).default(defaults.maxTurnCheckpointsPerSession),
+    maxFiles: z.number().step(1).min(1).default(defaults.maxFiles),
+    maxFileBytes: z.number().step(1).min(1).default(defaults.maxFileBytes),
+    maxSnapshotBytes: z.number().step(1).min(1).default(defaults.maxSnapshotBytes),
+    planTtlMs: z.number().step(1).min(1).default(defaults.planTtlMs),
+    staleLockMs: z.number().step(1).min(1).default(defaults.staleLockMs),
+    turnCheckpointMode: z.union(['off', 'git-native', 'legacy']).default(defaults.turnCheckpointMode),
+    turnCheckpointTimeoutMs: z.number().step(1).min(1).default(defaults.turnCheckpointTimeoutMs),
+    turnCheckpointMaxNewBytes: z.number().step(1).min(1).default(defaults.turnCheckpointMaxNewBytes),
+    turnCheckpointTrust: z.union(['fast', 'strict']).default(defaults.turnCheckpointTrust),
+  })
+})()
+
+/** Project one resolved configuration onto the settings namespace subset. */
+function tunableSettings(resolved: ResolvedChangeLedgerConfig): TurnRewindSettings {
+  return {
+    maxRestorePoints: resolved.maxRestorePoints,
+    maxTurnCheckpointsPerSession: resolved.maxTurnCheckpointsPerSession,
+    maxFiles: resolved.maxFiles,
+    maxFileBytes: resolved.maxFileBytes,
+    maxSnapshotBytes: resolved.maxSnapshotBytes,
+    planTtlMs: resolved.planTtlMs,
+    staleLockMs: resolved.staleLockMs,
+    turnCheckpointMode: resolved.turnCheckpointMode,
+    turnCheckpointTimeoutMs: resolved.turnCheckpointTimeoutMs,
+    turnCheckpointMaxNewBytes: resolved.turnCheckpointMaxNewBytes,
+    turnCheckpointTrust: resolved.turnCheckpointTrust,
+  }
+}
+
+/**
+ * Register the `turn-rewind` settings namespace and apply its resolved value to the
+ * running engine. The composition entry (from `cordis.patch.yml`) is the base layer;
+ * the user layer persists through the DSH settings provider. `storageDir` is never
+ * carried by the namespace: the storage root must not move while the engine runs.
+ */
+export function installTurnRewindSettings(ctx: Context, config: ChangeLedgerConfig, engine: ChangeLedgerEngine): void {
+  let source: () => TurnRewindSettings = () => tunableSettings(resolveConfig(config))
+  installSettingsSection(ctx, TURN_REWIND_SETTINGS_NAMESPACE, TurnRewindSettingsSchema, source(), {
+    setSource: (current) => { source = current },
+    onChange: () => {
+      try {
+        engine.updateConfig({ ...config, ...source() })
+      } catch (error) {
+        ctx.logger.warn(`[turn-rewind] could not apply settings update: ${error instanceof Error ? error.message : String(error)}`)
+      }
+    },
+  })
+}