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.

11.7 KB
Raw Blame
/** Eager native transcript authority shared by binding, Stop and resume preflight. */
import { homedir } from 'node:os'
import { basename, dirname, isAbsolute, join, relative } from 'node:path'
import { env } from '../config/env.js'
import { engineHomeSnapshot, sessionRoots, type EngineHomeSnapshot } from '../lib/engineHomes.js'
import { controlIdentity as claudeIdentity } from './claude/sessionStore.js'
import { PI_CONTROL_IDENTITY } from './pi/contract.js'
import { cursorDataDir } from './cursor/contract.js'
import { NativeFiles } from './kit/nativeFiles.js'
import type { ControlIdentityRule } from './kit/controlIdentity.js'
import { nativeFileKey } from './kit/nativePaths.js'
import { nativeUnavailable } from './kit/nativeEvidence.js'
import { sessionStoreOf } from './sessionStoreContracts.js'
import type { AgentEngine } from './types.js'

/** Null means the engine stores conversations in a database, or is only a shell. */
export const transcriptRoot: Readonly<Record<AgentEngine, (() => string) | 'store' | null>> = {
  amp: () => env.AMP_SESSIONS_DIR,
  muse: () => join(env.MUSE_HOME, 'sessions'),
  codex: 'store',
  grok: () => join(env.GROK_HOME, 'sessions'),
  agy: () => join(env.AGY_HOME, 'brain'),
  copilot: () => join(env.COPILOT_HOME, 'session-state'),
  cursor: () => join(cursorDataDir(), 'projects'),
  pi: () => join(env.PI_HOME, 'agent', 'sessions'),
  omp: () => join(homedir(), '.omp', 'agent', 'sessions'),
  commandcode: () => join(env.COMMANDCODE_HOME, 'projects'),
  claude: 'store',
  opencode: null, kilo: null, hermes: null, devin: null, terminal: null,
}
export const engineKeepsTranscriptFile = (engine: AgentEngine): boolean => transcriptRoot[engine] !== null
export const needsHomeCatalog = (engine: AgentEngine, profile?: string | null): boolean =>
  transcriptRoot[engine] === 'store' && !(sessionStoreOf(engine)?.sessions.profile && profile)

/** One explicit load batch can reuse root ancestry, including absent roots, then fence it
 * once before publishing its dependent rows. This proof never survives the operation. */
export function transcriptRootEvidence(engine: AgentEngine, profile?: string, snapshot?: EngineHomeSnapshot) {
  const files = new NativeFiles(), root = transcriptRoot[engine]
  const ownSnapshot = !snapshot && needsHomeCatalog(engine, profile) ? engineHomeSnapshot() : undefined
  const roots = root === 'store' ? sessionRoots(engine, profile, snapshot ?? ownSnapshot) : root ? [root()] : []
  const directories = roots.flatMap(path => {
    const location = files.locate(path, true)
    if (!location) return []
    if (!location.info.isDirectory()) return nativeUnavailable('a transcript root is not a directory')
    return [{ original: path, ...location }]
  })
  return { directories, verify(): void { files.verify(); ownSnapshot?.verify() } }
}

/** A deterministic engine locator can precede its directories. Retain the first
 * missing component and its owned ancestor; a dangling alias is not absence. */
function futureDirectory(files: NativeFiles, path: string): { path: string; present: boolean } {
  if (path.split('/').includes('..')) return nativeUnavailable('an unwritten transcript has an unresolved parent step')
  const suffix: string[] = []
  for (let at = path;; at = dirname(at)) {
    files.budget.step()
    const location = files.locate(at, true)
    if (location) {
      if (!location.info.isDirectory()) return nativeUnavailable('the announced transcript ancestor is not a directory')
      if (typeof process.getuid === 'function' && location.info.uid !== BigInt(process.getuid())) {
        return nativeUnavailable('the announced transcript ancestor has an unconfirmed owner')
      }
      if (suffix.length && !files.paths.absentLeaf(join(location.path, suffix[0]))) {
        return nativeUnavailable('the announced transcript ancestor is not a proven absent leaf')
      }
      return { path: join(location.path, ...suffix), present: !suffix.length }
    }
    if (suffix.length >= 64 || at === dirname(at)) return nativeUnavailable('the unwritten transcript ancestor limit was reached')
    suffix.unshift(basename(at))
  }
}

