Skip to content

Never stop coding. Free MIT AI gateway: one endpoint, 375 providers (150+ free), 1,400+ models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline & Copilot. Quota-aware auto-fallback, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 900+ contributors

15.6 KB
Raw Blame
/**
 * GrokCliExecutor — Grok Build Provider
 *
 * Routes Responses API requests through Grok's chat proxy using OAuth authentication.
 * The standard BaseExecutor transport provides streaming, retries, abort propagation,
 * proxy-aware fetch dispatch, upstream-header merging, and credential-refresh persistence.
 */

import { PROVIDERS } from "../config/constants.ts";
import {
  getGrokBuildSessionHeaders,
  GROK_BUILD_DEFAULT_REASONING_EFFORT,
  GROK_BUILD_REASONING_INCLUDE,
  GROK_BUILD_RESPONSES_URL,
  GROK_BUILD_SUPPORTED_REASONING_EFFORTS,
  GROK_BUILD_TOKEN_URL,
} from "../config/grokBuild.ts";
import { resolvePublicCred } from "../utils/publicCreds.ts";
import {
  BaseExecutor,
  type ExecuteInput,
  type ExecutorLog,
  type ProviderCredentials,
} from "./base.ts";
import { hoistGrokBuildAdditionalTools } from "./grokCliAdditionalTools.ts";
import {
  convertGrokBuildCustomTools,
  restoreGrokBuildCustomToolCalls,
} from "./grokCliCustomTools.ts";
import {
  flattenGrokBuildNamespaceTools,
  restoreGrokBuildNamespaceToolCalls,
} from "./grokCliNamespaceTools.ts";
import { stripForeignGrokBuildReasoning } from "./grokCliReasoningReplay.ts";
import { capGrokBuildTools } from "./grokCliToolCap.ts";
import { normalizeGrokBuildToolSchemas } from "./grokCliToolSchema.ts";

const GROK_BUILD_MAX_TOOLS = 200;
const GROK_BUILD_REASONING_EFFORT_SET = new Set(GROK_BUILD_SUPPORTED_REASONING_EFFORTS);
const GROK_BUILD_REFRESH_MAX_ATTEMPTS = 3;
const GROK_BUILD_REFRESH_MIN_DELAY_MS = 200;
const GROK_BUILD_TERMINAL_REFRESH_ERRORS = new Set(["invalid_grant", "invalid_client"]);
const GROK_BUILD_UNSUPPORTED_PARAMS = [
  "presencePenalty",
  "frequencyPenalty",
  "logprobs",
  "topLogprobs",
  "presence_penalty",
  "frequency_penalty",
  "top_logprobs",
  "reasoning_effort",
];
// OpenAI-only `web_search` tool arguments that Grok Build rejects with
// `400 Argument not supported: <name>`. Codex CLI sends `external_web_access` on every turn.
const GROK_BUILD_UNSUPPORTED_WEB_SEARCH_ARGS = ["external_web_access", "search_context_size"];

/**
 * Grok Build's cli-chat-proxy is stricter about Responses `function_call_output.output`
 * than OpenAI's Responses API. Agent tool results can contain truncated / incomplete
 * JSON strings or invalid `\uXXXX` escapes, which fail upstream with:
 *   Failed to parse the request body as JSON: input[N].output: unexpected end of hex escape
 *
 * Normalize outputs to valid JSON text (or plain text) before dispatch (#7611).
 */
function sanitizeGrokBuildFunctionCallOutput(output: unknown): string {
  if (output == null) return "";
  if (typeof output === "string") {
    const value = output;
    try {
      return JSON.stringify(JSON.parse(value));
    } catch {
      // fall through
    }
    // Drop incomplete \u escapes (0-3 hex digits) that break strict JSON parsers.
    const repaired = value.replace(/\\u([0-9A-Fa-f]{0,3})(?![0-9A-Fa-f])/g, "");
    try {
      return JSON.stringify(JSON.parse(repaired));
    } catch {
      return repaired.replace(/[\uD800-\uDFFF]/g, "\uFFFD");
    }
  }
  if (Array.isArray(output)) {
    const textParts = output
      .map((part) => {
        if (part && typeof part === "object") {
          const rec = part as Record<string, unknown>;
          if (typeof rec.text === "string") return rec.text;
        }
        return typeof part === "string" ? part : JSON.stringify(part);
      })
      .join("\n");
    return sanitizeGrokBuildFunctionCallOutput(textParts);
  }
  try {
    return JSON.stringify(output);
  } catch {
    return String(output);
  }
}

