@lincyaw/workspace 1.0.0-rc.0 → 1.0.0-rc.2

package/src/node/review/git-review.ts

@@ -1,25 +1,22 @@
 import { execFile } from 'node:child_process'
 import { mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, rmdirSync, rmSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
-import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'
+import { dirname, join, relative, resolve, sep } from 'node:path'
 import { gitConfigArgs, gitEnvironment } from '@lincyaw/kernel'
 import type { ChangeReview, DocumentFileChange, DocumentFiles, ReviewChange, ReviewChangeKind, ReviewStep } from '@lincyaw/kernel'
-import { guardGitDir } from './git-guard.ts'
-import type { GitGuard } from './git-guard.ts'
-import { holderRuns, readRecord, removeRecord, SELF, writeRecord } from './review-record.ts'
-import type { ReviewRecord, SessionRecord } from './review-record.ts'
-
-export function within(path: string, dir: string): boolean {
-  const rel = relative(resolve(dir), resolve(path))
-  return rel === '' || (rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel))
-}
+import { isInside } from '@lincyaw/kernel/node'
+import { snapshotGitDir } from './git-guard.ts'
+import type { SavedGitDir } from './git-guard.ts'
+import { isHolderAlive, readRecord, removeRecord, THIS_PROCESS, writeRecord } from './record.ts'
+import type { AgentSessionRecord, ReviewRecord } from './record.ts'
 
 export interface GitReview extends ChangeReview {
   readonly task: string
-  checkpoints(): readonly string[]
   restoreFiles(paths: string[]): Promise<void>
-  note(session: Omit<SessionRecord, 'checkpoints' | 'steps'>): void
+  noteSession(session: Omit<AgentSessionRecord, 'checkpoints' | 'steps'>): void
   suspend(): void
+  prepareAccept(reject: string[]): Promise<string[]>
+  finish(): void
 }
 
 export const GIT_ENGINE = 'git'
@@ -30,7 +27,7 @@ const MAX_DIFFS = 200
 
 const DIFF = ['diff', '--no-renames', '--no-ext-diff', '--no-textconv', '--no-color']
 
-const opened = new Set<string>()
+const openScopes = new Set<string>()
 
 function git(cwd: string, args: string[], env: Record<string, string> = {}): Promise<Buffer> {
   return new Promise((resolve, reject) => {
@@ -46,7 +43,7 @@ function git(cwd: string, args: string[], env: Record<string, string> = {}): Pro
   })
 }
 
