@cartanova/qgrid-cli 2.10.9 → 2.11.0

package/bundle/src/utils/providers/grok/__fixtures__/golden-responses-1.0.60.json

@@ -0,0 +1,164 @@
+{
+  "source": {
+    "binary": "grok-build 1.0.60",
+    "buildId": "01a8e1c591c0",
+    "capturedAt": "2026-10-16T08:08:47Z",
+    "tool": "Proxyman HAR",
+    "note": "system prompt and tool list elided; only shapes are pinned"
+  },
+  "request": {
+    "method": "POST",
+    "url": "https://cli-chat-proxy.grok.com/v1/responses",
+    "headerOrder": [
+      "content-type",
+      "user-agent",
+      "x-grok-client-mode",
+      "x-xai-token-auth",
+      "x-authenticateresponse",
+      "x-compactions-remaining",
+      "x-compaction-at",
+      "x-grok-client-version",
+      "x-grok-user-id",
+      "x-grok-conv-group-id",
+      "x-grok-client-identifier",
+      "authorization",
+      "traceparent",
+      "x-grok-conv-id",
+      "x-grok-req-id",
+      "x-grok-model-override",
+      "x-grok-session-id",
+      "x-grok-agent-id",
+      "x-grok-turn-idx",
+      "accept",
+      "x-grok-doom-loop-check",
+      "x-grok-exact-repetition-check",
+      "content-encoding",
+      "accept-encoding"
+    ],
+    "headers": {
+      "content-type": "application/json",
+      "user-agent": "grok-shell/1.0.60 (macos; aarch64)",
+      "x-grok-client-mode": "headless",
+      "x-xai-token-auth": "xai-grok-cli",
+      "x-authenticateresponse": "authenticate-response",
+      "x-compactions-remaining": "1",
+      "x-compaction-at": "204800",
+      "x-grok-client-version": "1.0.60",
+      "x-grok-user-id": "<user-id>",
+      "x-grok-conv-group-id": "<conv-group-id>",
+      "x-grok-client-identifier": "grok-shell",
+      "authorization": "Bearer <redacted>",
+      "traceparent": "<traceparent>",
+      "x-grok-conv-id": "<conv-id>",
+      "x-grok-req-id": "<req-id>",
+      "x-grok-model-override": "grok-4.7",
+      "x-grok-session-id": "<session-id>",
+      "x-grok-agent-id": "<agent-id>",
+      "x-grok-turn-idx": "1",
+      "accept": "text/event-stream",
+      "x-grok-doom-loop-check": "1024",
+      "x-grok-exact-repetition-check": "64",
+      "content-encoding": "zstd",
+      "accept-encoding": "gzip, br, deflate"
+    },
+    "bodyKeys": [
+      "include",
+      "input",
+      "model",
+      "prompt_cache_key",
+      "reasoning",
+      "store",
+      "stream",
+      "tools"
+    ],
+    "body": {
+      "include": ["reasoning.encrypted_content", "no_inline_citations"],
+      "model": "grok-4.7",
+      "prompt_cache_key": "<conv-id>",
+      "reasoning": {
+        "effort": "high",
+        "summary": "concise"
+      },
+      "store": false,
+      "stream": true,
+      "inputShape": [
+        {
+          "type": "message",
+          "role": "system",
+          "contentType": "string"
+        },
+        {
+          "type": "message",
+          "role": "user",
+          "contentType": "string"
+        },
+        {
+          "type": "message",
+          "role": "user",
+          "contentType": "string"
+        },
+        {
+          "type": "message",
+          "role": "user",
+          "contentType": "string"
+        },
+        {
+          "type": "message",
+          "role": "user",
+          "contentType": "string"
+        }
+      ],
+      "toolTypes": ["function", "x_search"],
+      "toolCount": 26
+    }
+  },
+  "response": {
+    "status": 200,
+    "headers": {
+      "content-type": "text/event-stream",
+      "x-zero-data-retention": "true",
+      "x-ratelimit-limit-tokens": "53000000",
+      "x-ratelimit-remaining-tokens": "53000000",
+      "x-ratelimit-limit-requests": "8300",
+      "x-ratelimit-remaining-requests": "8300",
+      "x-request-id": "19bfa1b2-a163-9e0c-8de1-832a73e2695e",
+      "x-data-retention": "zdr",
+      "x-models-etag": "\"4849638883941606653\"",
+      "x-grok-context-window": "256000"
+    },
+    "terminalUsage": {
+      "input_tokens": 27150,
+      "input_tokens_details": {
+        "cached_tokens": 6528
+      },
+      "output_tokens": 336,
+      "output_tokens_details": {
+        "reasoning_tokens": 335
+      },
+      "total_tokens": 27486,
+      "num_sources_used": 0,
+      "num_server_side_tools_used": 0,
+      "cost_in_usd_ticks": 465240000,
+      "context_details": {
+        "input_tokens": 27150,
+        "output_tokens": 344
+      }
+    },
+    "eventTypes": [
+      "response.created",
+      "response.in_progress",
+      "response.output_item.added",
+      "response.reasoning_summary_part.added",
+      "response.reasoning_summary_text.delta",
+      "response.reasoning_summary_text.done",
+      "response.reasoning_summary_part.done",
+      "response.output_item.done",
+      "response.content_part.added",
+      "response.output_text.delta",
+      "response.output_text.done",
+      "response.content_part.done",
+      "response.completed"
+    ],
+    "endsWithDone": false
+  }
+}

