Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

8.1 KB
Raw Blame
/**
 * Per-CLI conventions for xAI's "Grok Build" coding agent (binary: `grok`).
 *
 * Grok Build ships three PortOS provider shapes:
 *   - `grok`      (type `api`) — OpenAI-compatible chat completions at
 *                 https://api.x.ai/v1, handled generically by the API runner.
 *   - `grok-cli`  (type `cli`) — headless one-shot via `grok --prompt-file …`.
 *   - `grok-tui`  (type `tui`) — the interactive Grok Build TUI driven over a PTY.
 *
 * Unlike every other PortOS CLI provider, grok's headless mode does NOT read the
 * prompt from raw stdin — it takes a single-turn prompt from a file path
 * (`--prompt-file <PATH>`) or an argument (`-p/--single`). To keep PortOS's
 * existing stdin delivery (`childProcess.stdin.write(prompt)`) working unchanged
 * at every spawn site, `buildCliArgs` points grok at `--prompt-file /dev/stdin`
 * on POSIX — grok opens the path and reads the piped prompt. Windows has no
 * `/dev/stdin`, so the two primary spawn helpers rewrite the sentinel to a real
 * temp file via `prepareGrokPromptFile` (see runner.js / cliProviderRun.js).
 *
 * Dependency-light on purpose: imports only `providerModels.js` helpers and node
 * builtins, mirroring `cliProviderArgs.js` so it stays importable from the
 * standalone autofixer process.
 */

import { isCliProvider, isTuiProvider } from './providerTypes.js';
import os from 'os';
import { writeFileSync, unlinkSync } from 'fs';
import { join } from 'path';
import { randomUUID } from 'crypto';
import { argvHasFlag, hasModelFlag, commandBasename } from './providerModels.js';

const NOOP_CLEANUP = () => {};

export const GROK_API_ID = 'grok';
export const GROK_CLI_ID = 'grok-cli';
export const GROK_TUI_ID = 'grok-tui';
export const GROK_API_ENDPOINT = 'https://api.x.ai/v1';
// Shipped CLI/TUI providers pin a concrete model for accurate attribution.
// Legacy configured-default selections still omit --model for compatibility.

// grok reads a single-turn prompt from a file path. On POSIX we hand it
// /dev/stdin so the existing stdin write feeds it unchanged at every spawn site.
export const GROK_STDIN_PROMPT_PATH = '/dev/stdin';

/**
 * True when a provider command points at the Grok Build binary — the bare `grok`
 * on PATH, an absolute/relative path to it, or an optional Windows `.exe` suffix
 * (same matching rules as `isOpencodeCommand`/`isClaudeCommand`).
 * @param {string|null|undefined} command
 * @returns {boolean}
 */
export function isGrokCommand(command) {
  return commandBasename(command) === 'grok';
}

/** True for the CLI (headless) Grok provider. */
export function isGrokCliProvider(provider) {
  return provider?.id === GROK_CLI_ID
    || (isCliProvider(provider) && isGrokCommand(provider?.command));
}

/** True for the TUI (interactive) Grok provider. */
export function isGrokTuiProvider(provider) {
  return provider?.id === GROK_TUI_ID
    || (isTuiProvider(provider) && isGrokCommand(provider?.command));
}

// A prompt source already declared (single-turn prompt, prompt file, or JSON
// blocks) — so we don't append a second `--prompt-file`.
const PROMPT_SOURCE_FLAGS = ['-p', '--single', '--prompt-file', '--prompt-json'];
// An approval/permission posture already pinned by the user.
const PERMISSION_FLAGS = ['--permission-mode', '--always-approve'];
// An output format already pinned.
const OUTPUT_FORMAT_FLAGS = ['--output-format', '-o'];

/**
 * Build the headless (one-shot) argv for the Grok Build CLI. Appends, when not
 * already pinned by the user's saved `args`:
 *   - `--output-format plain`      — PortOS parses CLI stdout as plain text.
 *   - `--permission-mode bypassPermissions` — don't block file-writing agents on
 *     approval prompts (grok's analog of `claude --dangerously-skip-permissions`).
 *     With `toolFree` (a one-shot answer over caller text — Ask, AI app
 *     detection, #9008) it is the read-only `plan` mode instead; the caller
 *     then runs `toolFreeOneShotArgs` to empty the tool allowlist too.
 *   - `--model <id>`               — gated on no user-baked model flag.
 *   - `--prompt-file /dev/stdin`   — deliver the prompt over stdin (POSIX); the
 *     spawn helper rewrites this to a temp file on Windows.
 * @param {string[]} baseArgs - user/legacy args (already model-flag-sanitized)
 * @param {string|null|undefined} model - defaultModel to pin, or null to omit
 * @param {{ toolFree?: boolean }} [options]
 * @returns {string[]}
 */