-const text = async (cwd: string, args: string[], env?: Record<string, string>) => (await git(cwd, args, env)).toString('utf8')
+const gitText = async (cwd: string, args: string[], env?: Record<string, string>) => (await git(cwd, args, env)).toString('utf8')
 
 export interface GitDirs {
   top: string
@@ -55,16 +52,17 @@ export interface GitDirs {
 }
 
 async function gitDirsOf(root: string): Promise<GitDirs> {
-  const [top = '', gitDir = '', commonDir = ''] = (await text(root, ['rev-parse', '--show-toplevel', '--absolute-git-dir', '--git-common-dir'])).split('\n')
+  const [top = '', gitDir = '', commonDir = ''] = (await gitText(root, ['rev-parse', '--show-toplevel', '--absolute-git-dir', '--git-common-dir'])).split('\n')
   return { top: realpathSync(top), gitDir: realpathSync(gitDir), commonDir: realpathSync(resolve(root, commonDir)) }
 }
 
-const READING = '^(core\\.(filemode|symlinks|ignorecase|precomposeunicode|autocrlf|eol|safecrlf|excludesfile)|extensions\\.objectformat)$'
+const COPIED_CONFIG_KEYS = '^(core\\.(filemode|symlinks|ignorecase|precomposeunicode|autocrlf|eol|safecrlf|excludesfile)|extensions\\.objectformat)$'
 
 const quoted = (value: string) => `"${value.replace(/[\\"]/g, c => `\\${c}`).replace(/\n/g, '\\n')}"`
 
-async function readingOf(dirs: GitDirs): Promise<{ config: string, exclude?: string }> {
-  const listed = await text(dirs.top, ['config', '-z', '--get-regexp', READING], { GIT_DIR: dirs.gitDir, GIT_COMMON_DIR: dirs.commonDir }).catch(() => '')
+/** The settings of the repository's git configuration that reading its files depends on, for a git directory of the review's own. */
+async function isolatedGitConfig(dirs: GitDirs): Promise<{ config: string, exclude?: string }> {
+  const listed = await gitText(dirs.top, ['config', '-z', '--get-regexp', COPIED_CONFIG_KEYS], { GIT_DIR: dirs.gitDir, GIT_COMMON_DIR: dirs.commonDir }).catch(() => '')
   const sections = new Map<string, string[]>()
   for (const entry of listed.split('\0').filter(Boolean)) {
     const at = entry.indexOf('\n')
@@ -83,26 +81,27 @@ async function readingOf(dirs: GitDirs): Promise<{ config: string, exclude?: str
   return { config: `${config}\n`, ...exclude ? { exclude } : {} }
 }
 
-class Trees {
+/** Trees of the reviewed directory written with an index and a git directory of the review's own. */
+class ReviewTrees {
   readonly #work = mkdtempSync(join(tmpdir(), 'presmium-review-'))
   #indexes = 0
   readonly #pathspec: string
   readonly #env: Record<string, string>
   readonly #files?: DocumentFiles
   readonly top: string
-  readonly deck: string
+  readonly scopeDir: string
   readonly root: string
 
-  constructor(dirs: GitDirs, deck: string, root: string, reading: { config: string, exclude?: string }, options: { files?: DocumentFiles } = {}) {
+  constructor(dirs: GitDirs, scopeDir: string, root: string, gitConfig: { config: string, exclude?: string }, options: { files?: DocumentFiles } = {}) {
     this.top = dirs.top
-    this.deck = deck
+    this.scopeDir = scopeDir
     this.root = root
-    this.#pathspec = relative(dirs.top, deck).split(sep).join('/') || '.'
+    this.#pathspec = relative(dirs.top, scopeDir).split(sep).join('/') || '.'
     const own = join(this.#work, 'git')
     for (const dir of ['refs', 'objects', 'info']) mkdirSync(join(own, dir), { recursive: true })
     writeFileSync(join(own, 'HEAD'), 'ref: refs/heads/review\n')
-    writeFileSync(join(own, 'config'), reading.config)
-    if (reading.exclude !== undefined) writeFileSync(join(own, 'info', 'exclude'), reading.exclude)
+    writeFileSync(join(own, 'config'), gitConfig.config)
+    if (gitConfig.exclude !== undefined) writeFileSync(join(own, 'info', 'exclude'), gitConfig.exclude)
     this.#env = { GIT_DIR: own, GIT_OBJECT_DIRECTORY: join(dirs.commonDir, 'objects'), GIT_WORK_TREE: dirs.top }
     this.#files = options.files
   }
@@ -132,6 +131,12 @@ class Trees {
     }
   }
 
+  async changedPaths(from: string, to: string): Promise<string[]> {
+    if (from === to) return []
+    return (await this.#text([...DIFF, '--name-only', '-z', from, to])).split('\0').filter(Boolean)
+      .map(this.fromGit).sort((a, b) => a.localeCompare(b))
+  }
+
   async compare(from: string, to: string): Promise<ReviewChange[]> {
     if (from === to) return []
     const status = (await this.#text([...DIFF, '--name-status', '-z', from, to])).split('\0').filter(Boolean)
@@ -157,7 +162,7 @@ class Trees {
   }
 
   async restore(tree: string, paths: string[]): Promise<void> {
-    const ours = paths.map(this.toGit).filter(path => within(join(this.top, path), this.deck))
+    const ours = paths.map(this.toGit).filter(path => isInside(join(this.top, path), this.scopeDir))
     if (ours.length === 0) return
     if (this.#files) return this.#write(tree, ours)
     const known = new Set((await this.#text(['ls-tree', '-r', '-z', '--name-only', tree, '--', ...ours])).split('\0').filter(Boolean))
@@ -174,7 +179,7 @@ class Trees {
     for (const path of ours.filter(path => !known.has(path))) {
       const file = join(this.top, path)
       rmSync(file, { force: true })
-      for (let dir = dirname(file); within(dir, this.deck) && dir !== this.deck; dir = dirname(dir)) {
+      for (let dir = dirname(file); isInside(dir, this.scopeDir) && dir !== this.scopeDir; dir = dirname(dir)) {
         try {
           if (readdirSync(dir).length > 0) break
           rmdirSync(dir)
@@ -207,7 +212,7 @@ class Trees {
   }
 
   async reset(tree: string): Promise<void> {
-    await this.restore(tree, (await this.compare(tree, await this.tree())).map(change => change.path))
+    await this.restore(tree, await this.changedPaths(tree, await this.tree()))
   }
 
   dispose(): void {
@@ -217,7 +222,7 @@ class Trees {
 
 export interface GitReviewOptions {
   workspaceRoot: string
-  deckDir: string
+  scopeDir: string
   task: string
   onRestore?: (paths: string[]) => void
   warn?: (message: string) => void
@@ -226,88 +231,90 @@ export interface GitReviewOptions {
 
 const recovering = new Map<string, Promise<{ task: string, paths: string[] } | undefined>>()
 
-function guarding(gitDir: string, deck: string, root: string, onRestore: GitReviewOptions['onRestore'], guard?: GitGuard) {
-  const found = guard ?? (within(gitDir, deck) ? guardGitDir(gitDir) : undefined)
+/** Puts a git directory inside the reviewed directory back as it was, from a saved snapshot or one taken now. */
+function gitDirGuard(gitDir: string, scopeDir: string, root: string, onRestore: GitReviewOptions['onRestore'], saved?: SavedGitDir): { saved(): SavedGitDir | undefined, restore(): void } {
+  const snapshot = saved ? snapshotGitDir(gitDir, saved) : isInside(gitDir, scopeDir) ? snapshotGitDir(gitDir) : undefined
   return {
-    guard: found,
+    saved: () => snapshot?.saved(),
     restore() {
-      const paths = found?.restore() ?? []
+      const paths = snapshot?.restore() ?? []
       if (paths.length > 0) onRestore?.(paths.map(path => relative(root, join(gitDir, path)).split(sep).join('/')))
     },
   }
 }
 
 export function recoverGitReview(options: Omit<GitReviewOptions, 'task'>): Promise<{ task: string, paths: string[] } | undefined> {
-  const deck = realpathSync(options.deckDir)
-  let running = recovering.get(deck)
+  const scopeDir = realpathSync(options.scopeDir)
+  let running = recovering.get(scopeDir)
   if (!running) {
-    running = recover(deck, realpathSync(options.workspaceRoot), options).finally(() => recovering.delete(deck))
-    recovering.set(deck, running)
+    running = rollBackLeftReview(scopeDir, realpathSync(options.workspaceRoot), options).finally(() => recovering.delete(scopeDir))
+    recovering.set(scopeDir, running)
   }
   return running
 }
 
-async function recover(deck: string, root: string, options: Omit<GitReviewOptions, 'task'>): Promise<{ task: string, paths: string[] } | undefined> {
-  const { onRestore } = options
-  const record = readRecord(deck)
-  if (!record || record.session || opened.has(deck) || holderRuns(record)) return undefined
-  let trees: Trees | undefined
+async function rollBackLeftReview(scopeDir: string, root: string, options: Omit<GitReviewOptions, 'task'>): Promise<{ task: string, paths: string[] } | undefined> {
+  const record = readRecord(scopeDir)
+  if (!record || record.session || openScopes.has(scopeDir) || isHolderAlive(record)) return undefined
+  let trees: ReviewTrees | undefined
   try {
-    if (record.guard) guarding(record.dirs.gitDir, deck, root, onRestore, guardGitDir(record.dirs.gitDir, record.guard)).restore()
-    trees = new Trees(record.dirs, deck, root, await readingOf(record.dirs), options)
-    const paths = (await trees.compare(record.snapshot, await trees.tree())).map(change => change.path)
+    if (record.guard) gitDirGuard(record.dirs.gitDir, scopeDir, root, options.onRestore, record.guard).restore()
+    trees = new ReviewTrees(record.dirs, scopeDir, root, await isolatedGitConfig(record.dirs), options)
+    const paths = await trees.changedPaths(record.snapshot, await trees.tree())
     await trees.restore(record.snapshot, paths)
     return { task: record.task, paths }
   } finally {
-    removeRecord(deck)
+    removeRecord(scopeDir)
     trees?.dispose()
   }
 }
 
-export function leftSessionReview(deckDir: string): ReviewRecord | undefined {
-  const deck = realpathSync(deckDir)
-  const record = readRecord(deck)
-  return record?.session && !opened.has(deck) && !holderRuns(record) ? record : undefined
+/** The record of an agent session's review that a process which has ended left waiting for its author. */
+export function pendingAgentSessionReview(scopeDir: string): ReviewRecord | undefined {
+  const real = realpathSync(scopeDir)
+  const record = readRecord(real)
+  return record?.session && !openScopes.has(real) && !isHolderAlive(record) ? record : undefined
 }
 
-export async function openGitReview(options: GitReviewOptions & { session?: Omit<SessionRecord, 'checkpoints' | 'steps'> }): Promise<GitReview> {
-  const deck = realpathSync(options.deckDir)
+export async function openGitReview(options: GitReviewOptions & { session?: Omit<AgentSessionRecord, 'checkpoints' | 'steps'> }): Promise<GitReview> {
+  const scopeDir = realpathSync(options.scopeDir)
   const root = realpathSync(options.workspaceRoot)
-  if (opened.has(deck)) throw new Error(`a change of ${relative(root, deck) || '.'} is under way already`)
-  const left = readRecord(deck)
-  if (left && holderRuns(left)) throw new Error(`a change of ${relative(root, deck) || '.'} is under way in another process (${left.pid})`)
-  if (left?.session) throw new Error(`a review of ${relative(root, deck) || '.'} waits for its author (session ${left.session.session}): accept or reject it in the workbench first`)
+  if (openScopes.has(scopeDir)) throw new Error(`a change of ${relative(root, scopeDir) || '.'} is under way already`)
+  const left = readRecord(scopeDir)
+  if (left && isHolderAlive(left)) throw new Error(`a change of ${relative(root, scopeDir) || '.'} is under way in another process (${left.pid})`)
+  if (left?.session) throw new Error(`a review of ${relative(root, scopeDir) || '.'} waits for its author (session ${left.session.session}): accept or reject it in the workbench first`)
   if (left) await recoverGitReview(options)
   const dirs = await gitDirsOf(root)
-  const { guard, restore: guarded } = guarding(dirs.gitDir, deck, root, options.onRestore)
-  const trees = new Trees(dirs, deck, root, await readingOf(dirs), options)
+  const guard = gitDirGuard(dirs.gitDir, scopeDir, root, options.onRestore)
+  const trees = new ReviewTrees(dirs, scopeDir, root, await isolatedGitConfig(dirs), options)
 
-  opened.add(deck)
+  openScopes.add(scopeDir)
   let snapshot: string
   try {
     snapshot = await trees.tree()
   } catch (error) {
-    opened.delete(deck)
+    openScopes.delete(scopeDir)
     trees.dispose()
     throw error
   }
-  const record: ReviewRecord = { deck, dirs, snapshot, task: options.task, ...SELF, ...guard ? { guard: guard.saved() } : {}, ...options.session ? { session: { ...options.session, checkpoints: [], steps: [] } } : {} }
-  return reviewOf({ deck, trees, guarded, record, warn: options.warn })
+  const saved = guard.saved()
+  const record: ReviewRecord = { scopeDir, dirs, snapshot, task: options.task, ...THIS_PROCESS, ...saved ? { guard: saved } : {}, ...options.session ? { session: { ...options.session, checkpoints: [], steps: [] } } : {} }
+  return createGitReview({ scopeDir, trees, restoreGitDir: guard.restore, record, warn: options.warn })
 }
 
-export async function resumeGitReview(record: ReviewRecord, options: Omit<GitReviewOptions, 'task' | 'deckDir'>): Promise<GitReview> {
-  const deck = realpathSync(record.deck)
+export async function resumeGitReview(record: ReviewRecord, options: Omit<GitReviewOptions, 'task' | 'scopeDir'>): Promise<GitReview> {
+  const scopeDir = realpathSync(record.scopeDir)
   const root = realpathSync(options.workspaceRoot)
-  if (opened.has(deck) || holderRuns(record)) throw new Error(`a change of ${relative(root, deck) || '.'} is under way already`)
-  const { restore: guarded } = guarding(record.dirs.gitDir, deck, root, options.onRestore, record.guard ? guardGitDir(record.dirs.gitDir, record.guard) : undefined)
-  guarded()
-  const trees = new Trees(record.dirs, deck, root, await readingOf(record.dirs), options)
-  opened.add(deck)
-  return reviewOf({ deck, trees, guarded, record: { ...record, ...SELF }, warn: options.warn })
+  if (openScopes.has(scopeDir) || isHolderAlive(record)) throw new Error(`a change of ${relative(root, scopeDir) || '.'} is under way already`)
+  const { restore: restoreGitDir } = gitDirGuard(record.dirs.gitDir, scopeDir, root, options.onRestore, record.guard)
+  restoreGitDir()
+  const trees = new ReviewTrees(record.dirs, scopeDir, root, await isolatedGitConfig(record.dirs), options)
+  openScopes.add(scopeDir)
+  return createGitReview({ scopeDir, trees, restoreGitDir, record: { ...record, ...THIS_PROCESS }, warn: options.warn })
 }
 
-function reviewOf(open: { deck: string, trees: Trees, guarded: () => void, record: ReviewRecord, warn?: (message: string) => void }): GitReview {
-  const { deck, trees, guarded, record } = open
+function createGitReview(open: { scopeDir: string, trees: ReviewTrees, restoreGitDir: () => void, record: ReviewRecord, warn?: (message: string) => void }): GitReview {
+  const { scopeDir, trees, restoreGitDir, record } = open
   const { snapshot } = record
   const steps: ReviewStep[] = [...record.session?.steps ?? []]
   const checkpoints = [snapshot, ...record.session?.checkpoints ?? []]
@@ -327,22 +334,29 @@ function reviewOf(open: { deck: string, trees: Trees, guarded: () => void, recor
   const settle = () => {
     if (settled) return
     settled = true
-    opened.delete(deck)
-    if (!suspended) removeRecord(deck)
+    openScopes.delete(scopeDir)
+    if (!suspended) removeRecord(scopeDir)
     trees.dispose()
   }
   const live = () => {
     if (settled) throw new Error('this review has ended')
   }
+  const prepareAccept = async (reject: string[]) => {
+    live()
+    restoreGitDir()
+    const changes = await trees.changedPaths(snapshot, await trees.tree())
+    const rejected = new Set(reject.filter(path => changes.includes(path)))
+    await trees.restore(snapshot, [...rejected])
+    return changes.filter(path => !rejected.has(path))
+  }
 
   return {
-    root: deck,
+    root: scopeDir,
     visibility: 'immediate',
     task: record.task,
-    checkpoints: () => checkpoints.slice(1),
     async step(label, tool) {
       live()
-      guarded()
+      restoreGitDir()
       const now = await trees.tree()
       if (steps.length >= MAX_STEPS) {
         checkpoints[checkpoints.length - 1] = now
@@ -360,14 +374,14 @@ function reviewOf(open: { deck: string, trees: Trees, guarded: () => void, recor
     steps: () => steps,
     async diff() {
       live()
-      guarded()
+      restoreGitDir()
       return trees.compare(snapshot, await trees.tree())
     },
     async restoreTo(stepId) {
       live()
       const at = steps.findIndex(step => step.id === stepId)
       if (at < 0) throw new Error(`no step ${stepId} in this review`)
-      guarded()
+      restoreGitDir()
       await trees.reset(checkpoints[at]!)
       steps.splice(at)
       checkpoints.splice(at + 1)
@@ -375,34 +389,32 @@ function reviewOf(open: { deck: string, trees: Trees, guarded: () => void, recor
     },
     async restoreFiles(paths) {
       live()
-      guarded()
-      const changed = new Set((await trees.compare(snapshot, await trees.tree())).map(change => change.path))
+      restoreGitDir()
+      const changed = new Set(await trees.changedPaths(snapshot, await trees.tree()))
       await trees.restore(snapshot, paths.filter(path => changed.has(path)))
     },
-    note(session) {
+    noteSession(session) {
       if (!record.session) return
       record.session = { ...record.session, ...session }
       write()
     },
+    prepareAccept,
+    finish: settle,
     async accept(reject = []) {
-      live()
-      guarded()
-      const changes = await trees.compare(snapshot, await trees.tree())
-      const rejected = new Set(reject.filter(path => changes.some(change => change.path === path)))
-      await trees.restore(snapshot, [...rejected])
+      const files = await prepareAccept(reject)
       settle()
-      return changes.filter(change => !rejected.has(change.path)).map(change => change.path)
+      return files
     },
     async rollback() {
       live()
-      guarded()
+      restoreGitDir()
       await trees.reset(snapshot)
       settle()
     },
     async close() {
       if (settled) return
       try {
-        guarded()
+        restoreGitDir()
         await trees.reset(snapshot)
       } finally {
         settle()

package/src/node/review/record.ts

@@ -0,0 +1,77 @@
+import { createHash } from 'node:crypto'
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import type { Member, ReviewStep } from '@lincyaw/kernel'
+import type { SavedGitDir } from './git-guard.ts'
+import type { GitDirs } from './git-review.ts'
+
+export interface AgentSessionRecord {
+  session: string
+  document: string
+  member: Member
+  turns: { from: number, to: number }
+  opened: string
+  checkpoints: string[]
+  steps: ReviewStep[]
+}
+
+/** A review in progress, kept in the user's state directory so that another process can roll it back or resume it. */
+export interface ReviewRecord {
+  /** The directory the review covers: a document's for a plugin's task, the workspace root for an agent session. */
+  scopeDir: string
+  dirs: GitDirs
+  snapshot: string
+  task: string
+  pid: number
+  started?: string
+  guard?: SavedGitDir
+  session?: AgentSessionRecord
+}
+
+export function recordsDir(env: NodeJS.ProcessEnv = process.env): string {
+  return join(env.XDG_STATE_HOME || join(env.HOME || homedir(), '.local', 'state'), 'presmium', 'reviews')
+}
+
+const recordFile = (scopeDir: string) => join(recordsDir(), `${createHash('sha256').update(scopeDir).digest('hex').slice(0, 24)}.json`)
+
+export function processStartTime(pid: number): string | undefined {
+  try {
+    const stat = readFileSync(`/proc/${pid}/stat`, 'utf8')
+    return stat.slice(stat.lastIndexOf(')') + 2).split(' ')[19]
+  } catch {
+    return undefined
+  }
+}
+
+export const THIS_PROCESS = { pid: process.pid, started: processStartTime(process.pid) }
+
+export function isHolderAlive(record: ReviewRecord): boolean {
+  try {
+    process.kill(record.pid, 0)
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === 'EPERM'
+  }
+  return record.started === undefined || processStartTime(record.pid) === record.started
+}
+
+/** Reads the record of a review of the directory; records of earlier versions name the directory `deck`. */
+export function readRecord(scopeDir: string): ReviewRecord | undefined {
+  try {
+    const { deck, ...record } = JSON.parse(readFileSync(recordFile(scopeDir), 'utf8')) as Partial<ReviewRecord> & { deck?: string }
+    return { ...record, scopeDir: record.scopeDir ?? deck } as ReviewRecord
+  } catch {
+    return undefined
+  }
+}
+
+export function writeRecord(record: ReviewRecord): void {
+  const file = recordFile(record.scopeDir)
+  mkdirSync(recordsDir(), { recursive: true, mode: 0o700 })
+  writeFileSync(`${file}.${process.pid}`, JSON.stringify(record), { mode: 0o600 })
+  renameSync(`${file}.${process.pid}`, file)
+}
+
+export function removeRecord(scopeDir: string): void {
+  rmSync(recordFile(scopeDir), { force: true })
+}

package/src/node/review/routes.ts

@@ -1,72 +1,73 @@
-import { eventStream, isRecord, json, problem } from '@lincyaw/kernel'
+import { isRecord, jsonResponse, problemResponse, sseResponse } from '@lincyaw/kernel'
 import type { Route } from '@lincyaw/kernel'
-import type { Reviews } from './reviews.ts'
+import { catchRequestErrors } from '../errors.ts'
+import type { AgentSessionReviews } from './agent-session-reviews.ts'
 
-async function bodyOf(request: Request): Promise<Record<string, unknown>> {
+async function readBody(request: Request): Promise<Record<string, unknown>> {
   const body: unknown = await request.json().catch(() => undefined)
   return isRecord(body) ? body : {}
 }
 
-const text = (value: unknown, max = 4000) => (typeof value === 'string' && value.trim() ? value.trim().slice(0, max) : undefined)
-const turnOf = (value: unknown) => (typeof value === 'number' && Number.isInteger(value) && value >= 0 ? value : undefined)
-const paths = (value: unknown) => (Array.isArray(value) ? value.filter((path): path is string => typeof path === 'string' && path !== '') : undefined)
+const toText = (value: unknown, max = 4000) => (typeof value === 'string' && value.trim() ? value.trim().slice(0, max) : undefined)
+const toTurn = (value: unknown) => (typeof value === 'number' && Number.isInteger(value) && value >= 0 ? value : undefined)
+const toPaths = (value: unknown) => (Array.isArray(value) ? value.filter((path): path is string => typeof path === 'string' && path !== '') : undefined)
 
-export function reviewRoutes(reviews: Reviews, answer: (work: () => Promise<Response>) => Promise<Response>): Record<string, Route> {
+export function reviewRoutes(reviews: AgentSessionReviews): Record<string, Route> {
   const post = (handle: (body: Record<string, unknown>, document: string) => Promise<Response>): Route => ({
     role: 'editor',
-    handle: (request, ctx) => answer(async () => (request.method === 'POST' ? handle(await bodyOf(request), ctx.document) : problem(405, 'POST'))),
+    handle: (request, ctx) => catchRequestErrors(async () => (request.method === 'POST' ? handle(await readBody(request), ctx.document) : problemResponse(405, 'POST'))),
   })
   return {
     'review': {
       role: 'editor',
-      handle: (request, ctx) => answer(async () => {
-        if (request.method !== 'GET') return problem(405, 'GET')
-        if (request.headers.get('accept')?.includes('text/event-stream')) return eventStream(reviews.follow(ctx.document, request.signal), request.signal)
-        const review = await reviews.view(ctx.document)
-        return json(review ? { review } : {})
+      handle: (request, ctx) => catchRequestErrors(async () => {
+        if (request.method !== 'GET') return problemResponse(405, 'GET')
+        if (request.headers.get('accept')?.includes('text/event-stream')) return sseResponse(reviews.watch(ctx.document, request.signal), request.signal)
+        const review = await reviews.snapshot()
+        return jsonResponse(review ? { review } : {})
       }),
     },
     'review/events': {
       role: 'editor',
-      handle: async (request) => (request.method === 'GET' ? eventStream(reviews.events(request.signal), request.signal) : problem(405, 'GET')),
+      handle: async (request) => (request.method === 'GET' ? sseResponse(reviews.events(request.signal), request.signal) : problemResponse(405, 'GET')),
     },
     'review/open': {
       role: 'editor',
-      handle: (request, ctx) => answer(async () => {
-        if (request.method !== 'POST') return problem(405, 'POST')
-        const body = await bodyOf(request)
-        const session = text(body.session, 200)
-        if (!session) return problem(400, '{ session, turn? }')
-        const turn = turnOf(body.turn)
-        return json({ review: await reviews.open(ctx.document, { session, ...turn !== undefined ? { turn } : {} }, ctx.member) })
+      handle: (request, ctx) => catchRequestErrors(async () => {
+        if (request.method !== 'POST') return problemResponse(405, 'POST')
+        const body = await readBody(request)
+        const session = toText(body.session, 200)
+        if (!session) return problemResponse(400, '{ session, turn? }')
+        const turn = toTurn(body.turn)
+        return jsonResponse({ review: await reviews.open(ctx.document, { session, ...turn !== undefined ? { turn } : {} }, ctx.member) })
       }),
     },
     'review/step': post(async (body, document) => {
-      const session = text(body.session, 200)
-      if (!session) return problem(400, '{ session, turn?, label?, tool?, end? }')
-      const turn = turnOf(body.turn)
+      const session = toText(body.session, 200)
+      if (!session) return problemResponse(400, '{ session, turn?, label?, tool?, end? }')
+      const turn = toTurn(body.turn)
       const review = await reviews.step(document, {
         session,
         ...turn !== undefined ? { turn } : {},
-        ...text(body.label, 300) ? { label: text(body.label, 300)! } : {},
-        ...text(body.tool, 100) ? { tool: text(body.tool, 100)! } : {},
+        ...toText(body.label, 300) ? { label: toText(body.label, 300)! } : {},
+        ...toText(body.tool, 100) ? { tool: toText(body.tool, 100)! } : {},
         ...body.end === true ? { end: true } : {},
       })
-      return json(review ? { review } : {})
+      return jsonResponse(review ? { review } : {})
     }),
     'review/accept': post(async (body, document) => {
-      const reject = paths(body.reject)
-      const message = text(body.message)
-      return json({ ended: await reviews.accept(document, { ...reject ? { reject } : {}, ...message ? { message } : {} }) })
+      const reject = toPaths(body.reject)
+      const message = toText(body.message)
+      return jsonResponse({ ended: await reviews.accept(document, { ...reject ? { reject } : {}, ...message ? { message } : {} }) })
     }),
     'review/reject': post(async (body, document) => {
-      const chosen = paths(body.paths)
-      return json(await reviews.reject(document, chosen ? { paths: chosen } : {}))
+      const chosen = toPaths(body.paths)
+      return jsonResponse(await reviews.reject(document, chosen ? { paths: chosen } : {}))
     }),
     'review/restore': post(async (body, document) => {
-      const step = text(body.step, 100)
-      if (!step) return problem(400, '{ step }')
-      return json({ review: await reviews.restore(document, { step }) })
+      const step = toText(body.step, 100)
+      if (!step) return problemResponse(400, '{ step }')
+      return jsonResponse({ review: await reviews.restore(document, { step }) })
     }),
   }
 }

package/src/node/review/task-reviews.ts

@@ -0,0 +1,50 @@
+import { join } from 'node:path'
+import type { ChangeReviewService, DocumentFiles, Logger } from '@lincyaw/kernel'
+import type { WorkspaceConfig } from '../config.ts'
+import { lockedError } from '../locks.ts'
+import type { DocumentLocks } from '../locks.ts'
+import { GIT_ENGINE, openGitReview, recoverGitReview } from './git-review.ts'
+
+export interface TaskReviewOptions {
+  config: WorkspaceConfig
+  locks: DocumentLocks
+  files?: DocumentFiles
+  log: Logger
+}
+
+/** CHANGE_REVIEW for plugins: the review of a task's changes to one document, which holds that document's lock. */
+export function createTaskReviewService(options: TaskReviewOptions): ChangeReviewService {
+  return {
+    engine: GIT_ENGINE,
+    open: async ({ document, task }) => {
+      const release = options.locks.claim(document, `agent:${task}`)
+      if (!release) throw lockedError(document, options.locks.holder(document)!)
+      try {
+        const review = await openGitReview({
+          workspaceRoot: options.config.root,
+          scopeDir: join(options.config.root, document),
+          task,
+          files: options.files,
+          onRestore: paths => options.log.warn(`task ${task}: the agent changed the git directory, put back: ${paths.join(', ')}`),
+          warn: message => options.log.warn(`task ${task}: ${message}`),
+        })
+        const finish = <Args extends unknown[], T>(work: (...args: Args) => Promise<T>) => async (...args: Args): Promise<T> => {
+          const result = await work(...args)
+          release()
+          return result
+        }
+        return { ...review, accept: finish(review.accept), rollback: finish(review.rollback), close: finish(review.close) }
+      } catch (error) {
+        release()
+        throw error
+      }
+    },
+  }
+}
+
+/** Rolls back the changes of a task whose process ended while its review of the document was open. */
+export async function rollBackLeftTaskReview(options: Pick<TaskReviewOptions, 'config' | 'files' | 'log'>, document: string): Promise<void> {
+  const { config, log } = options
+  const found = await recoverGitReview({ workspaceRoot: config.root, scopeDir: join(config.root, document), files: options.files, onRestore: paths => log.warn(`the git directory as a change task found it, put back: ${paths.join(', ')}`) })
+  if (found) log.warn(`task ${found.task} was waiting for its review when the server ended: rolled back (${found.paths.join(', ') || 'no change'})`)
+}