Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

18.8 KB
Raw Blame
import { execFile, spawn } from 'child_process'
import fs from 'fs'
import os from 'os'
import path from 'path'
import { promisify } from 'util'
import type { GitResult, Settings } from '../shared/types'
import { directExecutableInvocation, findInPathString, shellPathNow } from './exec-path'
import { resolveGitRemote, runRemoteGit } from './remote-ssh/remote-git'
import { AUTH_ENV_STRIP } from './claude-accounts-core'

const run = promisify(execFile)

const STAGED_DIFF_BYTE_BUDGET = 200_000
const OUTPUT_LIMIT = 64_000
const TIMEOUT_MS = 120_000

const bytes = (s: string) => Buffer.byteLength(s, 'utf-8')

/** Resolve a CLI binary to an absolute path (GUI apps don't inherit the shell PATH).
 *  Exported for tests only — every caller is in this module. */
export function resolveBinary(name: string): string | null {
  // `path.isAbsolute`, not `startsWith('/')`. A Windows absolute path (`C:\Tools\agent.exe`, or a
  // UNC `\\server\share\agent.exe`) does not start with `/`, so it missed this branch, fell
  // through to the bare-name path below, and was then rejected by that branch's charset gate for
  // containing `:` and `\`. The effect was that a custom commit agent could not be given as a full
  // path on Windows at all.
  if (path.isAbsolute(name)) return fs.existsSync(name) ? name : null
  // `name` comes from a user setting (the custom commit agent), so anything that is not a bare
  // binary name is refused here — BEFORE it is interpolated into the paths below. It used to be
  // checked only after that loop, which let a name like `../../evil` normalize out of the
  // directories the loop is meant to confine it to (`~/.local/bin/../../evil` is `~/evil`). Same
  // rule as before, applied where it actually confines.
  if (!/^[A-Za-z0-9._-]+$/.test(name)) return null
  // GUI apps inherit a minimal PATH, so these user-install locations are checked BEFORE the PATH
  // walk — deliberately, and left in that order here. They are POSIX paths without a file
  // extension, which on Windows can only ever match an extensionless file: never the real
  // `<name>.exe`/`<name>.cmd`, and possibly something `spawn()` cannot execute at all (a shell
  // script, say). Skipped there rather than left to misfire; the PATH walk below is the one that
  // can actually answer on Windows.
  const candidates =
    os.platform() === 'win32'
      ? []
      : [
          `${os.homedir()}/.local/bin/${name}`,
          `${os.homedir()}/.claude/local/${name}`,
          `/opt/homebrew/bin/${name}`,
          `/usr/local/bin/${name}`,
          `/usr/bin/${name}`
        ]
  for (const c of candidates) {
    try {
      if (fs.existsSync(c)) return c
    } catch {
      // ignore
    }
  }
  // Resolve via PATH without a shell OR a subprocess: walk the cached login-shell PATH from
  // exec-path.ts (the inherited GUI PATH misses user-installed bins).
  return findInPathString(name, shellPathNow() ?? process.env.PATH)
}

async function git(cwd: string, args: string[]): Promise<string> {
  // SSH projects read the staged diff over the project's ControlMaster (the agent spawn stays
  // local). Local path is untouched when no remote owns this cwd.
  const ref = resolveGitRemote(cwd)
  if (ref) {
    const r = await runRemoteGit(ref, cwd, args, 50 * 1024 * 1024)
    return r.ok ? r.out : ''
  }
  try {
    const { stdout } = await run('git', args, { cwd, maxBuffer: 50 * 1024 * 1024 })
    return stdout
  } catch {
    return ''
  }
}

/**
 * Split a unified diff into per-file chunks (each starting at a `diff --git` header) and
 * fairly distribute a byte budget across them ("water-filling"), so one giant generated
 * file (lockfile etc.) can't starve the human-written changes. Each cut is on a line
 * boundary with a marker; the agent never sees a half line.
 */
