FN-7716: stop requiring a Fusion-visible API key for Grok CLI provider

Grok CLI provider readiness now mirrors the Cursor CLI provider: it is derived from the `grok` binary being available rather than requiring a Fusion-visible GROK_API_KEY or ~/.grok/user-settings.json, since the CLI manages its own auth. - probeGrokBinary now derives `authenticated` from binary availability (readiness) instead of API-key/user-settings presence; key detection surfaces as a non-blocking `apiKeyDetected` hint - /auth/status treats the grok-cli provider as authenticated when enabled + binary available - GrokCliProviderCard drops the blocking "Set GROK_API_KEY" state - Direct xAI streaming path is unchanged and still uses $GROK_API_KEY when present (FN-7711/FN-7714) - Added changeset for @runfusion/fusion (patch) Files changed: $(cat /tmp/diffstat_fn7716.txt) Fusion-Task-Id: FN-7716 Fusion-Task-Lineage: ac0efc79-2510-465e-9cd2-4938c08989c9 Co-authored-by: Fusion (runfusion.ai) <noreply@runfusion.ai>
2026-07-09 08:06:39 -07:00
parent c8fcbec94f
commit 71e9f484bb
11 changed files with 228 additions and 84 deletions
--- a/plugins/fusion-plugin-grok-runtime/README.md
+++ b/plugins/fusion-plugin-grok-runtime/README.md
@@ -21,13 +21,20 @@ binary on PATH — Fusion never downloads or bundles the CLI itself.

 - Provider ID: `grok-cli`
 - Binary probe: `grok --version`
- **Auth model — API key, not OAuth/session.** Grok has no `status`/`whoami`
-  subcommand. Authentication is derived from key PRESENCE only:
-  1. `GROK_API_KEY` environment variable, or
-  2. `~/.grok/user-settings.json` → `{ "apiKey": "..." }`
-  Base URL defaults to `https://api.x.ai/v1`. A missing/unreadable/malformed
-  key configuration fails closed to `authenticated: false` with an
-  actionable reason — never throws.
+- **Auth model — the `grok` CLI owns its own authentication; Fusion does
+  not require a Fusion-visible API key to enable/use it (FN-7716).** Grok
+  has no `status`/`whoami` subcommand, so Fusion probes binary availability
+  only and treats a working binary as "ready" (`authenticated: true`). The
+  CLI itself resolves credentials from more sources than Fusion can see
+  (`GROK_API_KEY` env var, a project `.env`, `grok -k <key>`,
+  `GROK_BASE_URL`, sandbox secrets, etc.). Fusion additionally probes two of
+  those locations — the `GROK_API_KEY` env var and
+  `~/.grok/user-settings.json` → `{ "apiKey": "..." }` — purely as a
+  **non-blocking informational hint** (`apiKeyDetected`); it never gates
+  Enable or the authenticated state, and a missing/unreadable/malformed
+  settings file degrades gracefully (never throws). The direct xAI
+  OpenAI-compatible streaming path (base URL `https://api.x.ai/v1`) still
+  uses `$GROK_API_KEY` when present, independent of the CLI provider.
 - Model discovery: `grok models` (plain-text output, with pricing hints per
  the upstream README). The exact line shape is
  `upstream-pending-verification`, so discovery parses conservatively: the
@@ -38,17 +45,20 @@ binary on PATH — Fusion never downloads or bundles the CLI itself.

 ## Enable via Settings → Authentication

-1. Install the `grok` CLI and set `GROK_API_KEY` (or populate
-   `~/.grok/user-settings.json`).
+1. Install the `grok` CLI and authenticate it by any method it supports
+   (env var, project `.env`, `grok -k`, etc.) — Fusion does not need to see
+   the key.
 2. Open Settings → Authentication in the Fusion dashboard.
-3. The "Grok — via Grok CLI" card shows probe status (binary found, API key
-   present). Click **Enable** once the binary is available.
+3. The "Grok — via Grok CLI" card shows probe status. Click **Enable** once
+   the binary is available; a non-blocking hint appears only if Fusion did
+   not detect a key, noting the direct xAI streaming path uses
+   `GROK_API_KEY` when present.
 4. Discovered Grok models (via `grok models`) then merge into the model
   picker under the `grok-cli` provider id.

 ## Notes

