@bitkyc08/opencodex 2.28.0 → 2.29.0

package/src/web-search/loop.ts

@@ -6,6 +6,10 @@ import type { AttemptRecoveryKind } from "../usage/log";
 import { bridgeToResponsesSSE } from "../bridge";
 import { runWebSearch, type SidecarOutcome, type SidecarOutcomeRecorder, type SidecarSettings } from "./executor";
 import { runAnthropicWebSearch } from "./anthropic-executor";
+import { runXaiWebSearch, type XaiSearchOptions } from "./xai-executor";
+import { runGeminiWebSearch } from "./gemini-executor";
+import { runExaWebSearch } from "./exa-executor";
+import type { WebSearchBackendId } from "./index";
 import { clearableDeadline } from "../lib/abort";
 import { redactSecretString } from "../lib/redact";
 import { readBoundedResponseBody } from "../lib/bounded-body";
@@ -250,12 +254,24 @@ export interface WebSearchLoopDeps {
   parsed: OcxParsedRequest;
   adapter: ProviderAdapter;
   incomingMeta: IncomingMeta;
-  /** Which executor runs searches. Defaults to "openai" so existing callers keep the ChatGPT path (audit F4). */
-  backend?: "openai" | "anthropic";
+  /**
+   * Which executor runs searches. Defaults to "openai" so existing callers keep the ChatGPT path
+   * (audit F4). The widened ids (xai/gemini/exa) cannot reach the loop yet: planWebSearch returns
+   * no plan for them (inert 060 arms), and the dispatch below only branches on "anthropic".
+   */
+  backend?: WebSearchBackendId;
   /** Required for the openai backend; unused (and typically undefined) for the anthropic backend. */
   forwardProvider?: OcxProviderConfig;
   /** Required for the anthropic backend: the stored-OAuth provider that runs web_search_20250305. */
   anthropicSidecar?: { providerName: string; provider: OcxProviderConfig };
+  /** Required for the xai backend: the stored Grok OAuth provider (L7). */
+  xaiSidecar?: { providerName: string; provider: OcxProviderConfig };
+  /** Required for the gemini backend: the stored Antigravity CCA provider (L8). */
+  geminiSidecar?: { providerName: string; provider: OcxProviderConfig };
+  /** Required for the exa backend: the operator key, read from config at plan unpack (L9). */
+  exaApiKey?: string;
+  /** Opt-in x_search options for the xai backend. */
+  xaiSearchOptions?: XaiSearchOptions;
   hostedTool: Record<string, unknown>;
   selectedForwardHeaders: Headers;
   settings: SidecarSettings;
@@ -294,6 +310,8 @@ export interface WebSearchLoopDeps {
   on429?: (retryAfterHeader: string | null) => ProviderAdapter | null;
   /** Opt-in same-target 429 policy (key-auth providers). When present, 429 replays on the SAME key before on429 rotation. */
   retryOn429Policy?: Required<RateLimitRetryPolicy> | null;
+  /** Called only when the final bridged Responses stream reaches completed or incomplete. */
+  onCompletedResponse?: (response: Record<string, unknown>) => void;
 }
 
 /**
@@ -656,9 +674,30 @@ export async function runWithWebSearch(deps: WebSearchLoopDeps): Promise<Respons
         // signal.aborted both after the await and in the catch (a fulfilled {error} on an aborted
         // signal would otherwise look like an ordinary degradable failure).
         try {
-          outcome = backend === "anthropic" && anthropicSidecar
-            ? await runAnthropicWebSearch(query, anthropicSidecar.providerName, anthropicSidecar.provider, settings, signal)
-            : await runWebSearch(query, hostedTool, forwardProvider!, selectedForwardHeaders, settings, signal, recordSidecarOutcome);
+          if (backend === "anthropic" && anthropicSidecar) {
+            outcome = await runAnthropicWebSearch(query, anthropicSidecar.providerName, anthropicSidecar.provider, settings, signal);
+          } else if (backend === "xai") {
+            // L7: stored Grok OAuth to the pinned api.x.ai Responses endpoint; same
+            // never-throws contract and no Codex/OpenAI pool outcome recording (F5 parity).
+            // A missing xaiSidecar is an invariant violation — fail CLOSED with an error
+            // outcome rather than falling through to the forward-header OpenAI executor
+            // (review High: that fallthrough would be credential-sensitive).
+            outcome = deps.xaiSidecar
+              ? await runXaiWebSearch(query, deps.xaiSidecar.providerName, deps.xaiSidecar.provider, settings, deps.xaiSearchOptions ?? {}, signal)
+              : { text: "", sources: [], error: "xai backend selected without a resolved Grok OAuth provider" };
+          } else if (backend === "gemini") {
+            // L8: Antigravity CCA grounding; same fail-closed invariant stance as xai.
+            outcome = deps.geminiSidecar
+              ? await runGeminiWebSearch(query, deps.geminiSidecar.providerName, deps.geminiSidecar.provider, settings, signal)
+              : { text: "", sources: [], error: "gemini backend selected without a resolved Antigravity provider" };
+          } else if (backend === "exa") {
+            // L9: non-LLM lane; key comes from the loop deps, never the plan. Fail closed.
+            outcome = deps.exaApiKey
+              ? await runExaWebSearch(query, deps.exaApiKey, settings, signal)
+              : { text: "", sources: [], error: "exa backend selected without an exaApiKey" };
+          } else {
+            outcome = await runWebSearch(query, hostedTool, forwardProvider!, selectedForwardHeaders, settings, signal, recordSidecarOutcome);
+          }
           if (signal.aborted) throw new LoopError(499, "client closed request during web-search");
         } catch (e) {
           if (e instanceof LoopError) throw e;
@@ -847,6 +886,7 @@ export async function runWithWebSearch(deps: WebSearchLoopDeps): Promise<Respons
       ...(deps.stallTimeoutSec !== undefined ? { stallTimeoutSec: deps.stallTimeoutSec } : {}),
       ...(deps.onFirstOutput ? { onFirstOutput: deps.onFirstOutput } : {}),
       ...(deps.onUsage ? { onUsage: deps.onUsage } : {}),
+      ...(deps.onCompletedResponse ? { onCompletedResponse: deps.onCompletedResponse } : {}),
     },
   );
   return new Response(sse, { headers: SSE_HEADERS });

package/src/web-search/parse.ts

@@ -1,10 +1,12 @@
 import { sseFieldValue } from "../lib/sse-decoder";
+import {
+  appendSafeWebSearchSource,
+  safeWebSearchSources,
+  type SafeWebSearchSource,
+} from "./sources";
 
 /** A single web source backing the sidecar's answer. */
-export interface WebSearchSource {
-  url: string;
-  title?: string;
-}
+export type WebSearchSource = SafeWebSearchSource;
 
 /** The sidecar's synthesized answer plus its sources (empty `sources` is fine). */
 export interface WebSearchResult {
@@ -36,8 +38,10 @@ export const MAX_SIDECAR_RESPONSE_BYTES = 64 * 1024;
 /** Push a `url_citation` annotation as a source, de-duplicated by URL. */
 function collectAnnotation(ann: AnnotationLike | undefined, sources: WebSearchSource[], seen: Set<string>): void {
   if (!ann || ann.type !== "url_citation" || typeof ann.url !== "string" || seen.has(ann.url)) return;
-  seen.add(ann.url);
-  sources.push({ url: ann.url, ...(ann.title ? { title: ann.title } : {}) });
+  if (appendSafeWebSearchSource(sources, {
+    url: ann.url,
+    ...(ann.title !== undefined ? { title: ann.title } : {}),
+  })) seen.add(ann.url);
 }
 
 /**
@@ -51,7 +55,11 @@ function collectAnnotation(ann: AnnotationLike | undefined, sources: WebSearchSo
  * (`### Sources:`, `**Sources**`), a title line whose URL sits on the FOLLOWING line, and trailing
  * URL punctuation (`;`, `,`, `)`, `]`, `.`). Prose that follows the source list is preserved.
  */
-const URL_RE = /https?:\/\/[^\s<>()\[\]]+/;
+const URL_RE = /https?:\/\/[^\s<>()\[\]]+/i;
+// Recognize URI-like candidates separately from the HTTP(S)-only acceptance boundary. A rejected
+// citation (for example `javascript:`) still belongs to the trailing Sources block and must not be
+// left behind as ordinary assistant text.
+const URI_LIKE_RE = /[a-z][a-z0-9+.-]*:[^\s<>()\[\]]+/i;
 // A "Sources:" / "Source:" header, allowing markdown prefixes (#, *, -, >) and bold/italic wrappers.
 const SOURCES_WORD_RE = /^sources?/i;
 
@@ -113,14 +121,14 @@ function cleanTitle(prefix: string): string {
   return title;
 }
 
-function extractTrailingSources(text: string): { text: string; sources: WebSearchSource[] } {
+function extractTrailingSources(text: string): { text: string; sources: WebSearchSource[]; stripped: boolean } {
   const lines = text.split("\n");
   // Find the LAST line that is a "Sources:" header (markdown prefixes allowed).
   let headerIdx = -1;
   for (let i = lines.length - 1; i >= 0; i--) {
     if (isSourcesHeader(lines[i])) { headerIdx = i; break; }
   }
-  if (headerIdx === -1) return { text, sources: [] };
+  if (headerIdx === -1) return { text, sources: [], stripped: false };
   const sources: WebSearchSource[] = [];
   const seen = new Set<string>();
   // Track the last line index actually consumed as part of the source list so trailing prose after
@@ -128,14 +136,16 @@ function extractTrailingSources(text: string): { text: string; sources: WebSearc
   let lastConsumed = headerIdx;
   // A title line whose URL is expected on a following line (multiline entry).
   let pendingTitle: string | null = null;
+  let consumedSourceLine = false;
   for (let i = headerIdx + 1; i < lines.length; i++) {
     const raw = lines[i].trim();
     if (raw === "") {
       // Blank line between header and first entry is fine; a blank AFTER entries ends the list.
-      if (sources.length > 0 || pendingTitle !== null) break;
+      if (consumedSourceLine || pendingTitle !== null) break;
       continue;
     }
-    const m = raw.match(URL_RE);
+    const httpMatch = raw.match(URL_RE);
+    const m = httpMatch ?? raw.match(URI_LIKE_RE);
     if (!m) {
       // A list-ish line with no URL may be a title whose URL is on the next line. Only treat it as a
       // pending title when it looks like a list item; otherwise it's prose → stop.
@@ -144,23 +154,27 @@ function extractTrailingSources(text: string): { text: string; sources: WebSearc
       }
       break;
     }
+    // A non-HTTP URI embedded in prose is not sufficient to classify the line as a citation.
+    // Accept it as a consumed source line only when it is a list item or the whole line starts with
+    // the URI candidate, matching the existing bare-URL grammar.
+    if (!httpMatch && !/^[-*>\d.)]/.test(raw) && m.index !== 0) break;
     const url = cleanUrl(m[0]);
     if (!url) { break; }
+    consumedSourceLine = true;
     lastConsumed = i;
     // Title: text before the URL on this line, else a buffered title from a preceding line.
     const inlinePrefix = raw.slice(0, m.index);
     const title = cleanTitle(inlinePrefix) || (pendingTitle ? cleanTitle(pendingTitle) : "");
     pendingTitle = null;
     if (seen.has(url)) continue;
-    seen.add(url);
-    sources.push(title ? { url, title } : { url });
+    if (appendSafeWebSearchSource(sources, title ? { url, title } : { url })) seen.add(url);
   }
-  if (sources.length === 0) return { text, sources: [] };
+  if (!consumedSourceLine) return { text, sources: [], stripped: false };
   // Keep text before the header AND any prose after the consumed source lines.
   const before = lines.slice(0, headerIdx).join("\n").replace(/\s+$/, "");
   const after = lines.slice(lastConsumed + 1).join("\n").replace(/^\s+/, "");
   const body = after ? (before ? `${before}\n\n${after}` : after) : before;
-  return { text: body, sources };
+  return { text: body, sources, stripped: true };
 }
 
 /** Pull final text + url_citation sources from a completed Responses `output[]` array. */
@@ -283,22 +297,19 @@ export async function parseSidecarSSE(response: Response): Promise<WebSearchResu
     || acc.doneText.trim() && acc.doneText
     || acc.deltaText;
   // Merge sources from the final output[] and the streaming annotation events.
-  const sources = [...(acc.final?.sources ?? [])];
-  const seenMerge = new Set(sources.map(s => s.url));
+  const sources = safeWebSearchSources(acc.final?.sources ?? []);
   for (const s of acc.streamSources) {
-    if (!seenMerge.has(s.url)) { seenMerge.add(s.url); sources.push(s); }
+    appendSafeWebSearchSource(sources, s);
   }
   // Hosted web_search usually omits url_citation annotations and lists sources in a trailing
   // `Sources:` markdown block instead. Pull those out (and strip the block from the answer so the
   // tool_result renderer doesn't print sources twice). Annotation titles win; text-block titles
   // only fill a gap. URL-deduped against annotation sources.
-  const { text: body, sources: textSources } = extractTrailingSources(typeof text === "string" ? text : "");
+  const { text: body, sources: textSources, stripped } = extractTrailingSources(typeof text === "string" ? text : "");
   for (const s of textSources) {
-    if (seenMerge.has(s.url)) continue;
-    seenMerge.add(s.url);
-    sources.push(s);
+    appendSafeWebSearchSource(sources, s);
   }
-  const finalText = textSources.length > 0 ? body : (typeof text === "string" ? text : "");
+  const finalText = stripped ? body : (typeof text === "string" ? text : "");
   if (!finalText.trim() && acc.error) return { text: "", sources, error: acc.error };
   return { text: finalText, sources };
 }

package/src/web-search/sources.ts

@@ -0,0 +1,60 @@
+export interface SafeWebSearchSource {
+  url: string;
+  title?: string;
+}
+
+export const MAX_WEB_SEARCH_SOURCES = 20;
+export const MAX_WEB_SEARCH_URL_BYTES = 2_048;
+export const MAX_WEB_SEARCH_TITLE_BYTES = 256;
+export const MAX_WEB_SEARCH_SOURCE_BYTES = 16_384;
+
+const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f-\u009f]/u;
+const encoder = new TextEncoder();
+
+function byteLength(value: string): number {
+  return encoder.encode(value).byteLength;
+}
+
+function serializedSourceBytes(source: SafeWebSearchSource): number {
+  return byteLength(JSON.stringify(source));
+}
+
+function safeTitle(value: unknown): string | undefined {
+  if (typeof value !== "string"
+    || value.trim().length === 0
+    || CONTROL_CHARACTERS.test(value)
+    || byteLength(value) > MAX_WEB_SEARCH_TITLE_BYTES) return undefined;
+  return value;
+}
+
+/** Add one client-safe citation while enforcing per-message count and byte budgets. */
+export function appendSafeWebSearchSource(target: SafeWebSearchSource[], source: unknown): boolean {
+  if (target.length >= MAX_WEB_SEARCH_SOURCES || !source || typeof source !== "object") return false;
+  const candidate = source as { url?: unknown; title?: unknown };
+  if (typeof candidate.url !== "string"
+    || candidate.url.length === 0
+    || candidate.url.trim() !== candidate.url
+    || CONTROL_CHARACTERS.test(candidate.url)
+    || byteLength(candidate.url) > MAX_WEB_SEARCH_URL_BYTES
+    || target.some(existing => existing.url === candidate.url)) return false;
+
+  let parsed: URL;
+  try { parsed = new URL(candidate.url); } catch { return false; }
+  if ((parsed.protocol !== "http:" && parsed.protocol !== "https:")
+    || parsed.username.length > 0
+    || parsed.password.length > 0) return false;
+
+  const title = safeTitle(candidate.title);
+  const next = title === undefined ? { url: candidate.url } : { url: candidate.url, title };
+  const usedBytes = target.reduce((sum, item) => sum + serializedSourceBytes(item), 0);
+  if (usedBytes + serializedSourceBytes(next) > MAX_WEB_SEARCH_SOURCE_BYTES) return false;
+  target.push(next);
+  return true;
+}
+
+export function safeWebSearchSources(sources: unknown): SafeWebSearchSource[] {
+  if (!Array.isArray(sources)) return [];
+  const safe: SafeWebSearchSource[] = [];
+  for (const source of sources) appendSafeWebSearchSource(safe, source);
+  return safe;
+}

package/src/web-search/xai-executor.ts

@@ -0,0 +1,219 @@
+/**
+ * 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 { fetchWithResetRetry } from "../lib/upstream-retry";
+import { cancelBodyOnAbort, signalWithTimeout } from "../lib/abort";
+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(
+      () => fetch(url, {
+        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",
+      }),
+      { abortSignal: linkedSignal.signal, label: "xai-web-search-sidecar" },
+    );
+    const detachBodyGuard = cancelBodyOnAbort(res.body, linkedSignal.signal);
+    if (!res.ok) {
+      const t = await res.text().catch(() => "");
+      detachBodyGuard();
+      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}: ${redactSecretString(t.slice(0, 200))}` };
+    }
+    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;
+}