@cartanova/qgrid-cli 2.10.10 → 2.11.0

package/bundle/src/utils/providers/grok/grok-constants.ts

@@ -0,0 +1,105 @@
+// Grok (xAI) fingerprint literals. Bumping GROK_BUILD_VERSION means: edit the constant,
+// re-capture __fixtures__/golden-responses-<ver>.json from the installed binary, and record
+// its build id in GROK_BUILD_COMMIT.
+
+// grok-build 1.0.45 xai-grok-env/src/lib.rs:21
+export const GROK_CHAT_PROXY_URL = "https://cli-chat-proxy.grok.com/v1";
+
+// grok-build 1.0.45 xai-grok-config/src/endpoints.rs:4
+export const GROK_PUBLIC_API_URL = "https://api.x.ai/v1";
+
+// grok-build 1.0.45 xai-grok-login/src/config.rs:124
+export const GROK_AUTH_ISSUER = "https://auth.x.ai";
+
+// grok-build 1.0.45 xai-grok-login/src/config.rs:380 (plaintext in manager_tests.rs:164)
+export const GROK_OAUTH_CLIENT_ID = "b1a00492-073a-47ea-816f-4c329264a828";
+
+// grok-build 1.0.45 xai-grok-login/src/config.rs:16-28 (order frozen by config.rs:624)
+export const GROK_OAUTH_SCOPES = Object.freeze([
+  "openid",
+  "profile",
+  "email",
+  "offline_access",
+  "grok-cli:access",
+  "api:access",
+  "conversations:read",
+  "conversations:write",
+  "workspaces:read",
+  "workspaces:write",
+] as const);
+
+// grok-build 1.0.45 xai-grok-login/src/config.rs:152
+export const GROK_OAUTH_REFERRER = "grok-build";
+
+// grok-build 1.0.45 xai-grok-login/src/device_code.rs:117
+export const GROK_DEVICE_CODE_URL = "https://auth.x.ai/oauth2/device/code";
+
+// grok-build 1.0.45 xai-grok-login/src/device_code.rs:187
+export const GROK_DEVICE_TOKEN_URL = "https://auth.x.ai/oauth2/token";
+
+// U0 capture 2026-10-16 (installed grok-build 1.0.60, user decision)
+export const GROK_BUILD_VERSION = "1.0.60" as const;
+
+// U0 capture 2026-10-16 (Homebrew cask build id of 1.0.60)
+export const GROK_BUILD_COMMIT = "01a8e1c591c0";
+
+// U0 capture 2026-10-16 (GET /settings min_client_version; HTTP 426 below it)
+export const GROK_MIN_CLIENT_VERSION_OBSERVED = "1.0.13";
+
+// grok-build 1.0.45 xai-grok-http/src/lib.rs:246-248
+export const GROK_CLIENT_IDENTIFIER = "grok-shell";
+
+// U0 capture 2026-10-16 (grok -p sends headless; xai-grok-http/src/lib.rs:250-260)
+export const GROK_CLIENT_MODE = "headless";
+
+// U0 capture 2026-10-16 (GET /models default and /settings default_model)
+export const GROK_DEFAULT_MODEL = "grok-4.7";
+
+// grok-build 1.0.45 image_gen/mod.rs:33
+export const GROK_IMAGE_DEFAULT_MODEL = "grok-imagine-image-quality";
+
+// grok-build 1.0.45 video_gen/mod.rs:36-40
+export const GROK_VIDEO_DEFAULT_MODEL = "grok-imagine-video-1.5";
+
+// U0 capture 2026-10-16 (packet contract; the STT probe did not name a model)
+export const GROK_STT_DEFAULT_MODEL = "grok-voice-transcribe-2.0";
+
+// U0 capture 2026-10-16 (api.x.ai /language-models prices vs public per-token pricing)
+export const GROK_USD_PER_TICK = 1e-10;
+
+// U0 capture 2026-10-16 (GET /models reasoning_efforts, identical on all four models)
+export const GROK_REASONING_EFFORTS = Object.freeze(["xhigh", "high", "medium", "low"] as const);
+
+export type GrokReasoningEffort = (typeof GROK_REASONING_EFFORTS)[number];
+
+export interface GrokSeedModel {
+  readonly id: string;
+  readonly contextWindow: number;
+  readonly reasoningEfforts: readonly GrokReasoningEffort[];
+  readonly defaultEffort: GrokReasoningEffort;
+}
+
+// U0 capture 2026-10-16 (GET /models: four ids, context_window 256000, default effort high)
+export const GROK_SEED_MODELS: readonly GrokSeedModel[] = Object.freeze(
+  ["grok-4.7", "grok-4.7-build-fast", "grok-4.6", "grok-4.5"].map(
+    (id): GrokSeedModel =>
+      Object.freeze({
+        id,
+        contextWindow: 256_000,
+        reasoningEfforts: GROK_REASONING_EFFORTS,
+        defaultEffort: "high",
+      }),
+  ),
+);
+
+// U0 capture 2026-10-16 (x-compaction-at request header)
+export const GROK_COMPACTION_AT = 204_800;
+
+// U0 capture 2026-10-16 (x-compactions-remaining request header)
+export const GROK_COMPACTIONS_REMAINING_DEFAULT = 1;
+
+// U0 capture 2026-10-16 (x-grok-doom-loop-check request header)
+export const GROK_DOOM_LOOP_CHECK = 1024;
+
+// U0 capture 2026-10-16 (x-grok-exact-repetition-check request header)
+export const GROK_EXACT_REPETITION_CHECK = 64;