-Do not invent a `grok status`/`whoami` JSON auth contract — Grok is
-API-key auth. See `AGENTS.md`'s "External-integration evidence" policy for
-why the release/checksum fields above stay at
-`upstream-pending-verification`.
+Do not invent a `grok status`/`whoami` JSON auth contract — readiness is
+derived from binary availability, mirroring the Cursor CLI provider. See
+`AGENTS.md`'s "External-integration evidence" policy for why the
+release/checksum fields above stay at `upstream-pending-verification`.
--- a/plugins/fusion-plugin-grok-runtime/src/tests/probe.test.ts
+++ b/plugins/fusion-plugin-grok-runtime/src/tests/probe.test.ts
@@ -16,7 +16,7 @@ describe("probeGrokBinary", () => {
    delete process.env.GROK_API_KEY;
  });

-  it("reports authenticated:true when GROK_API_KEY is set", async () => {
+  it("reports authenticated:true and apiKeyDetected:true when GROK_API_KEY is set", async () => {
    process.env.GROK_API_KEY = "xai-test-key";
    vi.mocked(runGrokCommand).mockResolvedValueOnce({ code: 0, stdout: "grok 1.0.0", stderr: "" });

@@ -26,11 +26,12 @@ describe("probeGrokBinary", () => {
    expect(readFile).not.toHaveBeenCalled();
    expect(result.available).toBe(true);
    expect(result.authenticated).toBe(true);
+    expect(result.apiKeyDetected).toBe(true);
    expect(result.version).toBe("grok 1.0.0");
    expect(result.reason).toBeUndefined();
  });

-  it("falls back to ~/.grok/user-settings.json apiKey when GROK_API_KEY is unset", async () => {
+  it("reports apiKeyDetected:true from ~/.grok/user-settings.json apiKey when GROK_API_KEY is unset", async () => {
    vi.mocked(runGrokCommand).mockResolvedValueOnce({ code: 0, stdout: "grok 1.0.0", stderr: "" });
    vi.mocked(readFile).mockResolvedValueOnce(JSON.stringify({ apiKey: "xai-from-file" }));

@@ -38,38 +39,53 @@ describe("probeGrokBinary", () => {

    expect(result.available).toBe(true);
    expect(result.authenticated).toBe(true);
+    expect(result.apiKeyDetected).toBe(true);
  });

-  it("fails closed to authenticated:false with an actionable reason when no key is configured", async () => {
+  /*
+  FNXC:GrokCli 2026-07-09-00:00:
+  FN-7716 Symptom Verification: this is the exact reproduction of the
+  original false-negative — binary available, no Fusion-visible key
+  (GROK_API_KEY unset, ~/.grok/user-settings.json unreadable). BEFORE the fix
+  this asserted `authenticated: false` with a "GROK_API_KEY is not set"
+  reason. AFTER the fix, readiness is decoupled from key presence: the CLI
+  is treated as ready (`authenticated: true`) because the binary works, and
+  the previous key-presence signal now surfaces only as the non-blocking
+  `apiKeyDetected: false` informational field.
+  */
+  it("reports authenticated:true (readiness) with apiKeyDetected:false when no key is configured — proves the original false-negative is resolved", async () => {
    vi.mocked(runGrokCommand).mockResolvedValueOnce({ code: 0, stdout: "grok 1.0.0", stderr: "" });
    vi.mocked(readFile).mockRejectedValueOnce(new Error("ENOENT"));

    const result = await probeGrokBinary();

    expect(result.available).toBe(true);
-    expect(result.authenticated).toBe(false);
-    expect(result.reason).toContain("GROK_API_KEY is not set");
+    expect(result.authenticated).toBe(true);
+    expect(result.apiKeyDetected).toBe(false);
+    expect(result.reason).toContain("No Grok API key detected by Fusion");
  });

-  it("fails closed to authenticated:false on malformed ~/.grok/user-settings.json", async () => {
+  it("reports apiKeyDetected:false on malformed ~/.grok/user-settings.json without blocking authenticated", async () => {
    vi.mocked(runGrokCommand).mockResolvedValueOnce({ code: 0, stdout: "grok 1.0.0", stderr: "" });
    vi.mocked(readFile).mockResolvedValueOnce("not json at all");

    const result = await probeGrokBinary();

    expect(result.available).toBe(true);
-    expect(result.authenticated).toBe(false);
+    expect(result.authenticated).toBe(true);
+    expect(result.apiKeyDetected).toBe(false);
    expect(result.reason).toContain("malformed JSON");
  });

-  it("fails closed to authenticated:false when the settings file has no non-empty apiKey", async () => {
+  it("reports apiKeyDetected:false when the settings file has no non-empty apiKey", async () => {
    vi.mocked(runGrokCommand).mockResolvedValueOnce({ code: 0, stdout: "grok 1.0.0", stderr: "" });
    vi.mocked(readFile).mockResolvedValueOnce(JSON.stringify({ apiKey: "" }));

    const result = await probeGrokBinary();

    expect(result.available).toBe(true);
-    expect(result.authenticated).toBe(false);
+    expect(result.authenticated).toBe(true);
+    expect(result.apiKeyDetected).toBe(false);
    expect(result.reason).toContain("no non-empty apiKey field");
  });

@@ -83,13 +99,14 @@ describe("probeGrokBinary", () => {
    expect(runGrokCommand).toHaveBeenCalledWith("grok", ["--version"], 3000);
  });

-  it("reports binary unavailable with actionable diagnostics when the candidate fails", async () => {
+  it("reports binary unavailable with authenticated:false and actionable diagnostics when the candidate fails", async () => {
    vi.mocked(runGrokCommand).mockResolvedValueOnce({ code: 127, stdout: "", stderr: "spawn error: ENOENT: grok" });

    const result = await probeGrokBinary();

    expect(result.available).toBe(false);
    expect(result.authenticated).toBe(false);
+    expect(result.apiKeyDetected).toBe(false);
    expect(result.reason).toContain("not found");
    expect(result.reason).toContain("grok: spawn error: ENOENT");
  });
@@ -105,6 +122,7 @@ describe("probeGrokBinary", () => {
    expect(runGrokCommand).toHaveBeenNthCalledWith(1, "/missing/grok", ["--version"], 3000);
    expect(runGrokCommand).toHaveBeenNthCalledWith(2, "grok", ["--version"], 3000);
    expect(result.available).toBe(true);
+    expect(result.authenticated).toBe(true);
    expect(result.binaryPath).toBe("grok");
    expect(result.usingConfiguredBinaryPath).toBe(false);
    expect(result.diagnostics?.[0]).toContain("/missing/grok: spawn error: ENOENT");
--- a/plugins/fusion-plugin-grok-runtime/src/probe.ts
+++ b/plugins/fusion-plugin-grok-runtime/src/probe.ts
@@ -25,22 +25,25 @@ function summarizeFailure(binary: string, stdout: string, stderr: string): strin
 }

 /*
-FNXC:GrokCli 2026-07-08-00:00:
-Grok is API-key auth, NOT an OAuth/session CLI like Cursor — there is no
-`grok status --format json` (or `whoami`) subcommand to probe. Auth is a Grok
-API key supplied via the `GROK_API_KEY` env var OR `~/.grok/user-settings.json`
-`{ "apiKey": ... }` (per the upstream README, verified 2026-07-08). We derive
-`authenticated` from key PRESENCE only — env var first, then the settings
-file — and fail closed to `authenticated: false` with an actionable reason on
-a missing key or an unreadable/malformed settings file. Never throw: a
-missing/corrupt `~/.grok/user-settings.json` must degrade gracefully, not
-crash the probe. Do NOT invent a status subcommand for Grok (AGENTS.md /
-PROMPT.md "Do NOT").
+FNXC:GrokCli 2026-07-09-00:00:
+FN-7716: the `grok` CLI resolves its OWN credentials from more sources than
+Fusion can inspect (project `.env`, `GROK_BASE_URL`, `grok -k`, sandbox
+secrets), on top of the two locations Fusion checks below (`GROK_API_KEY` env
+var, `~/.grok/user-settings.json` `{ apiKey }`). Requiring Fusion to see a key
+before treating the provider as "authenticated" produced false negatives for
+operators whose CLI was fully authenticated via a method Fusion doesn't
+check. Key presence is therefore surfaced ONLY as a non-blocking informational
+signal (`apiKeyDetected`) consumed by `probeGrokBinary` below — it never gates
+readiness/`authenticated`, which now derives solely from binary availability,
+mirroring the Cursor CLI provider (`authenticated: cursorEnabled &&
+cursorBinary.available`). Never throw: a missing/corrupt
+`~/.grok/user-settings.json` must degrade gracefully, not crash the probe. Do
+NOT invent a status subcommand for Grok (AGENTS.md / PROMPT.md "Do NOT").
 */
-async function probeGrokApiKeyPresence(): Promise<{ authenticated: boolean; reason?: string }> {
+async function probeGrokApiKeyPresence(): Promise<{ detected: boolean; reason?: string }> {
  const envKey = process.env.GROK_API_KEY;
  if (typeof envKey === "string" && envKey.trim().length > 0) {
-    return { authenticated: true };
+    return { detected: true };
  }

  const settingsPath = join(homedir(), ".grok", "user-settings.json");
@@ -48,17 +51,17 @@ async function probeGrokApiKeyPresence(): Promise<{ authenticated: boolean; reas
  try {
    raw = await readFile(settingsPath, "utf-8");
  } catch {
-    return { authenticated: false, reason: "GROK_API_KEY is not set and ~/.grok/user-settings.json was not found" };
+    return { detected: false, reason: "No Grok API key detected by Fusion (GROK_API_KEY unset, ~/.grok/user-settings.json not found); the CLI will use its own credentials." };
  }

  try {
    const parsed = JSON.parse(raw) as { apiKey?: unknown };
    if (typeof parsed?.apiKey === "string" && parsed.apiKey.trim().length > 0) {
-      return { authenticated: true };
+      return { detected: true };
    }
-    return { authenticated: false, reason: "~/.grok/user-settings.json has no non-empty apiKey field" };
+    return { detected: false, reason: "No Grok API key detected by Fusion (~/.grok/user-settings.json has no non-empty apiKey field); the CLI will use its own credentials." };
  } catch {
-    return { authenticated: false, reason: "~/.grok/user-settings.json is malformed JSON" };
+    return { detected: false, reason: "No Grok API key detected by Fusion (~/.grok/user-settings.json is malformed JSON); the CLI will use its own credentials." };
  }
 }

@@ -81,13 +84,15 @@ export async function probeGrokBinary(options?: { timeoutMs?: number; binaryPath
      probeDurationMs: Date.now() - startedAt,
    };
    if (version.code === 0) {
-      const auth = await probeGrokApiKeyPresence();
+      // FNXC:GrokCli 2026-07-09-00:00: readiness = binary available; the CLI owns auth (FN-7716).
+      const keyPresence = await probeGrokApiKeyPresence();
      return {
        available: true,
-        authenticated: auth.authenticated,
+        authenticated: true,
+        apiKeyDetected: keyPresence.detected,
        ...common,
        version: version.stdout.trim() || undefined,
-        reason: auth.authenticated ? undefined : auth.reason,
+        reason: keyPresence.detected ? undefined : keyPresence.reason,
      };
    }
  }
@@ -98,6 +103,7 @@ export async function probeGrokBinary(options?: { timeoutMs?: number; binaryPath
  return {
    available: false,
    authenticated: false,
+    apiKeyDetected: false,
    configuredBinaryPath,
    usingConfiguredBinaryPath: false,
    diagnostics: failureDetails.length > 0 ? failureDetails : undefined,
--- a/plugins/fusion-plugin-grok-runtime/src/types.ts
+++ b/plugins/fusion-plugin-grok-runtime/src/types.ts
@@ -1,6 +1,25 @@
 export interface GrokBinaryStatus {
  available: boolean;
+  /**
+   * FNXC:GrokCli 2026-07-09-00:00:
+   * FN-7716: means "Grok CLI runtime ready" (the `grok` binary is available
+   * on PATH or at a configured path) — NOT "a Fusion-visible API key was
+   * found". The `grok` CLI owns its own authentication (env var, project
+   * `.env`, `grok -k`, etc.); Fusion no longer requires visibility into a
+   * key to treat the provider as authenticated. See `apiKeyDetected` for the
+   * non-blocking informational key-presence signal.
+   */
  authenticated?: boolean;
+  /**
+   * FNXC:GrokCli 2026-07-09-00:00:
+   * FN-7716: non-blocking informational hint only — true when Fusion itself
+   * detected a Grok API key (GROK_API_KEY env var or
+   * ~/.grok/user-settings.json `apiKey`). Never gates `authenticated` or
+   * enable/disable; the direct xAI OpenAI-compatible streaming path
+   * (FN-7711/FN-7714) uses $GROK_API_KEY when present regardless of this CLI
+   * probe.
+   */
+  apiKeyDetected?: boolean;
  binaryPath?: string;
  binaryName?: string;
  configuredBinaryPath?: string;