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.4 KB
Raw Blame
/**
 * Explain a `New agent` that opened a pane but never produced a discoverable engine.
 *
 * `ENGINE_DID_NOT_START` on its own is unactionable at a distance. Reaching it already proves tmux
 * opened the pane AND the engine binary resolves from the user's own login shell, which leaves three
 * causes that need three different fixes: the engine ran and exited, the login shell is still
 * starting (its dotfiles are slower than the discovery window), or a process IS running that
 * discovery did not recognise. The only machine that can tell them apart is the one that failed —
 * and its `harness.log` is exactly what a person reporting this from another computer cannot reach.
 * So the facts travel back in the error itself, via the `detail` the New Agent dialog already renders.
 */

/** What tmux knows about the created pane at the moment discovery gave up. */
export interface AgentCreatePaneState {
  dead: boolean
  /** Exit status of the pane's process once it is dead; null while it is still running. */
  exitStatus: number | null
  /** `#{pane_current_command}` — the shell while startup files are still running, the engine after. */
  command: string
}

export interface AgentCreatePaneFacts {
  /** null when tmux no longer knows this pane, i.e. it exited and took its session with it. */
  state: AgentCreatePaneState | null
  /** Whatever the pane printed, ANSI already stripped. Empty when nothing could be read. */
  output: string
  /** The executable the launch was meant to `exec`, e.g. `codex`. */
  engineBin: string
  /** Process name of the wrapper login shell, e.g. `zsh`. Null when no interactive shell was used. */
  shellName: string | null
  /** Processes found under the pane, shallowest first, for the remote-readable diagnosis. */
  processes: ReadonlyArray<{ executable: string; args: string }>
  /** A fresh matcher pass found the requested engine, even though registry adoption did not finish. */
  engineProcessFound?: boolean
  elapsedMs: number
}

const MAX_OUTPUT_CHARS = 180
const MAX_DETAIL_CHARS = 520
const MAX_ARGV_CHARS = 90

/** tmux paints this into a pane it is keeping alive under `remain-on-exit`; it is our own artifact. */
const DEAD_PANE_NOTICE = /^Pane is dead \(.*\)$/

/**
 * The last few things the pane said, as one line.
 *
 * Errors print last, so the tail is read rather than the head — a full-screen TUI that merely failed
 * to be *discovered* would otherwise contribute a screenful of chrome and push its own message out.
 */
export function summarizePaneOutput(raw: string): string {
  const lines = raw
    // `capture-pane` without `-e` still lets stray control bytes through (a TUI's own writes, an
    // OSC title). Strip them so a detail string can never carry escape bytes into a log line or a
    // Flutter Text widget. Written as explicit \u escapes: literal ESC bytes in source do not
    // survive copy/paste and review.
    .replace(/\u001b\][^\u0007\u001b]*(?:\u0007|\u001b\\)/g, '')
    .replace(/\u001b\[[0-9;?]*[ -\/]*[@-~]/g, '')
    .replace(/\u001b[@-_]/g, '')
    .replace(/[\u0000-\u0008\u000b-\u001f\u007f]/g, '')
    .split('\n')
    .map((line) => line.trim())
    .filter((line) => line.length > 0 && !DEAD_PANE_NOTICE.test(line))
  if (lines.length === 0) return ''
  const tail = lines.slice(-3).join(' · ')
  return tail.length > MAX_OUTPUT_CHARS ? `${tail.slice(0, MAX_OUTPUT_CHARS - 1)}…` : tail
}

/**
 * Blank anything in an argv that looks like a credential before it travels into a dialog.
 *
 * The processes reported here are the ones under a pane this daemon just created, so their argv is
 * normally the engine launch we built ourselves. "Normally" is not a guarantee once the engine starts
 * spawning its own children, and an error string is the wrong place to find out.
 */
export function redactArgv(args: string): string {
  return args
    .replace(/(--?[\w-]*(?:key|token|secret|password|passwd|auth|credential)[\w-]*[= ])\S+/gi, '$1<redacted>')
    // A long opaque run of credential-shaped characters is not something a launch argv needs to show.
    .replace(/\b[A-Za-z0-9_-]{32,}\b/g, '<redacted>')
}

/** `node "/usr/local/bin/codex" · sh "..."` — what the pane was actually made of. */
export function summarizeProcessTree(
  processes: ReadonlyArray<{ executable: string; args: string }>,
): string {
  const rendered = processes.slice(0, 4).map(({ executable, args }) => {
    const argv = redactArgv(args).trim()
    const shown = argv.length > MAX_ARGV_CHARS ? `${argv.slice(0, MAX_ARGV_CHARS - 1)}\u2026` : argv
    return shown ? `${executable} "${shown}"` : executable
  })
  return rendered.join(' \u00b7 ')
}

function seconds(elapsedMs: number): string {
  return `${(elapsedMs / 1000).toFixed(1)}s`
}

function withOutput(summary: string, output: string): string {
  const detail = output ? `${summary} · pane said: ${output}` : summary
  return detail.length > MAX_DETAIL_CHARS ? `${detail.slice(0, MAX_DETAIL_CHARS - 1)}…` : detail
}

/**
 * One sentence naming which of the three causes happened, plus the pane's own words.
 *
 * Deliberately phrased for someone reading a dialog on a different computer than the one that
 * failed: it says what the pane was doing, not what the code checked.
 */
export function describeAgentCreateFailure(facts: AgentCreatePaneFacts): string {
  const { state, output, engineBin, shellName, processes, engineProcessFound = false, elapsedMs } = facts
  const waited = seconds(elapsedMs)

  // tmux forgot the pane entirely. `create` asks tmux to keep dead panes, so reaching this means the
  // option did not take (a tmux too old for it) and the process still exited — the output is gone
  // with the session, which is itself the finding.
  if (!state) {
    return withOutput(
      `the pane exited within ${waited} and tmux did not keep it, so "${engineBin}" left no output to read`,
      output,
    )
  }

  if (state.dead) {
    const status = state.exitStatus === null ? '' : ` with status ${state.exitStatus}`
    return withOutput(`"${engineBin}" started and exited${status} after ${waited}`, output)
  }

  // Still the login shell: the dotfiles (nvm, oh-my-zsh, asdf, corporate profiles) had not finished
  // by the time discovery gave up, so `exec` had not replaced the shell with the engine yet. The
  // agent normally still appears a few seconds later, once the periodic reconcile runs.
  if (shellName && state.command === shellName) {
    return withOutput(
      `after ${waited} the pane was still running "${shellName}" startup files, so "${engineBin}" had not launched yet`
        + ' — the agent may still appear on its own shortly',
      output,
    )
  }

  const tree = summarizeProcessTree(processes)
  if (engineProcessFound) {
    const waitingForTrust = /(?:yes,\s*i trust this folder|trust this folder)/i.test(output)
    return withOutput(
      waitingForTrust
        ? `"${engineBin}" is running and waiting for folder trust, but agent registration did not complete after ${waited}`
        : `"${engineBin}" process was found under the pane, but agent registration did not complete after ${waited}`
          + (tree ? ` · saw: ${tree}` : ''),
      output,
    )
  }

  // Naming only the foreground command is what left the last report unactionable: discovery searches
  // the WHOLE tree under the pane, so "it was running node" does not say what discovery rejected.
  return withOutput(
    `after ${waited} the pane was running "${state.command}" but no ${engineBin} process was found under it`
      + (tree ? ` · saw: ${tree}` : ''),
    output,
  )
}