package/bundle/src/utils/providers/grok/grok-backend-protocol.test.ts

@@ -0,0 +1,325 @@
+import { zstdDecompressSync } from "node:zlib";
+
+import { describe, expect, it } from "vitest";
+
+import golden from "./__fixtures__/golden-responses-1.0.60.json";
+import {
+  buildGrokResponsesRequest,
+  classifyGrokHttpError,
+  encodeGrokRequestBody,
+  encodeGrokRequestBodyPlain,
+  normalizeGrokEvent,
+  normalizeGrokSSE,
+  parseGrokSSE,
+  readGrokResponseHeaders,
+  type GrokNormalizedEvent,
+} from "./grok-backend-protocol";
+
+function streamOf(...chunks: string[]): ReadableStream<Uint8Array> {
+  const encoder = new TextEncoder();
+  return new ReadableStream({
+    start(controller) {
+      for (const chunk of chunks) controller.enqueue(encoder.encode(chunk));
+      controller.close();
+    },
+  });
+}
+
+function sse(type: string, payload: Record<string, unknown> = {}): string {
+  return `event: ${type}\ndata: ${JSON.stringify({ type, ...payload })}\n\n`;
+}
+
+async function collect(body: ReadableStream<Uint8Array>): Promise<GrokNormalizedEvent[]> {
+  const events: GrokNormalizedEvent[] = [];
+  for await (const event of normalizeGrokSSE(body)) events.push(event);
+  return events;
+}
+
+describe("buildGrokResponsesRequest", () => {
+  it("emits the captured body keys in fixture order", () => {
+    const body = buildGrokResponsesRequest({
+      model: "grok-4.7",
+      systemPrompt: "system",
+      history: [{ type: "message", role: "user", content: "hi" }],
+      promptCacheKey: "conv-1",
+      effort: "high",
+      tools: [{ type: "function", name: "f", parameters: { type: "object" }, strict: true }],
+    });
+    expect(Object.keys(body)).toEqual(golden.request.bodyKeys);
+    expect(body.include).toEqual(golden.request.body.include);
+    expect(body.reasoning).toEqual(golden.request.body.reasoning);
+    expect(body.store).toBe(golden.request.body.store);
+    expect(body.stream).toBe(golden.request.body.stream);
+    expect(body.prompt_cache_key).toBe("conv-1");
+    expect(body.input[0]).toEqual({ type: "message", role: "system", content: "system" });
+  });
+
+  it("replays full history, appends optional keys in order and never sends server state", () => {
+    const body = buildGrokResponsesRequest({
+      model: "grok-4.5",
+      history: [
+        {
+          type: "message",
+          role: "user",
+          content: [
+            { type: "input_text", text: "what colour?" },
+            { type: "input_image", image_url: "data:image/png;base64,AAAA" },
+          ],
+        },
+        { type: "reasoning", id: "rs_1", encrypted_content: "enc" },
+        { type: "reasoning", id: "rs_foreign", summary: [{ type: "summary_text", text: "x" }] },
+        { type: "function_call", call_id: "c1", name: "f", arguments: "{}" },
+        { type: "function_call_output", call_id: "c1", output: "ok" },
+        { type: "message", role: "assistant", content: "Red." },
+      ],
+      promptCacheKey: "conv-2",
+      effort: "xhigh",
+      outputSchema: { name: "pong", schema: { type: "object" } },
+      tools: [{ type: "web_search" }, { type: "x_search" }],
+      toolChoice: "auto",
+      maxOutputTokens: 256,
+    });
+    expect(Object.keys(body)).toEqual([
+      "include",
+      "input",
+      "model",
+      "prompt_cache_key",
+      "reasoning",
+      "store",
+      "stream",
+      "text",
+      "tools",
+      "tool_choice",
+      "max_output_tokens",
+    ]);
+    expect(body.input.map((item) => item.type)).toEqual([
+      "message",
+      "reasoning",
+      "function_call",
+      "function_call_output",
+      "message",
+    ]);
+    expect(body.input[1]).toEqual({
+      type: "reasoning",
+      id: "rs_1",
+      summary: [],
+      encrypted_content: "enc",
+    });
+    expect(body.text).toEqual({
+      format: { type: "json_schema", name: "pong", strict: true, schema: { type: "object" } },
+    });
+    for (const key of ["instructions", "previous_response_id", "conversation"])
+      expect(body).not.toHaveProperty(key);
+  });
+
+  it("rejects invalid options", () => {
+    const base = { model: "grok-4.7", history: [], promptCacheKey: "k", effort: "high" } as const;
+    expect(() => buildGrokResponsesRequest({ ...base, promptCacheKey: "" })).toThrow(TypeError);
+    expect(() => buildGrokResponsesRequest({ ...base, maxOutputTokens: 0 })).toThrow(TypeError);
+  });
+});
+
+describe("Grok body encoding", () => {
+  const body = buildGrokResponsesRequest({
+    model: "grok-4.7",
+    history: [{ type: "message", role: "user", content: "ping" }],
+    promptCacheKey: "k",
+    effort: "low",
+  });
+
+  it("zstd-compresses JSON that round-trips", async () => {
+    const encoded = await encodeGrokRequestBody(body);
+    expect(encoded.contentEncoding).toBe("zstd");
+    expect(JSON.parse(zstdDecompressSync(encoded.bytes).toString("utf8"))).toEqual(body);
+  });
+
+  it("has a plain variant", () => {
+    const encoded = encodeGrokRequestBodyPlain(body);
+    expect(encoded.contentEncoding).toBeUndefined();
+    expect(JSON.parse(new TextDecoder().decode(encoded.bytes))).toEqual(body);
+  });
+});
+
+describe("normalizeGrokEvent / normalizeGrokSSE", () => {
+  it("accepts every captured event type and ends at response.completed without [DONE]", async () => {
+    expect(golden.response.endsWithDone).toBe(false);
+    const chunks = golden.response.eventTypes.map((type) => {
+      if (type === "response.created") return sse(type, { response: { id: "resp_1" } });
+      if (type.endsWith(".delta")) return sse(type, { item_id: "it", delta: "x" });
+      if (type.startsWith("response.output_item."))
+        return sse(type, { item: { type: "message", id: "it" } });
+      if (type === "response.completed")
+        return sse(type, {
+          response: { id: "resp_1", model: "grok-4.7", usage: golden.response.terminalUsage },
+        });
+      return sse(type, { item_id: "it" });
+    });
+    // Split mid-way through a block and a CRLF to exercise chunk boundaries.
+    const joined = chunks.join("").replace("\n\n", "\r\n\r\n");
+    const events = await collect(streamOf(joined.slice(0, 37), joined.slice(37, 38), joined.slice(38)));
+    expect(events.map((event) => event.type)).toEqual([
+      "created",
+      "output-item",
+      "reasoning-summary-delta",
+      "output-item",
+      "text-delta",
+      "completed",
+    ]);
+    expect(events.at(-1)).toEqual({
+      type: "completed",
+      terminal: true,
+      responseId: "resp_1",
+      model: "grok-4.7",
+      usage: {
+        inputTokens: 27150,
+        cachedInputTokens: 6528,
+        outputTokens: 336,
+        reasoningTokens: 335,
+        totalTokens: 27486,
+        numSourcesUsed: 0,
+        numServerSideToolsUsed: 0,
+        costInUsdTicks: 465240000,
+        contextInputTokens: 27150,
+        contextOutputTokens: 344,
+      },
+    });
+  });
+
+  it("treats incomplete and failed as terminal", async () => {
+    const incomplete = await collect(
+      streamOf(
+        sse("response.incomplete", {
+          response: { id: "r", incomplete_details: { reason: "max_output_tokens" } },
+        }),
+        sse("response.output_text.delta", { delta: "ignored after terminal" }),
+      ),
+    );
+    expect(incomplete).toEqual([
+      { type: "incomplete", terminal: true, responseId: "r", reason: "max_output_tokens" },
+    ]);
+    const failed = normalizeGrokEvent({
+      data: JSON.stringify({
+        type: "response.failed",
+        response: { error: { code: "server_error", message: "boom" } },
+      }),
+    });
+    expect(failed).toMatchObject({ type: "error", terminal: true, error: { code: "server_error" } });
+  });
+
+  it("uses the SSE event name when the data has no type and tolerates [DONE]", () => {
+    expect(
+      normalizeGrokEvent({ event: "response.output_text.delta", data: '{"delta":"hi"}' }),
+    ).toEqual({ type: "text-delta", text: "hi" });
+    expect(normalizeGrokEvent({ data: "[DONE]" })).toBeUndefined();
+  });
+
+  it("rejects a stream that closes before a terminal event and invalid JSON", async () => {
+    await expect(collect(streamOf(sse("response.created", {})))).rejects.toThrow(
+      /closed before a terminal event/,
+    );
+    expect(() => normalizeGrokEvent({ data: "{" })).toThrow(/Invalid Grok SSE JSON/);
+  });
+
+  it("parses event names, comments and a BOM", async () => {
+    const blocks = [];
+    for await (const block of parseGrokSSE(streamOf("\uFEFF: ping\n\nevent: a\ndata: 1\ndata: 2\n\n")))
+      blocks.push(block);
+    expect(blocks).toEqual([{ event: "a", data: "1\n2" }]);
+  });
+});
+
+describe("readGrokResponseHeaders", () => {
+  it("reads the captured response headers", () => {
+    expect(readGrokResponseHeaders(new Headers(golden.response.headers))).toEqual({
+      contextWindow: 256000,
+      modelsEtag: '"4849638883941606653"',
+      requestId: "19bfa1b2-a163-9e0c-8de1-832a73e2695e",
+      rateLimitLimitTokens: 53000000,
+      rateLimitRemainingTokens: 53000000,
+      rateLimitLimitRequests: 8300,
+      rateLimitRemainingRequests: 8300,
+      zeroDataRetention: true,
+    });
+  });
+
+  it("reads x-zero-data-retention only as an explicit boolean", () => {
+    expect(readGrokResponseHeaders({ "X-Zero-Data-Retention": "TRUE" })).toEqual({
+      zeroDataRetention: true,
+    });
+    expect(readGrokResponseHeaders({ "x-zero-data-retention": "false" })).toEqual({
+      zeroDataRetention: false,
+    });
+    expect(readGrokResponseHeaders({ "x-zero-data-retention": "zdr" })).toEqual({});
+    expect(readGrokResponseHeaders({})).toEqual({});
+  });
+});
+
+describe("classifyGrokHttpError", () => {
+  it("classifies the U0 426 body as a version gate and parses the minimum version", () => {
+    const body = JSON.stringify({
+      error:
+        "Your Grok CLI version (0.0.1) is outdated. Please update to version 1.0.13 or later to continue.",
+    });
+    expect(classifyGrokHttpError(426, body, {})).toMatchObject({
+      kind: "version_gate",
+      status: 426,
+      minClientVersion: "1.0.13",
+    });
+  });
+
+  it("classifies a 400 invalid_image body", () => {
+    const body = JSON.stringify({
+      code: "invalid_image",
+      error: "Image dimensions must be at least 8 pixels on each side",
+    });
+    expect(classifyGrokHttpError(400, body, {})).toEqual({
+      kind: "invalid_request",
+      status: 400,
+      code: "invalid_image",
+      message: "Image dimensions must be at least 8 pixels on each side",
+    });
+  });
+
+  it("separates rate limiting from subscription exhaustion", () => {
+    expect(
+      classifyGrokHttpError(429, "slow down", new Headers({ "retry-after": "17" })),
+    ).toMatchObject({ kind: "rate_limited", retryAfterSec: 17 });
+    expect(
+      classifyGrokHttpError(
+        429,
+        JSON.stringify({ error: "Too many requests: subscription:free-usage-exhausted" }),
+        { "Retry-After": "60" },
+      ),
+    ).toMatchObject({ kind: "quota_exhausted", code: "subscription:free-usage-exhausted" });
+  });
+
+  it("parses an HTTP-date Retry-After", () => {
+    const date = new Date(Date.now() + 30_000).toUTCString();
+    const result = classifyGrokHttpError(429, "", { "retry-after": date });
+    expect(result.retryAfterSec).toBeGreaterThanOrEqual(28);
+    expect(result.retryAfterSec).toBeLessThanOrEqual(31);
+  });
+
+  it.each([
+    [401, "auth"],
+    [403, "entitlement"],
+    [422, "invalid_request"],
+    [404, "permanent"],
+    [408, "transient"],
+    [500, "transient"],
+    [503, "transient"],
+    [0, "transient"],
+  ] as const)("maps %i to %s", (status, kind) => {
+    expect(classifyGrokHttpError(status, "", {}).kind).toBe(kind);
+  });
+
+  it("exposes x-should-retry overrides", () => {
+    expect(classifyGrokHttpError(500, "", { "x-should-retry": "false" }).shouldRetry).toBe(false);
+    expect(classifyGrokHttpError(409, "", { "x-should-retry": "true" }).shouldRetry).toBe(true);
+    expect(classifyGrokHttpError(500, "", {})).not.toHaveProperty("shouldRetry");
+  });
+
+  it("caps the surfaced message length", () => {
+    expect(classifyGrokHttpError(500, "x".repeat(5000), {}).message).toHaveLength(500);
+  });
+});