function sanitizeGrokBuildResponsesBody(body: Record<string, unknown>): Record<string, unknown> {
  const input = body.input;
  if (!Array.isArray(input)) return body;
  let changed = false;
  const nextInput = input.map((item) => {
    if (!item || typeof item !== "object") return item;
    const rec = item as Record<string, unknown>;
    // Codex CLI replays reasoning items with `content: null`; Grok Build then fails to decode
    // the (unmodified) encrypted blob. Omitting the key is accepted.
    if (rec.type === "reasoning" && rec.content === null) {
      changed = true;
      const { content: _content, ...rest } = rec;
      return rest;
    }
    if (rec.type !== "function_call_output") return item;
    const sanitized = sanitizeGrokBuildFunctionCallOutput(rec.output);
    if (sanitized === rec.output) return item;
    changed = true;
    return { ...rec, output: sanitized };
  });
  return changed ? { ...body, input: nextInput } : body;
}

type GrokBuildRefreshResult = Partial<ProviderCredentials> | null | undefined;

function nonEmptyString(value: unknown): string | null {
  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
}

function getRefreshRetryDelayMs(retryNumber: number): number {
  const baseDelay = Math.min(
    2_000,
    GROK_BUILD_REFRESH_MIN_DELAY_MS * 2 ** Math.max(0, retryNumber - 1)
  );
  return Math.max(1, Math.round(baseDelay * (0.5 + Math.random())));
}

function asRequestRecord(value: unknown): Record<string, unknown> {
  return value && typeof value === "object" && !Array.isArray(value)
    ? { ...(value as Record<string, unknown>) }
    : {};
}

function ensureReasoningInclude(value: unknown): unknown[] {
  const include = Array.isArray(value) ? [...value] : [];
  if (!include.includes(GROK_BUILD_REASONING_INCLUDE)) {
    include.push(GROK_BUILD_REASONING_INCLUDE);
  }
  return include;
}

function normalizeGrokBuildReasoning(
  value: unknown,
  model: string
): Record<string, unknown> | null {
  const reasoning = asRequestRecord(value);
  // Capture BEFORE stripping: an explicit (but unsupported/invalid, e.g. "none"/"off"/
  // "xhigh") effort must still count as an explicit off-switch below — only the true
  // ABSENCE of an effort key gets the model default. Restores the #7358 behavior the
  // 4.6 default accidentally regressed: without this, every explicit "none"/"off" from
  // grok-cli got silently promoted to "high", leaving no way to disable reasoning.
  const hasExplicitEffort = Object.prototype.hasOwnProperty.call(reasoning, "effort");
  if (!GROK_BUILD_REASONING_EFFORT_SET.has(String(reasoning.effort))) {
    delete reasoning.effort;
  }
  if (model === "grok-composer-2.5-fast") {
    delete reasoning.effort;
  } else if (!hasExplicitEffort) {
    reasoning.effort = GROK_BUILD_DEFAULT_REASONING_EFFORT;
  }
  return Object.keys(reasoning).length > 0 ? reasoning : null;
}

function stripUnsupportedGrokBuildParams(request: Record<string, unknown>): void {
  for (const param of GROK_BUILD_UNSUPPORTED_PARAMS) {
    delete request[param];
  }
}

function stripUnsupportedGrokBuildWebSearchArgs(tools: unknown[]): unknown[] {
  return tools.map((tool) => {
    if (!tool || typeof tool !== "object") return tool;
    const rec = tool as Record<string, unknown>;
    // Exact match on purpose: only the Responses `web_search` shape carries these args.
    if (rec.type !== "web_search") return tool;
    if (!GROK_BUILD_UNSUPPORTED_WEB_SEARCH_ARGS.some((arg) => arg in rec)) return tool;
    const next = { ...rec };
    for (const arg of GROK_BUILD_UNSUPPORTED_WEB_SEARCH_ARGS) {
      delete next[arg];
    }
    return next;
  });
}

