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.

7.9 KB
Raw Blame
/**
 * The name an engine gives its own session — which is what a harness is called until the person
 * names it (registry.ts, projectDisplayName). "Unitree Go2 squats and wave" says what the agent is
 * doing; harness-43 says only that it was the forty-third.
 *
 *  - Claude Code titles its terminal after the conversation, once there is one ("✳ Harness Store
 *    launch video"; the leading glyph is its activity marker and is cleaned off by titleDisplayName).
 *  - OpenCode titles it "OC | <session title>"; the prefix is dropped.
 *  - Codex keeps a thread name per session in `$CODEX_HOME/session_index.jsonl`, updated when it
 *    names a thread and on `/rename`. Its terminal title carries the same name between status words
 *    and the folder — "[ ! ] Action Required | Build 555 LED flasher | harness-36" — so that is the
 *    fallback, with the status words and the folder taken out.
 *
 * What is left after cleaning can still be no name at all: an engine's own name before the first
 * prompt ("Claude Code"), or just the folder. Those fall through to the numbered default.
 */
import { closeSync, openSync, readFileSync, readSync, statSync } from 'node:fs'
import { basename, join } from 'node:path'
import { ENGINES } from '../engines/types.js'
import { launchCodexHome, sessionCodexHome } from './engineHomes.js'

/** An engine's own name, which is what a session is titled before it is about anything. */
const ENGINE_TITLES: ReadonlySet<string> = new Set([
  ...ENGINES,
  'claude code', 'openai codex', 'codex cli', 'cursor agent', 'gemini', 'gemini cli', 'hermes agent',
  'command code', 'devin', 'amp', 'kilo code', 'grok', 'github copilot', 'copilot cli', 'antigravity',
])

/** OpenCode (and Kilo, its fork) put their short name in front: "OC | Greeting". */
const OPENCODE_PREFIX = /^(?:oc|opencode|kilo)\s+\|\s+/i

/** Codex's status text, including the ellipsis and Braille spinner shown while naming a thread.
 *  Accepting `renaming... ⠹` as a title permanently names the worktree branch `renaming`. */
const CODEX_STATUS = /^(?:\[\s*[!.]\s*\]\s*)?(?:starting|ready|working|waiting|thinking|renaming|action required)(?:\s*(?:\.{3}|…))?(?:\s*[\u2800-\u28ff])?$/i

/**
 * A title that names the session, or null when it only names the engine, the folder or the default.
 * `title` is already cleaned of leading glyphs (titleDisplayName).
 */
export function namingTitle(
  title: string | null | undefined,
  context: { engine?: string | null; cwd?: string | null; defaultName?: string | null },
): string | null {
  if (!title) return null
  const cleaned = context.engine === 'codex'
    ? cleanCodexTitle(title, context.cwd)
    : title.trim().replace(OPENCODE_PREFIX, '').trim()
  if (!cleaned) return null
  const lower = cleaned.toLowerCase()
  if (ENGINE_TITLES.has(lower)) return null
  if (context.cwd && lower === basename(context.cwd).toLowerCase()) return null
  if (context.defaultName && lower === context.defaultName.toLowerCase()) return null
  return cleaned
}

/** Codex's terminal title without its status words and its folder item. */
export function cleanCodexTitle(title: string, cwd?: string | null): string {
  const folder = cwd ? basename(cwd).toLowerCase() : null
  return title
    .split(' | ')
    .map((part) => part.trim())
    .filter((part) => part && !CODEX_STATUS.test(part) && part.toLowerCase() !== folder && part.toLowerCase() !== 'codex')
    .join(' | ')
}

interface IndexCache { path: string; mtimeMs: number; size: number; names: Map<string, string> }
let codexIndexCache: IndexCache | null = null

/**
 * Codex's own name for a thread, from `session_index.jsonl` under the agent's CODEX_HOME. The file is
 * small (one line per named thread, later lines win) and re-read only when it changes; a missing or
 * unreadable file is simply no name.
 */