package/bundle/src/utils/providers/grok/grok-direct-client.test.ts

@@ -0,0 +1,179 @@
+import { zstdDecompressSync } from "node:zlib";
+
+import { describe, expect, it } from "vitest";
+
+import golden from "./__fixtures__/golden-responses-1.0.60.json";
+import { buildGrokResponsesRequest } from "./grok-backend-protocol";
+import {
+  GrokChatClient,
+  GrokHttpError,
+  GrokIdleTimeoutError,
+  grokProxyGet,
+} from "./grok-direct-client";
+
+const body = buildGrokResponsesRequest({
+  model: "grok-4.7",
+  history: [{ type: "message", role: "user", content: "ping" }],
+  promptCacheKey: "11111111-1111-4111-8111-111111111111",
+  effort: "high",
+});
+
+const headers = { "content-type": "application/json", authorization: "Bearer t" };
+
+function sse(events: Array<Record<string, unknown>>): string {
+  return events.map((e) => `data: ${JSON.stringify(e)}\n\n`).join("");
+}
+
+const completedStream = sse(
+  golden.response.eventTypes.map((type) =>
+    type === "response.output_text.delta"
+      ? { type, delta: "pong", item_id: "m" }
+      : type === "response.completed"
+        ? { type, response: { id: "r", usage: golden.response.terminalUsage } }
+        : { type, response: { id: "r" } },
+  ),
+);
+
+function openStream(): { stream: ReadableStream<Uint8Array>; push(text: string): void } {
+  let controller!: ReadableStreamDefaultController<Uint8Array>;
+  const stream = new ReadableStream<Uint8Array>({
+    start(c) {
+      controller = c;
+    },
+  });
+  return { stream, push: (text) => controller.enqueue(new TextEncoder().encode(text)) };
+}
+
+describe("GrokChatClient", () => {
+  it("POSTs a zstd body and parses the fixture stream without [DONE]", async () => {
+    let sent: { url: string; init: RequestInit | undefined } | undefined;
+    const client = new GrokChatClient({
+      fetch: async (input, init) => {
+        sent = { url: String(input), init };
+        return new Response(completedStream, { status: 200, headers: golden.response.headers });
+      },
+    });
+    const result = await client.stream({ body, headers });
+    expect(sent?.url).toBe("https://cli-chat-proxy.grok.com/v1/responses");
+    expect(new Headers(sent?.init?.headers).get("content-encoding")).toBe("zstd");
+    const raw = sent?.init?.body;
+    expect(raw).toBeInstanceOf(Uint8Array);
+    expect(JSON.parse(zstdDecompressSync(raw as Uint8Array).toString("utf8"))).toEqual(body);
+    expect(result.headers).toMatchObject({
+      contextWindow: 256000,
+      modelsEtag: '"4849638883941606653"',
+      rateLimitLimitTokens: 53000000,
+      rateLimitRemainingRequests: 8300,
+    });
+    const events = [];
+    for await (const event of result.events) events.push(event);
+    expect(events.map((e) => e.type)).toEqual(["created", "text-delta", "completed"]);
+    const last = events.at(-1);
+    expect(last?.type === "completed" && last.usage?.costInUsdTicks).toBe(465240000);
+  });
+
+  it("can send a plain JSON body", async () => {
+    let sent: RequestInit | undefined;
+    const client = new GrokChatClient({
+      fetch: async (_input, init) => {
+        sent = init;
+        return new Response(completedStream, { status: 200 });
+      },
+    });
+    await client.stream({ body, headers: { ...headers, "content-encoding": "zstd" }, encoding: "plain" });
+    expect(new Headers(sent?.headers).has("content-encoding")).toBe(false);
+    expect(JSON.parse(new TextDecoder().decode(sent?.body as Uint8Array))).toEqual(body);
+  });
+
+  it("rejects non-2xx with the classified error and body text", async () => {
+    const client = new GrokChatClient({
+      fetch: async () =>
+        new Response('{"error":"Your Grok CLI version (0.0.1) is outdated. Please update to version 1.0.13 or later"}', {
+          status: 426,
+        }),
+    });
+    const error = await client.stream({ body, headers }).catch((e: unknown) => e);
+    expect(error).toBeInstanceOf(GrokHttpError);
+    const http = error as GrokHttpError;
+    expect(http.classification).toMatchObject({ kind: "version_gate", minClientVersion: "1.0.13" });
+    expect(http.bodyText).toContain("outdated");
+  });
+
+  it("classifies a connect failure as transient status 0", async () => {
+    const client = new GrokChatClient({
+      fetch: async () => {
+        throw new TypeError("fetch failed");
+      },
+    });
+    const error = await client.stream({ body, headers }).catch((e: unknown) => e);
+    expect(error).toBeInstanceOf(GrokHttpError);
+    expect((error as GrokHttpError).classification).toMatchObject({ kind: "transient", status: 0 });
+  });
+
+  it("fails with GrokIdleTimeoutError and cancels the request when the stream stalls", async () => {
+    const { stream, push } = openStream();
+    let requestSignal: AbortSignal | undefined;
+    const client = new GrokChatClient({
+      fetch: async (_input, init) => {
+        requestSignal = init?.signal ?? undefined;
+        return new Response(stream, { status: 200 });
+      },
+    });
+    const result = await client.stream({ body, headers, idleTimeoutMs: 20 });
+    push(sse([{ type: "response.created", response: { id: "r" } }]));
+    const seen: string[] = [];
+    const error = await (async () => {
+      for await (const event of result.events) seen.push(event.type);
+    })().catch((e: unknown) => e);
+    expect(seen).toEqual(["created"]);
+    expect(error).toBeInstanceOf(GrokIdleTimeoutError);
+    expect(requestSignal?.aborted).toBe(true);
+  });
+
+  it("honors caller abort mid-stream", async () => {
+    const { stream, push } = openStream();
+    const controller = new AbortController();
+    const client = new GrokChatClient({ fetch: async () => new Response(stream, { status: 200 }) });
+    const result = await client.stream({ body, headers, signal: controller.signal });
+    push(sse([{ type: "response.created", response: { id: "r" } }]));
+    const pending = (async () => {
+      for await (const event of result.events) {
+        if (event.type === "created") controller.abort(new Error("caller gone"));
+      }
+    })();
+    await expect(pending).rejects.toThrow("caller gone");
+  });
+
+  it("rejects before fetch when already aborted", async () => {
+    let called = false;
+    const client = new GrokChatClient({
+      fetch: async () => {
+        called = true;
+        return new Response("");
+      },
+    });
+    await expect(
+      client.stream({ body, headers, signal: AbortSignal.abort(new Error("stop")) }),
+    ).rejects.toThrow("stop");
+    expect(called).toBe(false);
+  });
+});
+
+describe("grokProxyGet", () => {
+  it("returns JSON and response header info", async () => {
+    const result = await grokProxyGet("/models", {
+      headers: {},
+      fetch: async (input) => {
+        expect(String(input)).toBe("https://cli-chat-proxy.grok.com/v1/models");
+        return new Response('{"data":[]}', { headers: { "x-models-etag": '"1"' } });
+      },
+    });
+    expect(result).toMatchObject({ status: 200, json: { data: [] }, headers: { modelsEtag: '"1"' } });
+  });
+
+  it("throws GrokHttpError on non-2xx", async () => {
+    await expect(
+      grokProxyGet("/billing", { headers: {}, fetch: async () => new Response("no", { status: 401 }) }),
+    ).rejects.toMatchObject({ classification: { kind: "auth", status: 401 } });
+  });
+});