async function refreshGrokBuildCredentialsOnce(
  body: URLSearchParams,
  credentials: ProviderCredentials,
  attempt: number,
  log?: ExecutorLog | null
): Promise<GrokBuildRefreshResult> {
  try {
    const response = await fetch(GROK_BUILD_TOKEN_URL, {
      method: "POST",
      headers: { "Content-Type": "application/x-www-form-urlencoded" },
      body,
      signal: AbortSignal.timeout(15_000),
    });
    const data = (await response.json().catch(() => ({}))) as Record<string, unknown>;

    if (!response.ok) {
      const errorCode = nonEmptyString(data.error);
      const isTerminal =
        attempt === GROK_BUILD_REFRESH_MAX_ATTEMPTS ||
        (errorCode !== null && GROK_BUILD_TERMINAL_REFRESH_ERRORS.has(errorCode));
      log?.warn?.("TOKEN_REFRESH", `Grok Build: refresh failed with status ${response.status}`);
      return isTerminal ? null : undefined;
    }

    const accessToken = nonEmptyString(data.access_token);
    if (!accessToken) {
      log?.warn?.("TOKEN_REFRESH", "Grok Build: no access_token in refresh response");
      return attempt === GROK_BUILD_REFRESH_MAX_ATTEMPTS ? null : undefined;
    }

    const expiresIn =
      typeof data.expires_in === "number" && Number.isFinite(data.expires_in) && data.expires_in > 0
        ? data.expires_in
        : 21600;
    const expiresAt = new Date(Date.now() + expiresIn * 1000).toISOString();

    log?.info?.("TOKEN_REFRESH", `Grok Build: token refreshed, expires ${expiresAt}`);

    return {
      accessToken,
      refreshToken: nonEmptyString(data.refresh_token) || credentials.refreshToken,
      expiresAt,
    };
  } catch (error) {
    log?.warn?.(
      "TOKEN_REFRESH",
      `Grok Build: refresh error: ${error instanceof Error ? error.message : String(error)}`
    );
    return attempt === GROK_BUILD_REFRESH_MAX_ATTEMPTS ? null : undefined;
  }
}

export class GrokCliExecutor extends BaseExecutor {
  constructor() {
    super("grok-cli", PROVIDERS["grok-cli"]);
  }

  buildUrl(
    _model: string,
    _stream: boolean,
    _urlIndex = 0,
    _credentials: ProviderCredentials | null = null
  ) {
    return GROK_BUILD_RESPONSES_URL;
  }

  async execute(input: ExecuteInput) {
    // Grok Build rejects `additional_tools` input items (Codex lite mode), freeform `custom`
    // tools (e.g. Codex apply_patch, lite mode's namespaced `exec`) and `namespace` tool
    // groups (Codex CLI MCP tools). Additional tools merge into `tools` first; custom tools
    // then convert, also inside namespaces, so the namespace step flattens them and renames
    // a replayed namespaced custom_tool_call to its wire name. Restore runs in reverse.
    const converted = convertGrokBuildCustomTools(hoistGrokBuildAdditionalTools(input.body));
    const { customTools } = converted;
    const { body, identityMap } = flattenGrokBuildNamespaceTools(converted.body);
    const tools = (body as { tools?: unknown } | null)?.tools;
    if (identityMap && Array.isArray(tools) && tools.length > GROK_BUILD_MAX_TOOLS) {
      input.log?.warn?.(
        "GROK_CLI",
        `Flattened namespace tools exceed the Grok Build limit: sending ${GROK_BUILD_MAX_TOOLS} ` +
          `of ${tools.length} tools`
      );
    }
    const result = await super.execute(body === input.body ? input : { ...input, body });
    if (!identityMap && !customTools) return result;
    const restore = async (response: Response) => {
      const named = identityMap
        ? await restoreGrokBuildNamespaceToolCalls(response, identityMap)
        : response;
      return customTools ? restoreGrokBuildCustomToolCalls(named, customTools) : named;
    };
    if (result instanceof Response) return restore(result);
    return { ...result, response: await restore(result.response) };
  }