/** A caller can supply its explicit synchronous batch proofs and verify them before publication.
 * Only core-derived locators may name directories that the engine has not written yet. */
export function transcriptEvidence(engine: AgentEngine, path: string, profile?: string,
  allowMissing: boolean | 'derived' = false, snapshot?: EngineHomeSnapshot, roots?: ReturnType<typeof transcriptRootEvidence>,
) {
  const files = new NativeFiles(), root = transcriptRoot[engine]
  const scope = roots ?? transcriptRootEvidence(engine, profile, snapshot)
  const location = root ? files.file(path, true) : null
  if (!location && allowMissing === 'derived') {
    if (typeof root !== 'function') return nativeUnavailable('the unwritten transcript has no deterministic root')
    const parent = futureDirectory(files, dirname(path)), declared = futureDirectory(files, root())
    const actual = join(parent.path, basename(path))
    if (parent.present && !files.paths.absentLeaf(actual)) {
      return nativeUnavailable('the announced transcript is not a proven absent leaf')
    }
    const member = relative(declared.path, actual)
    return { valid: !!member && member !== '..' && !member.startsWith('../') && !isAbsolute(member), files,
      matchingRoots: scope.directories,
      verify(selected = path): void { files.verify(selected); if (!roots) scope.verify() } }
  }
  const parent = !location && allowMissing ? files.locate(dirname(path), true) : null
  if (parent && !parent.info.isDirectory()) return nativeUnavailable('the announced transcript parent is not a directory')
  if (parent && typeof process.getuid === 'function' && parent.info.uid !== BigInt(process.getuid())) {
    return nativeUnavailable('the announced transcript parent has an unconfirmed owner')
  }
  if (parent && !files.paths.absentLeaf(join(parent.path, basename(path)))) {
    return nativeUnavailable('the announced transcript is not a proven absent leaf')
  }
  const actual = location?.path ?? (parent ? join(parent.path, basename(path)) : null)
  const matchingRoots = actual ? scope.directories.filter(directory => files.paths.within(actual, [directory.info])) : []
  const valid = !!actual && matchingRoots.length > 0 && (engine !== 'cursor'
    || (!!basename(actual).replace(/\.jsonl$/, '') && basename(dirname(actual)) === basename(actual).replace(/\.jsonl$/, '')
      && basename(dirname(dirname(actual))) === 'agent-transcripts'))
  return {
    valid, files, matchingRoots,
    verify(selected = path): void { files.verify(selected); if (!roots) scope.verify() },
  }
}

/** Parent repair requires the complete declared pool, including unreadable or excluded candidates. */
function parentTranscript(files: NativeFiles, engine: AgentEngine, id: string,
  roots: ReturnType<typeof transcriptRootEvidence>['directories'],
): string | null {
  const store = sessionStoreOf(engine), rule = store?.byId
  if (rule?.layout !== 'walk' || !store?.first || !rule.id.test(id)) return null
  const visited = new Set<string>(), selected = new Map<string, string>()
  let candidates = 0
  const walk = (path: string, depth: number): void => {
    if (depth > 32) return nativeUnavailable('the binding transcript depth limit was reached')
    const location = files.locate(path, true)
    if (!location) return
    if (!location.info.isDirectory()) return nativeUnavailable('a binding transcript directory is not a directory')
    if (!roots.some(root => nativeFileKey(root.info) === nativeFileKey(location.info))
      && !files.paths.within(location.path, roots.map(root => root.info))) {
      return nativeUnavailable('a binding parent directory escaped its transcript roots')
    }
    const key = nativeFileKey(location.info)
    if (visited.has(key)) return
    visited.add(key)
    for (const name of files.entries(path)) {
      const candidate = join(path, name)
      if (name.endsWith(rule.suffix) && name.includes(id)) {
        if (++candidates > 64) return nativeUnavailable('the binding transcript candidate limit was reached')
        const file = files.file(candidate)!
        if (!files.paths.within(file.path, roots.map(root => root.info))) {
          return nativeUnavailable('a binding parent candidate escaped its transcript roots')
        }
        const meta = files.header(candidate, store.first!)
        if (meta.id === id && !meta.isSubagent) selected.set(nativeFileKey(file.info), selected.get(nativeFileKey(file.info)) ?? candidate)
      } else if (!name.includes('.')) {
        const child = files.locate(candidate)!
        if (child.info.isDirectory()) walk(candidate, depth + 1)
      }
    }
  }
  for (const root of roots) walk(root.original, 0)
  if (selected.size > 1) return nativeUnavailable('more than one transcript matches the bound parent conversation')
  return selected.values().next().value ?? null
}

