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.

4.7 KB
Raw Blame
// Capability probe for the LOCAL grok CLI.
//
// Separate from `claude-cli.ts` on purpose. Rule 9 of CLAUDE.md: *a capability gate that is fed by a
// version probe belongs to the agent it probes*. Answering "can grok mint a session id?" with what
// the OTHER CLI's probe returned would be a guess wearing a measurement's clothes — and the two are
// installed and upgraded independently, so the answer is not even correlated.
//
// Feature-detection over `grok --help`, never a version floor: an unknown flag makes grok EXIT, so a
// floor guessed too low kills every launch on the machines below it instead of degrading. Absent or
// unreadable help ⇒ false ⇒ no flag ⇒ the command line stays exactly what it is today.
import { execFile } from 'child_process'
import { promisify } from 'util'
import { IPC } from '../shared/ipc'
import { directExecutableInvocation } from './exec-path'
import { findInLoginPath } from './pty-manager'
import { platform } from './platform'
import { grokModelsFrom } from '../shared/agents/model-gateway'
import { listGrokSessionIds } from './grok-session-mint'
import { grokSessionsDir } from './agents/grok-paths'
import { UNKNOWN_GROK_CLI_CAPS, type GrokCliCaps } from '../shared/types'

const execFileP = promisify(execFile)
const PROBE_TIMEOUT_MS = 5000

export { UNKNOWN_GROK_CLI_CAPS, type GrokCliCaps }

/**
 * Pure: help output → caps. The impure probe below is plumbing around it.
 *
 * Anchored on a word boundary, which is load-bearing twice over. `--session-id-file` must not
 * answer yes for `--session-id`; and grok's own help MENTIONS `--session-id` inside the description
 * of `--fork-session`, wrapped in backticks — a looser match would report the flag from prose alone.
 */
export function grokCliCapsFrom(
  helpOutput: string | null | undefined,
  modelsOutput?: string | null
): GrokCliCaps {
  return {
    sessionIdFlag: /(^|\s)--session-id(\s|=|$)/m.test(helpOutput ?? ''),
    models: grokModelsFrom(modelsOutput).map((m) => m.id)
  }
}

/**
 * The two spawns, separated from HOW they are spawned so the composition is testable.
 *
 * `run` returns the subcommand's stdout, or null when it failed. Exported for tests: the wiring
 * between "ask `--help`" and "ask `models`" is precisely the kind of code the typecheck validates
 * and nothing exercises — drop the second call and every pure-parser test stays green while model
 * switching silently disappears.
 */
export async function grokCapsFromRunner(
  run: (args: string[]) => Promise<string | null>
): Promise<GrokCliCaps> {
  const help = await run(['--help'])
  if (help === null) return UNKNOWN_GROK_CLI_CAPS
  // A second spawn, paid once per process (the whole probe is memoized). Its failure must not cost
  // us the help answer, so it degrades on its own: no model list just means no model switching.
  const models = await run(['models'])
  return grokCliCapsFrom(help, models)
}

/** Probe the grok binary at `bin`, which may be a Windows npm shim the platform cannot spawn
 *  directly — `directExecutableInvocation` decides how it is run, once, for both subcommands. */
export function probeGrokCliAt(bin: string): Promise<GrokCliCaps> {
  return grokCapsFromRunner(async (args) => {
    try {
      const invocation = directExecutableInvocation(bin, args)
      if (!invocation) return null
      const { stdout } = await execFileP(invocation.executable, invocation.args, {
        ...invocation.options,
        timeout: PROBE_TIMEOUT_MS
      })
      return stdout
    } catch {
      // Missing CLI, timeout, non-zero exit — all mean "unknown", which means "omit the flag".
      return null
    }
  })
}

let cached: Promise<GrokCliCaps> | null = null

async function probe(): Promise<GrokCliCaps> {
  // GUI apps don't inherit the shell PATH — resolve through the login shell like every other CLI
  // lookup in the app.
  const bin = await findInLoginPath('grok').catch(() => null)
  return bin ? probeGrokCliAt(bin) : UNKNOWN_GROK_CLI_CAPS
}

/** The local grok CLI's capabilities. Memoized for the process lifetime. Never rejects. */
export function grokCliCaps(): Promise<GrokCliCaps> {
  if (!cached) cached = probe()
  return cached
}

/** Wire the probe onto the platform's RPC surface (Electron ipcMain / server WS-RPC alike), so both
 *  shells answer it — a probe registered in one shell only is a feature the other silently lacks. */
export function registerGrokCliIpc(): void {
  platform().handle(IPC.grokCliCaps, () => grokCliCaps())
  // The session ids grok already owns for a cwd. Sent as an ARRAY because a Set does not survive
  // the IPC/WS-RPC boundary — it would arrive as `{}` and silently report nothing taken.
  platform().handle(IPC.grokTakenSessionIds, (cwd: string) =>
    typeof cwd === 'string' && cwd ? [...listGrokSessionIds(grokSessionsDir(), cwd)] : []
  )
}