@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
230 lines (221 loc) • 10.4 kB
text/typescript
/**
* Execute ONE web search via a Grok sidecar through the STORED xai OAuth credential (#2188 L7).
*
* POSTs the canonical api.x.ai Responses endpoint with the hosted web_search tool (plus the
* opt-in x_search tool) and reduces the SSE stream to a SidecarOutcome. Wire shapes are
* probe-verified (devlog 003 / 070): reasoning.effort is accepted alongside tools; both hosted
* tools may share one request; annotations arrive as url_citation events on message items;
* x_search activity surfaces as custom_tool_call items (ctc_) rather than the documented
* x_search_call — both are tolerated, neither is required. `action` may be absent on
* output_item.added (skeleton-first) and fills in later. Never throws — returns `{error}` so
* the caller injects a graceful tool result.
*/
import type { OcxProviderConfig } from "../types";
import { getValidAccessToken, publicOAuthAuthenticationErrorMessage } from "../oauth";
import { applyUpstreamRecoveryInit, fetchWithResetRetry } from "../lib/upstream-retry";
import { cancelBodyOnAbort, signalWithTimeout } from "../lib/abort";
import { readBoundedResponseBytes } from "../lib/bounded-body";
import { sidecarEnter } from "../lib/sidecar-tracker";
import { redactSecretString } from "../lib/redact";
import { MAX_SIDECAR_RESPONSE_BYTES, type WebSearchSource } from "./parse";
import { BASE_INSTRUCTION, IMAGE_INSTRUCTION, type SidecarOutcome, type SidecarSettings } from "./executor";
/** The one destination the OAuth credential may be sent to; provider.baseUrl is honored only on the same origin. */
const XAI_RESPONSES_ORIGIN = "https://api.x.ai";
export interface XaiSearchOptions {
/** Opt-in: add the hosted x_search tool next to web_search. */
xSearch?: boolean;
allowedXHandles?: string[];
excludedXHandles?: string[];
fromDate?: string;
toDate?: string;
}
const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
/** Doc-validated limits (docs.x.ai x-search): <=20 handles, allow XOR exclude, ISO dates. */
export function validateXaiSearchOptions(options: XaiSearchOptions): string | undefined {
const allowed = options.allowedXHandles ?? [];
const excluded = options.excludedXHandles ?? [];
if (allowed.length > 0 && excluded.length > 0) return "allowedXHandles and excludedXHandles are mutually exclusive";
if (allowed.length > 20) return "allowedXHandles admits at most 20 handles";
if (excluded.length > 20) return "excludedXHandles admits at most 20 handles";
for (const [field, value] of [["fromDate", options.fromDate], ["toDate", options.toDate]] as const) {
if (value !== undefined && !ISO_DATE.test(value)) return `${field} must be an ISO-8601 date (YYYY-MM-DD)`;
}
return undefined;
}
function buildXSearchTool(options: XaiSearchOptions): Record<string, unknown> {
return {
type: "x_search",
...(options.allowedXHandles?.length ? { allowed_x_handles: options.allowedXHandles } : {}),
...(options.excludedXHandles?.length ? { excluded_x_handles: options.excludedXHandles } : {}),
...(options.fromDate ? { from_date: options.fromDate } : {}),
...(options.toDate ? { to_date: options.toDate } : {}),
};
}
function isRec(v: unknown): v is Record<string, unknown> {
return !!v && typeof v === "object" && !Array.isArray(v);
}
export async function runXaiWebSearch(
query: string,
providerName: string,
provider: OcxProviderConfig,
settings: SidecarSettings,
options: XaiSearchOptions = {},
abortSignal?: AbortSignal,
): Promise<SidecarOutcome> {
const invalid = validateXaiSearchOptions(options);
if (invalid) return { text: "", sources: [], error: `xai sidecar options invalid: ${invalid}` };
let token: string;
try {
token = await getValidAccessToken(providerName);
} catch (e) {
return { text: "", sources: [], error: `xai sidecar auth failed: ${publicOAuthAuthenticationErrorMessage(e)}` };
}
// Credential pinning: only the EXACT api.x.ai origin may carry the OAuth bearer.
// A prefix check would admit https://api.x.ai.evil/ (review Critical); parse and
// compare origins, falling back to the canonical endpoint on any mismatch.
let base = `${XAI_RESPONSES_ORIGIN}/v1`;
if (provider.baseUrl) {
try {
const parsed = new URL(provider.baseUrl);
if (parsed.origin === XAI_RESPONSES_ORIGIN) base = provider.baseUrl.replace(/\/+$/, "");
} catch { /* malformed baseUrl: keep the canonical endpoint */ }
}
const url = `${base}/responses`;
const instruction = settings.describeImages ? BASE_INSTRUCTION + IMAGE_INSTRUCTION : BASE_INSTRUCTION;
const body = {
model: settings.model,
instructions: instruction,
input: [{ role: "user", content: query }],
tools: [{ type: "web_search" }, ...(options.xSearch ? [buildXSearchTool(options)] : [])],
include: ["web_search_call.action.sources"],
reasoning: { effort: settings.reasoning },
stream: true,
};
const linkedSignal = signalWithTimeout(settings.timeoutMs, abortSignal);
const sidecarExit = sidecarEnter("web-search");
const t0 = Date.now();
try {
const res = await fetchWithResetRetry(
recovery => fetch(url, applyUpstreamRecoveryInit({
method: "POST",
headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}` },
body: JSON.stringify(body),
signal: linkedSignal.signal,
// Credential-bearing: never follow a redirect off the pinned origin.
redirect: "manual",
}, recovery)),
{ replaySafe: true, abortSignal: linkedSignal.signal, label: "xai-web-search-sidecar" },
);
const detachBodyGuard = cancelBodyOnAbort(res.body, linkedSignal.signal);
if (!res.ok) {
try {
const bounded = await readBoundedResponseBytes(res, {
maxBytes: MAX_SIDECAR_RESPONSE_BYTES,
signal: linkedSignal.signal,
});
const detail = bounded.oversized
? "response body exceeded byte bound"
: redactSecretString(new TextDecoder().decode(bounded.bytes).slice(0, 200));
const entitlement = res.status === 401 || res.status === 403 ? " (Grok OAuth entitlement — re-run ocx login xai?)" : "";
return { text: "", sources: [], error: `xai sidecar HTTP ${res.status}${entitlement}: ${detail}` };
} finally {
detachBodyGuard();
}
}
try {
return await parseXaiResponsesSSE(res);
} finally {
detachBodyGuard();
}
} catch (e) {
const kind = e instanceof Error && e.name === "TimeoutError" ? "timeout" : "connect_error";
console.warn(`[web-search] xai sidecar ${kind} (${Date.now() - t0}ms)`);
return { text: "", sources: [], error: redactSecretString(e instanceof Error ? e.message : String(e)) };
} finally {
sidecarExit();
linkedSignal.cleanup();
}
}
/**
* Reduce a Grok Responses SSE stream to a SidecarOutcome (probe-shapes in devlog 003):
* text from output_text deltas on message items; sources from url_citation annotations
* unioned with web_search_call action.sources (deduped by url). Tolerates custom_tool_call
* and x_search_call items, absent `action`, and unknown event names. Bounds raw bytes.
*/
export async function parseXaiResponsesSSE(response: Response): Promise<SidecarOutcome> {
if (!response.body) return { text: "", sources: [] };
const reader = response.body.getReader();
const decoder = new TextDecoder();
let buffer = "";
let responseBytes = 0;
let text = "";
let doneText = "";
const sourceUrls = new Map<string, WebSearchSource>();
let error: string | null = null;
const addSource = (url: unknown, title?: unknown) => {
if (typeof url !== "string" || url.length === 0) return;
if (!sourceUrls.has(url)) sourceUrls.set(url, { url, ...(typeof title === "string" && title.length > 0 && title !== url ? { title } : {}) });
};
try {
while (true) {
const { done, value } = await reader.read();
if (done) break;
responseBytes += value.byteLength;
if (responseBytes > MAX_SIDECAR_RESPONSE_BYTES * 8) {
error = "xai sidecar stream exceeded byte bound";
await reader.cancel(error).catch(() => {});
break;
}
buffer += decoder.decode(value, { stream: true });
let idx;
while ((idx = buffer.indexOf("\n\n")) >= 0) {
const frame = buffer.slice(0, idx);
buffer = buffer.slice(idx + 2);
const dataLine = frame.match(/^data: (.+)$/m)?.[1];
if (!dataLine || dataLine === "[DONE]") continue;
let payload: unknown;
try { payload = JSON.parse(dataLine); } catch { continue; }
if (!isRec(payload) || typeof payload.type !== "string") continue;
switch (payload.type) {
case "response.output_text.delta": {
if (typeof payload.delta === "string") text += payload.delta;
break;
}
case "response.output_text.done": {
if (typeof payload.text === "string") doneText = payload.text;
break;
}
case "response.output_text.annotation.added": {
const annotation = payload.annotation;
if (isRec(annotation) && annotation.type === "url_citation") addSource(annotation.url, annotation.title);
break;
}
case "response.output_item.done": {
const item = payload.item;
if (isRec(item) && item.type === "web_search_call" && isRec(item.action) && Array.isArray(item.action.sources)) {
for (const s of item.action.sources) if (isRec(s)) addSource(s.url);
}
break;
}
case "response.failed":
case "error": {
const message = isRec(payload.response) && isRec(payload.response.error) && typeof payload.response.error.message === "string"
? payload.response.error.message
: typeof payload.message === "string" ? payload.message : "upstream reported failure";
error = redactSecretString(String(message).slice(0, 200));
break;
}
default: break;
}
}
}
} catch (e) {
error = redactSecretString(e instanceof Error ? e.message : String(e));
} finally {
reader.releaseLock();
}
const finalText = doneText.length >= text.length ? doneText : text;
const outcome: SidecarOutcome = { text: finalText, sources: [...sourceUrls.values()] };
if (error && finalText.length === 0) outcome.error = error;
return outcome;
}