function truncateDiffForPrompt(diff: string, budget: number): string {
  if (bytes(diff) <= budget) return diff

  const chunks: string[] = []
  const re = /(^|\n)(diff --git )/g
  let lastIndex = 0
  let m: RegExpExecArray | null
  const starts: number[] = []
  while ((m = re.exec(diff))) starts.push(m.index + (m[1] ? 1 : 0))
  if (starts.length === 0) return capAtLine(diff, budget)
  for (let i = 0; i < starts.length; i++) {
    chunks.push(diff.slice(starts[i], i + 1 < starts.length ? starts[i + 1] : diff.length))
  }
  lastIndex = starts[0]
  const preamble = diff.slice(0, lastIndex)

  // Water-fill: smallest files first take their full size; the rest share what remains.
  let remaining = budget - bytes(preamble)
  let left = chunks.length
  const caps = new Array<number>(chunks.length)
  chunks
    .map((c, i) => ({ i, size: bytes(c) }))
    .sort((a, b) => a.size - b.size)
    .forEach(({ i, size }) => {
      const share = Math.max(0, Math.floor(remaining / Math.max(1, left)))
      const take = Math.min(size, share)
      caps[i] = take
      remaining -= take
      left--
    })

  return preamble + chunks.map((c, i) => capAtLine(c, caps[i])).join('')
}

function capAtLine(text: string, cap: number): string {
  if (bytes(text) <= cap) return text
  let cut = Buffer.from(text, 'utf-8').slice(0, Math.max(0, cap)).toString('utf-8')
  const nl = cut.lastIndexOf('\n')
  if (nl > 0) cut = cut.slice(0, nl)
  const omitted = bytes(text) - bytes(cut)
  return `${cut}\n...(diff truncated, ${omitted} bytes omitted)\n`
}

function buildPrompt(diff: string, files: string, extra: string): string {
  const base = `Write a git commit message for the staged changes below.
Output ONLY the commit message - no preamble, no code fences, no quotes.
Use a concise subject line of at most 72 characters; if useful, add a blank line then a short body.
Do not include "Co-authored-by" trailers.`
  const body = diff
    ? `\n\nStaged diff:\n\`\`\`diff\n${diff}\n\`\`\``
    : `\n\nStaged files (diff omitted due to size):\n${files}`
  const suffix = extra.trim() ? `\n\nAdditional user prompt:\n${extra.trim()}` : ''
  return base + body + suffix
}

/** Split a command template into tokens (quote-aware, NO shell expansion). */
function tokenize(cmd: string): string[] {
  const out: string[] = []
  const re = /"([^"]*)"|'([^']*)'|(\S+)/g
  let m: RegExpExecArray | null
  while ((m = re.exec(cmd))) out.push(m[1] ?? m[2] ?? m[3])
  return out
}

interface Plan {
  bin: string
  args: string[]
  stdin: string | null
  /** Removes what the plan created ({promptFile}'s temp dir); call once the agent has exited. */
  cleanup?: () => void
}

/** CreateProcess caps the whole command line at 32,767 UTF-16 units; keep headroom for quoting. */
const WIN_CMDLINE_MAX = 32_000

/** A Windows command line's length for `bin args…` as libuv quotes it: each element wrapped in
 *  quotes, every `"` and `\` possibly escaped — an upper bound, which is what a refusal needs. */
