@sayknow-cli/ai 0.3.15 → 0.4.0

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

@@ -4,19 +4,18 @@
  * Where the OpenAI / Anthropic / Responses route modules translate foreign
  * wire shapes through pi-ai's canonical {@link Context}, this module accepts
  * the canonical shape *directly* — for clients that already speak pi-ai
- * (containerized skc and roboskc's sidecar auth-gateway).
+ * (containerized SKC deployments and sidecar auth gateways).
  * Skipping the wire-format → Context → wire-format round-trip cuts
  * per-request CPU but, more importantly, avoids the quantization that those
  * 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;
@@ -56,6 +62,7 @@ const ALLOWED_OPTION_KEYS: ReadonlySet<keyof SimpleStreamOptions> = new Set([
 	"headers",
 	"initiatorOverride",
 	"maxRetryDelayMs",
+	"fallbackManaged",
 	"metadata",
 	"sessionId",
 	"streamFirstEventTimeoutMs",
@@ -147,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 skc → host gateway, roboskc slot → skc-auth-gateway
- * sidecar) 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

@@ -28,6 +28,7 @@ import type { OpenAICodexResponsesOptions } from "./providers/openai-codex-respo
 import type { OpenAICompletionsOptions } from "./providers/openai-completions";
 import type { OpenAIResponsesOptions } from "./providers/openai-responses";
 import type { AssistantMessageEventStream } from "./utils/event-stream";
+import type { FallbackAttemptToken, TransportFailureFacts } from "./utils/fallback-transport";
 
 export type { AssistantMessageEventStream } from "./utils/event-stream";
 
@@ -77,6 +78,23 @@ export type ThinkingControlMode =
 	| "anthropic-adaptive"
 	| "anthropic-budget-effort";
 
+/** Canonical runtime vocabulary for provider thinking transports. */
+export const THINKING_CONTROL_MODES = [
+	"effort",
+	"budget",
+	"google-level",
+	"anthropic-adaptive",
+	"anthropic-budget-effort",
+] as const satisfies readonly ThinkingControlMode[];
+
+type _CheckThinkingControlModes = [
+	Exclude<ThinkingControlMode, (typeof THINKING_CONTROL_MODES)[number]>,
+	Exclude<(typeof THINKING_CONTROL_MODES)[number], ThinkingControlMode>,
+] extends [never, never]
+	? true
+	: false;
+true satisfies _CheckThinkingControlModes;
+
 /** Per-model thinking capabilities used to clamp and map user-facing effort levels. */
 export interface ThinkingConfig {
 	/** Least intensive supported user-facing effort level. */
@@ -306,6 +324,10 @@ export interface StreamOptions {
 	maxTokens?: number;
 	signal?: AbortSignal;
 	apiKey?: string;
+	/** Disables all transport-level replay; the fallback controller owns retries. */
+	fallbackManaged?: boolean;
+	/** Opaque token returned by beginAttempt for a managed transport invocation. */
+	fallbackAttempt?: FallbackAttemptToken;
 	/**
 	 * Called when a provider returns 401 before any replay-unsafe assistant
 	 * event has been emitted. Returning a different key retries the provider
@@ -466,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 {
@@ -598,6 +623,8 @@ export interface AssistantMessage {
 	errorKind?: AssistantErrorKind;
 	/** HTTP status surfaced by the provider when the request failed. Populated by every provider's catch block alongside `errorMessage` so consumers (auth retry, telemetry, UI) can branch without regex-scraping the message. */
 	errorStatus?: number;
+	/** Typed upstream failure facts retained for retry classification without parsing errorMessage. */
+	transportFailure?: TransportFailureFacts;
 	/**
 	 * Stable identifiers for request features the provider silently dropped
 	 * during this turn (e.g. `"priority"`). Set when a server-side rejection
@@ -682,10 +709,17 @@ export type TSchema = ZodType | TJsonSchema;
 /** Resolve parameter types for tool execution / handlers. */
 export type Static<S> = S extends ZodType ? z.infer<S> : S extends { static: infer T } ? T : unknown;
 
+export type RawArgumentValidationResult =
+	| { outcome: "passthrough" }
+	| { outcome: "accept"; arguments: ToolCall["arguments"] }
+	| { outcome: "reject" };
+
 export interface Tool<TParameters extends TSchema = TSchema> {
 	name: string;
 	description: string;
 	parameters: TParameters;
+	/** Optional pre-coercion adapter for narrowly scoped raw argument recovery or rejection. */
+	rawArgumentValidation?: (arguments_: ToolCall["arguments"]) => RawArgumentValidationResult;
 	/** If true, tool is strictly typed and validated against the parameters schema before execution */
 	strict?: boolean;
 	/**
@@ -705,6 +739,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 {
@@ -721,6 +762,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 }
@@ -865,6 +909,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";
 }
 
 /**
@@ -939,10 +989,9 @@ export interface Model<TApi extends Api = any> {
 	 * (or compatible) host; `headers.Authorization` (or `apiKey` resolved by
 	 * the registry) carries the gateway bearer.
 	 *
-	 * Used by containerized skc installs (e.g. roboskc slots) to route every
-	 * LLM call through a sidecar gateway that holds the real provider
-	 * credentials. The model's other metadata (pricing, context window,
-	 * thinking config, …) still resolves locally; only the streaming
+	 * Used by containerized SKC installs to route every LLM call through a
+	 * sidecar gateway that holds the real provider credentials. The model's other
+	 * metadata (pricing, context window, thinking config, …) still resolves locally; only the streaming
 	 * dispatch is redirected.
 	 */
 	transport?: "pi-native";

package/src/utils/discovery/codex.ts

@@ -1,10 +1,10 @@
 import * as z from "zod/v4";
+import { resolveCodexGpt56DiscoveryContext } from "../../context-cap-policy";
 import { CODEX_BASE_URL, OPENAI_HEADER_VALUES, OPENAI_HEADERS } from "../../providers/openai-codex/constants";
 import type { Model } from "../../types";
 import { isRecord } from "../../utils";
 
 const DEFAULT_MODEL_LIST_PATHS = ["/codex/models", "/models"] as const;
-const DEFAULT_CONTEXT_WINDOW = 272_000;
 const DEFAULT_MAX_TOKENS = 128_000;
 const DEFAULT_CODEX_CLIENT_VERSION = "0.99.0";
 const NPM_CODEX_LATEST_URL = "https://registry.npmjs.org/@openai%2Fcodex/latest";
@@ -258,7 +258,8 @@ function normalizeCodexModelEntry(entry: unknown, baseUrl: string): NormalizedCo
 	}
 
 	const name = toNonEmptyString(payload.display_name) ?? slug;
-	const contextWindow = toPositiveInt(payload.context_window) ?? DEFAULT_CONTEXT_WINDOW;
+	const modelIdentity = { id: slug, api: "openai-codex-responses", provider: "openai-codex" } as const;
+	const contextWindow = resolveCodexGpt56DiscoveryContext(modelIdentity, payload.context_window);
 	const maxTokens = Math.min(DEFAULT_MAX_TOKENS, contextWindow);
 	const reasoning = supportsReasoning(payload.default_reasoning_level, payload.supported_reasoning_levels);
 	const input = normalizeInputModalities(payload.input_modalities);
@@ -346,16 +347,6 @@ function toNonEmptyString(value: unknown): string | null {
 	return trimmed.length > 0 ? trimmed : null;
 }
 
-function toPositiveInt(value: unknown): number | null {
-	if (typeof value !== "number" || !Number.isFinite(value)) {
-		return null;
-	}
-	if (value <= 0) {
-		return null;
-	}
-	return Math.trunc(value);
-}
-
 function toFiniteNumber(value: unknown): number | null {
 	if (typeof value !== "number" || !Number.isFinite(value)) {
 		return null;