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.

15.3 KB
Raw Blame
/**
 * What every provider reads with: bounded file reads, a scan's memo, and the machine's processes.
 * Each system call here is small, read-only, and has a timeout.
 */

import { execFile } from 'node:child_process'
import type { Dirent } from 'node:fs'
import { open, readdir, readFile, readlink, realpath, stat } from 'node:fs/promises'
import { homedir } from 'node:os'
import { dirname, isAbsolute, join, relative, resolve } from 'node:path'

import { isHarnessSession, paneOwnerFormat } from '../../harnessSessionLabel.js'
import { processRows } from '../../processTable.js'
import { tmuxFeatures } from '../../tmuxVersion.js'
import { type ProcessView, type RunningProcess, type ScanContext, UNSETTLED } from './types.js'
import { externalReadFailed } from '../evidence.js'

/** A folder's entries, or none when it is missing or unreadable. */
export async function entries(dir: string): Promise<Dirent[]> {
  return readdir(dir, { withFileTypes: true }).catch(error => { externalReadFailed(error, 'folder'); return [] })
}

/** Up to [bytes] from the start of a file; '' when it cannot be read. */
export async function readHead(path: string, bytes: number): Promise<string> {
  const handle = await open(path, 'r').catch(error => { externalReadFailed(error, 'file'); return null })
  if (!handle) return ''
  try {
    const buffer = Buffer.alloc(bytes)
    const { bytesRead } = await handle.read(buffer, 0, bytes, 0)
    return buffer.subarray(0, bytesRead).toString('utf8')
  } finally {
    await handle.close()
  }
}

/** Up to [bytes] from the end of a file; '' when it cannot be read. */
export async function readTail(path: string, bytes: number): Promise<string> {
  const handle = await open(path, 'r').catch(error => { externalReadFailed(error, 'file'); return null })
  if (!handle) return ''
  try {
    const { size } = await handle.stat()
    const length = Math.min(size, bytes)
    const buffer = Buffer.alloc(length)
    await handle.read(buffer, 0, length, size - length)
    return buffer.toString('utf8')
  } finally {
    await handle.close()
  }
}

/** A file's first line, whole, when it fits in [bytes]; null otherwise. */
export async function firstLine(path: string, bytes: number): Promise<string | null> {
  const text = await readHead(path, bytes)
  const newline = text.indexOf('\n')
  return newline < 0 ? null : text.slice(0, newline)
}

/** A file's text, or '' when it is missing or unreadable. */
export async function readText(path: string): Promise<string> {
  return readFile(path, 'utf8').catch(error => { externalReadFailed(error, 'file'); return '' })
}

/** A JSON file's value, or null when it is missing, unreadable or being written. */
export async function readJson(path: string): Promise<unknown> {
  try {
    const value: unknown = JSON.parse(await readFile(path, 'utf8'))
    if (value === null) externalReadFailed(new Error('null document'), 'record')
    return value
  } catch (error) {
    externalReadFailed(error, 'record')
    return null
  }
}

/** One JSON line's value, or null. */
export function parseLine(line: string): unknown {
  try {
    return JSON.parse(line)
  } catch {
    return null
  }
}

/** A file's size and change time, the fingerprint a memo is keyed on; null when it is not a file. */
export async function fileStamp(path: string): Promise<{ stamp: string; mtime: number } | null> {
  const info = await stat(path).catch(error => { externalReadFailed(error, 'file metadata'); return null })
  if (!info?.isFile()) return null
  return { stamp: `${info.size}:${info.mtimeMs}`, mtime: Math.floor(info.mtimeMs) }
}

/** An object's field when it is a non-empty string, else ''. */
export function text(value: unknown): string {
  return typeof value === 'string' ? value : ''
}

/** A record, when [value] is one. */
export function record(value: unknown): Record<string, unknown> | null {
  return value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : null
}

export const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i

