@gajae-code/ai 0.11.1 → 0.11.3

package/src/providers/openai-responses-shared.ts

@@ -376,6 +376,9 @@ export async function processResponsesStream<TApi extends Api>(
 		item: StreamItem;
 		block: StreamBlock;
 		blockContentIndex: number;
+		summaryBuffer: string;
+		rawBuffer: string;
+		summaryStarted: boolean;
 	}
 	// Per-item argument buffer keyed on stable item identity. Multiple tool-call
 	// items can stream interleaved argument deltas in one response, so a single
@@ -412,7 +415,14 @@ export async function processResponsesStream<TApi extends Api>(
 	};
 	const registerEntry = (item: StreamItem, block: StreamBlock, outputIndex: number | undefined): ItemEntry => {
 		output.content.push(block);
-		const entry: ItemEntry = { item, block, blockContentIndex: output.content.length - 1 };
+		const entry: ItemEntry = {
+			item,
+			block,
+			blockContentIndex: output.content.length - 1,
+			summaryBuffer: "",
+			rawBuffer: "",
+			summaryStarted: false,
+		};
 		// Primary key prefers the stable item id; if the wire omits it, fall back to
 		// the positional index. A synthetic key keeps the entry addressable as lastKey
 		// for continuation-style non-tool events even when neither is present.
@@ -480,9 +490,13 @@ export async function processResponsesStream<TApi extends Api>(
 			}
 		} else if (event.type === "response.reasoning_summary_part.added") {
 			const entry = resolveEntry(event.item_id, event.output_index, "always");
-			if (entry?.item.type === "reasoning") {
+			if (entry?.item.type === "reasoning" && entry.block.type === "thinking") {
 				entry.item.summary = entry.item.summary || [];
 				entry.item.summary.push(event.part);
+				if (!entry.summaryStarted) {
+					entry.summaryStarted = true;
+					stream.push({ type: "reasoning_summary_start", contentIndex: entry.blockContentIndex, partial: output });
+				}
 			}
 		} else if (event.type === "response.reasoning_summary_text.delta") {
 			const entry = resolveEntry(event.item_id, event.output_index, "always");
@@ -491,9 +505,10 @@ export async function processResponsesStream<TApi extends Api>(
 				const lastPart = entry.item.summary[entry.item.summary.length - 1];
 				if (lastPart) {
 					entry.block.thinking += event.delta;
+					entry.summaryBuffer += event.delta;
 					lastPart.text += event.delta;
 					stream.push({
-						type: "thinking_delta",
+						type: "reasoning_summary_delta",
 						contentIndex: entry.blockContentIndex,
 						delta: event.delta,
 						partial: output,
@@ -507,9 +522,10 @@ export async function processResponsesStream<TApi extends Api>(
 				const lastPart = entry.item.summary[entry.item.summary.length - 1];
 				if (lastPart) {
 					entry.block.thinking += "\n\n";
+					entry.summaryBuffer += "\n\n";
 					lastPart.text += "\n\n";
 					stream.push({
-						type: "thinking_delta",
+						type: "reasoning_summary_delta",
 						contentIndex: entry.blockContentIndex,
 						delta: "\n\n",
 						partial: output,
@@ -522,6 +538,7 @@ export async function processResponsesStream<TApi extends Api>(
 			const entry = resolveEntry(event.item_id, event.output_index, "always");
 			if (entry?.item.type === "reasoning" && entry.block.type === "thinking") {
 				entry.block.thinking += event.delta;
+				entry.rawBuffer += event.delta;
 				stream.push({
 					type: "thinking_delta",
 					contentIndex: entry.blockContentIndex,
@@ -608,12 +625,15 @@ export async function processResponsesStream<TApi extends Api>(
 			options?.onOutputItemDone?.(item);
 			const entry = resolveEntry(item.id, event.output_index, "never");
 			if (item.type === "reasoning") {
-				const thinking =
-					item.summary?.length > 0
-						? item.summary.map(part => part.text).join("\n\n")
-						: item.content?.[0]?.type === "reasoning_text"
-							? (item.content[0].text ?? "")
-							: "";
+				// Prefer the streamed summary buffer only when it carries real text. When it
+				// holds only synthetic separators (e.g. a part.done arrived before/without any
+				// summary_text delta), fall back to the canonical `item.summary` from
+				// output_item.done so the materialized summaryText is not blank/separator-only.
+				const bufferSummary = entry?.summaryBuffer ?? "";
+				const itemSummary = item.summary?.map(part => part.text).join("\n\n") ?? "";
+				const summaryText = bufferSummary.trim() ? bufferSummary : itemSummary;
+				const rawText =
+					entry?.rawBuffer || (item.content?.[0]?.type === "reasoning_text" ? (item.content[0].text ?? "") : "");
 				const reasoningBlock =
 					entry?.block.type === "thinking"
 						? entry.block
@@ -621,14 +641,53 @@ export async function processResponsesStream<TApi extends Api>(
 								| ThinkingContent
 								| undefined);
 				if (reasoningBlock) {
-					reasoningBlock.thinking = thinking;
+					const mutable = reasoningBlock as {
+						provenance?: "summary" | "raw" | "mixed";
+						summaryText?: string;
+						rawText?: string;
+					};
+					if (mutable.provenance === undefined) {
+						if (mutable.summaryText === undefined && summaryText) mutable.summaryText = summaryText;
+						if (mutable.rawText === undefined && rawText) mutable.rawText = rawText;
+						mutable.provenance =
+							summaryText && rawText ? "mixed" : summaryText ? "summary" : rawText ? "raw" : undefined;
+					}
+					// Finalized display string must exclude raw CoT when a summary exists.
+					// Derive it from the STORED write-once provenance fields (falling back to
+					// this event's locals only for a first classification) so a later or
+					// duplicate finalization carrying only raw can never overwrite a summary/
+					// mixed block's safe display with raw CoT. Raw-only stays raw.
+					{
+						const effSummary = mutable.summaryText ?? summaryText;
+						const effRaw = mutable.rawText ?? rawText;
+						reasoningBlock.thinking = mutable.provenance === "raw" ? effRaw : effSummary || effRaw;
+					}
 					reasoningBlock.thinkingSignature = JSON.stringify(item);
 					const reasoningBlockIndex =
 						entry?.block === reasoningBlock ? entry.blockContentIndex : output.content.indexOf(reasoningBlock);
+					if (summaryText) {
+						// If the summary text came only from the canonical item.summary (no
+						// streamed summary deltas/part.added), no reasoning_summary_start was
+						// emitted. Emit one now so consumers that open a summary on start
+						// (e.g. the Responses SSE encoder) don't receive an orphaned end.
+						if (!entry?.summaryStarted) {
+							stream.push({
+								type: "reasoning_summary_start",
+								contentIndex: reasoningBlockIndex,
+								partial: output,
+							});
+						}
+						stream.push({
+							type: "reasoning_summary_end",
+							contentIndex: reasoningBlockIndex,
+							content: summaryText,
+							partial: output,
+						});
+					}
 					stream.push({
 						type: "thinking_end",
 						contentIndex: reasoningBlockIndex,
-						content: thinking,
+						content: reasoningBlock.thinking,
 						partial: output,
 					});
 				}

package/src/providers/pi-native-server.ts

@@ -10,13 +10,12 @@
  * translations impose on first-class pi-ai fields (service tier, cache
  * markers, thinking budgets, tool-choice variants, …).
  *
- * The streaming wire is {@link AssistantMessageEvent} serialized verbatim and
- * SSE-framed. Same type pi-ai already produces internally; the client feeds
- * each parsed event straight into `AssistantMessageEventStream.push()` with
- * no translation. Including `partial: AssistantMessage` on every delta is
- * O(N²) in turn length on the wire — acceptable for the loopback / sidecar
- * topology this transport is designed for; provider latency dominates the
- * actual cost.
+ * The streaming wire is {@link AssistantMessageEvent} serialized as SSE. Public
+ * projections omit private raw reasoning and serialized Responses reasoning
+ * signatures while preserving provider-displayable summaries and genuine opaque
+ * signatures. Including `partial: AssistantMessage` on every delta is O(N²) in
+ * turn length on the wire — acceptable for the loopback / sidecar topology this
+ * transport is designed for; provider latency dominates the actual cost.
  *
  * Endpoint contract:
  *   POST /v1/pi/stream
@@ -25,7 +24,14 @@
  *   200 JSON (stream=false): { message: AssistantMessage }
  *   4xx/5xx: { error: { type, message } }
  */
-import type { AssistantMessageEventStream, Context, SimpleStreamOptions } from "../types";
+import type {
+	AssistantMessage,
+	AssistantMessageEvent,
+	AssistantMessageEventStream,
+	Context,
+	SimpleStreamOptions,
+	ThinkingContent,
+} from "../types";
 
 export interface PiNativeParsedRequest {
 	modelId: string;
@@ -148,25 +154,272 @@ export function parseRequest(body: unknown, _headers?: Headers): PiNativeParsedR
 const SSE_ENCODER = new TextEncoder();
 const SSE_DONE = SSE_ENCODER.encode("data: [DONE]\n\n");
 
+function isSerializedResponsesReasoningItem(signature: string): boolean {
+	try {
+		const parsed: unknown = JSON.parse(signature);
+		return (
+			typeof parsed === "object" &&
+			parsed !== null &&
+			!Array.isArray(parsed) &&
+			(parsed as { type?: unknown }).type === "reasoning"
+		);
+	} catch {
+		return false;
+	}
+}
+
 /**
- * Ship every {@link AssistantMessageEvent} verbatim, SSE-framed.
- *
- * No per-event re-shaping: the pi-native client is pi-ai itself, so the
- * canonical event type IS the wire type. Including the rolling
- * `partial: AssistantMessage` on every delta is quadratic in turn length
- * on the wire, but for the loopback / sidecar topology this transport
- * targets (containerized GJC → host gateway) the bandwidth cost is negligible
- * compared to provider latency —
- * and the client gets to feed the events straight into its existing
- * `AssistantMessageEventStream.push()` plumbing with zero translation.
+ * Clone a thinking block for public transport. Raw reasoning is private: omit
+ * raw-only blocks, retain only the displayable summary for mixed blocks, and
+ * never forward a serialized Responses reasoning item as a signature.
+ */
+function isResponsesFamilyApi(api: AssistantMessage["api"]): boolean {
+	return api === "openai-responses" || api === "openai-codex-responses";
+}
+
+function sanitizeThinking(content: ThinkingContent, api: AssistantMessage["api"]): ThinkingContent | undefined {
+	if (isResponsesFamilyApi(api) && content.provenance === undefined) return undefined;
+	if (content.provenance === "raw") return undefined;
+
+	let thinking: string;
+	if (content.provenance === "mixed") {
+		if (content.summaryText === undefined) return undefined;
+		thinking = content.summaryText;
+	} else {
+		thinking = content.provenance === "summary" ? (content.summaryText ?? content.thinking) : content.thinking;
+	}
+	const signature =
+		content.thinkingSignature && isSerializedResponsesReasoningItem(content.thinkingSignature)
+			? undefined
+			: content.thinkingSignature;
+	const { rawText: _rawText, thinkingSignature: _thinkingSignature, ...rest } = content;
+	return signature === undefined ? { ...rest, thinking } : { ...rest, thinking, thinkingSignature: signature };
+}
+
+function sanitizeMessage(message: AssistantMessage): AssistantMessage {
+	let changed = false;
+	const content: AssistantMessage["content"] = [];
+	for (const part of message.content) {
+		if (part.type !== "thinking") {
+			content.push(part);
+			continue;
+		}
+		const needsSanitizing =
+			(isResponsesFamilyApi(message.api) && part.provenance === undefined) ||
+			part.provenance !== undefined ||
+			part.rawText !== undefined ||
+			(part.thinkingSignature !== undefined && isSerializedResponsesReasoningItem(part.thinkingSignature));
+		if (!needsSanitizing) {
+			content.push(part);
+			continue;
+		}
+		const sanitized = sanitizeThinking(part, message.api);
+		changed = true;
+		if (sanitized !== undefined) content.push(sanitized);
+	}
+	return changed ? { ...message, content } : message;
+}
+
+function hasRawOrMixedThinking(partial: AssistantMessage, contentIndex: number): boolean {
+	const content = partial.content[contentIndex];
+	return content?.type === "thinking" && (content.provenance === "raw" || content.provenance === "mixed");
+}
+
+type ThinkingEvent = Extract<AssistantMessageEvent, { type: "thinking_start" | "thinking_delta" | "thinking_end" }>;
+
+interface BufferedThinkingEvent {
+	event: ThinkingEvent;
+	sequence: number;
+}
+
+function isFinalSafeThinking(partial: AssistantMessage, contentIndex: number): boolean {
+	const content = partial.content[contentIndex];
+	return (
+		content?.type === "thinking" &&
+		(!isResponsesFamilyApi(partial.api) || content.provenance !== undefined) &&
+		!hasRawOrMixedThinking(partial, contentIndex)
+	);
+}
+
+function maskBufferedThinking(message: AssistantMessage, contentIndexes: ReadonlySet<number>): AssistantMessage {
+	let changed = false;
+	const content = message.content.map((part, contentIndex) => {
+		if (!contentIndexes.has(contentIndex) || part.type !== "thinking") return part;
+		changed = true;
+		return { type: "thinking" as const, thinking: "", ...(part.itemId ? { itemId: part.itemId } : {}) };
+	});
+	return changed ? { ...message, content } : message;
+}
+
+function maskBufferedThinkingInEvent(
+	event: AssistantMessageEvent,
+	contentIndexes: ReadonlySet<number>,
+): AssistantMessageEvent {
+	if (contentIndexes.size === 0) return event;
+	switch (event.type) {
+		case "done":
+		case "error":
+		case "toolChoiceIncapability":
+			return event;
+		case "start":
+		case "text_start":
+		case "text_delta":
+		case "text_end":
+		case "thinking_start":
+		case "thinking_delta":
+		case "thinking_end":
+		case "reasoning_summary_start":
+		case "reasoning_summary_delta":
+		case "reasoning_summary_end":
+		case "toolcall_start":
+		case "toolcall_delta":
+		case "toolcall_end":
+			return { ...event, partial: maskBufferedThinking(event.partial, contentIndexes) };
+	}
+}
+
+function withSummaryPartial<
+	T extends Extract<
+		AssistantMessageEvent,
+		{ type: "reasoning_summary_start" | "reasoning_summary_delta" | "reasoning_summary_end" }
+	>,
+>(event: T, contentIndexes: ReadonlySet<number>, summaryText: string): T {
+	const partial = maskBufferedThinking(event.partial, contentIndexes);
+	const content = [...partial.content];
+	const original = event.partial.content[event.contentIndex];
+	content[event.contentIndex] = {
+		type: "thinking",
+		thinking: summaryText,
+		provenance: "summary",
+		summaryText,
+		...(original?.type === "thinking" && original.itemId ? { itemId: original.itemId } : {}),
+	};
+	return { ...event, partial: { ...partial, content } };
+}
+
+function sanitizeEvent(event: AssistantMessageEvent): AssistantMessageEvent | undefined {
+	switch (event.type) {
+		case "done":
+			return { ...event, message: sanitizeMessage(event.message) };
+		case "error":
+			return { ...event, error: sanitizeMessage(event.error) };
+		case "toolChoiceIncapability":
+			return event;
+		case "thinking_start":
+		case "thinking_delta":
+		case "thinking_end":
+			return hasRawOrMixedThinking(event.partial, event.contentIndex)
+				? undefined
+				: { ...event, partial: sanitizeMessage(event.partial) };
+		case "start":
+		case "text_start":
+		case "text_delta":
+		case "text_end":
+		case "reasoning_summary_start":
+		case "reasoning_summary_delta":
+		case "reasoning_summary_end":
+		case "toolcall_start":
+		case "toolcall_delta":
+		case "toolcall_end":
+			return { ...event, partial: sanitizeMessage(event.partial) };
+	}
+}
+
+/**
+ * Ship only public-safe {@link AssistantMessageEvent} projections. Unknown
+ * thinking blocks remain buffered until their terminal partial establishes that
+ * the provider-native block is safe; raw and mixed blocks never reach SSE.
  */
 export function encodeStream(events: AssistantMessageEventStream): ReadableStream<Uint8Array> {
 	return new ReadableStream<Uint8Array>({
 		async start(controller) {
+			const bufferedThinking = new Map<number, BufferedThinkingEvent[]>();
+			const summaryTextByIndex = new Map<number, string>();
+			let sequence = 0;
+			const write = (event: AssistantMessageEvent): void => {
+				const sanitized = sanitizeEvent(event);
+				if (sanitized !== undefined) {
+					controller.enqueue(SSE_ENCODER.encode(`data: ${JSON.stringify(sanitized)}\n\n`));
+				}
+			};
+			const emit = (event: AssistantMessageEvent): void => {
+				write(maskBufferedThinkingInEvent(event, new Set(bufferedThinking.keys())));
+			};
+			const flush = (buffered: BufferedThinkingEvent[]): void => {
+				for (const { event } of buffered.sort((a, b) => a.sequence - b.sequence)) emit(event);
+			};
+			const resolveBufferedThinking = (final: AssistantMessage): void => {
+				const ready: BufferedThinkingEvent[] = [];
+				for (const [contentIndex, buffered] of bufferedThinking) {
+					if (isFinalSafeThinking(final, contentIndex)) ready.push(...buffered);
+				}
+				bufferedThinking.clear();
+				flush(ready);
+			};
 			try {
 				for await (const event of events) {
-					controller.enqueue(SSE_ENCODER.encode(`data: ${JSON.stringify(event)}\n\n`));
-					if (event.type === "done" || event.type === "error") break;
+					switch (event.type) {
+						case "thinking_start":
+						case "thinking_delta": {
+							if (hasRawOrMixedThinking(event.partial, event.contentIndex)) {
+								bufferedThinking.delete(event.contentIndex);
+								break;
+							}
+							const buffered = bufferedThinking.get(event.contentIndex) ?? [];
+							buffered.push({ event, sequence: sequence++ });
+							bufferedThinking.set(event.contentIndex, buffered);
+							break;
+						}
+						case "thinking_end": {
+							const buffered = bufferedThinking.get(event.contentIndex) ?? [];
+							bufferedThinking.delete(event.contentIndex);
+							if (!isFinalSafeThinking(event.partial, event.contentIndex)) break;
+							buffered.push({ event, sequence: sequence++ });
+							flush(buffered);
+							break;
+						}
+						case "done":
+							resolveBufferedThinking(event.message);
+							summaryTextByIndex.clear();
+							emit(event);
+							controller.enqueue(SSE_DONE);
+							controller.close();
+							return;
+						case "error":
+							resolveBufferedThinking(event.error);
+							summaryTextByIndex.clear();
+							emit(event);
+							controller.enqueue(SSE_DONE);
+							controller.close();
+							return;
+						case "reasoning_summary_start": {
+							summaryTextByIndex.set(event.contentIndex, "");
+							write(withSummaryPartial(event, new Set(bufferedThinking.keys()), ""));
+							break;
+						}
+						case "reasoning_summary_delta": {
+							const summaryText = `${summaryTextByIndex.get(event.contentIndex) ?? ""}${event.delta}`;
+							summaryTextByIndex.set(event.contentIndex, summaryText);
+							write(withSummaryPartial(event, new Set(bufferedThinking.keys()), summaryText));
+							break;
+						}
+						case "reasoning_summary_end": {
+							const summaryText = event.content || summaryTextByIndex.get(event.contentIndex) || "";
+							summaryTextByIndex.delete(event.contentIndex);
+							write(withSummaryPartial(event, new Set(bufferedThinking.keys()), summaryText));
+							break;
+						}
+						case "start":
+						case "text_start":
+						case "text_delta":
+						case "text_end":
+						case "toolcall_start":
+						case "toolcall_delta":
+						case "toolcall_end":
+						case "toolChoiceIncapability":
+							emit(event);
+							break;
+					}
 				}
 				controller.enqueue(SSE_DONE);
 				controller.close();

package/src/types.ts

@@ -488,6 +488,9 @@ export interface ThinkingContent {
 	thinking: string;
 	thinkingSignature?: string; // e.g., for OpenAI responses, the reasoning item ID
 	itemId?: string; // item.id from output_item.added, used to match output_item.done
+	readonly provenance?: "summary" | "raw" | "mixed";
+	readonly summaryText?: string;
+	readonly rawText?: string;
 }
 
 export interface RedactedThinkingContent {
@@ -729,6 +732,13 @@ export interface Tool<TParameters extends TSchema = TSchema> {
 	 * calls route correctly. Absent for regular JSON function tools.
 	 */
 	customWireName?: string;
+	/**
+	 * Optional safe projection for tool arguments or results. Extensions use this
+	 * only for explicitly opt-in, display-safe summaries.
+	 */
+	safeSummary?: (kind: "args" | "result", value: unknown) => string | undefined;
+	/** Allowlisted argument/result field names for a safe fallback summary. */
+	safeSummaryFields?: { args?: string[]; result?: string[] };
 }
 
 export interface Context {
@@ -745,6 +755,9 @@ export type AssistantMessageEvent =
 	| { type: "thinking_start"; contentIndex: number; partial: AssistantMessage }
 	| { type: "thinking_delta"; contentIndex: number; delta: string; partial: AssistantMessage }
 	| { type: "thinking_end"; contentIndex: number; content: string; partial: AssistantMessage }
+	| { type: "reasoning_summary_start"; contentIndex: number; partial: AssistantMessage }
+	| { type: "reasoning_summary_delta"; contentIndex: number; delta: string; partial: AssistantMessage }
+	| { type: "reasoning_summary_end"; contentIndex: number; content: string; partial: AssistantMessage }
 	| { type: "toolcall_start"; contentIndex: number; partial: AssistantMessage }
 	| { type: "toolcall_delta"; contentIndex: number; delta: string; partial: AssistantMessage }
 	| { type: "toolcall_end"; contentIndex: number; toolCall: ToolCall; partial: AssistantMessage }
@@ -889,6 +902,12 @@ export interface AnthropicCompat extends ToolChoiceCompat {
 	supportsForcedToolChoice?: boolean;
 	/** Whether long prompt-cache retention (`ttl: "1h"`) is supported. Default: true for canonical Anthropic API. */
 	supportsLongCacheRetention?: boolean;
+	/**
+	 * Prompt-cache transport accepted by this Anthropic-compatible endpoint.
+	 * Canonical Anthropic defaults to `"automatic"`; noncanonical endpoints default
+	 * to `"none"` and must explicitly opt into generated `"explicit"` markers.
+	 */
+	promptCacheMode?: "none" | "explicit" | "automatic";
 }
 
 /**

package/src/utils/event-stream.ts

@@ -123,12 +123,16 @@ export class EventStream<T, R = T> implements AsyncIterable<T> {
 
 	push(event: T): void {
 		if (this.done) return;
-
-		if (this.isComplete(event)) {
-			this.done = true;
-			this.resolveFinalResult(this.extractResult(event));
+		try {
+			if (this.isComplete(event)) {
+				const result = this.extractResult(event);
+				this.done = true;
+				this.resolveFinalResult(result);
+			}
+		} catch (error) {
+			this.fail(error);
+			return;
 		}
-
 		this.deliver(event);
 	}