  async refreshCredentials(
    credentials: ProviderCredentials,
    log?: ExecutorLog | null
  ): Promise<Partial<ProviderCredentials> | null> {
    if (!credentials?.refreshToken) {
      log?.warn?.("TOKEN_REFRESH", "Grok Build: no refresh token available");
      return null;
    }

    const clientId = resolvePublicCred("grok_id", "GROK_OAUTH_CLIENT_ID");

    const body = new URLSearchParams({
      grant_type: "refresh_token",
      client_id: clientId,
      refresh_token: credentials.refreshToken,
    });

    const providerData = credentials.providerSpecificData || {};
    const principalType = nonEmptyString(providerData.principalType);
    const principalId = nonEmptyString(providerData.principalId);
    if (principalType) body.set("principal_type", principalType);
    if (principalId) body.set("principal_id", principalId);

    for (let attempt = 1; attempt <= GROK_BUILD_REFRESH_MAX_ATTEMPTS; attempt++) {
      if (attempt > 1) {
        const delayMs = getRefreshRetryDelayMs(attempt - 1);
        log?.debug?.(
          "TOKEN_REFRESH",
          `Grok Build: retrying token refresh (${attempt}/${GROK_BUILD_REFRESH_MAX_ATTEMPTS})`
        );
        await new Promise((resolve) => setTimeout(resolve, delayMs));
      }

      const refreshed = await refreshGrokBuildCredentialsOnce(body, credentials, attempt, log);
      if (refreshed !== undefined) return refreshed;
    }

    return null;
  }

  buildHeaders(
    credentials: ProviderCredentials,
    stream = true,
    clientHeaders?: Record<string, string> | null,
    model?: string
  ) {
    const headers = super.buildHeaders(credentials, stream, clientHeaders, model);
    const providerData = credentials.providerSpecificData || {};
    const principalType = nonEmptyString(providerData.principalType);
    const sessionHeaders = getGrokBuildSessionHeaders({
      model,
      stream,
      userId: nonEmptyString(providerData.userId),
      email: nonEmptyString(credentials.email) || nonEmptyString(providerData.email),
      principalType,
    });

    // Preserve the standard GROK_CLI_USER_AGENT override produced by BaseExecutor.
    if (headers["User-Agent"] || headers["user-agent"]) {
      delete sessionHeaders["User-Agent"];
    }

    return { ...headers, ...sessionHeaders };
  }

  transformRequest(
    model: string,
    body: unknown,
    stream: boolean,
    _credentials: ProviderCredentials
  ) {
    const base = super.transformRequest(model, body, stream, _credentials);
    const transformed = asRequestRecord(base);
    if (!transformed.model) {
      transformed.model = model || "grok-composer-2.5-fast";
    }
    transformed.stream = !!stream;

    // Grok Build applies these Responses defaults before every request.
    if (transformed.store === undefined) transformed.store = false;
    transformed.include = ensureReasoningInclude(transformed.include);

    // OpenAI-compatible clients may carry fields the Grok Responses endpoint rejects.
    stripUnsupportedGrokBuildParams(transformed);
    // Grok Build cannot decrypt reasoning another provider encrypted (e.g. a codex combo turn).
    if (Array.isArray(transformed.input)) {
      transformed.input = stripForeignGrokBuildReasoning(transformed.input);
    }

    const reasoning = normalizeGrokBuildReasoning(transformed.reasoning, model);
    if (reasoning) {
      transformed.reasoning = reasoning;
    } else {
      delete transformed.reasoning;
    }

    if (Array.isArray(transformed.tools)) {
      transformed.tools = stripUnsupportedGrokBuildWebSearchArgs(transformed.tools);
    }

    // Grok Build rejects the Responses named native-tool choice (ModelToolChoice).
    // "required" is equivalent only when every offered tool is native web search;
    // with mixed tools it could force an unrelated function instead.
    if (
      asRequestRecord(transformed.tool_choice).type === "web_search" &&
      Array.isArray(transformed.tools) &&
      transformed.tools.length > 0 &&
      transformed.tools.every((tool) => asRequestRecord(tool).type === "web_search")
    ) {
      transformed.tool_choice = "required";
    }

    // xAI's cli-chat-proxy rejects requests containing more than 200 tools. The cap keeps
    // hosted web_search/x_search tools and the function tool_choice forces.
    if (Array.isArray(transformed.tools)) {
      transformed.tools = capGrokBuildTools(
        transformed.tools,
        transformed.tool_choice,
        GROK_BUILD_MAX_TOOLS
      );
    }
    // Grok Build refuses a root anyOf/oneOf with a `$ref` or non-object branch
    // (`invalid_client_tool_schema`), e.g. Codex desktop's `automation_update`.
    if (Array.isArray(transformed.tools)) {
      transformed.tools = normalizeGrokBuildToolSchemas(transformed.tools);
    }

    // Repair tool-result payloads that would fail Grok's strict JSON body parser (#7611)
    // and drop null reasoning content Grok cannot decode.
    return sanitizeGrokBuildResponsesBody(transformed);
  }
}