/** An absolute folder, as a session records it. */
export function absoluteFolder(value: unknown): string | null {
  return typeof value === 'string' && value.startsWith('/') ? value : null
}

/** Epoch ms from seconds, milliseconds, microseconds or an ISO string; null for anything else. */
export function epochMs(value: unknown): number | null {
  if (typeof value === 'string') {
    if (/^\d+(?:\.\d+)?$/.test(value)) return epochMs(Number(value))
    const parsed = Date.parse(value)
    return Number.isFinite(parsed) ? parsed : null
  }
  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) return null
  if (value < 1e11) return Math.round(value * 1000)
  if (value < 1e14) return Math.round(value)
  if (value < 1e17) return Math.round(value / 1000)
  return Math.round(value / 1e6)
}

/** Whether [path] is [dir] or inside it. */
export function within(dir: string, path: string): boolean {
  const rel = relative(resolve(dir), resolve(path))
  return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel))
}

export interface ScanMemo {
  context(): ScanContext
  /** Forgets whatever this scan did not ask for again. */
  prune(): void
}

/**
 * A scan's memory between scans: each key's last value, kept while its fingerprint holds. A first
 * scan reads everything once; later ones read only what changed.
 */
export function scanMemo(options: { excluded: readonly string[]; paceEvery?: number } = { excluded: [] }): ScanMemo {
  const kept = new Map<string, { fingerprint: string; value: unknown; settled?: boolean }>()
  let touched = new Set<string>()
  let reads = 0
  const every = options.paceEvery ?? 64
  return {
    context: () => ({
      memo: async <T>(key: string, fingerprint: string, read: () => Promise<T>): Promise<T> => {
        touched.add(key)
        const found = kept.get(key)
        if (found && found.fingerprint === fingerprint) return found.value as T
        const value = await read()
        kept.set(key, { fingerprint, value })
        return value
      },
      head: async <T>(key: string, stamp: string, read: () => Promise<T | null | typeof UNSETTLED>): Promise<T | null> => {
        touched.add(key)
        const found = kept.get(key)
        if (found && (found.settled || found.fingerprint === stamp)) return found.value as T | null
        const value = await read()
        const settled = value !== UNSETTLED
        kept.set(key, { fingerprint: stamp, value: settled ? value : null, settled })
        return settled ? value : null
      },
      excluded: (cwd) => options.excluded.some((dir) => within(dir, cwd)),
      pace: async () => {
        if (++reads % every === 0) await new Promise<void>((resolve) => setImmediate(resolve))
      },
    }),
    prune: () => {
      for (const key of [...kept.keys()]) if (!touched.has(key)) kept.delete(key)
      touched = new Set()
    },
  }
}

export function processAlive(pid: number): boolean {
  try { process.kill(pid, 0); return true } catch (error) { return (error as NodeJS.ErrnoException).code === 'EPERM' }
}

type Run = (command: string, args: readonly string[], timeout: number) => Promise<string | null>

/** A command's output; what it printed even when it exits non-zero (lsof does, for a gone pid). */
export const run: Run = (command, args, timeout) => new Promise((resolve) => {
  execFile(command, [...args], { timeout, maxBuffer: 16 * 1024 * 1024 }, (error, stdout, stderr) => {
    // lsof's documented empty match is exit 1 with no diagnostic. Timeouts, truncation and errors
    // remain unknown even if they produced a partial list; display callers retain their old answer.
    if (error && !(command === 'lsof' && Number(error.code) === 1 && !stderr)) externalReadFailed(error, 'process files')
    resolve(error && !stdout ? null : String(stdout))
  })
})

/** `lsof -F pn` output as files by pid. */
export function parseLsof(stdout: string): Map<number, string[]> {
  const files = new Map<number, string[]>()
  let pid = 0
  for (const line of stdout.split('\n')) {
    if (line.startsWith('p')) {
      pid = Number(line.slice(1)) || 0
      if (pid && !files.has(pid)) files.set(pid, [])
    } else if (pid && line.startsWith('n')) {
      files.get(pid)!.push(line.slice(1))
    }
  }
  return files
}