export function codexThreadName(sessionId: string | null | undefined, codexHome?: string | null): string | null {
  if (!sessionId) return null
  const home = launchCodexHome(codexHome)
  const path = join(home, 'session_index.jsonl')
  let stat
  try { stat = statSync(path) } catch { return null }
  if (!codexIndexCache || codexIndexCache.path !== path || codexIndexCache.mtimeMs !== stat.mtimeMs || codexIndexCache.size !== stat.size) {
    const names = new Map<string, string>()
    try {
      for (const line of readFileSync(path, 'utf8').split('\n')) {
        if (!line.trim()) continue
        try {
          const row = JSON.parse(line) as { id?: unknown; thread_name?: unknown }
          if (typeof row.id === 'string' && typeof row.thread_name === 'string' && row.thread_name.trim()) {
            names.set(row.id, row.thread_name.trim())
          }
        } catch { /* one torn line (Codex mid-append) costs that line, not the index */ }
      }
    } catch { return null }
    codexIndexCache = { path, mtimeMs: stat.mtimeMs, size: stat.size, names }
  }
  return codexIndexCache.names.get(sessionId) ?? null
}

/** Test seam. */
export function resetCodexThreadNames(): void { codexIndexCache = null }

/** omp's terminal title: "π ⠴ 󰣳 Fix login: …": its name, a status mark (a Braille spinner frame
 *  while working, ">" when idle, or another single mark), then an optional Nerd Font icon. */
const OMP_TITLE_PREFIX = /^π\s+(?:[\u2800-\u28ff]|[^\s\p{L}\p{N}])?\s*/u
/** A leading Nerd Font / private-use icon, as omp puts on its own session titles. */
const PRIVATE_USE_ICON = /^[\u{E000}-\u{F8FF}\u{F0000}-\u{FFFFD}\u{100000}-\u{10FFFD}]+\s*/u

/**
 * An omp title with the parts that churn stripped: the "π" name, the status/spinner mark (so a
 * working pane does not retitle on every spinner frame) and the topic icon. A title that is not
 * omp's is only trimmed of a leading icon.
 */
export function cleanOmpTitle(title: string | null | undefined): string | null {
  if (!title) return null
  const cleaned = title.trim().replace(OMP_TITLE_PREFIX, '').replace(PRIVATE_USE_ICON, '').trim()
  return cleaned || null
}

/** How much of the head of an omp session file is read for its `{"type":"title"}` line. */
const OMP_TITLE_HEAD_BYTES = 16 * 1024

/**
 * omp's own session title: the `{"type":"title"}` line it keeps (padded, rewritten in place) at the
 * head of its session .jsonl. Null for a missing file or no title line; the last title line in the
 * head wins.
 */
export function ompSessionTitle(transcriptPath: string | null | undefined): string | null {
  if (!transcriptPath) return null
  let head = ''
  try {
    const fd = openSync(transcriptPath, 'r')
    try {
      const buffer = Buffer.alloc(OMP_TITLE_HEAD_BYTES)
      const read = readSync(fd, buffer, 0, buffer.length, 0)
      head = buffer.subarray(0, read).toString('utf8')
    } finally { closeSync(fd) }
  } catch { return null }
  let title: string | null = null
  for (const line of head.split('\n')) {
    if (!line.includes('"type":"title"')) continue
    try {
      const row = JSON.parse(line) as { type?: unknown; title?: unknown }
      if (row.type === 'title' && typeof row.title === 'string') title = cleanOmpTitle(row.title) ?? title
    } catch { /* a line cut by the head limit, or mid-rewrite */ }
  }
  return title
}

/**
 * The title the terminal sweep records for a session: Codex's thread name when it has one, else the
 * terminal title as the engine wrote it. Cleaning for display happens in namingTitle, so a title
 * recorded before this existed is read the same way.
 */
export function engineSessionTitle(
  session: { engine?: string | null; sessionId?: string | null; codexHome?: string | null; transcriptPath?: string | null },
  terminalTitle: string | null | undefined,
): string | null {
  if (session.engine === 'codex') {
    const named = codexThreadName(session.sessionId, sessionCodexHome(session))
    if (named) return named
  }
  // The live terminal title first (it follows /rename at once), else omp's own session file.
  if (session.engine === 'omp') return cleanOmpTitle(terminalTitle) ?? ompSessionTitle(session.transcriptPath)
  return terminalTitle ?? null
}