@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
766 lines (727 loc) • 38.2 kB
text/typescript
import { sseFieldValue } from "../lib/sse-decoder";
import {
appendSafeWebSearchSource,
fillMissingWebSearchSourceTitle,
safeWebSearchSources,
type SafeWebSearchSource,
} from "./sources";
/** A single web source backing the sidecar's answer. */
export type WebSearchSource = SafeWebSearchSource;
/** The sidecar's synthesized answer plus its sources (empty `sources` is fine). */
export interface WebSearchResult {
text: string;
sources: WebSearchSource[];
/** Set when the stream failed, including when partial text was decoded before failure. */
error?: string;
}
interface AnnotationLike {
type?: string;
url?: string;
title?: string;
}
interface OutputTextBlock {
type?: string;
text?: string;
annotations?: AnnotationLike[];
}
interface OutputItem {
id?: string;
type?: string;
content?: OutputTextBlock[];
}
/**
* Completed output text and citations. `parts` holds each output_text block's text keyed by
* `output_index:content_index`, and `incomplete` marks skipped malformed entries.
*/
type CompletedOutput = WebSearchResult & {
incomplete: boolean;
parts: Map<string, string>;
slots: Map<string, { itemId?: string; outputIndex: number; contentIndex: number; singleContent: boolean }>;
/** Unique message positions survive malformed content; null marks a repeated item ID. */
items: Map<string, { outputIndex: number; missingContent: boolean } | null>;
};
/** Streamed text for one `output_text` content part. */
interface StreamedPart {
key: string;
order: number;
delta: string;
done: string | null;
itemId?: string;
outputIndex?: number;
contentIndex?: number;
promotedFromContent?: boolean;
}
/** The streamed part for events that carry no valid `output_index`/`content_index`. */
const UNINDEXED_PART = "unindexed";
// Identity buckets allow a unique compatible match without scanning prior parts on every frame.
type PartLookup = Map<string, Set<StreamedPart>>;
function partBucket(itemId: string, contentIndex: number | undefined, exact: boolean, unindexed: boolean, output?: number | null): string {
return JSON.stringify([itemId, contentIndex ?? null, exact, unindexed, output === undefined ? "any" : output]);
}
function indexPart(lookup: PartLookup, part: StreamedPart, add: boolean): void {
const positionBuckets = part.outputIndex !== undefined
? [["output", part.outputIndex], ["output-content", part.outputIndex, part.contentIndex ?? null]]
: [["unpositioned-content", part.contentIndex ?? null]];
for (const positionBucket of positionBuckets) {
const key = JSON.stringify(positionBucket);
let bucket = lookup.get(key);
if (add) {
if (!bucket) { bucket = new Set(); lookup.set(key, bucket); }
bucket.add(part);
} else if (bucket) {
bucket.delete(part);
if (!bucket.size) lookup.delete(key);
}
}
if (!part.itemId) return;
for (const exact of [false, true]) {
for (const unindexed of isIndexedPartKey(part.key) ? [false] : [false, true]) {
for (const output of [undefined, part.outputIndex ?? null]) {
const key = partBucket(part.itemId, exact ? part.contentIndex : undefined, exact, unindexed, output);
let bucket = lookup.get(key);
if (add) {
if (!bucket) { bucket = new Set(); lookup.set(key, bucket); }
bucket.add(part);
} else if (bucket) {
bucket.delete(part);
if (!bucket.size) lookup.delete(key);
}
}
}
}
}
function identifiedPart(lookup: PartLookup, itemId: string, contentIndex: number | undefined, unindexed: boolean, outputIndex?: number): StreamedPart | undefined {
const outputs = outputIndex === undefined ? [undefined] : [outputIndex, null];
const buckets = outputs.flatMap(output => contentIndex === undefined
? [lookup.get(partBucket(itemId, undefined, false, unindexed, output))]
: [lookup.get(partBucket(itemId, contentIndex, true, unindexed, output)), lookup.get(partBucket(itemId, undefined, true, unindexed, output))]);
if (buckets.reduce((count, bucket) => count + (bucket?.size ?? 0), 0) !== 1) return undefined;
return buckets.find(bucket => bucket?.size)?.values().next().value;
}
/**
* Match explicit item identity before applying the legacy single-part fallback. Indexed parts
* retain their numeric keys so incomplete completed outputs can fill individual missing parts.
*/
function streamedPartKey(data: Record<string, unknown>, parts: Map<string, StreamedPart>, lookup: PartLookup, nextOrder: number): string {
const output = data.output_index;
const content = data.content_index;
const outputIndex = Number.isInteger(output) ? output as number : undefined;
const contentIndex = Number.isInteger(content) ? content as number : undefined;
const itemId = typeof data.item_id === "string" && data.item_id ? data.item_id : undefined;
const indexedKey = outputIndex !== undefined && contentIndex !== undefined ? `${outputIndex}:${contentIndex}` : undefined;
const outputOnly = outputIndex === undefined ? undefined : parts.get(`output:${outputIndex}`);
const compatible = (part: StreamedPart): boolean =>
(!itemId || !part.itemId || itemId === part.itemId)
&& (outputIndex === undefined || part.outputIndex === undefined || outputIndex === part.outputIndex)
&& (contentIndex === undefined || part.contentIndex === undefined || contentIndex === part.contentIndex);
const indexedPart = indexedKey ? parts.get(indexedKey) : undefined;
let match = itemId ? identifiedPart(lookup, itemId, contentIndex, !!indexedKey, outputIndex) : undefined;
if (!match && itemId && indexedPart?.itemId === itemId
&& identifiedPart(lookup, itemId, contentIndex, false, outputIndex) === indexedPart) match = indexedPart;
if (match && !compatible(match)) match = undefined;
const outputBucket = outputIndex === undefined ? undefined : lookup.get(JSON.stringify(["output", outputIndex]));
const outputContentBucket = outputIndex === undefined || contentIndex === undefined ? undefined
: lookup.get(JSON.stringify(["output-content", outputIndex, contentIndex]));
const outputUnknownContentBucket = outputIndex === undefined ? undefined
: lookup.get(JSON.stringify(["output-content", outputIndex, null]));
const outputCandidates = contentIndex === undefined ? outputBucket?.size ?? 0
: (outputContentBucket?.size ?? 0) + (outputUnknownContentBucket?.size ?? 0);
// A linking snapshot can identify an anonymous position even when either frame omitted the
// content index. Only inspect the buckets when their total proves there are at most two parts.
if (data.type === "response.output_text.done" && itemId && match
&& outputCandidates === (match.outputIndex === undefined ? 1 : 2)) {
const matchedContent = match.contentIndex;
const buckets = contentIndex === undefined ? [outputBucket] : [outputContentBucket, outputUnknownContentBucket];
const anonymous = buckets.flatMap(bucket => bucket ? [...bucket] : [])
.find(part => part !== match && !part.itemId && compatible(part)
&& (matchedContent === undefined || part.contentIndex === undefined || matchedContent === part.contentIndex));
if (anonymous) {
indexPart(lookup, match, false);
parts.delete(match.key);
// The linking frame can omit a field that the identified draft already supplied.
if (anonymous.contentIndex === undefined && matchedContent !== undefined) {
indexPart(lookup, anonymous, false);
anonymous.contentIndex = matchedContent;
indexPart(lookup, anonymous, true);
}
return anonymous.key;
}
}
if (indexedPart && compatible(indexedPart)) {
if (match && match !== indexedPart) return match.key;
if ((itemId && indexedPart.itemId === itemId) || outputCandidates === 1) return indexedKey!;
}
if (outputCandidates > 1 && (indexedPart || outputOnly) && !match) return `conflict:${nextOrder}`;
if (!match && outputOnly && compatible(outputOnly) && outputCandidates === 1) match = outputOnly;
if (!match && outputIndex !== undefined && contentIndex === undefined) {
const only = outputBucket?.size === 1 ? outputBucket.values().next().value : undefined;
if (only && compatible(only)) match = only;
}
if (!match && !itemId && indexedKey && !indexedPart && outputCandidates === 0) {
const bucket = lookup.get(JSON.stringify(["unpositioned-content", contentIndex]));
const unknown = lookup.get(JSON.stringify(["unpositioned-content", null]));
if ((bucket?.size ?? 0) + (unknown?.size ?? 0) === 1) {
const candidate = (bucket ?? unknown)?.values().next().value;
if (candidate?.contentIndex !== undefined || candidate?.itemId || parts.size === 1) match = candidate;
}
}
// A content-only part can acquire its item or output identity after other parts arrived.
const contentOnly = contentIndex === undefined ? undefined : parts.get(`content:${contentIndex}`);
if (!match && (itemId || !indexedKey) && contentOnly && compatible(contentOnly)) match = contentOnly;
if (!match && parts.size === 1) {
const only = parts.values().next().value;
if (only && compatible(only) && (!indexedKey || !isIndexedPartKey(only.key))
&& (!itemId || !only.itemId)) match = only;
}
if (match) {
const mergedOutput = outputIndex ?? match.outputIndex;
const mergedContent = contentIndex ?? match.contentIndex;
const mergedKey = mergedOutput === undefined ? undefined : mergedContent === undefined
? `output:${mergedOutput}` : `${mergedOutput}:${mergedContent}`;
if (mergedKey && !parts.has(mergedKey) && match.key !== mergedKey) {
indexPart(lookup, match, false);
parts.delete(match.key);
if (match.key.startsWith("content:")) match.promotedFromContent = true;
match.key = mergedKey;
parts.set(mergedKey, match);
indexPart(lookup, match, true);
return mergedKey;
}
return match.key;
}
if (indexedKey && !indexedPart) return indexedKey;
const key = outputIndex !== undefined && !outputOnly ? `output:${outputIndex}`
: itemId ? `item:${JSON.stringify([itemId, contentIndex ?? null])}`
: contentIndex !== undefined ? `content:${contentIndex}` : UNINDEXED_PART;
const existing = parts.get(key);
return !existing || compatible(existing) ? key : `conflict:${nextOrder}`;
}
function isIndexedPartKey(key: string): boolean {
return key !== UNINDEXED_PART && !key.startsWith("item:") && !key.startsWith("content:") && !key.startsWith("output:") && !key.startsWith("conflict:");
}
/** Order known output indexes numerically; an unknown content index follows known siblings. */
function comparePartKeys(left: string, right: string, streamed: Map<string, StreamedPart>): number {
const position = (key: string): [number, number] => {
const part = streamed.get(key);
if (part?.outputIndex !== undefined) return [part.outputIndex, part.contentIndex ?? Infinity];
return key.split(":").map(Number) as [number, number];
};
const [leftOutput, leftContent] = position(left);
const [rightOutput, rightContent] = position(right);
return leftOutput - rightOutput || leftContent - rightContent
|| (streamed.get(left)?.order ?? -1) - (streamed.get(right)?.order ?? -1);
}
/** One part's streamed text: its done text when present, otherwise its deltas. */
function streamedPartText(part: StreamedPart): string {
return part.done ?? part.delta;
}
/** Keep earlier content-only siblings before a part promoted to an indexed identity. */
function orderedPartKeys(completed: Iterable<string>, streamed: Map<string, StreamedPart>): string[] {
const ordered = (key: string): boolean => isIndexedPartKey(key) || streamed.get(key)?.outputIndex !== undefined;
const indexed = [...new Set([...completed, ...streamed.keys()].filter(ordered))]
.sort((left, right) => comparePartKeys(left, right, streamed));
const contentOnly = [...streamed].filter(([key]) => key.startsWith("content:") && !ordered(key))
.sort((a, b) => a[1].order - b[1].order);
const keys: string[] = [];
let next = 0;
for (const key of indexed) {
const part = streamed.get(key);
if (part?.promotedFromContent) {
while (next < contentOnly.length && contentOnly[next]![1].order < part.order) keys.push(contentOnly[next++]![0]);
}
keys.push(key);
}
const emitted = new Set(contentOnly.slice(0, next).map(([key]) => key));
const remaining = [...streamed].filter(([key]) => !ordered(key) && !emitted.has(key));
remaining.sort((a, b) => a[1].order - b[1].order);
keys.push(...remaining.map(([key]) => key));
return keys;
}
/** Join parts with known output indexes in order, then other parts in arrival order. */
function assembleStreamedText(parts: Map<string, StreamedPart>): string {
return orderedPartKeys([], parts).map(key => streamedPartText(parts.get(key)!)).join("");
}
/**
* Rebuild an incomplete completed output part by part: a part keeps its completed text when the
* completed output has it, and otherwise takes that part's streamed text.
*/
function mergeIncompleteOutput(completed: Map<string, string>, streamed: Map<string, StreamedPart>): string {
const keys = orderedPartKeys(completed.keys(), streamed);
return keys.map(key => {
const text = completed.get(key);
if (text?.trim()) return text;
const part = streamed.get(key);
return part ? streamedPartText(part) : text ?? "";
}).join("");
}
/** Match completed slots to unique compatible streamed parts before filling missing output. */
function reconcileCompletedParts(final: CompletedOutput, streamed: Map<string, StreamedPart>, lookup: PartLookup): Map<string, StreamedPart> {
const reconciled = new Map(streamed);
const matched = new Set<StreamedPart>();
for (const [key, identity] of final.slots) {
const existing = reconciled.get(key);
let part = identity.itemId ? identifiedPart(lookup, identity.itemId, identity.contentIndex, true) : undefined;
if (existing) {
const atContent = lookup.get(JSON.stringify(["output-content", identity.outputIndex, identity.contentIndex]));
const atUnknownContent = lookup.get(JSON.stringify(["output-content", identity.outputIndex, null]));
const ambiguous = !identity.itemId && (atContent?.size ?? 0) + (atUnknownContent?.size ?? 0) > 1;
const different = identity.itemId && existing.itemId && identity.itemId !== existing.itemId;
const otherIdentified = identity.itemId && !existing.itemId && part && part !== existing;
if (!ambiguous && !different && !otherIdentified) continue;
// Preserve a conflicting or ambiguous stream beside the completed slot.
reconciled.delete(key);
reconciled.set(`conflict:completed:${existing.order}`, existing);
}
if (!part && identity.singleContent) {
const bucket = lookup.get(JSON.stringify(["output", identity.outputIndex]));
const candidate = bucket?.size === 1 ? bucket.values().next().value : undefined;
if (candidate?.key.startsWith("output:") && (!identity.itemId || !candidate.itemId || identity.itemId === candidate.itemId)) part = candidate;
}
if (part?.outputIndex !== undefined && part.outputIndex !== identity.outputIndex) continue;
if (!part || matched.has(part) || (part.contentIndex === undefined && !identity.singleContent)) continue;
matched.add(part);
reconciled.delete(part.key);
reconciled.set(key, { ...part, key });
}
for (const [key, part] of reconciled) {
const item = part.itemId ? final.items.get(part.itemId) : undefined;
if (item?.missingContent && part.outputIndex === undefined && !isIndexedPartKey(key)) {
// The message identifies an output position, but cannot invent a content index.
reconciled.set(key, { ...part, outputIndex: item.outputIndex });
}
}
return reconciled;
}
// Keep this compatibility export for non-Responses sidecar executors and bounded error bodies.
export const MAX_SIDECAR_RESPONSE_BYTES = 64 * 1024;
// Responses SSE can spend far more wire bytes on JSON framing than on useful model output. Keep a
// larger finite wire ceiling while separately bounding the decoded text copies accumulated below.
export const MAX_SIDECAR_STREAM_BYTES = MAX_SIDECAR_RESPONSE_BYTES * 16;
export const MAX_SIDECAR_DECODED_CHARS = 64 * 1024;
/**
* Push a `url_citation` annotation as a source, de-duplicated by URL. A repeated URL whose kept
* entry has no usable title takes the first later valid title (#8351), in place and within the
* same source caps; an entry that already has a title keeps it.
*/
function collectAnnotation(ann: AnnotationLike | undefined, sources: WebSearchSource[], seen: Set<string>): void {
if (!ann || ann.type !== "url_citation" || typeof ann.url !== "string") return;
if (seen.has(ann.url)) {
fillMissingWebSearchSourceTitle(sources, ann.url, ann.title);
return;
}
if (appendSafeWebSearchSource(sources, {
url: ann.url,
...(ann.title !== undefined ? { title: ann.title } : {}),
})) seen.add(ann.url);
}
/**
* Hosted web_search (gpt-mini) rarely emits structured `url_citation` annotations; instead it ends
* its answer with a markdown `Sources:` section. Extract sources from that TRAILING section only
* (a whole-body URL scan would false-positive on URLs the model merely mentions), and return the
* answer text with that section stripped so the tool_result renderer doesn't double-print sources.
*
* Handles the per-line forms seen from the backend: `- title: url`, `- title (url)`,
* `- [title](url)`, `- <url>`, `- url`, numbered `1. ...` variants, a markdown-prefixed header
* (`### 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<>()\[\]]+/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.
// The scheme length is bounded so a long word without a colon is scanned in linear time.
const URI_LIKE_RE = /[a-z][a-z0-9+.-]{0,31}:[^\s<>()\[\]]+/i;
// A "Sources:" / "Source:" header, allowing markdown prefixes (#, *, -, >) and bold/italic wrappers.
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 and code backticks. */
function cleanUrl(url: string): string {
return url.replace(/^<+/, "").replace(/[)>\].,;:`]+$/, "");
}
/** Derive a human title from the list-item text preceding the URL (strip markers, md link, seps). */
function cleanTitle(prefix: string): string {
let title = prefix.replace(/^[-*+>\d.)\s]+/, "").trim();
// `[title](` from a markdown link, or a leading `[`.
title = title.replace(/^\[/, "").replace(/\]\(?$/, "");
// Trailing separators and an opening code backtick, trimmed by a linear scan.
let end = title.length;
while (end > 0 && TITLE_TRAILING_SEPARATORS.has(title[end - 1]!)) end -= 1;
return title.slice(0, end).trim();
}
const TITLE_TRAILING_SEPARATORS = new Set([":", "-", "—", "(", "<", "`", " ", "\t"]);
/** A line that looks like a list item (bullet, quote or ordinal marker). */
const LIST_ITEM_RE = /^[-*+>\d.)]/;
/**
* Replace inline code spans with spaces of equal length. A span opens and closes with backtick runs
* of equal length; runs are paired in one pass, so an unmatched run cannot cause backtracking.
*/
function maskInlineCode(line: string): string {
const runs: Array<{ start: number; end: number }> = [];
for (let index = 0; index < line.length;) {
if (line[index] !== "`") { index += 1; continue; }
const start = index;
while (line[index] === "`") index += 1;
runs.push({ start, end: index });
}
if (runs.length < 2) return line;
// For each run, the index of the next run with the same length, or -1.
const next = new Array<number>(runs.length).fill(-1);
const lastByLength = new Map<number, number>();
for (let run = runs.length - 1; run >= 0; run -= 1) {
const length = runs[run]!.end - runs[run]!.start;
next[run] = lastByLength.get(length) ?? -1;
lastByLength.set(length, run);
}
let masked = "";
let cursor = 0;
for (let run = 0; run < runs.length;) {
const close = next[run]!;
if (close === -1) { run += 1; continue; }
masked += line.slice(cursor, runs[run]!.start) + " ".repeat(runs[close]!.end - runs[run]!.start);
cursor = runs[close]!.end;
run = close + 1;
}
return masked + line.slice(cursor);
}
/**
* Move citation lines from the last `Sources:` block into `sources` and strip them from the text.
* List items that cannot be paired with a URL stay in the answer, and every consumed citation line,
* including one whose URL is rejected as unsafe, leaves the text.
*/
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: [], 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
// the list survives (we strip the header through the last consumed source line, not to EOF).
let lastConsumed = headerIdx;
// A title line whose URL is expected on a following line (multiline entry).
let pendingTitle: string | null = null;
let pendingIndex = -1;
// Line indexes of list items that turned out not to title a URL; they remain answer text.
const keptNotes: number[] = [];
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 (consumedSourceLine || pendingTitle !== null) break;
continue;
}
const httpMatch = raw.match(URL_RE);
// URI-like text inside an inline code span of any backtick run, such as `mode:fast`, is prose
// rather than a citation. HTTP(S) URLs keep their citation meaning even when code-formatted.
const m = httpMatch ?? maskInlineCode(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. A second list item
// means the previous one was a note, so it is kept instead of discarded.
if (!LIST_ITEM_RE.test(raw)) break;
if (pendingTitle !== null) keptNotes.push(pendingIndex);
pendingTitle = raw;
pendingIndex = i;
continue;
}
// 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 && !LIST_ITEM_RE.test(raw) && m.index !== 0) break;
const url = cleanUrl(m[0]);
if (!url) { break; }
const inlinePrefix = raw.slice(0, m.index);
const inlineTitle = cleanTitle(inlinePrefix);
// A self-titled citation, or a URL that starts its own list item, does not prove that the
// preceding bullet was its title. Only an unmarked continuation line pairs with it.
const startsListItem = /^(?:[-*+>]|\d+[.)])\s/.test(raw);
const pairsWithPending = pendingTitle !== null && !inlineTitle && !startsListItem;
if (pendingTitle !== null && !pairsWithPending) keptNotes.push(pendingIndex);
consumedSourceLine = true;
lastConsumed = i;
// Title: text before the URL on this line, else a buffered title from a preceding line.
const title = inlineTitle || (pairsWithPending ? cleanTitle(pendingTitle!) : "");
pendingTitle = null;
if (seen.has(url)) continue;
if (appendSafeWebSearchSource(sources, title ? { url, title } : { url })) seen.add(url);
}
if (!consumedSourceLine) return { text, sources: [], stripped: false };
// Keep text before the header, notes found between citations, and anything after the last citation.
const before = lines.slice(0, headerIdx).join("\n").replace(/\s+$/, "");
const notes = keptNotes.filter(index => index < lastConsumed).map(index => lines[index]);
const after = [...notes, lines.slice(lastConsumed + 1).join("\n").replace(/^\s+/, "")].filter(Boolean).join("\n");
const body = after ? (before ? `${before}\n\n${after}` : after) : before;
return { text: body, sources, stripped: true };
}
/**
* Pull final text + url_citation sources from a completed Responses `output[]` array.
* Malformed entries are skipped, and `incomplete` records that the text may be partial.
*/
function fromOutputArray(output: OutputItem[], seen: Set<string>): CompletedOutput {
let text = "";
let incomplete = false;
const parts = new Map<string, string>();
const slots: CompletedOutput["slots"] = new Map();
const items: CompletedOutput["items"] = new Map();
const sources: WebSearchSource[] = [];
for (const [outputIndex, item] of output.entries()) {
if (!item || typeof item !== "object") { incomplete = true; continue; }
if (item.type !== "message") continue;
if (typeof item.id === "string" && item.id) {
items.set(item.id, items.has(item.id) ? null : { outputIndex, missingContent: !Array.isArray(item.content) });
}
if (!Array.isArray(item.content)) { incomplete = true; continue; }
for (const [contentIndex, block] of item.content.entries()) {
if (!block || typeof block !== "object") { incomplete = true; continue; }
if (block.type === "output_text") {
const key = `${outputIndex}:${contentIndex}`;
slots.set(key, { itemId: typeof item.id === "string" && item.id ? item.id : undefined,
outputIndex, contentIndex, singleContent: item.content.length === 1 });
if (typeof block.text !== "string") { incomplete = true; continue; }
text += block.text;
parts.set(key, block.text);
for (const ann of Array.isArray(block.annotations) ? block.annotations : []) collectAnnotation(ann, sources, seen);
}
}
}
return { text, sources, incomplete, parts, slots, items };
}
export 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
* `response.output_text.done` text; falls back to accumulated `response.output_text.delta`. Sources are
* collected from EVERY shape they arrive in — `response.output_text.annotation.added` events (the
* streaming path, which earlier testing missed → empty citations), `done`-block `annotations[]`, and
* the final output[]. A terminal failure, a safety bound, or EOF before a terminal event surfaces as
* `error` even when partial answer text was decoded.
*/
export async function parseSidecarSSE(response: Response): Promise<WebSearchResult> {
if (!response.body) return { text: "", sources: [], error: "sidecar stream returned no response body" };
const reader = response.body.getReader();
const decoder = new TextDecoder();
let buffer = "";
let responseBytes = 0;
const seen = new Set<string>();
const partLookup: PartLookup = new Map();
let nextPartOrder = 0;
// Holder object — fields are mutated inside the closure, so they can't live as narrowed locals.
const acc: {
parts: Map<string, StreamedPart>;
final: CompletedOutput | null;
streamSources: WebSearchSource[];
error: string | null;
decodedChars: number;
terminalEvent: boolean;
limitReached: boolean;
} = {
parts: new Map(),
final: null,
streamSources: [],
error: null,
decodedChars: 0,
terminalEvent: false,
limitReached: false,
};
/** The accumulator for the content part that `data` belongs to. */
const streamedPart = (data: Record<string, unknown>): StreamedPart => {
const key = streamedPartKey(data, acc.parts, partLookup, nextPartOrder);
let part = acc.parts.get(key);
if (!part) { part = { key, order: nextPartOrder++, delta: "", done: null }; acc.parts.set(key, part); }
indexPart(partLookup, part, false);
if (typeof data.item_id === "string" && data.item_id) part.itemId = data.item_id;
if (Number.isInteger(data.output_index)) part.outputIndex = data.output_index as number;
if (Number.isInteger(data.content_index)) part.contentIndex = data.content_index as number;
indexPart(partLookup, part, true);
return part;
};
const acceptDecodedChars = (count: number): boolean => {
if (count > MAX_SIDECAR_DECODED_CHARS - acc.decodedChars) {
acc.error = "sidecar response decoded text limit reached";
acc.limitReached = true;
return false;
}
acc.decodedChars += count;
return true;
};
const handle = (payload: string): void => {
if (!payload || acc.terminalEvent) return;
if (payload === "[DONE]") {
acc.terminalEvent = true;
return;
}
if (acc.limitReached) return;
// 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 = typeof data.type === "string" ? data.type : undefined;
if (type === "response.output_text.delta" && typeof data.delta === "string") {
if (acceptDecodedChars(data.delta.length)) streamedPart(data).delta += data.delta;
} else if (type === "response.output_text.done" && typeof data.text === "string") {
// The `done` event carries the full, authoritative text for one content part.
if (acceptDecodedChars(data.text.length)) streamedPart(data).done = data.text;
} else if (type === "response.completed" || type === "response.done") {
acc.terminalEvent = true;
const resp = data.response as { output?: OutputItem[] } | undefined;
if (Array.isArray(resp?.output)) {
const final = fromOutputArray(resp.output, new Set<string>());
if (acceptDecodedChars(final.text.length)) acc.final = final;
}
} else if (type === "response.failed" || type === "response.incomplete" || type === "error") {
acc.terminalEvent = true;
const resp = data.response as { error?: { message?: string } } | undefined;
const msg = resp?.error?.message
?? (data.error as { message?: string } | undefined)?.message
?? (typeof data.message === "string" ? data.message : undefined);
acc.error = typeof msg === "string" && msg.trim() ? msg : `sidecar stream ended with ${type}`;
} else if (type?.includes("reasoning") && typeof data.delta === "string") {
// Reasoning is not returned, but it is still decoded payload retained transiently by JSON.parse.
acceptDecodedChars(data.delta.length);
}
// Citations stream as a dedicated `response.output_text.annotation.added` event (singular
// `annotation`); capture it regardless of the exact event name so they aren't lost.
if (data.annotation) collectAnnotation(data.annotation as AnnotationLike, acc.streamSources, seen);
};
try {
while (true) {
const { done, value } = await reader.read();
if (done) {
// Compatible Responses servers may omit the final newline. Only physical EOF
// admits this carry; byte/decoded limits and failed reads must not flush it.
buffer += decoder.decode();
const data = sseFieldValue(buffer, "data");
if (data !== null) handle(data.trim());
break;
}
const remaining = MAX_SIDECAR_STREAM_BYTES - responseBytes;
const accepted = value.byteLength <= remaining ? value : value.subarray(0, remaining);
responseBytes += accepted.byteLength;
buffer += decoder.decode(accepted, { stream: true });
// SSE permits CR, LF and CRLF. A split CRLF adds only an ignored empty line here.
const lines = buffer.split(/\r\n|[\r\n]/);
buffer = lines.pop() ?? "";
for (const line of lines) {
const data = sseFieldValue(line, "data");
if (data !== null) handle(data.trim());
}
if (acc.limitReached) {
cancelReaderWithoutWaiting(reader, "sidecar response decoded text limit reached");
buffer = "";
break;
}
if (acc.terminalEvent) {
cancelReaderWithoutWaiting(reader, "sidecar terminal event received");
buffer = "";
break;
}
if (responseBytes >= MAX_SIDECAR_STREAM_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");
acc.error = "sidecar response byte limit reached before terminal event";
acc.limitReached = true;
buffer = "";
break;
}
}
} finally {
reader.releaseLock();
}
// Prefer the authoritative completed output[], then the done text, then accumulated deltas.
// Each streamed content part contributes its done text, or its deltas when the done event never
// arrived. A completed output that skipped malformed entries may be partial: identified parts
// can be matched by item ID, and indexed streams fill only the parts that output lacks.
const streamedText = assembleStreamedText(acc.parts);
const completedText = acc.final?.text.trim() ? acc.final.text : "";
let text = completedText || streamedText;
if (acc.final?.incomplete) {
const reconciled = reconcileCompletedParts(acc.final, acc.parts, partLookup);
const repaired = [...reconciled].some(([key, part]) => isIndexedPartKey(key) || part.outputIndex !== undefined)
? mergeIncompleteOutput(acc.final.parts, reconciled) : streamedText;
if (repaired.trim()) text = repaired;
}
// Merge sources from the final output[] and the streaming annotation events.
const finalSources = acc.final?.sources.map(source => source.title !== undefined ? source
: acc.streamSources.find(streamed => streamed.url === source.url) ?? source);
const sources = safeWebSearchSources(finalSources ?? []);
for (const s of acc.streamSources) {
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, stripped } = extractTrailingSources(typeof text === "string" ? text : "");
for (const s of textSources) {
appendSafeWebSearchSource(sources, s);
}
const finalText = stripped ? body : (typeof text === "string" ? text : "");
const error = acc.error ?? (!acc.terminalEvent ? "sidecar stream ended before terminal event" : null);
if (error) return { text: finalText, sources, error };
return { text: finalText, sources };
}