@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
569 lines (550 loc) • 24 kB
text/typescript
// LOCAL PATCH (runturn-websearch): web-search sidecar loop for runTurn adapters.
//
// Upstream's runWithWebSearch (loop.ts) only drives the buildRequest/fetch/
// parseStream transport, so adapters that own their turn loop (devin, cursor,
// qoder, codebuddy) silently dropped the hosted `web_search` declaration. This
// module replays the same interception contract over the runTurn event stream:
// the synthetic `web_search` function tool is injected into each iteration's
// tool list, calls to it are intercepted and executed through the configured
// sidecar backend, and the assistant call + toolResult are appended to the
// OcxMessage history before the next runTurn dispatch. Everything else passes
// through untouched.
//
// The file is deliberately self-contained (small helpers duplicated from
// loop.ts instead of exported) so the patch stays a pure addition plus a few
// small call-site edits — easier to re-apply after `ocx update`.
import type {
AdapterEvent,
OcxAssistantContentPart,
OcxMessage,
OcxParsedRequest,
OcxProviderConfig,
} from "../types";
import type { SidecarPlan } from "./index";
import { WEB_SEARCH_TOOL_NAME, buildWebSearchTool } from "./synthetic-tool";
import { hasVisibleAssistantText, scanEventsForWebSearch } from "./loop";
import { isTruncatedStopReason } from "../responses/truncated-stop-reason";
import {
runWebSearch,
type SidecarOutcome,
type SidecarOutcomeRecorder,
} from "./executor";
import { runAnthropicWebSearch } from "./anthropic-executor";
import { runXaiWebSearch } from "./xai-executor";
import { runGeminiWebSearch } from "./gemini-executor";
import { runExaWebSearch } from "./exa-executor";
import { formatWebSearchResults } from "./format-result";
import { cloneProviderOpaqueToolCallMetadata } from "../responses/provider-opaque-metadata";
import { redactSecretString } from "../lib/redact";
import { guardEmptyCompletionEventStream } from "../server/responses/empty-completion-guard";
import {
isTranslatorBudgetExceededError,
type TranslatorBudget,
} from "../lib/translator-budget";
import { jsonUtf8Bytes } from "../lib/json-byte-size";
export interface RunTurnWebSearchDeps {
parsed: OcxParsedRequest;
plan: SidecarPlan;
/** Required for the openai backend (ChatGPT forward path). */
forwardProvider?: OcxProviderConfig;
forwardHeaders?: Headers;
/** Operator key for the exa backend; read from config by the caller. */
exaApiKey?: string;
abortSignal?: AbortSignal;
recordSidecarOutcome?: SidecarOutcomeRecorder;
/** Preserve the request's opt-in empty-completion retry before the search cap. */
emptyCompletionRetry?: boolean;
/**
* Optional request translator budget. When present the loop charges what it
* retains — each iteration's buffered event batch and the replay history it
* appends to messages — with its own local byte counters, and releases
* exactly those totals when the retention ends. It deliberately does NOT use
* the shared event-ownership WeakMap helpers: other owners (queue, bridge,
* output collector) may hold independent leases on the same event objects.
*/
translatorBudget?: TranslatorBudget;
/**
* Dispatch one more routed-model iteration. Iterations 2+ get a fresh event
* stream from the runTurn transport with the grown message history.
*/
dispatch: (iterParsed: OcxParsedRequest) => AsyncIterable<AdapterEvent>;
}
/**
* Parsed request for the FIRST iteration when the runTurn web-search loop is
* active: same request plus the synthetic tool so the model can ask to search.
*/
export function runTurnWebSearchInitialParsed(parsed: OcxParsedRequest): OcxParsedRequest {
return {
...parsed,
context: {
...parsed.context,
tools: [...(parsed.context.tools ?? []), buildWebSearchTool()],
},
};
}
// --- helpers duplicated from loop.ts (kept private there; see header note) ---
function normalizeQuery(q: string): string {
return q.trim().toLowerCase().replace(/\s+/g, " ");
}
/**
* Rebuild the assistant content parts that preceded a web_search call in this
* iteration: visible text AND thinking, in event order, so the replayed
* assistant message preserves everything the model emitted before the call.
* Thinking extraction mirrors loop.ts's rules (signed blocks keep their own
* signature, raw reasoning stays a separate unsigned part); text_delta parts
* are folded in as OcxTextContent — upstream's thinking-only version silently
* dropped visible text that preceded a tool call.
*/
function extractIterationContent(events: AdapterEvent[]): OcxAssistantContentPart[] {
const parts: OcxAssistantContentPart[] = [];
let text = "";
let thinking = "";
let signature: string | undefined;
let rawReasoning = "";
const flushText = () => {
if (!text) return;
parts.push({ type: "text", text });
text = "";
};
const flushVisible = () => {
if (!thinking && !signature) return;
parts.push({ type: "thinking", thinking, ...(signature ? { signature } : {}) });
thinking = "";
signature = undefined;
};
const flushRaw = () => {
if (!rawReasoning) return;
parts.push({ type: "thinking", thinking: rawReasoning });
rawReasoning = "";
};
for (const e of events) {
if (e.type === "thinking_delta") {
flushText();
flushRaw();
thinking += e.thinking;
} else if (e.type === "reasoning_raw_delta") {
flushText();
flushVisible();
rawReasoning += e.text;
} else if (e.type === "thinking_signature") {
signature = e.signature;
flushVisible();
} else if (e.type === "redacted_thinking") {
flushText();
flushVisible();
flushRaw();
parts.push({ type: "thinking", thinking: "", redacted: [e.data] });
} else if (e.type === "text_delta") {
flushVisible();
flushRaw();
text += e.text;
}
}
flushText();
flushVisible();
flushRaw();
return parts;
}
function forcedAnswerNudge(): OcxMessage {
return {
role: "developer",
content:
"Answer the user's question now using the web search results already gathered above. " +
"Ground your answer in what those results actually say, and reference the relevant sources " +
"when they are available. Do not claim you lack information that the results contain, and do " +
"not invent sources that were not returned.",
timestamp: Date.now(),
};
}
/**
* Transient developer-role nudge for the ONE recovery pass after a forced
* answer came back empty. The recovery also removes every tool (toolChoice:
* "none"), so the model has nothing to call and can only return text.
*/
function forcedAnswerRetryNudge(): OcxMessage {
return {
role: "developer",
content:
"Your previous response contained no usable answer. Web search has finished for this turn and " +
"no tools are available for this response. Answer the user's question now in assistant text, " +
"using the web search results already gathered above. If those results are insufficient, say " +
"what is missing instead of returning an empty response.",
timestamp: Date.now(),
};
}
/**
* Drive a runTurn adapter through the web-search loop. `first` is iteration
* 0's already-dispatched event stream (built from
* runTurnWebSearchInitialParsed); later iterations go through deps.dispatch.
* Intermediate iterations emit only heartbeats and the search cell begin/end
* pair — their text/thinking is folded back into the replayed history instead
* of reaching the client mid-turn, matching the fetch-path loop's ordering.
*/
export async function* runTurnWebSearchLoop(
first: AsyncIterable<AdapterEvent>,
deps: RunTurnWebSearchDeps,
): AsyncGenerator<AdapterEvent> {
const { parsed, plan, abortSignal } = deps;
const messages: OcxMessage[] = [...parsed.context.messages];
const allTools = [...(parsed.context.tools ?? []), buildWebSearchTool()];
const toolsNoWebSearch = (parsed.context.tools ?? []).filter(t => !t.webSearch);
const failedQueries = new Set<string>();
let searchesExecuted = 0;
let executedSearchCount = 0;
const HARD_CAP = plan.maxSearches + 3;
let source = first;
const loopT0 = Date.now();
// Translator-budget ownership (deps.translatorBudget): the loop charges only
// what it retains, tracks both totals locally, and releases exactly those
// amounts — never a shared stage total another owner may also be releasing
// from. Iteration event buffers release when the iteration's events are
// consumed; the replay history appended to messages stays charged until the
// loop exits because every later dispatch rebuilds its request from it.
// Event objects are NOT leased through the shared ownership WeakMap: the
// queue, the bridge, and the buffered-path output collector may each hold
// their own independent accounting on the same objects.
let bufferedBytes = 0;
let historyBytes = 0;
const chargeBuffered = (event: AdapterEvent): void => {
if (!deps.translatorBudget) return;
// Same per-event convention as retainTranslatedEvent: the first event owns
// the array brackets, later events own their separator.
const bytes = jsonUtf8Bytes(event) + (bufferedBytes === 0 ? 2 : 1);
deps.translatorBudget.chargeRetained(bytes, { kind: "retained_collectors" });
bufferedBytes += bytes;
};
const releaseBuffered = (): void => {
if (!deps.translatorBudget || bufferedBytes === 0) return;
deps.translatorBudget.releaseRetained(bufferedBytes, { kind: "retained_collectors" });
bufferedBytes = 0;
};
const chargeHistory = (message: OcxMessage): void => {
if (!deps.translatorBudget) return;
const bytes = jsonUtf8Bytes(message) + 1;
deps.translatorBudget.chargeRetained(bytes, { kind: "request_copies" });
historyBytes += bytes;
};
const releaseHistory = (): void => {
if (!deps.translatorBudget || historyBytes === 0) return;
deps.translatorBudget.releaseRetained(historyBytes, { kind: "request_copies" });
historyBytes = 0;
};
// Shared budget-failure convention (loop.ts): a 502 upstream_error carrying
// the translation_buffer_limit code.
const budgetErrorEvent = (): AdapterEvent => ({
type: "error",
status: 502,
errorType: "upstream_error",
code: "translation_buffer_limit",
message: "upstream translation buffer exceeded the safe limit",
});
const appendMessage = (message: OcxMessage): void => {
chargeHistory(message);
messages.push(message);
};
const liveTypes = new Set<AdapterEvent["type"]>([
"text_delta", "thinking_delta", "reasoning_raw_delta", "thinking_signature",
"redacted_thinking", "kiro_redacted_reasoning",
]);
const executeQuery = async (query: string, signal: AbortSignal | undefined): Promise<SidecarOutcome> => {
try {
switch (plan.backend) {
case "anthropic":
return plan.anthropicSidecar
? await runAnthropicWebSearch(query, plan.anthropicSidecar.providerName, plan.anthropicSidecar.provider, plan.settings, signal)
: { text: "", sources: [], error: "anthropic backend selected without a resolved sidecar provider" };
case "xai":
return plan.xaiSidecar
? await runXaiWebSearch(query, plan.xaiSidecar.providerName, plan.xaiSidecar.provider, plan.settings, plan.xaiSearchOptions ?? {}, signal)
: { text: "", sources: [], error: "xai backend selected without a resolved Grok OAuth provider" };
case "gemini":
return plan.geminiSidecar
? await runGeminiWebSearch(query, plan.geminiSidecar.providerName, plan.geminiSidecar.provider, plan.settings, signal)
: { text: "", sources: [], error: "gemini backend selected without a resolved Antigravity provider" };
case "exa":
return deps.exaApiKey
? await runExaWebSearch(query, deps.exaApiKey, plan.settings, signal)
: { text: "", sources: [], error: "exa backend selected without an exaApiKey" };
default:
return deps.forwardProvider
? await runWebSearch(query, plan.hostedTool, deps.forwardProvider, deps.forwardHeaders ?? new Headers(), plan.settings, signal, deps.recordSidecarOutcome)
: { text: "", sources: [], error: "openai backend selected without a resolved forward sidecar" };
}
} catch (e) {
return { text: "", sources: [], error: `sidecar failed: ${redactSecretString(e instanceof Error ? e.message : String(e))}` };
}
};
async function* runSearchCall(
call: { id: string; queries: string[]; providerMetadata?: Parameters<typeof cloneProviderOpaqueToolCallMetadata>[0] },
precedingContent: OcxAssistantContentPart[],
): AsyncGenerator<AdapterEvent> {
const results: { query: string; outcome: SidecarOutcome }[] = [];
let beganCell = false;
if (call.queries.length === 0) {
searchesExecuted++;
results.push({ query: "", outcome: { text: "", sources: [], error: "the model called web_search with an empty query" } });
}
for (const query of call.queries) {
if (abortSignal?.aborted) {
if (beganCell) yield { type: "web_search_call_end", id: call.id, queries: call.queries, status: "failed" };
return;
}
yield { type: "heartbeat" };
if (abortSignal?.aborted) {
if (beganCell) yield { type: "web_search_call_end", id: call.id, queries: call.queries, status: "failed" };
return;
}
let outcome: SidecarOutcome;
if (failedQueries.has(normalizeQuery(query))) {
outcome = { text: "", sources: [], error: "this query already failed earlier in the turn — do not call web_search again for it; answer from existing context" };
} else if (searchesExecuted >= plan.maxSearches) {
outcome = { text: "", sources: [], error: "web search limit reached for this turn — answer from results already gathered" };
} else {
if (!beganCell) {
beganCell = true;
yield { type: "web_search_call_begin", id: call.id };
}
if (abortSignal?.aborted) {
yield { type: "web_search_call_end", id: call.id, queries: call.queries, status: "failed" };
return;
}
outcome = await executeQuery(query, abortSignal);
if (abortSignal?.aborted) {
// The client already saw this cell's begin — close it so the UI never
// shows a "Searching the web" spinner that never resolves.
yield { type: "web_search_call_end", id: call.id, queries: call.queries, status: "failed" };
return;
}
searchesExecuted++;
executedSearchCount++;
if (outcome.error) failedQueries.add(normalizeQuery(query));
}
results.push({ query, outcome });
}
const now = Date.now();
const callArgs: Record<string, unknown> = call.queries.length > 1
? { queries: call.queries }
: { query: call.queries[0] ?? "" };
appendMessage({
role: "assistant",
content: [
...precedingContent,
{
type: "toolCall" as const,
id: call.id,
name: WEB_SEARCH_TOOL_NAME,
arguments: callArgs,
...(cloneProviderOpaqueToolCallMetadata(call.providerMetadata)
? { providerMetadata: cloneProviderOpaqueToolCallMetadata(call.providerMetadata) }
: {}),
},
],
timestamp: now,
});
const allFailed = results.every(r => !!r.outcome.error);
appendMessage({
role: "toolResult", toolCallId: call.id, toolName: WEB_SEARCH_TOOL_NAME,
content: formatWebSearchResults(results, !!parsed._structuredOutput),
isError: allFailed, timestamp: now,
});
if (beganCell) {
const anySuccess = results.some(r => !r.outcome.error);
const sources: { url: string; title?: string }[] = [];
const seenSrc = new Set<string>();
for (const r of results) {
for (const s of r.outcome.sources) {
if (seenSrc.has(s.url)) continue;
seenSrc.add(s.url);
sources.push(s.title ? { url: s.url, title: s.title } : { url: s.url });
}
}
yield {
type: "web_search_call_end", id: call.id,
queries: call.queries,
status: anySuccess ? "completed" : "failed",
...(sources.length > 0 ? { sources } : {}),
};
}
}
const abortEvent = (): AdapterEvent => ({
type: "error",
message: "client closed request during web-search",
});
const logDone = (iterations: number): void => {
if (executedSearchCount === 0) return;
const failedCount = failedQueries.size;
console.warn(
`[web-search-runturn] done — ${executedSearchCount} search${executedSearchCount > 1 ? "es" : ""}`
+ (failedCount > 0 ? ` (${failedCount} failed)` : "")
+ `, ${iterations + 1} iteration${iterations > 0 ? "s" : ""}, ${Date.now() - loopT0}ms`,
);
};
let emptyAnswerRetries = 0;
let ordinaryEmptyRetries = 0;
let currentParsed = runTurnWebSearchInitialParsed(parsed);
try {
for (let i = 0; i < HARD_CAP; i++) {
releaseBuffered();
if (abortSignal?.aborted) {
yield abortEvent();
return;
}
const events: AdapterEvent[] = [];
let liveWindowOpen = plan.streamRoutedModelOutput;
let streamedCount = 0;
// One identical-turn retry per request: once it is spent the guard is
// not re-applied, so a later empty terminal reaches the loop itself —
// at the search cap the forced-answer recovery below handles it, the
// same contract loop.ts keeps by running no inner guard at all. A
// maxRetries:0 wrap would instead convert that empty done into
// empty_completion_retry_failed and end the turn before recovery.
if (deps.emptyCompletionRetry && searchesExecuted < plan.maxSearches
&& ordinaryEmptyRetries === 0) {
source = guardEmptyCompletionEventStream({
firstEvents: source,
continuation: () => {
ordinaryEmptyRetries++;
return deps.dispatch(currentParsed);
},
});
}
try {
for await (const e of source) {
if (abortSignal?.aborted) {
yield abortEvent();
return;
}
if (e.type === "error") {
yield e;
return;
}
if (e.type === "heartbeat") {
yield e;
continue;
}
chargeBuffered(e);
events.push(e);
if (liveWindowOpen && liveTypes.has(e.type)) {
streamedCount++;
yield e;
continue;
}
liveWindowOpen = false;
// Buffered text/reasoning/tool deltas are upstream activity too. Keep
// the bridge alive without exposing the synthetic call to the client.
if (e.type !== "done" && e.type !== "incomplete") yield { type: "heartbeat" };
}
} catch (e) {
if (isTranslatorBudgetExceededError(e)) throw e;
yield { type: "error", message: e instanceof Error ? e.message : String(e) };
return;
}
const terminals = events.filter(e => e.type === "done" || e.type === "incomplete");
if (terminals.length !== 1 || terminals[0] !== events.at(-1)) {
yield { type: "error", status: 502, errorType: "upstream_error",
message: "web-search runTurn stream must end with exactly one terminal event" };
return;
}
const split = scanEventsForWebSearch(events);
const terminal = terminals[0];
const replayEvents = split.passthrough.slice(streamedCount);
if (terminal.type === "incomplete") {
for (const e of replayEvents) yield e;
return;
}
const forceAnswer = searchesExecuted >= plan.maxSearches;
// Loop only when the model's actionable output is purely web_search calls:
// a real tool call belongs to Codex, and a budget-exhausted turn must
// answer from what it already gathered.
const shouldLoop = split.calls.length > 0 && !split.hasRealToolCall && !forceAnswer;
if (!shouldLoop) {
// A forced-answer pass that ends `done` must have produced usable output —
// never a malformed tool call, and never silence. A truncated/refusal
// stop is authoritative and replays as-is; an empty one gets exactly one
// recovery pass with all tools removed (same contract as loop.ts #1001).
if (forceAnswer) {
const terminalEvent = split.passthrough.find(event => event.type === "done");
if (terminalEvent?.type === "done" && !split.hasMalformedToolCall
&& isTruncatedStopReason(terminalEvent.stopReason)) {
logDone(i);
for (const e of replayEvents) yield e;
return;
}
if (terminalEvent?.type === "done"
&& (split.hasMalformedToolCall
|| (!split.hasRealToolCall && !hasVisibleAssistantText(split.passthrough)))) {
console.warn("[web-search-runturn] unusable forced answer", JSON.stringify({
model: parsed.modelId,
recoveryAttempt: emptyAnswerRetries,
searchCalls: split.calls.length,
malformed: split.hasMalformedToolCall,
stopReason: terminalEvent.stopReason,
eventTypes: [...new Set(split.passthrough.map(event => event.type))],
}));
if (!split.hasMalformedToolCall && !split.hasRealToolCall && emptyAnswerRetries === 0) {
emptyAnswerRetries++;
console.warn("[web-search-runturn] empty forced answer — retrying once without tools");
yield { type: "heartbeat" };
if (abortSignal?.aborted) { yield abortEvent(); return; }
source = deps.dispatch({
...parsed,
options: { ...parsed.options, toolChoice: "none" as const },
context: {
...parsed.context,
messages: [
...messages,
...(executedSearchCount > 0 ? [forcedAnswerNudge()] : []),
forcedAnswerRetryNudge(),
],
tools: [],
},
});
continue;
}
yield {
type: "error",
status: 502,
errorType: "upstream_error",
message: "forced-answer pass produced no usable assistant output",
};
return;
}
}
logDone(i);
for (const e of replayEvents) yield e;
return;
}
const iterationContent = extractIterationContent(split.passthrough);
for (const [callIndex, call] of split.calls.entries()) {
if (abortSignal?.aborted) { yield abortEvent(); return; }
yield* runSearchCall(call, callIndex === 0 ? iterationContent : []);
}
if (abortSignal?.aborted) {
yield abortEvent();
return;
}
const nextForceAnswer = searchesExecuted >= plan.maxSearches;
const iterParsed: OcxParsedRequest = {
...parsed,
context: {
...parsed.context,
messages: nextForceAnswer && executedSearchCount > 0
? [...messages, forcedAnswerNudge()]
: messages,
tools: nextForceAnswer ? toolsNoWebSearch : allTools,
},
};
currentParsed = iterParsed;
source = deps.dispatch(iterParsed);
}
// Safety net: the hard cap should be unreachable (forceAnswer ends the loop
// first), but never hang a client stream if an adapter misbehaves.
yield { type: "error", message: "web-search runTurn loop exceeded its iteration cap" };
} catch (error) {
if (!isTranslatorBudgetExceededError(error)) throw error;
yield budgetErrorEvent();
} finally {
releaseBuffered();
releaseHistory();
}
}