Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

9.4 KB
Raw Blame
/** Durable associations, scoped to one conversation on its owning machine. Never cleanup authority. */
import { createHash, randomUUID } from 'node:crypto'
import { mkdir, readFile, rename, stat, unlink, writeFile } from 'node:fs/promises'
import { join } from 'node:path'
import { env } from '../config/env.js'
import type { RegisteredSession } from './registry.js'
import type { SessionGitContext } from './sessionGitContext.js'
import { validPullRequestUrl, validWorkPath } from './sessionWorkWire.js'
import type { WorkPullRequest } from './sessionWork.js'
import type { PullRequestResult } from './gitPullRequest.js'

export type WorkBranch = { cwd: string; remote: string | null; branch: string; at: string }
export type RecordedPullRequest = WorkPullRequest & { result?: PullRequestResult; checkedAt?: string; aliases?: string[] }
export type GitHistory = { branches: WorkBranch[]; pullRequests: RecordedPullRequest[]; truncated: boolean }
type Target = Pick<RegisteredSession, 'engine' | 'sessionId' | 'agentId' | 'codexHome' | 'forkedFrom' | 'registeredAt'>
type Entry = { value: GitHistory; loaded: Promise<void>; saving: Promise<void>; readers: number; writes: number }
const MAX = 128
const empty = (): GitHistory => ({ branches: [], pullRequests: [], truncated: false })
function keyFor(target: Target): string {
  return createHash('sha256').update(JSON.stringify([target.engine, target.codexHome ?? '',
    target.sessionId || target.agentId, target.forkedFrom ? target.registeredAt : null])).digest('hex')
}
const label = (v: unknown): v is string => typeof v === 'string' && v.length > 0 && v.length <= 4096 && !/[\x00-\x1f\x7f]/.test(v)
const date = (v: unknown): v is string => typeof v === 'string' && Number.isFinite(Date.parse(v))
/** The server pages in the same order the two clients display. Unknown precedes finished work. */
export function comparePullRequests(a: RecordedPullRequest, b: RecordedPullRequest): number {
  const rank = (p: RecordedPullRequest) => p.result?.status !== 'found' ? 1
    : p.result.state === 'Open' || p.result.state === 'Draft' ? 0 : 2
  const time = (p: RecordedPullRequest) => {
    const pr = p.result?.status === 'found' ? p.result : null
    const value = pr?.state === 'Merged' ? pr.mergedAt : pr?.state === 'Closed' ? pr.closedAt : pr?.updatedAt ?? pr?.createdAt
    return value && date(value) ? Date.parse(value) : Date.parse(p.at)
  }
  return rank(a) - rank(b) || time(b) - time(a)
    || (a.url === b.url ? 0 : a.url < b.url ? -1 : 1)
}
function valid(value: unknown): value is GitHistory {
  if (!value || typeof value !== 'object') return false
  const row = value as GitHistory
  return typeof row.truncated === 'boolean' && Array.isArray(row.branches) && row.branches.length <= MAX
    && row.branches.every(b => validWorkPath(b?.cwd) && label(b.branch) && (b.remote === null || label(b.remote)) && date(b.at))
    && Array.isArray(row.pullRequests) && row.pullRequests.length <= MAX
    && row.pullRequests.every(p => validPullRequestUrl(p?.url) && (p.cwd === null || validWorkPath(p.cwd)) && date(p.at)
      && (p.aliases === undefined || Array.isArray(p.aliases) && p.aliases.length <= 16 && p.aliases.every(validPullRequestUrl))
      && (p.checkedAt === undefined || date(p.checkedAt)) && (p.result === undefined || p.result.status === 'none'
        || p.result.status === 'unavailable' || p.result.status === 'found' && p.result.url === p.url
        && Number.isSafeInteger(p.result.number) && p.result.number > 0 && p.url.endsWith(`/pull/${p.result.number}`)
        && ['Draft', 'Open', 'Merged', 'Closed'].includes(p.result.state)))
}