/** Validate a saved binding and repair a conclusively identified child overwrite before committing. */
export function savedTranscriptEvidence(engine: AgentEngine, sessionId: string, path: string,
  profile?: string, snapshot?: EngineHomeSnapshot, roots?: ReturnType<typeof transcriptRootEvidence>,
) {
  const proof = transcriptEvidence(engine, path, profile, false, snapshot, roots)
  let selected: string | null = proof.valid ? path : null
  const store = sessionStoreOf(engine)
  if (selected && store?.first) {
    const meta = proof.files.header(selected, store.first)
    if (meta.isSubagent) {
      selected = store.repairsOverwrittenParent && meta.parentThreadId === sessionId
        ? parentTranscript(proof.files, engine, sessionId, proof.matchingRoots) : null
    } else if (meta.id !== sessionId) {
      return nativeUnavailable('the saved transcript names a different conversation')
    }
  }
  const fileKey = selected ? nativeFileKey(proof.files.file(selected)!.info) : null
  return { path: selected, fileKey, verify: () => proof.verify(selected ?? path) }
}

/** Keep immutable identity across awaits, not a lookup's expiring work budget.
 * Each control boundary earns fresh header, root and catalog evidence before acting. */
export function controlTranscriptEvidence(engine: AgentEngine, sessionId: string, path: string, profile?: string, cwd?: string | null) {
  const read = () => {
    const proof = savedTranscriptEvidence(engine, sessionId, path, profile)
    if (!proof.path) return nativeUnavailable('the saved conversation file is unavailable')
    const rule: ControlIdentityRule | undefined = engine === 'claude' ? claudeIdentity : engine === 'pi' ? PI_CONTROL_IDENTITY : undefined
    if (rule) {
      const files = new NativeFiles()
      const head = files.opening(proof.path, rule)
      if (head.fileKey !== proof.fileKey) return nativeUnavailable('the conversation opening belongs to a replaced file')
      if (head.id !== sessionId || head.delegated) return nativeUnavailable('the saved transcript names a different or delegated conversation')
      if (rule.canonicalWorkspace) {
        if (!cwd) return nativeUnavailable('the saved conversation workspace is unavailable')
        const expected = files.locate(cwd), actual = files.locate(head.cwd)
        if (!expected?.info.isDirectory() || !actual?.info.isDirectory()
          || nativeFileKey(expected.info) !== nativeFileKey(actual.info)) return nativeUnavailable('the saved conversation workspace does not match')
      }
      files.verify(proof.path)
    }
    proof.verify()
    return { path: proof.path, fileKey: proof.fileKey }
  }
  const before = read()
  return { path: before.path, verify(openedFileKey?: string): void {
    const after = read()
    if (after.path !== before.path || after.fileKey !== before.fileKey
      || openedFileKey !== undefined && openedFileKey !== before.fileKey) {
      nativeUnavailable('the saved conversation file was replaced during the operation')
    }
  } }
}