function winCommandLineLength(bin: string, args: string[]): number {
  const quoted = (a: string) => a.length + 3 + (a.match(/["\\]/g)?.length ?? 0)
  return [bin, ...args].reduce((n, a) => n + quoted(a), 0)
}

/** Why a `{prompt}` plan cannot work on Windows — said up front, instead of the spawn failing with
 *  "Cannot safely execute Windows script" or a raw ENAMETOOLONG. */
export const WINDOWS_INLINE_PROMPT_ERROR =
  'On Windows this command cannot receive a multi-line prompt as an argument (npm .cmd shim / command-line length limit). Remove {prompt} to send it on stdin, or use {promptFile}.'

export interface PlanAgentOptions {
  /** The platform to plan for (default `os.platform()`). */
  platform?: NodeJS.Platform
  /** Where {promptFile}'s private temp dir is made (default `os.tmpdir()`). */
  tmpDir?: string
}

/** Exported for tests only. */
export function planAgent(settings: Settings, prompt: string, opts: PlanAgentOptions = {}): Plan | { error: string } {
  const platform = opts.platform ?? os.platform()
  if (settings.commitAgent === 'custom') {
    const tokens = tokenize(settings.commitAgentCommand)
    if (tokens.length === 0) return { error: 'No custom commit command set (Settings → Commit messages).' }
    const bin = resolveBinary(tokens[0])
    if (!bin) return { error: `Command "${tokens[0]}" not found.` }
    const rest = tokens.slice(1)
    const inlineRefused = (args: string[]): boolean =>
      platform === 'win32' &&
      rest.includes('{prompt}') &&
      (directExecutableInvocation(bin, args, { platform }) === null || winCommandLineLength(bin, args) > WIN_CMDLINE_MAX)
    if (rest.includes('{promptFile}')) {
      // The prompt as a FILE PATH: no argv quoting, no shim line-break refusal, no length limit —
      // the one inline form that works for every CLI on every platform. A private dir per run
      // (mkdtemp is 0700 on POSIX; Windows' per-user %TEMP% is already private), removed by
      // `cleanup` after the agent exits.
      const dir = fs.mkdtempSync(path.join(opts.tmpDir ?? os.tmpdir(), 'nt-prompt-'))
      const file = path.join(dir, 'prompt.txt')
      try {
        fs.writeFileSync(file, prompt, { mode: 0o600 })
      } catch (e) {
        fs.rmSync(dir, { recursive: true, force: true })
        return { error: `Could not write the prompt file: ${(e as Error).message}` }
      }
      const cleanup = () => fs.rmSync(dir, { recursive: true, force: true })
      const args = rest.map((t) => (t === '{promptFile}' ? file : t === '{prompt}' ? prompt : t))
      if (inlineRefused(args)) {
        cleanup()
        return { error: WINDOWS_INLINE_PROMPT_ERROR }
      }
      return { bin, args, stdin: null, cleanup }
    }
    if (rest.includes('{prompt}')) {
      const args = rest.map((t) => (t === '{prompt}' ? prompt : t))
      if (inlineRefused(args)) return { error: WINDOWS_INLINE_PROMPT_ERROR }
      return { bin, args, stdin: null }
    }
    return { bin, args: rest, stdin: prompt }
  }
  if (settings.commitAgent === 'codex') {
    const bin = resolveBinary('codex')
    if (!bin) return { error: 'codex CLI not found.' }
    return { bin, args: ['exec', '--sandbox', 'read-only'], stdin: prompt }
  }
  const bin = resolveBinary('claude')
  if (!bin) return { error: 'claude CLI not found. Install Claude Code or pick another agent in Settings.' }
  return { bin, args: ['-p', '--permission-mode', 'plan'], stdin: prompt }
}

function spawnAgent(
  bin: string,
  args: string[],
  cwd: string,
  stdin: string | null,
  env: NodeJS.ProcessEnv = process.env
): Promise<{ code: number; stdout: string; stderr: string }> {
  return new Promise((resolve) => {
    const invocation = directExecutableInvocation(bin, args)
    if (!invocation) {
      resolve({ code: 1, stdout: '', stderr: `Cannot safely execute Windows script: ${bin}` })
      return
    }

    const child = spawn(invocation.executable, invocation.args, {
      ...invocation.options,
      cwd,
      env,
      stdio: ['pipe', 'pipe', 'pipe'],
      windowsHide: true
    })
    let stdout = ''
    let stderr = ''
    const timer = setTimeout(() => child.kill('SIGKILL'), TIMEOUT_MS)
    child.stdout.on('data', (d) => {
      if (stdout.length < OUTPUT_LIMIT) stdout += d.toString()
    })
    child.stderr.on('data', (d) => {
      if (stderr.length < OUTPUT_LIMIT) stderr += d.toString()
    })
    child.on('error', (e) => {
      clearTimeout(timer)
      resolve({ code: 1, stdout, stderr: stderr || String(e) })
    })
    child.on('close', (code) => {
      clearTimeout(timer)
      resolve({ code: code ?? 1, stdout, stderr })
    })
    if (stdin !== null) {
      // The agent CLI can exit before draining the prompt (bad flag, instant auth failure, crash
      // on boot) — the resulting EPIPE is NOT a throw at the write below but an async 'error'
      // EVENT on the pipe, and unhandled it takes the whole main process down (issue #382's
      // class). The close handler above already owns the outcome; log it and let the exit code
      // plus stderr tell the real story.
      child.stdin.on('error', (e: NodeJS.ErrnoException) => {
        console.warn(`[commit-message] agent stdin write failed (${e.code ?? e})`)
      })
      child.stdin.write(stdin)
      child.stdin.end()
    }
  })
}

// eslint-disable-next-line no-control-regex
const ANSI = /\[[0-9;]*m/g

/** Strip CLI noise (ANSI, status lines, wrapping fence, quotes) to leave the message. */
function cleanMessage(raw: string): string {
  let s = raw.replace(ANSI, '').trim()
  const fence = s.match(/^```[a-zA-Z]*\n([\s\S]*?)\n```$/)
  if (fence) s = fence[1].trim()
  const noise = /^(generating|thinking|loading|analyzing|working|reading|here'?s|sure[,.!]?|okay|certainly|i'?ll|let me)\b/i
  const lines = s.split('\n')
  while (lines.length && noise.test(lines[0].trim())) lines.shift()
  s = lines.join('\n').trim()
  s = s.replace(/^["'`]+/, '').replace(/["'`]+$/, '').trim()
  return s
}

function extractError(text: string): string {
  const lines = text
    .replace(ANSI, '')
    .split('\n')
    .map((l) => l.trim())
    .filter(Boolean)
  const meaningful = lines.reverse().find((l) => /error|fail|denied|not found|429|unauthor/i.test(l))
  return meaningful || lines[0] || 'Agent produced no output.'
}

/** Orchestrates: staged diff -> budget -> prompt -> read-only agent spawn -> clean message. */
export async function generateCommitMessage(cwd: string, settings: Settings): Promise<GitResult> {
  if (!cwd) return { ok: false, message: 'No project folder set.' }

  const names = (await git(cwd, ['diff', '--cached', '--name-status'])).trim()
  if (!names) return { ok: false, message: 'No staged changes. Stage files first.' }

  const rawDiff = await git(cwd, ['diff', '--cached', '--patch', '--minimal'])
  const diff = rawDiff ? truncateDiffForPrompt(rawDiff, STAGED_DIFF_BYTE_BUDGET) : ''
  const prompt = buildPrompt(diff, names, settings.commitExtraPrompt)

  return runAgent(prompt, cwd, settings)
}

/**
 * The working directory to give the LOCAL agent spawn.
 *
 * The agent always runs on THIS machine — only the git reads route over an SSH project's
 * ControlMaster (see `git` above), and by the time we spawn, the diff is already inside the prompt.
 * So a REMOTE project's cwd is a path on the server, and handing it to a local `spawn` is asking
 * macOS to chdir into a directory that does not exist here.
 *
 * That failed in the most misleading way possible: Node reports a missing CWD as `spawn <command>
 * ENOENT`, naming the BINARY. The 2026-08-05 report was "Error: spawn
 * /Users/enes/.local/bin/claude ENOENT" on SSH servers — which reads as "claude is not installed"
 * and sent the hunt to the CLI, while claude was sitting exactly where the path said and the
 * unreachable thing was `/root/<project>` on a Mac.
 *
 * Home is the right substitute rather than, say, a temp dir: it is where every other read-only
 * agent invocation without a project runs (`cwd || os.homedir()` has always been the fallback for
 * a project with no folder), and the agent needs no repo — it is given a prompt on stdin.
 */
export function localAgentCwd(cwd: string, isRemote: boolean, home: string): string {
  return !cwd || isRemote ? home : cwd
}

/**
 * The env for running an agent under a managed Claude account: `CLAUDE_CONFIG_DIR` points at the
 * account's dir and the auth vars that would shadow its OAuth login are stripped — the same two
 * moves `PtyManager` makes for the node's own session, so a one-shot request goes out as the same
 * identity the node runs as.
 */
export function claudeAccountEnv(base: NodeJS.ProcessEnv, configDir: string): NodeJS.ProcessEnv {
  const env: NodeJS.ProcessEnv = { ...base, CLAUDE_CONFIG_DIR: configDir }
  for (const k of AUTH_ENV_STRIP) delete env[k]
  return env
}

/**
 * A CLI error printed where the answer should be. `claude -p` writes "Failed to authenticate: …" /
 * "Invalid API key …" / "API Error: …" to STDOUT, so the exit code alone is not enough evidence —
 * and treating that line as the answer is how a node ended up titled "Failed to authenticate: OAuth s…".
 */
const CLI_ERROR_OUTPUT =
  /^(failed to authenticate|invalid api key|api error|error:|oauth token|authentication_error|please run \/login|credit balance is too low)/i

export function isCliErrorOutput(message: string): boolean {
  return CLI_ERROR_OUTPUT.test(message.trim())
}

/** Plan + spawn the configured agent on a prompt and return its cleaned output. */
export async function runAgent(
  prompt: string,
  cwd: string,
  settings: Settings,
  env?: NodeJS.ProcessEnv
): Promise<GitResult> {
  const plan = planAgent(settings, prompt)
  if ('error' in plan) return { ok: false, message: plan.error }

  const spawnCwd = localAgentCwd(cwd, !!resolveGitRemote(cwd), os.homedir())
  let res: Awaited<ReturnType<typeof spawnAgent>>
  try {
    res = await spawnAgent(plan.bin, plan.args, spawnCwd, plan.stdin, env)
  } finally {
    plan.cleanup?.()
  }
  const message = cleanMessage(res.stdout)
  // A nonzero exit is a failure even when stdout has text: that text is the CLI's error message,
  // never an answer. Same for a known error line on a zero exit.
  if (res.code !== 0 || isCliErrorOutput(message)) {
    return { ok: false, message: extractError(res.stderr || res.stdout) }
  }
  if (!message) return { ok: false, message: 'Agent produced no output.' }
  return { ok: true, message }
}

/** Suggest a short terminal title from its recent output. */
export async function generateTerminalName(
  content: string,
  cwd: string,
  settings: Settings,
  env?: NodeJS.ProcessEnv
): Promise<GitResult> {
  const trimmed = content.trim()
  if (!trimmed) return { ok: false, message: 'No terminal output to read yet.' }
  const clip = trimmed.split('\n').slice(-150).join('\n').slice(-8000)
  const prompt = `Below is the recent output of a terminal session. Suggest a very short title (2-4 words, Title Case, no surrounding quotes, no trailing punctuation) describing what this terminal is used for. Output ONLY the title.

Terminal output:
\`\`\`
${clip}
\`\`\``
  const r = await runAgent(prompt, cwd, settings, env)
  if (!r.ok) return r
  const name = r.message
    .split('\n')[0]
    .replace(/["'`.]+$/g, '')
    .trim()
    .slice(0, 40)
  return name ? { ok: true, message: name } : { ok: false, message: 'No name produced.' }
}

/** Suggest a short group title from the recent output of its member terminals. */
export async function generateGroupName(
  contents: string[],
  cwd: string,
  settings: Settings
): Promise<GitResult> {
  const blocks = contents
    .map((c, i) => {
      const clip = c.trim().split('\n').slice(-50).join('\n').slice(-2500)
      return clip ? `Terminal ${i + 1}:\n\`\`\`\n${clip}\n\`\`\`` : ''
    })
    .filter(Boolean)
  if (!blocks.length) return { ok: false, message: 'No terminal output to read yet.' }
  const prompt = `Below are the recent outputs of several terminal sessions that belong to one group. Suggest a very short group title (2-4 words, Title Case, no surrounding quotes, no trailing punctuation) describing the group's shared purpose. Output ONLY the title.

${blocks.join('\n\n')}`
  const r = await runAgent(prompt, cwd, settings)
  if (!r.ok) return r
  const name = r.message
    .split('\n')[0]
    .replace(/["'`.]+$/g, '')
    .trim()
    .slice(0, 40)
  return name ? { ok: true, message: name } : { ok: false, message: 'No name produced.' }
}