/** `ps -o pid=,tty=` output as each process's terminal (`/dev/ttys003`), or null for none. */
export function parseTtys(stdout: string): Map<number, string | null> {
  const ttys = new Map<number, string | null>()
  for (const line of stdout.split('\n')) {
    const [pid, tty] = line.trim().split(/\s+/)
    if (!pid) continue
    ttys.set(Number(pid), tty && !tty.startsWith('?') ? `/dev/${tty}` : null)
  }
  return ttys
}

/** The machine's processes, as the daemon's own process scan reads them (it repairs rewritten rows);
 *  none when `ps` could not be read. */
export async function listProcesses(read: typeof processRows = processRows): Promise<RunningProcess[]> {
  const rows = await read()
  if (!rows) externalReadFailed(new Error('process table unavailable'), 'process table')
  return (rows ?? []).map((row) => {
    const started = Date.parse(row.startMarker)
    return { pid: row.pid, ppid: row.parentPid, executable: row.executable, args: row.args,
      ...(Number.isFinite(started) ? { started } : {}),
      ...(row.startTicks !== undefined ? { generation: `linux:${row.startTicks}` }
        : Number.isFinite(started) ? { generation: `ps:${started}` } : {}) }
  })
}

/**
 * Each of [pids]' working folder. Linux says it in /proc; macOS only through lsof, asked once for every pid
 * (`-a -d cwd`: that one descriptor) under the same timeout and output bound as its open files. A pid whose
 * folder cannot be read (gone, another user's) is left out: unknown, which admission reads as "may hold any".
 */
export async function processCwds(
  pids: readonly number[],
  exec: Run = run,
  os: NodeJS.Platform = process.platform,
  link: (path: string) => Promise<string> = readlink,
): Promise<Map<number, string>> {
  const cwds = new Map<number, string>()
  if (!pids.length) return cwds
  if (os === 'linux') {
    await Promise.all(pids.map(async (pid) => {
      const cwd = await link(`/proc/${pid}/cwd`).catch(() => null)
      if (cwd) cwds.set(pid, cwd)
    }))
    return cwds
  }
  for (const [pid, files] of parseLsof(await exec('lsof', ['-n', '-P', '-a', '-d', 'cwd', '-Fpn', '-p', pids.join(',')], 3_000) ?? '')) {
    if (files[0]) cwds.set(pid, files[0])
  }
  return cwds
}

/**
 * A folder as one key whichever way it was spelled: a trailing slash, `..`, or a link (macOS's /tmp is
 * /private/tmp, and lsof reports the resolved one). A folder that cannot be resolved keeps its spelling.
 */
export async function folderKey(path: string): Promise<string> {
  const absolute = resolve(path)
  return realpath(absolute).catch(() => absolute)
}

/**
 * The git store a folder's repository shares with all its worktrees, read from disk without running git: the
 * first `.git` above it, a folder (the store itself) or a worktree's `gitdir:` file, whose
 * `<store>/worktrees/<name>` names the store two levels up. Null outside a repository. The walk stops at the
 * folder holding the homes, so a stray `.git` there cannot make every project one.
 */
export async function gitCommonDir(folder: string, stop: string = dirname(homedir())): Promise<string | null> {
  const ceiling = await folderKey(stop)
  let dir = await folderKey(folder)
  for (let depth = 0; depth < 128 && dir !== ceiling; depth++) {
    const dotgit = join(dir, '.git')
    const found = await stat(dotgit).catch(() => null)
    if (found?.isDirectory()) return folderKey(dotgit)
    if (found?.isFile()) {
      const named = /^gitdir:\s*(.+?)\s*$/m.exec(await readFile(dotgit, 'utf8').catch(() => ''))?.[1]
      if (!named) return null
      const gitdir = resolve(dir, named)
      return folderKey(/[\\/]worktrees[\\/][^\\/]+[\\/]?$/.test(gitdir) ? dirname(dirname(gitdir)) : gitdir)
    }
    const parent = dirname(dir)
    if (parent === dir) break
    dir = parent
  }
  return null
}

