Skip to content

Commit 1c0f6df

Browse files
committed
feat(sidecar): OpenCode Zen keyed web-search backend (#1616)
1 parent 395cfdb commit 1c0f6df

11 files changed

Lines changed: 509 additions & 36 deletions

File tree

‎docs-site/src/content/docs/guides/sidecars.md‎

Lines changed: 24 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -23,8 +23,10 @@ When Codex requests hosted `web_search` for a non-passthrough routed model, open
2323
to the routed model instead. The original hosted-tool options are retained for the sidecar call.
2424
2. Runs the routed model in a small **agentic loop**. When it calls `web_search`, opencodex uses the
2525
selected sidecar backend: OpenAI runs hosted `web_search` with `gpt-5.6-luna` by default;
26-
Anthropic runs `web_search_20250305` with `claude-sonnet-5` by default. The streamed answer and
27-
citations become a tool result.
26+
Anthropic runs `web_search_20250305` with `claude-sonnet-5` by default; a `keyed` backend POSTs
27+
hosted `web_search` to a configured key-auth `openai-responses` provider that natively serves the
28+
tool (for example OpenCode Zen with `deepseek-v4-flash`). The streamed answer and citations
29+
become a tool result.
2830
3. **Loops** until the model answers or the total real-query budget reaches `maxSearchesPerTurn`
2931
(default 3), then removes the search tool and forces a final answer. Real client tools such as
3032
`apply_patch` or shell finalize the turn so those calls reach Codex.
@@ -38,7 +40,7 @@ Opt-in `webSearchSidecar.streamRoutedModelOutput` (default `false`) streams each
3840
leading text/thinking deltas live instead — the client sees output as soon as the model produces
3941
it, exactly like the sidecar-less path. The live window closes permanently at the first tool-call
4042
boundary, so the decision to intercept `web_search` stays atomic and nothing is ever delivered
41-
twice (the terminal replay skips what already streamed). Tradeoff: text the model emits *before*
43+
twice (the terminal replay skips what already streamed). Tradeoff: text the model emits _before_
4244
deciding to search — which buffered mode silently drops — becomes visible and may partially repeat
4345
in the post-search answer. The Dashboard overview page exposes this as the **Stream answers live**
4446
toggle on the web-search sidecar card (`PUT /api/sidecar-settings` with
@@ -73,6 +75,25 @@ relevant images in words and include their source URLs.
7375
search is returned to the routed model as a bounded error result, allowing it to answer from the
7476
context it already has.
7577

78+
For the `keyed` backend, set `webSearchSidecar.provider` to an enabled key-auth provider whose model
79+
supports native hosted web_search over the Responses wire, and `webSearchSidecar.model` to that model:
80+
81+
```json
82+
{
83+
"webSearchSidecar": {
84+
"enabled": true,
85+
"backend": "keyed",
86+
"provider": "opencode-go",
87+
"model": "deepseek-v4-flash"
88+
}
89+
}
90+
```
91+
92+
Selection fails closed: if the provider is disabled, has no resolvable API key, does not use the
93+
Responses wire, or does not declare hosted web_search support for the configured model, the sidecar
94+
is not selected and the routed model takes the normal non-search path rather than borrowing
95+
ChatGPT/Anthropic quota.
96+
7697
Four separate clocks apply. `stallTimeoutSec` is the base bridge event-stall budget.
7798
`connectTimeoutMs` (default `200000`) covers only DNS/TCP/TLS and final response headers.
7899
Config-file-only `webSearchSidecar.routedModelStallTimeoutMs` (default `200000`, integer

‎src/cli/integrations.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ const CLAUDE_USAGE = `Usage:
1818
[--system-env <on|off>] [--fast-mode <on|off>] [--auto-context <on|off>]
1919
[--compact-window <tokens|default>] [--inject-agents <on|off>]
2020
[--small-fast-model <id|->] [--model-map <from=to,from=to|->]
21-
[--blocked-skills <name,name|->] [--web-model <id|->] [--web-backend <openai|anthropic|->]
21+
[--blocked-skills <name,name|->] [--web-model <id|->] [--web-backend <openai|anthropic|keyed|->]
2222
[--vision-model <id|->] [--vision-backend <openai|anthropic|->] [--json]`;
2323

2424
const GROK_USAGE = `Usage:

‎src/providers/registry.ts‎

Lines changed: 26 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -175,6 +175,8 @@ export interface ProviderRegistryEntry {
175175
modelResponsesUpstreamStreaming?: Record<string, boolean>;
176176
/** Registry-only repair for a model whose native Responses stream may omit its terminal. */
177177
modelResponsesTerminalRepair?: Record<string, ResponsesTerminalRepairPolicy>;
178+
/** Registry-only capability: model ids that natively serve hosted web_search over the Responses wire. */
179+
hostedWebSearchResponsesModels?: Record<string, boolean>;
178180
/**
179181
* Registry-only client-facing item-id repair policy (#938), filled onto the
180182
* runtime provider only when the user has no explicit policy (derive.ts);
@@ -1242,6 +1244,10 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
12421244
id: "opencode-go", label: "opencode go", adapter: "openai-chat", baseUrl: "https://opencode.ai/zen/go/v1",
12431245
authKind: "key", featured: true, dashboardUrl: "https://opencode.ai/auth", defaultModel: "kimi-k2.7-code",
12441246
jawcodeBundle: "opencode-go", note: "GLM, DeepSeek, Kimi, Qwen, MiMo…",
1247+
// #1616: OpenCode Zen natively serves hosted web_search over /zen/go/v1/responses for
1248+
// deepseek-v4-flash (verified 2026-08-13). Per-model and fail-closed: other models must be
1249+
// probed before enabling the keyed web-search sidecar on them.
1250+
hostedWebSearchResponsesModels: { "deepseek-v4-flash": true },
12451251
/* [Decision Log]
12461252
- 목적과 의도: Route GPT 5.6 Luna to the Responses endpoint that OpenCode Go documents for that exact model.
12471253
- 기존 구현 및 제약 조건: The provider is mixed-wire but its provider-wide `openai-chat` adapter sent Luna to `/chat/completions`; explicit user `modelAdapters` entries must remain authoritative.
@@ -1250,7 +1256,11 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
12501256
- 다른 대안 대신 이 방식을 선택한 이유: OpenCode Go documents sibling models on Chat or Anthropic endpoints, and an exact registry default preserves both those routes and explicit opt-out precedence.
12511257
- 장점, 단점 및 영향: Luna reaches `/responses` from every inbound surface without changing siblings; a future upstream endpoint change requires an evidence-backed registry update.
12521258
*/
1253-
modelWireDefaults: { "gpt-5.6-luna": "openai-responses" },
1259+
modelWireDefaults: {
1260+
"gpt-5.6-luna": "openai-responses",
1261+
// #1616: deepseek-v4-flash rides the Responses wire (hosted web_search needs it).
1262+
"deepseek-v4-flash": "openai-responses",
1263+
},
12541264
modelContextWindows: { "kimi-k3": KIMI_K3_STANDARD_CONTEXT_WINDOW },
12551265
modelInputModalities: { "kimi-k3": ["text", "image"] },
12561266
modelReasoningEfforts: {
@@ -2645,6 +2655,21 @@ export function providerModelResponsesTerminalRepair(
26452655
return { graceMs };
26462656
}
26472657

2658+
/**
2659+
* True when a registry entry declares the given model natively serves hosted web_search over the
2660+
* Responses wire. The keyed web-search sidecar uses this as its capability gate: without it, a
2661+
* misconfigured provider would send its API key to an endpoint that cannot answer.
2662+
*/
2663+
export function providerHostsHostedWebSearchResponses(
2664+
id: string,
2665+
provider: Pick<OcxProviderConfig, "baseUrl" | "adapter"> & Partial<Pick<OcxProviderConfig, "authMode">>,
2666+
modelId: string,
2667+
): boolean {
2668+
const entry = getProviderRegistryEntry(id);
2669+
if (!entry?.hostedWebSearchResponsesModels || !providerMatchesRegistryTransport(id, provider)) return false;
2670+
return entry.hostedWebSearchResponsesModels[modelId.trim().toLowerCase()] === true;
2671+
}
2672+
26482673
/**
26492674
* Effective Codex account mode for a provider. For canonical `openai`, a valid persisted
26502675
* `codexAccountMode` on the provider config wins and a missing/invalid value defaults to

‎src/server/management/agent-settings-routes.ts‎

Lines changed: 15 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1051,9 +1051,13 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
10511051
const section = body[field];
10521052
if (section === undefined || section === null) continue;
10531053
if (!isPlainObject(section)) return jsonResponse({ error: `${field} must be an object or null` }, 400);
1054-
if (section.backend !== undefined && section.backend !== null
1055-
&& section.backend !== "openai" && section.backend !== "anthropic") {
1056-
return jsonResponse({ error: `${field}.backend must be openai, anthropic, or null` }, 400);
1054+
if (section.backend !== undefined && section.backend !== null
1055+
&& section.backend !== "openai" && section.backend !== "anthropic") {
1056+
return jsonResponse({ error: `${field}.backend must be openai, anthropic, keyed, or null` }, 400);
1057+
}
1058+
if (field === "webSearchSidecar" && section.provider !== undefined && section.provider !== null
1059+
&& (typeof section.provider !== "string" || section.provider.trim() === "")) {
1060+
return jsonResponse({ error: "webSearchSidecar.provider must be a nonblank provider name" }, 400);
10571061
}
10581062
if (section.model !== undefined && typeof section.model !== "string") {
10591063
return jsonResponse({ error: `${field}.model must be a string` }, 400);
@@ -1080,10 +1084,16 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
10801084
delete next[field];
10811085
continue;
10821086
}
1083-
const requested = section as { backend?: "openai" | "anthropic" | null; model?: string };
1084-
const override: NonNullable<OcxClaudeCodeConfig[typeof field]> = { ...next[field] };
1087+
const requested = section as {
1088+
backend?: "openai" | "anthropic" | "keyed" | null;
1089+
model?: string;
1090+
provider?: string | null;
1091+
};
1092+
const override: Record<string, unknown> = { ...next[field] };
10851093
if (requested.backend === null) delete override.backend;
10861094
else if (requested.backend !== undefined) override.backend = requested.backend;
1095+
if (requested.provider === null || requested.provider === "") delete override.provider;
1096+
else if (requested.provider !== undefined) override.provider = requested.provider;
10871097
if (requested.model === "") delete override.model;
10881098
else if (requested.model !== undefined) override.model = requested.model;
10891099
if (Object.keys(override).length > 0) next[field] = override;

‎src/server/management/config-routes.ts‎

Lines changed: 18 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -438,6 +438,7 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
438438
webSearch: {
439439
model: ws.model ?? "gpt-5.6-luna",
440440
backend: ws.backend,
441+
provider: ws.provider,
441442
streamRoutedModelOutput: ws.streamRoutedModelOutput === true,
442443
},
443444
vision: publicVisionSidecarSettings(config, vision),
@@ -454,7 +455,7 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
454455
if (raw.webSearch !== undefined && !isPlainRecord(raw.webSearch)) return jsonResponse({ error: "webSearch must be an object" }, 400);
455456
if (raw.vision !== undefined && !isPlainRecord(raw.vision)) return jsonResponse({ error: "vision must be an object" }, 400);
456457
const body = raw as {
457-
webSearch?: { model?: unknown; backend?: unknown; reasoning?: unknown; streamRoutedModelOutput?: unknown };
458+
webSearch?: { model?: unknown; backend?: unknown; provider?: unknown; reasoning?: unknown; streamRoutedModelOutput?: unknown };
458459
vision?: {
459460
model?: unknown;
460461
backend?: unknown;
@@ -466,7 +467,11 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
466467
};
467468
if (body.webSearch && body.webSearch.backend !== undefined && body.webSearch.backend !== null
468469
&& body.webSearch.backend !== "openai" && body.webSearch.backend !== "anthropic") {
469-
return jsonResponse({ error: "webSearch.backend must be openai, anthropic, or null" }, 400);
470+
return jsonResponse({ error: "webSearch.backend must be openai, anthropic, keyed, or null" }, 400);
471+
}
472+
if (body.webSearch && body.webSearch.provider !== undefined && body.webSearch.provider !== null
473+
&& (typeof body.webSearch.provider !== "string" || body.webSearch.provider.trim() === "")) {
474+
return jsonResponse({ error: "webSearch.provider must be a nonblank provider name" }, 400);
470475
}
471476
if (body.webSearch && body.webSearch.streamRoutedModelOutput !== undefined
472477
&& typeof body.webSearch.streamRoutedModelOutput !== "boolean") {
@@ -529,9 +534,18 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
529534
else config.webSearchSidecar.model = body.webSearch.model;
530535
}
531536
if (body.webSearch.backend === null) delete config.webSearchSidecar.backend;
532-
else if (body.webSearch.backend === "openai" || body.webSearch.backend === "anthropic") {
537+
else if (
538+
body.webSearch.backend === "openai"
539+
|| body.webSearch.backend === "anthropic"
540+
|| body.webSearch.backend === "keyed"
541+
) {
533542
config.webSearchSidecar.backend = body.webSearch.backend;
534543
}
544+
if (body.webSearch.provider === null || body.webSearch.provider === "") {
545+
delete config.webSearchSidecar.provider;
546+
} else if (typeof body.webSearch.provider === "string") {
547+
config.webSearchSidecar.provider = body.webSearch.provider;
548+
}
535549
if (typeof body.webSearch.reasoning === "string") config.webSearchSidecar.reasoning = body.webSearch.reasoning;
536550
if (typeof body.webSearch.streamRoutedModelOutput === "boolean") {
537551
// `false` is the default — drop the key so config files stay minimal.
@@ -573,6 +587,7 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
573587
webSearch: {
574588
model: ws.model ?? "gpt-5.6-luna",
575589
backend: ws.backend,
590+
provider: ws.provider,
576591
streamRoutedModelOutput: ws.streamRoutedModelOutput === true,
577592
},
578593
vision: publicVisionSidecarSettings(config, vision),

‎src/server/responses/core.ts‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3261,9 +3261,10 @@ async function handleResponsesInner(
32613261
const wsResponse = await runWithWebSearch({
32623262
parsed, adapter,
32633263
incomingMeta: { headers: selectedForwardHeaders, abortSignal: options.abortSignal, translatorBudget },
3264-
backend: wsPlan.backend,
3265-
forwardProvider: wsPlan.forwardSidecar?.provider,
3266-
anthropicSidecar: wsPlan.anthropicSidecar,
3264+
backend: wsPlan.backend,
3265+
forwardProvider: wsPlan.forwardSidecar?.provider,
3266+
anthropicSidecar: wsPlan.anthropicSidecar,
3267+
keyedSidecar: wsPlan.keyedSidecar,
32673268
hostedTool: wsPlan.hostedTool,
32683269
selectedForwardHeaders: wsPlan.forwardSidecar?.headers ?? selectedForwardHeaders,
32693270
settings: wsPlan.settings,

‎src/types.ts‎

Lines changed: 13 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -550,8 +550,8 @@ export interface OcxClaudeCodeConfig {
550550
* definition. Unset inherits the parent session effort.
551551
*/
552552
subagentEffort?: "low" | "medium" | "high" | "xhigh" | "max";
553-
/** Claude-originated web-search override. Unset fields inherit the global sidecar settings. */
554-
webSearchSidecar?: { backend?: "openai" | "anthropic"; model?: string };
553+
/** Claude-originated web-search override. Unset fields inherit the global sidecar settings. */
554+
webSearchSidecar?: { backend?: "openai" | "anthropic" | "keyed"; model?: string; provider?: string };
555555
/** Claude-originated vision override. Unset fields inherit the global sidecar settings. */
556556
visionSidecar?: { backend?: "openai" | "anthropic"; model?: string };
557557
/** Persisted Claude Desktop four-family routing profile. */
@@ -1211,14 +1211,19 @@ export interface OcxVisionSidecarConfig {
12111211
export interface OcxWebSearchSidecarConfig {
12121212
/** Master switch. Default: enabled when a forward (ChatGPT) provider exists and the caller is logged in. */
12131213
enabled?: boolean;
1214+
/**
1215+
* Which backend actually runs the server-side search. "openai" replays the hosted web_search via
1216+
* the ChatGPT forward provider (gpt-mini sidecar); "anthropic" runs web_search_20250305 on a Claude
1217+
* model authenticated by the STORED anthropic OAuth credential. Unset resolves to "anthropic" when a
1218+
* usable anthropic OAuth credential exists, else "openai".
1219+
*/
1220+
backend?: "openai" | "anthropic" | "keyed";
12141221
/**
1215-
* Which backend actually runs the server-side search. "openai" replays the hosted web_search via
1216-
* the ChatGPT forward provider (gpt-mini sidecar); "anthropic" runs web_search_20250305 on a Claude
1217-
* model authenticated by the STORED anthropic OAuth credential. Unset resolves to "anthropic" when a
1218-
* usable anthropic OAuth credential exists, else "openai".
1222+
* Provider name backing the `keyed` backend. Must name an enabled key-auth provider that uses an
1223+
* openai-responses wire and declares hosted web_search support via its registry capability flag.
12191224
*/
1220-
backend?: "openai" | "anthropic";
1221-
/** Sidecar model that runs the real server-side web_search (must be a native ChatGPT model). */
1225+
provider?: string;
1226+
/** Sidecar model that runs the real server-side web_search (must be a native ChatGPT model). */
12221227
model?: string;
12231228
/** Reasoning effort for the sidecar — "minimal" (non-thinking) keeps it fast/cheap. */
12241229
reasoning?: string;

‎src/web-search/executor.ts‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -111,3 +111,77 @@ export async function runWebSearch(
111111
linkedSignal.cleanup();
112112
}
113113
}
114+
115+
export interface KeyedWebSearchRequest {
116+
/** Resolved provider name (for logs). */
117+
providerName: string;
118+
/** Resolved key-auth provider pointing at an openai-responses wire. */
119+
provider: OcxProviderConfig;
120+
/** The resolved plaintext API key (already validated present). */
121+
apiKey: string;
122+
}
123+
124+
/**
125+
* Execute ONE web search via a key-fed openai-responses provider that natively serves hosted
126+
* web_search (e.g. OpenCode Zen at https://opencode.ai/zen/go/v1). Authenticates with the provider's
127+
* own API key via `Authorization: Bearer <apiKey>` — it must NEVER touch the ChatGPT forward headers
128+
* or the Anthropic stored-OAuth credential, so neither ChatGPT nor Anthropic quota is consumed.
129+
* Reuses the hosted web_search tool verbatim and the shared SSE parser. Never throws.
130+
*/
131+
export async function runKeyedWebSearch(
132+
query: string,
133+
hostedTool: Record<string, unknown>,
134+
sidecar: KeyedWebSearchRequest,
135+
settings: SidecarSettings,
136+
abortSignal?: AbortSignal,
137+
): Promise<SidecarOutcome> {
138+
const headers: Record<string, string> = { "Content-Type": "application/json" };
139+
if (sidecar.provider.headers) Object.assign(headers, sidecar.provider.headers);
140+
headers["authorization"] = `Bearer ${sidecar.apiKey}`;
141+
const body = {
142+
model: settings.model,
143+
instructions: settings.describeImages ? BASE_INSTRUCTION + IMAGE_INSTRUCTION : BASE_INSTRUCTION,
144+
input: [{ type: "message", role: "user", content: [{ type: "input_text", text: query }] }],
145+
tools: [hostedTool],
146+
tool_choice: "auto",
147+
reasoning: { effort: settings.reasoning },
148+
store: false,
149+
stream: true,
150+
};
151+
const url = `${sidecar.provider.baseUrl.replace(/\/+$/, "")}/responses`;
152+
const linkedSignal = signalWithTimeout(settings.timeoutMs, abortSignal);
153+
const sidecarExit = sidecarEnter("web-search");
154+
const t0 = Date.now();
155+
try {
156+
const res = await fetchWithResetRetry(
157+
() => fetch(url, {
158+
method: "POST",
159+
headers,
160+
body: JSON.stringify(body),
161+
signal: linkedSignal.signal,
162+
// Credential-bearing: never follow a 3xx that could leak the API key to the redirect target.
163+
redirect: "manual",
164+
}),
165+
{ abortSignal: linkedSignal.signal, label: "web-search-sidecar-keyed" },
166+
);
167+
const detachBodyGuard = cancelBodyOnAbort(res.body, linkedSignal.signal);
168+
if (!res.ok) {
169+
const t = await res.text().catch(() => "");
170+
detachBodyGuard();
171+
console.warn(`[web-search] keyed sidecar HTTP ${res.status} for query "${query.slice(0, 80)}" (${Date.now() - t0}ms)`);
172+
return { text: "", sources: [], error: `sidecar HTTP ${res.status}: ${redactSecretString(t.slice(0, 200))}` };
173+
}
174+
try {
175+
return await parseSidecarSSE(res);
176+
} finally {
177+
detachBodyGuard();
178+
}
179+
} catch (e) {
180+
const kind = e instanceof Error && e.name === "TimeoutError" ? "timeout" : "connect_error";
181+
console.warn(`[web-search] keyed sidecar ${kind} for query "${query.slice(0, 80)}" (${Date.now() - t0}ms)`);
182+
return { text: "", sources: [], error: e instanceof Error ? e.message : String(e) };
183+
} finally {
184+
sidecarExit();
185+
linkedSignal.cleanup();
186+
}
187+
}

0 commit comments

Comments
 (0)