Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
6.8 KB
Raw Blame
/**
 * Grok runner — invokes the real `grok` binary (xAI Grok Build CLI) in a
 * tempdir with a BRIEF.md prompt. Live mode only.
 *
 * Invocation pattern (verified against a pinned local install, v1.0.4 —
 * see docs/mcp/GROK-CLI-PIN.md):
 *   grok -p "<brief>" --output-format plain
 *
 * The p flag ("single") is Grok Build's headless one-shot: prompt in, final
 * response text on stdout, exit. We deliberately do NOT pass grok's cwd flag
 * — `spawnWithCapture` already sets `cwd`. `opts.agentName` is unused: the
 * one-shot mode targets the default agent. The permission posture
 * ("always-approve" / "permission-mode", both spelled dash-free here on
 * purpose) is deliberately NOT passed until the authed observation proves it
 * required for headless MCP tool calls — GROK-CLI-PIN.md marks that item
 * pending auth; revisit after the first authed live run.
 *
 * Naming: grok (xAI, XAI_API_KEY) is not groq (Groq Inc. inference recipe,
 * GROQ_API_KEY) and not ngrok (tunnels).
 *
 * Hermeticity posture (deliberate): live mode runs the OPERATOR's configured
 * Grok — the real ~/.grok (auth, model settings, trusted folders) is
 * inherited unless GROK_HOME points elsewhere — against a hermetic BRAIN.
 * Grok-specific contamination channel (observed): grok reads VENDOR MCP
 * configs — ~/.claude.json and project .mcp.json — for folders the operator
 * has trusted. If the operator's ~/.claude.json registers gbrain, a live-lane
 * grok turn in a trusted folder can bind the operator's REAL brain while the
 * oracle probes the hermetic one. `invoke()` logs a loud warning when it
 * detects that case; the fully hermetic lane is the door e2e
 * (install-real-grok.serial.test.ts), where fresh HOME + cwd make vendor
 * fallback structurally impossible (entries show "folder untrusted").
 * Also observed: grok loads .envrc from the cwd by default — live-mode
 * workspaces are harness-created tempdirs, so no operator .envrc is in reach.
 *
 * Binary resolution: $GROK_BIN > `which grok` > unavailable.
 * Path validation: must be absolute, must be executable, no '..' segments.
 * Collision note: the community superagent-ai grok-cli ships a colliding
 * `grok` binary; the official one is identified by its version output shape
 * `grok X.Y.Z (buildhash)` — the live lane writes a version preamble into
 * the transcript so a mis-bound binary is diagnosable from the transcript.
 */

import { execFileSync } from '../../spawn.ts';
import { existsSync, readFileSync } from 'fs';
import { join } from 'path';
import {
  BASE_ENV_ALLOWLIST,
  detectBinary,
  filterAllowlistEnv,
  type AgentRunner,
  type DetectResult,
  type InvokeOpts,
  type InvokeResult,
} from '../agent-runner.ts';
import { spawnWithCapture } from '../transcript-capture.ts';

/**
 * Allow-list for env propagation when spawning grok. Delta from the shared
 * base: GROK_HOME, so callers (door e2e, dx scenarios) can point Grok at an
 * isolated home instead of the operator's real ~/.grok; and XAI_API_KEY,
 * grok's documented headless auth path (keyless one-shot exits 1 with
 * "Not signed in" — see docs/mcp/GROK-CLI-PIN.md) — an operator who auths
 * via that env var would otherwise be blamed as an agent failure.
 * FOREIGN provider keys are removed from the base: grok is single-provider
 * (xAI) — forwarding the operator's Anthropic/OpenAI credentials to a
 * third-party binary buys nothing and is the exact cross-provider exposure
 * the door lane's grokChildEnv scrub exists to prevent.
 */
const FOREIGN_PROVIDER_KEYS = new Set(['ANTHROPIC_API_KEY', 'OPENAI_API_KEY']);
const ENV_ALLOWLIST = [
  ...BASE_ENV_ALLOWLIST.filter((k) => !FOREIGN_PROVIDER_KEYS.has(k)),
  'GROK_HOME',
  'XAI_API_KEY',
];

export class GrokRunner implements AgentRunner {
  readonly name = 'grok';

  async detect(): Promise<DetectResult> {
    return detectBinary('GROK_BIN', 'grok');
  }

  async invoke(opts: InvokeOpts): Promise<InvokeResult> {
    const detected = await this.detect();
    if (!detected.available || !detected.binPath) {
      throw new Error(`grok runner unavailable: ${detected.reason ?? 'unknown'}`);
    }
    const args = ['-p', opts.brief, '--output-format', 'plain'];
    const env = filterAllowlistEnv(ENV_ALLOWLIST, opts.env);

    this.warnOnVendorGbrainEntry(env);

    // Version preamble: recorded as a plain stdout transcript event (the
    // transcript schema is stdio-bytes-only, so this is a captured preamble,
    // not a new event type). Makes a mis-bound community binary or an
    // auto-updated version diagnosable from the transcript alone.
    // execFileSync (no shell — the which-resolved path is not metachar-
    // validated) with the SAME filtered env as the turn itself: the resolved
    // binary must never see ambient secrets the allowlist excludes.
    try {
      const version = execFileSync(detected.binPath, ['--version'], {
        encoding: 'utf-8',
        stdio: ['ignore', 'pipe', 'ignore'],
        timeout: 15_000,
        env: env as NodeJS.ProcessEnv,
        cwd: opts.cwd,
      }).trim();
      opts.transcriptSink.write({
        ts: Date.now(),
        channel: 'stdout',
        bytes: Buffer.from(`[grok-runner preamble] version: ${version}\n`, 'utf-8'),
      });
    } catch {
      // Preamble is diagnostic only — never fail the run for it.
    }

    const result = await spawnWithCapture(detected.binPath, args, {
      cwd: opts.cwd,
      env,
      timeoutMs: opts.timeoutMs,
      transcriptSink: opts.transcriptSink,
    });

    return { exitCode: result.exitCode, durationMs: result.durationMs };
  }

  /**
   * Loud tripwire for the vendor-config contamination channel: when the HOME
   * grok will see carries a ~/.claude.json with an mcpServers.gbrain entry,
   * a trusted-folder grok turn may route gbrain tool calls at the operator's
   * REAL brain. Warning only (live mode deliberately runs the operator's
   * agent); the hermetic lane is the door e2e.
   */
  private warnOnVendorGbrainEntry(env: Record<string, string>): void {
    try {
      const home = env.HOME ?? process.env.HOME;
      if (!home) return;
      const claudeJson = join(home, '.claude.json');
      if (!existsSync(claudeJson)) return;
      const parsed = JSON.parse(readFileSync(claudeJson, 'utf-8')) as {
        mcpServers?: Record<string, unknown>;
      };
      if (parsed?.mcpServers && Object.prototype.hasOwnProperty.call(parsed.mcpServers, 'gbrain')) {
        console.warn(
          '[grok-runner] WARNING: ~/.claude.json registers an mcpServers.gbrain entry. ' +
            'Grok Build reads vendor MCP configs for trusted folders, so this live run ' +
            'may bind the OPERATOR\'S REAL brain instead of the hermetic one. ' +
            'Use a scratch HOME/GROK_HOME for clean measurements (docs/mcp/GROK-CLI-PIN.md).',
        );
      }
    } catch {
      // Best-effort tripwire — unreadable/invalid vendor config is not an error here.
    }
  }
}