@iislee/opencodex 2.11.0 → 2.31.0

package/src/web-search/parse.ts

@@ -1,8 +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 {
@@ -27,11 +31,17 @@ interface OutputItem {
   content?: OutputTextBlock[];
 }
 
+// ChatGPT's Codex backend does not accept `max_output_tokens` on sidecar requests. Bound the raw
+// streamed response here, before decoded text and authoritative/delta copies can accumulate.
+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);
 }
 
 /**
@@ -45,9 +55,58 @@ 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_HEADER_RE = /^\s*(?:#{1,6}\s*)?[-*>\s]*\**\s*sources?\s*\**\s*:?\s*\**\s*$/i;
+const SOURCES_WORD_RE = /^sources?/i;
+
+/** Match the legacy Sources-header grammar without overlapping regex quantifiers. */
+function isSourcesHeader(line: string): boolean {
+  let cursor = 0;
+  /** Match one code unit using JavaScript's existing `\s` semantics. */
+  const isWhitespace = (char: string | undefined): boolean => char !== undefined && /\s/u.test(char);
+  /** Advance over the current contiguous whitespace run. */
+  const skipWhitespace = (): void => {
+    while (isWhitespace(line[cursor])) cursor += 1;
+  };
+  /** Advance over the current contiguous Markdown-star run. */
+  const skipStars = (): void => {
+    while (line[cursor] === "*") cursor += 1;
+  };
+
+  skipWhitespace();
+  if (line[cursor] === "#") {
+    const start = cursor;
+    while (line[cursor] === "#") cursor += 1;
+    if (cursor - start > 6) return false;
+    skipWhitespace();
+  }
+
+  while (isWhitespace(line[cursor]) || line[cursor] === "-" || line[cursor] === "*" || line[cursor] === ">") {
+    cursor += 1;
+  }
+
+  const word = SOURCES_WORD_RE.exec(line.slice(cursor, cursor + 7));
+  if (!word) return false;
+  cursor += word[0].length;
+
+  // Preserve `\s*\**\s*:?\s*\**\s*$`: at most two star runs, with the optional
+  // colon between them. Either run may be empty, so `Sources:*` is one trailing run; three
+  // separated runs and a colon after the second run remain invalid.
+  skipWhitespace();
+  skipStars();
+  skipWhitespace();
+  if (line[cursor] === ":") {
+    cursor += 1;
+    skipWhitespace();
+  }
+  skipStars();
+  skipWhitespace();
+  return cursor === line.length;
+}
 
 /** Trim wrapping/trailing noise from a captured URL: angle brackets, then trailing punctuation. */
 function cleanUrl(url: string): string {
@@ -62,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 (SOURCES_HEADER_RE.test(lines[i])) { headerIdx = i; break; }
+    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
@@ -77,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.
@@ -93,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. */
@@ -128,6 +193,15 @@ function fromOutputArray(output: OutputItem[], seen: Set<string>): WebSearchResu
   return { text, sources };
 }
 
+function cancelReaderWithoutWaiting(
+  reader: ReadableStreamDefaultReader<Uint8Array>,
+  reason: string,
+): void {
+  try {
+    void reader.cancel(reason).catch(() => undefined);
+  } catch { /* best-effort body teardown */ }
+}
+
 /**
  * Parse the sidecar's streamed Responses SSE into a final answer + sources. Tolerant of the full set of
  * Responses streaming events: prefers the authoritative `response.completed` output[], then the
@@ -141,6 +215,7 @@ export async function parseSidecarSSE(response: Response): Promise<WebSearchResu
   const reader = response.body.getReader();
   const decoder = new TextDecoder();
   let buffer = "";
+  let responseBytes = 0;
   const seen = new Set<string>();
   // Holder object — fields are mutated inside the closure, so they can't live as narrowed locals.
   const acc: {
@@ -153,11 +228,23 @@ export async function parseSidecarSSE(response: Response): Promise<WebSearchResu
 
   const handle = (payload: string): void => {
     if (!payload || payload === "[DONE]") return;
-    let data: Record<string, unknown>;
-    try { data = JSON.parse(payload) as Record<string, unknown>; } catch {
-      console.warn(`[web-search-parse] malformed SSE JSON (${payload.length} chars): ${payload.slice(0, 120)}`);
+    // Neither warning below copies the frame's content. An upstream SSE payload can carry model
+    // output or credential material, and a malformed frame is exactly the case where the content
+    // is least trustworthy. Length plus a classification separates the two failure modes in a log
+    // without reproducing anything from the wire.
+    let parsed: unknown;
+    try { parsed = JSON.parse(payload); } catch {
+      console.warn(`[web-search-parse] malformed SSE JSON (${payload.length} chars)`);
       return;
     }
+    // `JSON.parse("null")` returns null rather than throwing, so the catch above cannot cover it
+    // and the `data.type` read below threw out of parseSidecarSSE.
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+      const shape = Array.isArray(parsed) ? "array" : parsed === null ? "null" : typeof parsed;
+      console.warn(`[web-search-parse] non-record SSE JSON frame (${payload.length} chars, ${shape})`);
+      return;
+    }
+    const data = parsed as Record<string, unknown>;
     const type = data.type as string | undefined;
     if (type === "response.output_text.delta" && typeof data.delta === "string") {
       acc.deltaText += data.delta;
@@ -183,11 +270,22 @@ export async function parseSidecarSSE(response: Response): Promise<WebSearchResu
     while (true) {
       const { done, value } = await reader.read();
       if (done) break;
-      buffer += decoder.decode(value, { stream: true });
+      const remaining = MAX_SIDECAR_RESPONSE_BYTES - responseBytes;
+      const accepted = value.byteLength <= remaining ? value : value.subarray(0, remaining);
+      responseBytes += accepted.byteLength;
+      buffer += decoder.decode(accepted, { stream: true });
       const lines = buffer.split("\n");
       buffer = lines.pop() ?? "";
       for (const line of lines) {
-        if (line.startsWith("data: ")) handle(line.slice(6).trim());
+        const data = sseFieldValue(line, "data");
+        if (data !== null) handle(data.trim());
+      }
+      if (responseBytes >= MAX_SIDECAR_RESPONSE_BYTES) {
+        // Preserve complete events accepted up to the cap, but discard any unterminated line and
+        // TextDecoder carry. Do not let a rejecting/hung cancel turn bounded partial output into
+        // an error or keep this parser waiting on upstream teardown.
+        cancelReaderWithoutWaiting(reader, "sidecar response byte limit reached");
+        break;
       }
     }
   } finally {
@@ -199,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;
+}