package/bundle/src/utils/providers/grok/grok-direct-client.ts

@@ -0,0 +1,313 @@
+import {
+  classifyGrokHttpError,
+  encodeGrokRequestBody,
+  normalizeGrokSSE,
+  readGrokResponseHeaders,
+  type GrokHttpErrorClassification,
+  type GrokNormalizedEvent,
+  type GrokResponseHeaderInfo,
+  type GrokResponsesRequest,
+} from "./grok-backend-protocol";
+import { GROK_CHAT_PROXY_URL } from "./grok-constants";
+
+// HTTPS/SSE transport for the chat proxy. Headers are built by the caller (grok-headers.ts) so the
+// fingerprint stays in one place; this module only moves bytes, classifies HTTP failures, and
+// enforces abort and idle limits.
+
+export const GROK_DEFAULT_IDLE_TIMEOUT_MS = 300_000;
+export const GROK_PROXY_GET_TIMEOUT_MS = 10_000;
+const MAX_ERROR_BODY_LENGTH = 2_000;
+
+/**
+ * A non-2xx response or a transport failure before any response arrived (`status = 0`).
+ * Media/voice ports should throw this class too, so the dispatcher can apply §5.4 handling.
+ */
+export class GrokHttpError extends Error {
+  readonly classification: GrokHttpErrorClassification;
+  readonly bodyText: string;
+  readonly responseHeaders: GrokResponseHeaderInfo;
+
+  constructor(
+    classification: GrokHttpErrorClassification,
+    bodyText: string,
+    responseHeaders: GrokResponseHeaderInfo = {},
+    options?: ErrorOptions,
+  ) {
+    const detail = classification.message ? `: ${classification.message}` : "";
+    super(
+      classification.status === 0
+        ? `Grok request failed before a response${detail}`
+        : `Grok HTTP ${classification.status} (${classification.kind})${detail}`,
+      options,
+    );
+    this.name = "GrokHttpError";
+    this.classification = classification;
+    this.bodyText = bodyText.slice(0, MAX_ERROR_BODY_LENGTH);
+    this.responseHeaders = responseHeaders;
+  }
+
+  get status(): number {
+    return this.classification.status;
+  }
+}
+
+/** The stream produced no bytes for `idleTimeoutMs`. Upstream may already be executing. */
+export class GrokIdleTimeoutError extends Error {
+  readonly idleTimeoutMs: number;
+
+  constructor(idleTimeoutMs: number) {
+    super(`Grok stream idle for ${idleTimeoutMs} ms`);
+    this.name = "GrokIdleTimeoutError";
+    this.idleTimeoutMs = idleTimeoutMs;
+  }
+}
+
+function abortReason(signal: AbortSignal): Error {
+  const reason: unknown = signal.reason;
+
+  return reason instanceof Error ? reason : new DOMException("Aborted", "AbortError");
+}
+
+function connectError(cause: unknown): GrokHttpError {
+  const message = cause instanceof Error ? cause.message : String(cause);
+
+  return new GrokHttpError({ ...classifyGrokHttpError(0, "", {}), message }, "", {}, { cause });
+}
+
+async function readErrorBody(response: Response): Promise<string> {
+  try {
+    return (await response.text()).slice(0, MAX_ERROR_BODY_LENGTH);
+  } catch {
+    return "";
+  }
+}
+
+export async function grokHttpErrorFromResponse(response: Response): Promise<GrokHttpError> {
+  const bodyText = await readErrorBody(response);
+
+  return new GrokHttpError(
+    classifyGrokHttpError(response.status, bodyText, response.headers),
+    bodyText,
+    readGrokResponseHeaders(response.headers),
+  );
+}
+
+/**
+ * Yields from `source` but fails with GrokIdleTimeoutError when no item arrives within
+ * `idleTimeoutMs`, and with the abort reason when `signal` aborts. `onStop` runs exactly once
+ * when iteration ends for any reason, so the caller can cancel the underlying request.
+ */
+async function* guardStream<T>(
+  source: AsyncIterable<T>,
+  idleTimeoutMs: number,
+  signal: AbortSignal | undefined,
+  onStop: (reason: Error | undefined) => void,
+): AsyncGenerator<T> {
+  const iterator = source[Symbol.asyncIterator]();
+  let settledNormally = false;
+  let pendingNext = false;
+  let stopped = false;
+
+  const stop = (reason: Error | undefined) => {
+    if (stopped) return;
+    stopped = true;
+    onStop(reason);
+  };
+
+  try {
+    while (true) {
+      if (signal?.aborted) throw abortReason(signal);
+      let timer: NodeJS.Timeout | undefined;
+      let removeAbort: (() => void) | undefined;
+
+      const interrupt = new Promise<never>((_, reject) => {
+        timer = setTimeout(() => reject(new GrokIdleTimeoutError(idleTimeoutMs)), idleTimeoutMs);
+
+        if (signal) {
+          const onAbort = () => reject(abortReason(signal));
+          signal.addEventListener("abort", onAbort, { once: true });
+          removeAbort = () => signal.removeEventListener("abort", onAbort);
+        }
+      });
+
+      pendingNext = true;
+
+      const next = iterator.next().finally(() => {
+        pendingNext = false;
+      });
+
+      let result: IteratorResult<T>;
+
+      try {
+        result = await Promise.race([next, interrupt]);
+      } finally {
+        clearTimeout(timer);
+        removeAbort?.();
+      }
+
+      if (result.done) {
+        settledNormally = true;
+
+        return;
+      }
+
+      yield result.value;
+    }
+  } catch (error) {
+    stop(error instanceof Error ? error : new Error(String(error)));
+    throw error;
+  } finally {
+    if (settledNormally) stop(undefined);
+    else stop(new DOMException("Grok stream consumer stopped", "AbortError"));
+
+    // A pending next() would block return(); the cancelled request settles it instead.
+    if (!pendingNext) await iterator.return?.(undefined).catch(() => undefined);
+  }
+}
+
+export interface GrokChatStreamRequest {
+  body: GrokResponsesRequest;
+  /** Complete header map from buildGrokChatHeaders (bearer included). */
+  headers: Record<string, string>;
+  signal?: AbortSignal;
+  idleTimeoutMs?: number;
+  /** Defaults to zstd, as the pinned grok-build sends. */
+  encoding?: "zstd" | "plain";
+}
+
+export interface GrokChatStream {
+  status: number;
+  headers: GrokResponseHeaderInfo;
+  events: AsyncGenerator<GrokNormalizedEvent>;
+}
+
+export interface GrokChatClientOptions {
+  fetch?: typeof fetch;
+  baseUrl?: string;
+}
+
+export class GrokChatClient {
+  readonly fetchImpl: typeof fetch;
+  readonly baseUrl: string;
+
+  constructor(options: GrokChatClientOptions = {}) {
+    this.fetchImpl = options.fetch ?? fetch;
+    this.baseUrl = options.baseUrl ?? GROK_CHAT_PROXY_URL;
+  }
+
+  /**
+   * POST {proxy}/responses. Resolves once response headers arrive; rejects with GrokHttpError on
+   * a non-2xx status or a transport failure, or with the abort reason when `signal` aborts.
+   * The stream ends at the first terminal event; `[DONE]` is not required.
+   */
+  async stream(request: GrokChatStreamRequest): Promise<GrokChatStream> {
+    request.signal?.throwIfAborted();
+
+    const encoded =
+      request.encoding === "plain"
+        ? {
+            bytes: new TextEncoder().encode(JSON.stringify(request.body)),
+            contentEncoding: undefined,
+          }
+        : await encodeGrokRequestBody(request.body);
+
+    const headers = { ...request.headers };
+
+    if (encoded.contentEncoding) headers["content-encoding"] = encoded.contentEncoding;
+    else delete headers["content-encoding"];
+
+    const controller = new AbortController();
+
+    const signal = request.signal
+      ? AbortSignal.any([request.signal, controller.signal])
+      : controller.signal;
+
+    let response: Response;
+
+    try {
+      response = await this.fetchImpl(`${this.baseUrl}/responses`, {
+        method: "POST",
+        headers,
+        body: new Uint8Array(encoded.bytes),
+        signal,
+      });
+    } catch (error) {
+      if (request.signal?.aborted) throw abortReason(request.signal);
+      throw connectError(error);
+    }
+
+    if (!response.ok) throw await grokHttpErrorFromResponse(response);
+
+    if (!response.body) {
+      throw new GrokHttpError(
+        { ...classifyGrokHttpError(502, "", response.headers), message: "empty body" },
+        "",
+        readGrokResponseHeaders(response.headers),
+      );
+    }
+
+    const events = guardStream(
+      normalizeGrokSSE(response.body),
+      request.idleTimeoutMs ?? GROK_DEFAULT_IDLE_TIMEOUT_MS,
+      request.signal,
+      (reason) => {
+        if (reason) controller.abort(reason);
+      },
+    );
+
+    return {
+      status: response.status,
+      headers: readGrokResponseHeaders(response.headers),
+      events,
+    };
+  }
+}
+
+export interface GrokProxyGetResult {
+  status: number;
+  headers: GrokResponseHeaderInfo;
+  json: unknown;
+}
+
+/** GET {proxy}{path} returning parsed JSON; rejects with GrokHttpError on failure. */
+export async function grokProxyGet(
+  path: string,
+  options: {
+    headers: Record<string, string>;
+    fetch?: typeof fetch;
+    signal?: AbortSignal;
+    baseUrl?: string;
+    timeoutMs?: number;
+  },
+): Promise<GrokProxyGetResult> {
+  const timeout = AbortSignal.timeout(options.timeoutMs ?? GROK_PROXY_GET_TIMEOUT_MS);
+  const signal = options.signal ? AbortSignal.any([options.signal, timeout]) : timeout;
+  let response: Response;
+
+  try {
+    response = await (options.fetch ?? fetch)(`${options.baseUrl ?? GROK_CHAT_PROXY_URL}${path}`, {
+      method: "GET",
+      headers: options.headers,
+      signal,
+    });
+  } catch (error) {
+    if (options.signal?.aborted) throw abortReason(options.signal);
+    throw connectError(error);
+  }
+
+  if (!response.ok) throw await grokHttpErrorFromResponse(response);
+  let json: unknown;
+
+  try {
+    json = await response.json();
+  } catch (error) {
+    throw new GrokHttpError(
+      { ...classifyGrokHttpError(502, "", response.headers), message: "invalid JSON body" },
+      "",
+      readGrokResponseHeaders(response.headers),
+      { cause: error },
+    );
+  }
+
+  return { status: response.status, headers: readGrokResponseHeaders(response.headers), json };
+}