export function ensureGrokHeadlessArgs(baseArgs = [], model, { toolFree = false } = {}) {
  const out = [...baseArgs];
  if (!argvHasFlag(out, OUTPUT_FORMAT_FLAGS)) {
    out.push('--output-format', 'plain');
  }
  if (!argvHasFlag(out, PERMISSION_FLAGS)) {
    out.push('--permission-mode', toolFree ? 'plan' : 'bypassPermissions');
  }
  if (model && !hasModelFlag(out)) {
    out.push('--model', model);
  }
  if (!argvHasFlag(out, PROMPT_SOURCE_FLAGS)) {
    out.push('--prompt-file', GROK_STDIN_PROMPT_PATH);
  }
  return out;
}

/**
 * Ensure the interactive Grok TUI argv auto-approves tool executions so a
 * file-writing agent isn't stranded on an approval prompt (mirrors the codex
 * `--dangerously-bypass-approvals-and-sandbox` / antigravity
 * `--dangerously-skip-permissions` TUI defaults). Idempotent when the user
 * already pinned a permission posture.
 * @param {string[]} args
 * @returns {string[]}
 */
export function ensureGrokTuiArgs(args = []) {
  const out = [...args];
  if (!argvHasFlag(out, PERMISSION_FLAGS)) {
    out.push('--permission-mode', 'bypassPermissions');
  }
  return out;
}

/**
 * Resolve how the prompt reaches grok for a spawned headless run.
 *
 * POSIX: the `--prompt-file /dev/stdin` sentinel stays put and the caller feeds
 * the prompt via stdin exactly as for every other CLI (`useStdin: true`).
 *
 * Windows: `/dev/stdin` doesn't exist, so write the prompt to a real temp file,
 * rewrite the argv to point `--prompt-file` at it, and tell the caller to skip
 * the stdin write (`useStdin: false`). `cleanup()` removes the temp file and
 * must be invoked from the child's close/error handler.
 *
 * A no-op (returns the argv untouched, `useStdin: true`) for any argv that isn't
 * the grok stdin sentinel, so it's safe to call unconditionally before a spawn.
 * @param {string[]} args - the built argv (may contain the /dev/stdin sentinel)
 * @param {string} prompt - the prompt text
 * `cleanup({ throwOnError: true })` lets an owner retain failed cleanup as a
 * recovery blocker; the default remains best-effort for existing callers.
 * @returns {{ args: string[], useStdin: boolean, cleanup: (options?: {throwOnError?: boolean}) => void }}
 */
export function prepareGrokPromptFile(args, prompt) {
  if (process.platform !== 'win32') return { args, useStdin: true, cleanup: NOOP_CLEANUP };
  // Locate the /dev/stdin sentinel in either form: separated
  // (`--prompt-file /dev/stdin`, what buildCliArgs emits) or joined
  // (`--prompt-file=/dev/stdin`, which a user could bake into provider.args and
  // which ensureGrokHeadlessArgs then leaves in place as an existing prompt
  // source). Both are a POSIX-only path grok can't open on Windows.
  const joined = `--prompt-file=${GROK_STDIN_PROMPT_PATH}`;
  const sepIdx = args.findIndex((a, i) => a === GROK_STDIN_PROMPT_PATH && args[i - 1] === '--prompt-file');
  const joinIdx = sepIdx === -1 ? args.indexOf(joined) : -1;
  if (sepIdx === -1 && joinIdx === -1) return { args, useStdin: true, cleanup: NOOP_CLEANUP };
  // A collision-resistant name — concurrent grok runs in the same process (e.g.
  // parallel CoS agents / pipeline stages) can reach here in the same millisecond,
  // so a pid+timestamp name would clobber each other's prompt or delete a file a
  // sibling still needs. randomUUID is unique per call (server-side Node crypto).
  const file = join(os.tmpdir(), `grok-prompt-${process.pid}-${randomUUID()}.txt`);
  writeFileSync(file, typeof prompt === 'string' ? prompt : '', 'utf8');
  const rewritten = [...args];
  if (sepIdx !== -1) rewritten[sepIdx] = file;
  else rewritten[joinIdx] = `--prompt-file=${file}`;
  return {
    args: rewritten,
    useStdin: false,
    cleanup: ({ throwOnError = false } = {}) => {
      try { unlinkSync(file); }
      catch (error) { if (throwOnError && error.code !== 'ENOENT') throw error; }
    },
  };
}