feat(xai): expose Grok X Search as a hosted tool surface (x_search) #2190

Why

Grok 페이지의 X Search를 OpenCodex에 새 툴 서페이스로 올리려고 한다. #2188 웹서치 사이드카와는 다른 선이다.

• #2188은 ChatGPT/Claude 호스트 web_search를 사이드카로 빌려 쓰는 선택 규칙이다.
• 이 이슈는 xAI가 서버에서 실행하는 x_search 를 Codex/라우티드 턴에 노출하는 조사+구현이다. 웹이 아니라 X(트위터) 포스트/유저/스레드를 검색한다.

Grok 페이지에서 하는 방법 (2026-08-20 문서)

공식 문서:

• Overview: https://docs.x.ai/developers/tools/overview
• X Search: https://docs.x.ai/developers/tools/x-search
• Web Search (형제, 이 이슈 범위 아님): https://docs.x.ai/developers/tools/web-search
• Streaming / include: https://docs.x.ai/developers/tools/streaming-and-sync
• Pricing: https://docs.x.ai/developers/pricing

xAI는 툴을 두 종류로 나눈다. Built-in (서버 실행) 과 Function calling (클라 실행). X Search는 built-in이다. 우리가 함수로 흉내 내서 X API를 두들기면 안 되고, https://api.x.ai/v1/responses에 도구를 실어 보내면 xAI가 실행한다.

최소 호출 (문서 그대로):

curl https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.6",
    "input": [{"role":"user","content":"What are people saying about xAI on X?"}],
    "tools": [{"type":"x_search"}]
  }'

OpenAI SDK도 된다. base_url=https://api.x.ai/v1, tools: [{ type: "x_search" }]. xAI SDK는 x_search(), Vercel AI SDK는 xai.tools.xSearch().

문서에 적힌 파라미터:

가격: x_search $5 / 1k calls. view_image / view_x_video는 별도 토큰. Web Search와 같은 호출당 가격이지만 인덱스가 다르다.

스트림에서 서버 아이템 타입은 x_search_call이다 (web_search_call과 형제). raw output을 받으려면 Chat Completions 쪽에 include: ["x_search_call_output"]. Responses 쪽 include 표는 문서가 web_search_call.action.sources만 자세히 적고 x_search는 덜 적혀 있다. 프로브에서 확인할 것.

옛 Live Search (search_parameters on Chat Completions)는 2026-01-12 deprecate / 410. 이 이슈는 그 경로를 부활시키지 않는다.

web_search와 x_search는 한 요청에 같이 넣을 수 있다. 문서 overview 예제가 둘을 나란히 넣는다. 그래도 제품 서페이스는 분리한다. 웹서치 사이드카가 X를 흉내 내면 안 된다.

지금 레포가 하는 일 / 안 하는 일

• src/responses/parser.ts buildTools는 OpenAI 호스트 툴로 web_search와 image_generation만 명시적으로 drop한다 (:230-231). x_search는 이름 있는 기타 툴로 떨어져 function으로 flatten된다 (:223-228). 서버 실행이어야 할 도구가 클라 function이 된다. 라우티드 Grok이어도 호스트 실행이 아니라 모델이 가짜 함수를 부른다.
• 호스트 web_search만 stash한다 (extractHostedWebSearch, :784-787). x_search extractor가 없다.
• src/adapters/openai-responses.ts stripInvalidItemIds prefix 표에 web_search_call: "ws_"는 있고 x_search_call은 없다 (:98-106). #2173이 tsc_/ctc_를 넣은 것과 같은 구멍이다. 업스트림이 x_search_call을 돌려주면 다음 턴 id가 잘리거나 item_이 된다.
• SPARK_SAFE_TOOL_TYPES는 function / web_search / web_search_preview만 (openai-responses.ts:295). x_search 없음.
• src/web-search/*는 ChatGPT/Claude 사이드카다. xAI x_search를 실행하지 않는다.
• Grok 인증은 있다. API 키, ocx login xai OAuth (src/oauth/xai.ts), Grok CLI ~/.grok/auth.json import. 문서 예제는 API 키 + api.x.ai. OAuth/Grok CLI/Build 경로가 같은 Responses 툴을 받는지는 라이브 프로브 필요.

구현 방향 (조사 후)

1. 라이브 프로브 (머지 전 필수).
   api.x.ai API 키로 위 curl을 실제로 보낸다. 확인: HTTP 200, x_search_call 아이템, citations, allowed_x_handles 동작, 스트림 이벤트 이름, id prefix. 그다음 OAuth/Grok CLI 경로를 같은 payload로 친다. 실패하면 그 인증 모드는 노출하지 않는다.
2. 새 툴 서페이스.
   Codex/클라에 x_search를 호스트 툴로 보이게 한다. web_search 사이드카로 접지 않는다. GUI/CLI에 X Search on/off, handle allow/deny, 날짜 범위를 둔다.
3. xAI Responses로 갈 때만 호스트 패스스루.
   라우트가 xAI Responses(또는 프로브된 Grok OAuth)일 때 tools: [{type:"x_search", ...}]를 그대로 보낸다. buildTools flatten을 이 타입만 예외로 뺀다. 다른 프로바이더로 라우트되면 호스트 실행이 불가능하니 숨기거나 disable. feat(sidecar): unify web-search and vision sidecar selection (auth slot + picker/probe filters) #2188 거름망과 같이 "로직+프로브된 active만".
4. 와이어.
   x_search_call id prefix를 stripInvalidItemIds / responses-field-backfill에 넣는다. 프로브가 준 prefix를 쓴다. 스트림에 x_search_call begin/end를 릴레이한다. include로 output을 받을지 정한다.
5. 과금/가드.
   호출당 $5. video/image understanding은 기본 끄고 옵트인. handle 필터는 문서대로 20개, allow/exclude 동시 금지.

하지 않는 것

• 옛 search_parameters Live Search.
• X 공식 API를 우리가 직접 두들기는 클라 function 구현.
• feat(sidecar): unify web-search and vision sidecar selection (auth slot + picker/probe filters) #2188 웹서치 사이드카 백엔드로 x_search를 몰래 넣기.
• 프로브 없이 Grok 피커에 켜 두기.

Acceptance

• 조사 코멘트로 프로브 결과 (API 키 / OAuth / CLI)와 실제 이벤트 타입·id prefix를 남긴다.
• xAI로 가는 턴에서 x_search가 호스트 툴로 나가고, function으로 flatten되지 않는다.
• 비-xAI 라우트에는 노출되지 않는다.
• 문서 파라미터(handles, dates, image/video understanding)가 설정 가능하고 동시 allow+exclude는 거절한다.