pi-openai-toolkit 0.20.8 → 0.21.1

package/src/compact-client.ts

@@ -1,9 +1,10 @@
 import { writeDebugArtifact } from "./debug";
+import { decodeCompactionError, readCompactionResponseText, type CompactionErrorInfo } from "./compaction-errors";
 import { buildResponsesRequestHeaders } from "./responses-headers";
 import { stripConfigurationUpdateItems } from "./remote-v2-client";
 import type { NativeCompactionRuntime } from "./runtime";
 import type { NativeCompactionRequestBody } from "./serializer";
-import type { ArtifactContext, CompactionConfig } from "./types";
+import { isCompactedWindowItem, type ArtifactContext, type CompactionConfig } from "./types";
 
 const JSON_CONTENT_TYPE = "application/json";
 
@@ -21,7 +22,9 @@ export type NativeCompactionClientFailureReason =
 	| "empty-body"
 	| "invalid-json"
 	| "malformed-response"
-	| "empty-output";
+	| "empty-output"
+	| "missing-compaction"
+	| "malformed-compaction-item";
 
 export type NativeCompactionClientSuccess = {
 	ok: true;
@@ -29,12 +32,12 @@ export type NativeCompactionClientSuccess = {
 	compactedWindow: unknown[];
 	compactResponseId?: string;
 	createdAt?: string;
-	/** Assistant summary text extracted from the compact output, for CompactionEntry.summary. */
+	/** Retained assistant text only; not a portable summary of the opaque window. */
 	summaryText?: string;
 	response: CompactResponseEnvelope;
 };
 
-export type NativeCompactionClientFailure = {
+export type NativeCompactionClientFailure = CompactionErrorInfo & {
 	ok: false;
 	reason: NativeCompactionClientFailureReason;
 	status?: number;
@@ -83,19 +86,11 @@ function normalizeResponseTimestamp(value: unknown): string | undefined {
 	return Number.isNaN(parsed) ? trimmed : new Date(parsed).toISOString();
 }
 
-function isCompactOutputItem(value: unknown): value is Record<string, unknown> {
-	return isRecord(value);
-}
-
 function isCompactResponseEnvelope(value: unknown): value is CompactResponseEnvelope {
-	return isRecord(value) && Array.isArray(value.output) && value.output.every(isCompactOutputItem);
+	return isRecord(value) && Array.isArray(value.output) && value.output.every(isCompactedWindowItem);
 }
 
-/**
- * Extract the assistant-authored summary text from the compacted window so the
- * persisted CompactionEntry.summary carries real context. Without this, switching
- * to a non-Responses model later would replay a meaningless placeholder.
- */
+/** Extract retained assistant text. It must not be used as an opaque-window summary. */
 export function extractCompactedSummaryText(output: readonly unknown[]): string | undefined {
 	const texts: string[] = [];
 	for (const item of output) {
@@ -131,7 +126,24 @@ function writeCompactArtifact(
 		return;
 	}
 
-	writeDebugArtifact("compact-response", data, settings, context);
+	writeDebugArtifact("compact-response", isRecord(data) ? { ...data, protocol: "standalone-compact" } : { protocol: "standalone-compact", data }, settings, context);
+}
+
+/** Installed SDK CompactParams allowlist; complete input makes previous_response_id unnecessary. */
+export function buildStandaloneCompactionRequest(request: NativeCompactionRequestBody): NativeCompactionRequestBody {
+	const body: NativeCompactionRequestBody = {
+		model: request.model,
+		input: structuredClone(stripConfigurationUpdateItems(request.input)) as NativeCompactionRequestBody["input"],
+		instructions: request.instructions,
+	};
+	if (["auto", "default", "fast", "flex", "priority"].includes(request.service_tier ?? "")) body.service_tier = request.service_tier;
+	if (typeof request.prompt_cache_key === "string") body.prompt_cache_key = request.prompt_cache_key;
+	if (request.prompt_cache_retention === "in_memory" || request.prompt_cache_retention === "24h") body.prompt_cache_retention = request.prompt_cache_retention;
+	const cache = request.prompt_cache_options;
+	if (isRecord(cache) && Object.keys(cache).every((key) => key === "mode" || key === "ttl") &&
+		(cache.mode === undefined || cache.mode === "implicit" || cache.mode === "explicit") &&
+		(cache.ttl === undefined || cache.ttl === "30m")) body.prompt_cache_options = structuredClone(cache);
+	return body;
 }
 
 export async function executeNativeCompaction(
@@ -140,10 +152,7 @@ export async function executeNativeCompaction(
 	const { runtime, signal, settings, context } = options;
 	// Same Astra-history rejection as remote v2: `/responses/compact` rejects
 	// `configuration_update` items, so a replayed history never carries one.
-	const request: NativeCompactionRequestBody = {
-		...options.request,
-		input: stripConfigurationUpdateItems(options.request.input) as NativeCompactionRequestBody["input"],
-	};
+	const request = buildStandaloneCompactionRequest(options.request);
 	const headers = toHeaders(runtime);
 
 	if (signal?.aborted) {
@@ -171,9 +180,10 @@ export async function executeNativeCompaction(
 			method: "POST",
 			headers,
 			body: JSON.stringify(request),
+			redirect: "error",
 			signal,
 		});
-		const responseText = await response.text();
+		const responseText = await readCompactionResponseText(response, signal);
 		const responseHeaders: Record<string, string> = {};
 		response.headers.forEach((value, key) => {
 			responseHeaders[key] = value;
@@ -193,6 +203,7 @@ export async function executeNativeCompaction(
 				ok: false,
 				reason: "non-2xx",
 				status: response.status,
+				...decodeCompactionError(responseJson),
 				responseText: responseText || undefined,
 				responseJson,
 			};
@@ -245,12 +256,12 @@ export async function executeNativeCompaction(
 		let parsed: unknown;
 		try {
 			parsed = JSON.parse(responseText);
-		} catch (error) {
+		} catch {
 			const failure: NativeCompactionClientFailure = {
 				ok: false,
 				reason: "invalid-json",
 				status: response.status,
-				errorMessage: error instanceof Error ? error.message : String(error),
+				errorMessage: "The compact endpoint returned invalid JSON.",
 				responseText,
 			};
 			writeCompactArtifact(
@@ -327,10 +338,22 @@ export async function executeNativeCompaction(
 			return failure;
 		}
 
+		const checkpoints = parsed.output.filter((item) => isRecord(item) && item.type === "compaction");
+		const malformed = checkpoints.some((item) => !isRecord(item) || typeof item.encrypted_content !== "string" || !item.encrypted_content.trim());
+		if (!checkpoints.length || malformed) {
+			const failure: NativeCompactionClientFailure = {
+				ok: false,
+				reason: malformed ? "malformed-compaction-item" : "missing-compaction",
+				status: response.status,
+			};
+			writeCompactArtifact({ protocol: "standalone-compact", outcome: failure }, settings, context);
+			return failure;
+		}
+		if (signal?.aborted) return { ok: false, reason: "aborted" };
 		const success: NativeCompactionClientSuccess = {
 			ok: true,
 			status: response.status,
-			compactedWindow: [...parsed.output],
+			compactedWindow: structuredClone(parsed.output),
 			compactResponseId: typeof parsed.id === "string" && parsed.id.trim() ? parsed.id.trim() : undefined,
 			createdAt: normalizeResponseTimestamp(parsed.created_at),
 			summaryText: extractCompactedSummaryText(parsed.output),
@@ -361,7 +384,7 @@ export async function executeNativeCompaction(
 		);
 		return success;
 	} catch (error) {
-		const failure: NativeCompactionClientFailure = isAbortError(error)
+		const failure: NativeCompactionClientFailure = signal?.aborted || isAbortError(error)
 			? {
 				ok: false,
 				reason: "aborted",
@@ -369,7 +392,7 @@ export async function executeNativeCompaction(
 			: {
 				ok: false,
 				reason: "network-error",
-				errorMessage: error instanceof Error ? error.message : String(error),
+				errorMessage: "Compaction transport failed; no remote checkpoint was produced.",
 			};
 
 		writeCompactArtifact(

package/src/compaction-errors.ts

@@ -0,0 +1,96 @@
+/** Content-free diagnostics shared by the compaction HTTP/stream boundaries. */
+export type CompactionErrorInfo = {
+	errorCode?: string;
+	errorType?: string;
+	errorParam?: string;
+	/** Controlled text, never a provider-authored message. */
+	errorMessage?: string;
+	errorCategory?: "auth" | "quota" | "protocol";
+};
+
+const HINTS: Record<string, string> = {
+	subscription_sharing_unsupported_capability: "This OpenAI subscription-sharing grant does not authorize compaction. Use a separately authenticated supported API-key or native Codex route; credentials are not interchangeable.",
+	hardened_oauth_rule_missing: "This OAuth grant does not authorize this operation. Select a separately authenticated supported route; Toolkit will not switch credentials.",
+	rejected_by_hardened_oauth_boundary: "This OAuth grant does not authorize this operation. Select a separately authenticated supported route; Toolkit will not switch credentials.",
+	missing_scope: "The credential lacks the required Responses authorization scope. Authenticate the intended route separately.",
+	invalid_api_key: "The selected route rejected its credential. Check authentication for that route.",
+	insufficient_quota: "The selected route has insufficient quota. Check its billing and quota.",
+	rate_limit_exceeded: "The selected route is rate limited. Retry later.",
+	unsupported_capability: "The endpoint does not support the requested compaction protocol.",
+	unsupported_compaction: "The endpoint does not support the requested compaction protocol.",
+	unsupported_protocol: "The endpoint does not support the requested compaction protocol.",
+	unsupported_parameter: "The endpoint rejected a compaction request parameter.",
+	unknown_parameter: "The endpoint rejected a compaction request parameter.",
+	invalid_request_error: "The endpoint rejected the compaction request.",
+};
+const PROTOCOL_CODES = new Set(["unsupported_capability", "unsupported_compaction", "unsupported_protocol", "unsupported_parameter", "unknown_parameter"]);
+const SAFE_TYPES = new Set(["invalid_request_error", "authentication_error", "permission_error", "rate_limit_error", "insufficient_quota", "server_error"]);
+const SAFE_PARAMS = new Set(["input", "model", "compaction_trigger", "stream", "store", "tools", "instructions", "reasoning", "text"]);
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+export function decodeCompactionError(value: unknown): CompactionErrorInfo {
+	if (!isRecord(value)) return {};
+	const source = isRecord(value.error) ? value.error
+		: isRecord(value.response) && isRecord(value.response.error) ? value.response.error : value;
+	// Unknown identifiers may themselves contain secrets. Only public vocabulary
+	// is emitted; classification can conservatively exclude an unknown auth code.
+	const code = typeof source.code === "string" && source.code.length <= 128 ? source.code : undefined;
+	const type = typeof source.type === "string" && source.type.length <= 128 ? source.type : undefined;
+	const excluded = [code, type].filter((item): item is string => !!item).join(" ");
+	const missingScope = typeof source.message === "string" && source.message.length <= 4096 && /missing (?:required )?scopes?\b/i.test(source.message);
+	const errorCategory = missingScope || /auth|oauth|permission|subscription|scope|access_denied|forbidden|api_key|token|credential|invalid_grant/i.test(excluded) ? "auth"
+		: /quota|billing|rate_limit|too_many_requests/i.test(excluded) ? "quota"
+		: code && PROTOCOL_CODES.has(code) ? "protocol" : undefined;
+	const errorCode = code && Object.hasOwn(HINTS, code) ? code : undefined;
+	return {
+		...(errorCode ? { errorCode } : {}),
+		...(type && SAFE_TYPES.has(type) ? { errorType: type } : {}),
+		...(typeof source.param === "string" && SAFE_PARAMS.has(source.param) ? { errorParam: source.param } : {}),
+		...(missingScope ? { errorMessage: HINTS.missing_scope } : errorCode ? { errorMessage: HINTS[errorCode] } : {}),
+		...(errorCategory ? { errorCategory } : {}),
+	};
+}
+
+/** One protocol probe, not a transport/auth retry. Unknown failures fail closed. */
+export function qualifiesForStandaloneCompaction(failure: CompactionErrorInfo & { reason: string; status?: number }): boolean {
+	if (failure.errorCategory === "auth" || failure.errorCategory === "quota") return false;
+	if (failure.reason === "non-2xx") return [400, 404, 405, 422, 501].includes(failure.status ?? 0);
+	if (failure.reason === "error-event") return failure.errorCategory === "protocol";
+	return failure.status !== undefined && failure.status >= 200 && failure.status < 300 && [
+		"empty-body", "invalid-sse", "missing-completed-event", "incomplete-response",
+		"invalid-compaction-count", "malformed-compaction-item", "conflicting-compaction-item",
+		"invalid-compaction-metadata", "invalid-event-order", "duplicate-completed-event",
+	].includes(failure.reason);
+}
+
+/** Body collection must be cancellable even with a stalled mocked/custom transport. */
+export async function readCompactionResponseText(response: Response, signal?: AbortSignal): Promise<string> {
+	if (signal?.aborted) throw new DOMException("Compaction aborted", "AbortError");
+	const reader = response.body?.getReader();
+	if (!reader) return "";
+	const decoder = new TextDecoder();
+	const parts: string[] = [];
+	let onAbort: (() => void) | undefined;
+	const aborted = new Promise<never>((_resolve, reject) => {
+		onAbort = () => reject(new DOMException("Compaction aborted", "AbortError"));
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+	try {
+		while (true) {
+			if (signal?.aborted) throw new DOMException("Compaction aborted", "AbortError");
+			const chunk = await Promise.race([reader.read(), aborted]);
+			if (signal?.aborted) throw new DOMException("Compaction aborted", "AbortError");
+			parts.push(chunk.done ? decoder.decode() : decoder.decode(chunk.value, { stream: true }));
+			if (chunk.done) return parts.join("");
+		}
+	} finally {
+		if (onAbort) signal?.removeEventListener("abort", onAbort);
+		// Abort/completion never waits for transport cleanup. Cancel the reader,
+		// not the locked body, and observe late rejection before releasing it.
+		try { void reader.cancel().catch(() => undefined); } catch { /* Custom transport cleanup. */ }
+		finally { try { reader.releaseLock(); } catch { /* Preserve the operation outcome. */ } }
+	}
+}