@sayknow-cli/ai 0.3.16 → 0.4.1

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

@@ -95,12 +95,20 @@ let warnedReasoningSummaryLevel = false;
 
 // ─── inbound parser helpers ─────────────────────────────────────────────────
 
-function extractReasoningTextFromItem(item: OpenAIResponsesReasoningItem): string {
-	// Prefer `summary[]` — mirrors real OpenAI and the openai-responses provider
-	// which writes the surfaced reasoning summary into `summary[].text`.
-	const fromSummary = (item.summary ?? []).map(c => c.text).join("");
-	if (fromSummary) return fromSummary;
-	return (item.content ?? []).map(c => c.text).join("");
+function reasoningContentFromItem(
+	item: OpenAIResponsesReasoningItem,
+): Pick<ThinkingContent, "thinking" | "provenance" | "summaryText" | "rawText"> {
+	// `summary[]` is provider-displayable; `content[]` is raw reasoning. Keep
+	// these channels distinct so a Responses gateway round-trip cannot relabel
+	// raw CoT as a summary merely because summary text is absent.
+	const summaryText = (item.summary ?? []).map(part => part.text).join("");
+	const rawText = (item.content ?? []).map(part => part.text).join("");
+	if (summaryText && rawText) {
+		return { thinking: summaryText, provenance: "mixed", summaryText, rawText };
+	}
+	if (summaryText) return { thinking: summaryText, provenance: "summary", summaryText };
+	if (rawText) return { thinking: rawText, provenance: "raw", rawText };
+	return { thinking: "" };
 }
 
 type InputBlockUnion =
@@ -335,10 +343,10 @@ export function parseRequest(body: unknown, headers?: Headers): ParsedRequest {
 			}
 			if (effectiveType === "reasoning") {
 				const reasoning = item as OpenAIResponsesReasoningItem;
-				const text = extractReasoningTextFromItem(reasoning);
+				const content = reasoningContentFromItem(reasoning);
 				const thinking: ThinkingContent = {
 					type: "thinking",
-					thinking: text,
+					...content,
 					thinkingSignature: JSON.stringify(reasoning),
 					...(reasoning.id ? { itemId: reasoning.id } : {}),
 				};
@@ -538,6 +546,41 @@ function responseStatusForStopReason(message: AssistantMessage): ResponseStatus
 	return "completed";
 }
 
+/**
+ * Privacy boundary for the public Responses envelope: a reasoning item's
+ * `summary_text` must carry ONLY provider-displayable summary text, never raw
+ * chain-of-thought. A summary is published ONLY for blocks explicitly marked
+ * `provenance: "summary" | "mixed"` (the #2304 provenance path), sourced from
+ * `summaryText`. Raw-provenance AND unmarked blocks are omitted: unmarked
+ * `thinking` can be raw CoT from providers that stream unmarked reasoning (e.g.
+ * openai-completions / ollama) which the auth gateway re-encodes into the
+ * Responses wire format, so falling open to `part.thinking` would leak raw CoT.
+ */
+function envelopeSummaryText(part: ThinkingContent): string | undefined {
+	if (part.provenance === "summary" || part.provenance === "mixed") return part.summaryText;
+	return undefined;
+}
+
+function envelopeSummaryParts(part: ThinkingContent): Array<{ type: "summary_text"; text: string }> {
+	const text = envelopeSummaryText(part);
+	return text ? [{ type: "summary_text", text }] : [];
+}
+
+function normalizeSummaryParts(value: unknown): Array<{ type: "summary_text"; text: string }> {
+	// A serialized signature's `summary` is, by the Responses protocol, provider-
+	// displayable summary text (raw reasoning lives in content[]/encrypted_content,
+	// which is stripped). Coerce to the canonical shape, keeping only well-formed
+	// summary_text entries. This is NOT the unsafe `part.thinking` fallback.
+	if (!Array.isArray(value)) return [];
+	const out: Array<{ type: "summary_text"; text: string }> = [];
+	for (const entry of value) {
+		if (isObj(entry) && entry.type === "summary_text" && typeof entry.text === "string") {
+			out.push({ type: "summary_text", text: entry.text });
+		}
+	}
+	return out;
+}
+
 function buildReasoningItem(part: ThinkingContent): ReasoningOutputItem {
 	const baseId = part.itemId ?? makeReasoningId();
 	if (part.thinkingSignature) {
@@ -548,10 +591,15 @@ function buildReasoningItem(part: ThinkingContent): ReasoningOutputItem {
 				// Preserve any extra fields (encrypted_content, …) the original carried,
 				// but normalize the summary into the canonical `{type, text}[]` shape.
 				const merged: Record<string, unknown> = { ...sigParsed, type: "reasoning", id };
-				merged.summary = [{ type: "summary_text", text: part.thinking }];
-				// `content[]` is the encrypted/raw side-channel; leave whatever was
-				// already there. If absent, omit — real OpenAI only emits `content[]`
-				// when `include=['reasoning.encrypted_content']` is set.
+				merged.summary =
+					part.provenance === "summary" || part.provenance === "mixed"
+						? envelopeSummaryParts(part)
+						: normalizeSummaryParts(sigParsed.summary);
+				// Strip any `content[]` (raw `reasoning_text`) the serialized signature
+				// carried: raw chain-of-thought must never surface in the public final
+				// envelope (#2304 CoT boundary). Opaque top-level `encrypted_content`
+				// (when present) is a separate field and is preserved by the spread above.
+				delete merged.content;
 				return merged as ReasoningOutputItem;
 			}
 		} catch {
@@ -561,7 +609,7 @@ function buildReasoningItem(part: ThinkingContent): ReasoningOutputItem {
 	return {
 		type: "reasoning",
 		id: baseId,
-		summary: [{ type: "summary_text", text: part.thinking }],
+		summary: envelopeSummaryParts(part),
 	};
 }
 
@@ -701,7 +749,8 @@ interface OpenReasoning {
 	kind: "reasoning";
 	itemId: string;
 	outputIndex: number;
-	reasoningText: string;
+	summaryText: string;
+	summaryPartText: string;
 }
 interface OpenFunctionCall {
 	kind: "function_call";
@@ -781,16 +830,13 @@ export function encodeStream(
 					summary: [] as Array<{ type: "summary_text"; text: string }>,
 				};
 				emit("response.output_item.added", { output_index: outputIndex, item });
-				// Open the summary part. Real OpenAI streams summary text in the
-				// canonical `reasoning_summary_*` lifecycle; pi-ai's own decoder
-				// reads `summary[].text` from the eventual `output_item.done`.
-				emit("response.reasoning_summary_part.added", {
-					item_id: itemId,
-					output_index: outputIndex,
-					summary_index: 0,
-					part: { type: "summary_text", text: "" },
-				});
-				const next: OpenReasoning = { kind: "reasoning", itemId, outputIndex, reasoningText: "" };
+				const next: OpenReasoning = {
+					kind: "reasoning",
+					itemId,
+					outputIndex,
+					summaryText: "",
+					summaryPartText: "",
+				};
 				state.open = next;
 				return next;
 			};
@@ -856,18 +902,21 @@ export function encodeStream(
 						content: state.open.content,
 					});
 				} else if (state.open.kind === "reasoning") {
-					const summary = [{ type: "summary_text" as const, text: state.open.reasoningText ?? "" }];
-					const item = {
+					const summary = state.open.summaryText
+						? [{ type: "summary_text" as const, text: state.open.summaryText }]
+						: [];
+					// Final reasoning envelope carries the displayable summary ONLY. Raw
+					// chain-of-thought is streamed live via response.reasoning_text.delta
+					// (the internal raw channel) and is deliberately NOT persisted into the
+					// terminal item's content[] — the public final envelope must never carry
+					// raw CoT (#2304 CoT boundary).
+					const item: ReasoningOutputItem = {
 						type: "reasoning",
 						id: state.open.itemId,
 						summary,
 					};
 					emit("response.output_item.done", { output_index: state.open.outputIndex, item });
-					finishedItems.push({
-						type: "reasoning",
-						id: state.open.itemId,
-						summary,
-					});
+					finishedItems.push(item);
 				} else {
 					const text = state.open.argsText ?? "";
 					if (state.open.customWireName) {
@@ -1006,9 +1055,34 @@ export function encodeStream(
 							break;
 						}
 						case "thinking_delta": {
+							// Raw reasoning is private. The public Responses gateway emits only
+							// provider-displayable reasoning_summary_* events.
+							break;
+						}
+						case "thinking_end": {
+							if (state.open?.kind !== "reasoning") break;
+							// Raw reasoning is intentionally omitted from every public gateway
+							// frame. Only reasoning_summary_* events populate the terminal item.
+							closeOpen();
+							break;
+						}
+						case "reasoning_summary_start": {
 							if (state.open?.kind !== "reasoning") break;
 							const cur: OpenReasoning = state.open;
-							cur.reasoningText += ev.delta;
+							cur.summaryPartText = "";
+							emit("response.reasoning_summary_part.added", {
+								item_id: cur.itemId,
+								output_index: cur.outputIndex,
+								summary_index: 0,
+								part: { type: "summary_text", text: "" },
+							});
+							break;
+						}
+						case "reasoning_summary_delta": {
+							if (state.open?.kind !== "reasoning") break;
+							const cur: OpenReasoning = state.open;
+							cur.summaryPartText += ev.delta;
+							cur.summaryText += ev.delta;
 							emit("response.reasoning_summary_text.delta", {
 								item_id: cur.itemId,
 								output_index: cur.outputIndex,
@@ -1017,11 +1091,13 @@ export function encodeStream(
 							});
 							break;
 						}
-						case "thinking_end": {
+						case "reasoning_summary_end": {
 							if (state.open?.kind !== "reasoning") break;
 							const cur: OpenReasoning = state.open;
-							const text = ev.content ?? cur.reasoningText;
-							cur.reasoningText = text;
+							const text = ev.content ?? cur.summaryPartText;
+							// A separator-only accumulated summary (e.g. a part.done "\n\n" before any
+							// real text) is treated as empty so the real end content wins.
+							if (!cur.summaryText.trim()) cur.summaryText = text;
 							emit("response.reasoning_summary_text.done", {
 								item_id: cur.itemId,
 								output_index: cur.outputIndex,
@@ -1034,7 +1110,6 @@ export function encodeStream(
 								summary_index: 0,
 								part: { type: "summary_text", text },
 							});
-							closeOpen();
 							break;
 						}
 						case "toolcall_start": {

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/openai-responses.ts

@@ -33,12 +33,15 @@ import {
 	createOpenAIResponsesHistoryPayload,
 	getOpenAIResponsesHistoryItems,
 	getOpenAIResponsesHistoryPayload,
+	isInvalidPromptError,
+	neutralizeResponsesInputControlTokens,
 	normalizeSystemPrompts,
 	resolveCacheRetention,
 	sanitizeOpenAIResponsesHistoryItemsForReplay,
 } from "../utils";
 import { createAbortSourceTracker } from "../utils/abort";
 import { AssistantMessageEventStream } from "../utils/event-stream";
+import { transportFailureFacts } from "../utils/fallback-transport";
 import { finalizeErrorMessage, type RawHttpRequestDump, rewriteCopilotError } from "../utils/http-inspector";
 import {
 	createWatchdog,
@@ -298,9 +301,12 @@ export const streamOpenAIResponses: StreamFunction<"openai-responses"> = (
 					await notifyProviderResponse(options, response, model, request_id);
 					return data;
 				},
-				{ provider: model.provider, signal: requestSignal },
+				{ provider: model.provider, signal: requestSignal, fallbackManaged: options?.fallbackManaged },
 			).catch(async error => {
-				if (!isForcedToolChoiceUnsupportedError(error, isForcedOpenAIResponsesToolChoice(params.tool_choice))) {
+				if (
+					options?.fallbackManaged ||
+					!isForcedToolChoiceUnsupportedError(error, isForcedOpenAIResponsesToolChoice(params.tool_choice))
+				) {
 					throw error;
 				}
 				const reason = await finalizeErrorMessage(error, rawRequestDump);
@@ -379,8 +385,25 @@ export const streamOpenAIResponses: StreamFunction<"openai-responses"> = (
 			const firstEventTimeoutError = abortTracker.getLocalAbortReason();
 			output.stopReason = abortTracker.wasCallerAbort() ? "aborted" : "error";
 			output.errorStatus = extractHttpStatusFromError(error);
+			output.transportFailure = transportFailureFacts(error);
 			output.errorMessage = firstEventTimeoutError?.message ?? (await finalizeErrorMessage(error, rawRequestDump));
 			output.errorMessage = rewriteCopilotError(output.errorMessage, error, model.provider);
+			// Explicitly mark the poisoned-history rejection so the shared
+			// `invalid_prompt` contract is present even when the SDK error surfaces
+			// only a message (no structured code). This keeps the responses
+			// transport's classification uniform with the codex transport's
+			// non-retryable event set and lets the session-level circuit breaker
+			// key on one durable marker instead of per-transport string matching.
+			if (
+				output.stopReason === "error" &&
+				!output.transportFailure?.providerCode &&
+				(isInvalidPromptError(error) || isInvalidPromptError(output.errorMessage))
+			) {
+				output.transportFailure = {
+					...(output.transportFailure ?? { kind: "transport" }),
+					providerCode: "invalid_prompt",
+				};
+			}
 			output.duration = Date.now() - startTime;
 			if (firstTokenTime) output.ttft = firstTokenTime - startTime;
 			stream.push({ type: "error", reason: output.stopReason, error: output });
@@ -493,7 +516,7 @@ function buildParams(
 		strictResponsesPairing,
 		providerSessionState,
 	);
-	const messages: ResponseInput = [...conversationMessages];
+	const messages: ResponseInput = neutralizeResponsesInputControlTokens(conversationMessages);
 
 	const systemPrompts = normalizeSystemPrompts(context.systemPrompt);
 	if (isComposerHarnessModel(model.id)) {

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

@@ -11,8 +11,8 @@
  *
  * Activated when a {@link Model} has `transport: "pi-native"` set; the
  * dispatch hook lives in `streamSimple()` (see `../stream.ts`). Used by
- * containerized skc deployments (e.g. roboskc slots) that route every LLM call
- * through a credential-holding sidecar so the slot itself stays credential-free.
+ * containerized SKC deployments that route every LLM call through a
+ * credential-holding sidecar so the container stays credential-free.
  */
 import { readSseJson } from "@sayknow-cli/utils";
 import type {
@@ -44,6 +44,7 @@ const NON_WIRE_KEYS = new Set<keyof SimpleStreamOptions>([
 	"cursorExecHandlers",
 	"cursorOnToolResult",
 	"providerSessionState",
+	"fallbackAttempt",
 ]);
 
 function buildWireOptions(options: SimpleStreamOptions | undefined): Record<string, unknown> {
@@ -70,15 +71,27 @@ async function decodeGatewayError(response: Response): Promise<Error> {
 		if (typeof err === "object" && err !== null) {
 			const message = (err as { message?: unknown }).message;
 			const type = (err as { type?: unknown }).type;
+			const code = (err as { code?: unknown }).code;
 			const out = new Error(typeof message === "string" ? message : `auth-gateway ${status}`);
-			(out as { status?: number; type?: string }).status = status;
-			if (typeof type === "string") (out as { type?: string }).type = type;
+			const transportError = out as Error & {
+				status?: number;
+				type?: string;
+				providerCode?: string;
+				headers?: Headers;
+			};
+			transportError.status = status;
+			transportError.headers = response.headers;
+			if (typeof type === "string") transportError.type = type;
+			if (typeof code === "string") transportError.providerCode = code;
+			else if (typeof type === "string") transportError.providerCode = type;
 			return out;
 		}
 	}
 	const text = typeof body === "string" ? body : JSON.stringify(body);
 	const err = new Error(`auth-gateway ${status}: ${text || response.statusText}`);
-	(err as { status?: number }).status = status;
+	const transportError = err as Error & { status?: number; headers?: Headers };
+	transportError.status = status;
+	transportError.headers = response.headers;
 	return err;
 }
 
@@ -180,19 +193,18 @@ export function streamPiNative<TApi extends Api>(
 			}
 
 			if (!sawTerminal) {
-				// SSE closed before a terminal event reached us — synthesize one
-				// so awaiters of `.result()` resolve instead of hanging forever.
-				// Matches the gateway's own defensive fallback in
-				// `pi-native-server.encodeStream`.
 				const aborted = signal?.aborted === true;
-				const partial = makeSyntheticAssistant(model as Model<Api>);
 				if (aborted) {
+					const partial = makeSyntheticAssistant(model as Model<Api>);
 					partial.stopReason = "aborted";
 					partial.errorMessage = "stream closed without terminal event";
 					stream.push({ type: "error", reason: "aborted", error: partial });
 				} else {
-					partial.stopReason = "stop";
-					stream.push({ type: "done", reason: "stop", message: partial });
+					const error = Object.assign(new Error("pi-native SSE stream closed without terminal event"), {
+						status: 502,
+						headers: response.headers,
+					});
+					stream.fail(error);
 				}
 			}
 			stream.end();