export class SessionGitHistoryStore {
  private entries = new Map<string, Entry>()
  constructor(private readonly directory: string, private readonly capacity = 512) {}
  private trim(): void {
    for (const [key, entry] of this.entries) {
      if (this.entries.size <= this.capacity) break
      if (!entry.readers && !entry.writes) this.entries.delete(key)
    }
  }
  private entry(target: Target): [string, Entry] {
    const key = keyFor(target)
    let entry = this.entries.get(key)
    if (!entry) {
      entry = { value: empty(), loaded: Promise.resolve(), saving: Promise.resolve(), readers: 0, writes: 0 }
      const current = entry
      entry.loaded = (async () => {
        try {
          const path = join(this.directory, `${key}.json`)
          if ((await stat(path)).size > 512 * 1024) return
          const data: unknown = JSON.parse(await readFile(path, 'utf8'))
          if (valid(data)) current.value = data
        } catch { /* Missing/corrupt history remains unknown, never a reason to stop a session. */ }
      })()
      this.entries.set(key, entry)
    }
    entry.readers++
    this.trim()
    return [key, entry]
  }
  async get(target: Target): Promise<GitHistory> {
    const [, entry] = this.entry(target)
    try {
      await entry.loaded
      const value = structuredClone(entry.value)
      value.pullRequests.sort(comparePullRequests)
      return value
    } finally { entry.readers--; this.trim() }
  }
  async observe(target: Target, context: SessionGitContext): Promise<GitHistory> {
    const [key, entry] = this.entry(target)
    try {
      await entry.loaded
      const before = JSON.stringify(entry.value)
      // This records branches checked out for the session, not authorship or proof of edits.
      // Engine logs are optional enrichment; direct Git observations work for every engine.
      for (const current of context.checkouts ?? (context.current ? [context.current] : [])) {
        const branch = current.branch
        if (!current.root || !branch || current.branchPending || branch.startsWith('Detached ')) continue
        const same = (b: WorkBranch) => b.cwd === (current.root ?? current.cwd) && b.branch === branch && b.remote === current.remote
        const previous = entry.value.branches.find(same)
        // Retrospective tool receipts cannot establish when this branch was checked out.
        const at = previous?.at ?? new Date().toISOString()
        if (!previous || previous.at < at) entry.value.branches = [
          { cwd: current.root ?? current.cwd, branch, remote: current.remote, at }, ...entry.value.branches.filter(b => !same(b)),
        ]
      }
      for (const pr of context.pullRequests) if (!entry.value.pullRequests.some(p => p.url === pr.url || p.aliases?.includes(pr.url))) entry.value.pullRequests.unshift({ ...pr })
      entry.value.truncated ||= context.truncated || entry.value.branches.length > MAX || entry.value.pullRequests.length > MAX
      entry.value.branches = entry.value.branches.sort((a, b) => b.at.localeCompare(a.at)).slice(0, MAX)
      entry.value.pullRequests = entry.value.pullRequests.sort((a, b) => b.at.localeCompare(a.at)).slice(0, MAX)
      if (before !== JSON.stringify(entry.value)) this.save(key, entry)
      const value = structuredClone(entry.value)
      value.pullRequests.sort(comparePullRequests)
      return value
    } finally { entry.readers--; this.trim() }
  }
  async recordPullRequest(target: Target, pr: WorkPullRequest, result: PullRequestResult, checkedAt: string): Promise<void> {
    if (!validPullRequestUrl(pr.url)) return
    const [key, entry] = this.entry(target)
    try {
      await entry.loaded
      let url = result.status === 'found' ? result.url : pr.url
      if (!validPullRequestUrl(url)) return
      const matches = (p: RecordedPullRequest) => p.url === pr.url || p.url === url || !!p.aliases?.includes(pr.url)
      const candidates = entry.value.pullRequests.filter(matches)
      const existing = candidates.sort((a, b) => (b.checkedAt ?? '').localeCompare(a.checkedAt ?? ''))[0]
      // Network failures preserve the last observed state, with its original observation time.
      if (result.status === 'unavailable' && existing) return
      const source = existing?.checkedAt && existing.checkedAt > checkedAt ? existing
        : { ...pr, at: existing?.at ?? pr.at, cwd: existing?.cwd ?? pr.cwd, result, checkedAt }
      if (source === existing) url = existing.url
      const aliases = [...new Set([pr.url, ...candidates.flatMap(p => [p.url, ...(p.aliases ?? [])])])].filter(alias => alias !== url).slice(0, 16)
      const next = { ...source, url,
        ...(aliases.length ? { aliases } : {}),
        ...(source.result?.status === 'found' ? { result: { ...source.result, url } } : {}) }
      entry.value.pullRequests = [next, ...entry.value.pullRequests.filter(p => !matches(p))]
      if (entry.value.pullRequests.length > MAX) { entry.value.pullRequests.length = MAX; entry.value.truncated = true }
      this.save(key, entry)
    } finally { entry.readers--; this.trim() }
  }
  private save(key: string, entry: Entry): void {
    const bytes = JSON.stringify(entry.value)
    entry.writes++
    entry.saving = entry.saving.then(async () => {
      const temporary = join(this.directory, `${key}.${randomUUID()}.tmp`)
      try {
        await mkdir(this.directory, { recursive: true, mode: 0o700 })
        await writeFile(temporary, bytes, { mode: 0o600, flag: 'wx' })
        await rename(temporary, join(this.directory, `${key}.json`))
      } finally { await unlink(temporary).catch(() => {}) }
    }).catch(() => { /* Display keeps the in-memory observations if disk is temporarily unavailable. */ })
      .finally(() => { entry.writes--; this.trim() })
  }
  async settled(): Promise<void> { await Promise.all([...this.entries.values()].map(e => e.saving)) }
}
export const sessionGitHistory = new SessionGitHistoryStore(join(env.ADAPTER_DATA_DIR, 'session-git-history'))