/**
 * Whether a process working in [a] might list a conversation of [b] in its own picker: Claude Code's `/resume`
 * lists its own folder's, and newer versions its repository's worktrees too, so the same folder or one git
 * store. Never a folder merely above or below: a TUI left open in the home folder is common, and counting
 * every folder below it would hold every adoption on the machine again, the bug this check replaced.
 */
export async function sameProject(a: string, b: string, stop?: string): Promise<boolean> {
  const [x, y] = await Promise.all([folderKey(a), folderKey(b)])
  if (x === y) return true
  const [left, right] = await Promise.all([gitCommonDir(x, stop), gitCommonDir(y, stop)])
  return left !== null && left === right
}

/** The machine's processes, looked at once per view: the list is read on first use and kept. */
export function processView(
  exec: Run = run,
  alive: (pid: number) => boolean = processAlive,
  list: () => Promise<RunningProcess[]> = listProcesses,
  cwds: (pids: readonly number[]) => Promise<Map<number, string>> = (pids) => processCwds(pids, exec),
): ProcessView {
  let listed: Promise<RunningProcess[]> | null = null
  return {
    list: () => (listed ??= list()),
    openFiles: async (pids) => pids.length
      ? parseLsof(await exec('lsof', ['-n', '-P', '-Fpn', '-a', '-p', pids.join(',')], 3_000) ?? '')
      : new Map(),
    openFilesOf: async (commands) => commands.length
      ? parseLsof(await exec('lsof', ['-n', '-P', '-Fpn', ...commands.flatMap((name) => ['-c', name])], 3_000) ?? '')
      : new Map(),
    cwds,
    alive,
  }
}

/** Each of [pids]' terminal, or null for a process with none (an app, a server). */
export async function processTtys(pids: readonly number[], exec: Run = run): Promise<Map<number, string | null>> {
  if (!pids.length) return new Map()
  return parseTtys(await exec('ps', ['-o', 'pid=,tty=', '-p', pids.join(',')], 3_000) ?? '')
}

type Ask = (command: string, args: readonly string[], timeout: number) => Promise<{ stdout: string; failed: boolean; stderr: string }>

const ask: Ask = (command, args, timeout) => new Promise((resolve) => {
  execFile(command, [...args], { timeout }, (error, stdout, stderr) => {
    resolve({ stdout: String(stdout), failed: !!error, stderr: String(stderr) })
  })
})

/**
 * The terminals of Harness's own panes: the ones a daemon tagged (`HARNESS_OWNER_OPTION`), in whatever
 * session the person has moved them into, and any in a tmux session named `harness-…`. A process there
 * is one of Harness's agents — any daemon's — whatever its session looks like while the daemon is still
 * binding it, and a take-over never stops it. None when no tmux server is running; null when tmux could
 * not be asked (a timeout): then nobody can say.
 */
export async function harnessTtys(
  exec: Ask = ask,
  // Before tmux 3.0 the tag is not a pane option (`paneOwnerFormat`).
  paneOptions?: boolean,
): Promise<Set<string> | null> {
  const format = `#{pane_tty}\t#{session_name}\t${paneOwnerFormat(paneOptions ?? (await tmuxFeatures()).paneOptions)}`
  const { stdout, failed, stderr } = await exec('tmux', ['list-panes', '-a', '-F', format], 3_000)
  if (failed && !/no server running|error connecting to .*\(No such file or directory\)/i.test(stderr)) return null
  const ttys = new Set<string>()
  for (const line of stdout.split('\n')) {
    const [tty, session, tag] = line.split('\t')
    if (tty && (tag || (session && isHarnessSession(session)))) ttys.add(tty)
  }
  return ttys
}