@narumitw/pi-codex-compact 0.51.3 → 0.53.0

package/src/remote-compact.ts

@@ -0,0 +1,276 @@
+import type { Usage } from "@earendil-works/pi-ai";
+import type { ResponsesCompactionProfile } from "./model-api.js";
+import {
+  CodexCompactionProtocolError,
+  type CollectedCompactResponse,
+  collectCompactResponse,
+  expandRemoteCompactionPayload,
+  type JsonObject,
+} from "./protocol.js";
+import { collectProviderUsage } from "./remote-shared.js";
+import {
+  abortError,
+  assertPreparedInput,
+  isJsonObject,
+  type RemoteCompactionRequest,
+  type RemoteCompactionResponse,
+} from "./remote-types.js";
+
+const OFFICIAL_COMPACT_FIELDS = [
+  "model",
+  "input",
+  "instructions",
+  "previous_response_id",
+  "prompt_cache_key",
+  "prompt_cache_retention",
+  "service_tier",
+] as const;
+
+const CODEX_COMPACT_FIELDS = [
+  "model",
+  "input",
+  "instructions",
+  "tools",
+  "parallel_tool_calls",
+  "reasoning",
+  "service_tier",
+  "prompt_cache_key",
+  "text",
+  "access_programs",
+] as const;
+
+function compactPayload(payload: JsonObject, profile: ResponsesCompactionProfile): JsonObject {
+  const fields = profile === "codex-responses-v1" ? CODEX_COMPACT_FIELDS : OFFICIAL_COMPACT_FIELDS;
+  const result: JsonObject = {};
+  for (const field of fields) {
+    if (Object.hasOwn(payload, field) && payload[field] !== undefined) {
+      result[field] = structuredClone(payload[field]);
+    }
+  }
+  if (typeof result.model !== "string" || result.model.length === 0) {
+    throw new CodexCompactionProtocolError("Responses payload is missing a model");
+  }
+  assertPreparedInput(result);
+  return result;
+}
+
+function requestUrl(input: string | URL | Request): URL {
+  return new URL(input instanceof Request ? input.url : String(input));
+}
+
+export function responsesCompactUrl(input: string | URL | Request): URL {
+  const original = requestUrl(input);
+  if (!original.pathname.endsWith("/responses")) {
+    throw new CodexCompactionProtocolError("Provider request URL does not end with the Responses endpoint");
+  }
+  const compact = new URL(original);
+  compact.pathname = `${compact.pathname}/compact`;
+  if (compact.origin !== original.origin) {
+    throw new CodexCompactionProtocolError("Responses Compact URL changed origin");
+  }
+  return compact;
+}
+
+function mergedHeaders(input: string | URL | Request, init?: RequestInit): Headers {
+  const headers = new Headers(input instanceof Request ? input.headers : undefined);
+  new Headers(init?.headers).forEach((value, name) => {
+    headers.set(name, value);
+  });
+  headers.delete("content-encoding");
+  headers.delete("content-length");
+  headers.set("accept", "application/json");
+  headers.set("content-type", "application/json");
+  return headers;
+}
+
+function mergedSignal(
+  input: string | URL | Request,
+  init: RequestInit | undefined,
+  ownerSignal: AbortSignal,
+): AbortSignal {
+  const signals = [ownerSignal];
+  if (input instanceof Request) signals.push(input.signal);
+  if (init?.signal) signals.push(init.signal);
+  return signals.length === 1 ? ownerSignal : AbortSignal.any(signals);
+}
+
+function nonRetryableBridgeFailure(error: unknown): Response {
+  const message = error instanceof Error ? error.message : String(error);
+  return Response.json(
+    {
+      error: {
+        message,
+        type: "invalid_request_error",
+        code: "invalid_compact_response",
+      },
+    },
+    { status: 400 },
+  );
+}
+
+function nonNegativeInteger(value: unknown): value is number {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+
+function optionalUsageDetail(details: unknown, field: string): number {
+  if (details === undefined || details === null) return 0;
+  if (!isJsonObject(details)) {
+    throw new CodexCompactionProtocolError("Responses Compact response has invalid usage details");
+  }
+  const value = details[field];
+  if (value === undefined || value === null) return 0;
+  if (!nonNegativeInteger(value)) {
+    throw new CodexCompactionProtocolError(`Responses Compact response has invalid usage detail ${field}`);
+  }
+  return value;
+}
+
+function validatedUsage(response: JsonObject): JsonObject {
+  const usage = response.usage;
+  if (!isJsonObject(usage)) {
+    throw new CodexCompactionProtocolError("Responses Compact response is missing usage");
+  }
+  for (const field of ["input_tokens", "output_tokens", "total_tokens"] as const) {
+    if (!nonNegativeInteger(usage[field])) {
+      throw new CodexCompactionProtocolError(`Responses Compact response has invalid ${field}`);
+    }
+  }
+  const inputTokens = usage.input_tokens as number;
+  const outputTokens = usage.output_tokens as number;
+  const totalTokens = usage.total_tokens as number;
+  const cachedTokens = optionalUsageDetail(usage.input_tokens_details, "cached_tokens");
+  const cacheWriteTokens = optionalUsageDetail(usage.input_tokens_details, "cache_write_tokens");
+  const reasoningTokens = optionalUsageDetail(usage.output_tokens_details, "reasoning_tokens");
+  if (cachedTokens + cacheWriteTokens > inputTokens || reasoningTokens > outputTokens) {
+    throw new CodexCompactionProtocolError("Responses Compact response has inconsistent usage details");
+  }
+  if (totalTokens !== inputTokens + outputTokens) {
+    throw new CodexCompactionProtocolError("Responses Compact response has inconsistent total usage");
+  }
+  return structuredClone(usage);
+}
+
+function syntheticCompletion(result: CollectedCompactResponse, payload: JsonObject): Response {
+  const completed = {
+    id: typeof result.response.id === "string" ? result.response.id : "resp_pi_compact_bridge",
+    object: "response",
+    created_at:
+      typeof result.response.created_at === "number" ? result.response.created_at : Math.floor(Date.now() / 1000),
+    status: "completed",
+    model: payload.model,
+    output: [],
+    parallel_tool_calls: false,
+    tool_choice: "auto",
+    tools: [],
+    usage: validatedUsage(result.response),
+  };
+  const events = [
+    { type: "response.created", response: { ...completed, status: "in_progress" } },
+    { type: "response.completed", response: completed },
+  ];
+  return new Response(events.map((event) => `data: ${JSON.stringify(event)}\n\n`).join(""), {
+    status: 200,
+    headers: { "content-type": "text/event-stream" },
+  });
+}
+
+export async function requestResponsesCompact(request: RemoteCompactionRequest): Promise<RemoteCompactionResponse> {
+  if (request.signal.aborted) throw abortError();
+  let preparedPayload: JsonObject | undefined;
+  let sentInput: JsonObject[] | undefined;
+  let compactResult: CollectedCompactResponse | undefined;
+  let bridgeError: unknown;
+  let dispatchInFlight = false;
+  let successfulResponses = 0;
+  const baseFetch = request.fetch ?? globalThis.fetch;
+  const bridgeFetch: typeof globalThis.fetch = async (input, init) => {
+    if (request.signal.aborted) throw abortError();
+    if (successfulResponses > 0) {
+      bridgeError = new CodexCompactionProtocolError("Provider dispatched again after Responses Compact succeeded");
+      return nonRetryableBridgeFailure(bridgeError);
+    }
+    if (dispatchInFlight) {
+      bridgeError = new CodexCompactionProtocolError("Provider dispatched overlapping Responses Compact requests");
+      return nonRetryableBridgeFailure(bridgeError);
+    }
+    if (!preparedPayload) {
+      bridgeError = new CodexCompactionProtocolError("Provider dispatched before exposing its request payload");
+      return nonRetryableBridgeFailure(bridgeError);
+    }
+    let compactUrl: URL;
+    try {
+      compactUrl = responsesCompactUrl(input);
+    } catch (error) {
+      bridgeError = error;
+      return nonRetryableBridgeFailure(error);
+    }
+    const signal = mergedSignal(input, init, request.signal);
+    dispatchInFlight = true;
+    try {
+      const response = await baseFetch(compactUrl, {
+        ...init,
+        method: "POST",
+        headers: mergedHeaders(input, init),
+        body: JSON.stringify(preparedPayload),
+        signal,
+      });
+      if (!response.ok) return response;
+      try {
+        const result = await collectCompactResponse(response, { signal });
+        successfulResponses += 1;
+        if (successfulResponses !== 1) {
+          throw new CodexCompactionProtocolError(
+            "Provider returned more than one successful Responses Compact response",
+          );
+        }
+        compactResult = result;
+        return syntheticCompletion(result, preparedPayload);
+      } catch (error) {
+        bridgeError = error;
+        return nonRetryableBridgeFailure(error);
+      }
+    } finally {
+      dispatchInFlight = false;
+    }
+  };
+
+  const stream = request.provider.stream(request.model, request.context, {
+    apiKey: request.apiKey,
+    headers: request.headers,
+    env: request.env,
+    signal: request.signal,
+    transport: "sse",
+    cacheRetention: "none",
+    timeoutMs: request.requestTimeoutMs ?? 5 * 60 * 1000,
+    maxRetries: request.maxRetries ?? 2,
+    fetch: bridgeFetch,
+    onPayload: (payload) => {
+      if (preparedPayload) {
+        throw new CodexCompactionProtocolError("Provider exposed more than one compaction request payload");
+      }
+      const expanded = expandRemoteCompactionPayload(payload, request.priorCheckpoint);
+      preparedPayload = compactPayload(expanded, request.profile);
+      sentInput = assertPreparedInput(preparedPayload);
+      return expanded;
+    },
+  });
+
+  let usage: Usage;
+  try {
+    usage = await collectProviderUsage(stream, request.signal);
+  } catch (error) {
+    if (bridgeError) throw bridgeError;
+    throw error;
+  }
+  if (request.signal.aborted) throw abortError();
+  if (bridgeError) throw bridgeError;
+  if (!preparedPayload || !sentInput || !compactResult || successfulResponses !== 1) {
+    throw new CodexCompactionProtocolError("Provider did not complete exactly one Responses Compact request");
+  }
+  return {
+    item: compactResult.item,
+    promptInput: sentInput,
+    compactedOutput: compactResult.output,
+    usage,
+  };
+}

package/src/remote-shared.ts

@@ -0,0 +1,16 @@
+import type { AssistantMessageEventStream, Usage } from "@earendil-works/pi-ai";
+import { abortError } from "./remote-types.js";
+
+export async function collectProviderUsage(stream: AssistantMessageEventStream, signal: AbortSignal): Promise<Usage> {
+  let usage: Usage | undefined;
+  for await (const event of stream) {
+    if (signal.aborted) throw abortError();
+    if (event.type === "error") {
+      throw new Error(event.error.errorMessage ?? "Responses compaction request failed");
+    }
+    if (event.type === "done") usage = event.message.usage;
+  }
+  if (signal.aborted) throw abortError();
+  if (!usage) throw new Error("Responses provider stream ended without completion usage");
+  return usage;
+}

package/src/remote-types.ts

@@ -0,0 +1,46 @@
+import type { Api, Context, Model, Provider, ProviderHeaders, Usage } from "@earendil-works/pi-ai";
+import type { RemoteCompactionProtocol, ResponsesCompactionProfile } from "./model-api.js";
+import type { JsonObject } from "./protocol.js";
+
+export interface PriorCheckpointPayload {
+  marker: string;
+  replacementHistory: readonly unknown[];
+}
+
+export interface RemoteCompactionRequest {
+  provider: Provider;
+  model: Model<Api>;
+  profile: ResponsesCompactionProfile;
+  context: Context;
+  protocol: RemoteCompactionProtocol;
+  apiKey?: string;
+  headers?: ProviderHeaders;
+  env?: Record<string, string>;
+  signal: AbortSignal;
+  priorCheckpoint?: PriorCheckpointPayload;
+  requestTimeoutMs?: number;
+  maxRetries?: number;
+  fetch?: typeof globalThis.fetch;
+}
+
+export interface RemoteCompactionResponse {
+  item: JsonObject;
+  promptInput: JsonObject[];
+  compactedOutput?: JsonObject[];
+  usage: Usage;
+}
+
+export function isJsonObject(value: unknown): value is JsonObject {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function abortError(): DOMException {
+  return new DOMException("Compaction aborted", "AbortError");
+}
+
+export function assertPreparedInput(payload: JsonObject): JsonObject[] {
+  if (!Array.isArray(payload.input) || !payload.input.every(isJsonObject)) {
+    throw new Error("Prepared compaction payload has invalid input items");
+  }
+  return structuredClone(payload.input);
+}

package/src/remote-v2.ts

@@ -0,0 +1,66 @@
+import {
+  CodexCompactionProtocolError,
+  type CollectedCompaction,
+  collectCompactionSse,
+  prepareRemoteCompactionPayload,
+} from "./protocol.js";
+import { collectProviderUsage } from "./remote-shared.js";
+import {
+  abortError,
+  assertPreparedInput,
+  type RemoteCompactionRequest,
+  type RemoteCompactionResponse,
+} from "./remote-types.js";
+
+export async function requestRemoteCompactionV2(request: RemoteCompactionRequest): Promise<RemoteCompactionResponse> {
+  if (request.signal.aborted) throw abortError();
+  let sentInput: ReturnType<typeof assertPreparedInput> | undefined;
+  const inspections: Promise<{ ok: true; value: CollectedCompaction } | { ok: false; error: unknown }>[] = [];
+  const baseFetch = request.fetch ?? globalThis.fetch;
+  const inspectedFetch: typeof globalThis.fetch = async (input, init) => {
+    const response = await baseFetch(input, init);
+    if (!response.ok || !response.body) return response;
+    const [providerBody, inspectionBody] = response.body.tee();
+    const inspection = collectCompactionSse(inspectionBody, { signal: request.signal }).then(
+      (value) => ({ ok: true as const, value }),
+      (error: unknown) => ({ ok: false as const, error }),
+    );
+    inspections.push(inspection);
+    return new Response(providerBody, {
+      status: response.status,
+      statusText: response.statusText,
+      headers: response.headers,
+    });
+  };
+
+  const stream = request.provider.stream(request.model, request.context, {
+    apiKey: request.apiKey,
+    headers: request.headers,
+    env: request.env,
+    signal: request.signal,
+    transport: "sse",
+    cacheRetention: "none",
+    timeoutMs: request.requestTimeoutMs ?? 5 * 60 * 1000,
+    maxRetries: request.maxRetries ?? 2,
+    fetch: inspectedFetch,
+    onPayload: (payload) => {
+      const prepared = prepareRemoteCompactionPayload(payload, request.priorCheckpoint);
+      sentInput = assertPreparedInput(prepared).slice(0, -1);
+      return prepared;
+    },
+  });
+
+  const usage = await collectProviderUsage(stream, request.signal);
+  if (!sentInput) {
+    throw new CodexCompactionProtocolError("Provider did not expose a request payload");
+  }
+  if (inspections.length !== 1) {
+    throw new CodexCompactionProtocolError(
+      `Provider exposed ${inspections.length} successful SSE responses; expected exactly one`,
+    );
+  }
+  const inspection = await inspections[0];
+  if (request.signal.aborted) throw abortError();
+  if (!inspection.ok) throw inspection.error;
+  return { item: inspection.value.item, promptInput: sentInput, usage };
+}

package/src/remote.ts

@@ -1,117 +1,15 @@
-import type { Context, Model, Provider, ProviderHeaders, Usage } from "@earendil-works/pi-ai";
-import {
-	CodexCompactionProtocolError,
-	type CollectedCompaction,
-	collectCompactionSse,
-	type JsonObject,
-	prepareRemoteCompactionPayload,
-} from "./protocol.js";
-
-interface PriorCheckpointPayload {
-	marker: string;
-	replacementHistory: readonly unknown[];
-}
-
-export interface RemoteCompactionRequest {
-	provider: Provider;
-	model: Model<"openai-codex-responses">;
-	context: Context;
-	apiKey?: string;
-	headers?: ProviderHeaders;
-	env?: Record<string, string>;
-	signal: AbortSignal;
-	priorCheckpoint?: PriorCheckpointPayload;
-	requestTimeoutMs?: number;
-	maxRetries?: number;
-	fetch?: typeof globalThis.fetch;
-}
-
-export interface RemoteCompactionResponse {
-	item: JsonObject;
-	promptInput: JsonObject[];
-	usage: Usage;
-}
-
-const EMPTY_USAGE: Usage = {
-	input: 0,
-	output: 0,
-	cacheRead: 0,
-	cacheWrite: 0,
-	totalTokens: 0,
-	cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
-};
-
-function isObject(value: unknown): value is JsonObject {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-function abortError(): DOMException {
-	return new DOMException("Compaction aborted", "AbortError");
-}
-
-export async function requestRemoteCompaction(
-	request: RemoteCompactionRequest,
-): Promise<RemoteCompactionResponse> {
-	if (request.signal.aborted) throw abortError();
-	let sentInput: JsonObject[] | undefined;
-	const inspections: Promise<
-		{ ok: true; value: CollectedCompaction } | { ok: false; error: unknown }
-	>[] = [];
-	const baseFetch = request.fetch ?? globalThis.fetch;
-	const inspectedFetch: typeof globalThis.fetch = async (input, init) => {
-		const response = await baseFetch(input, init);
-		if (!response.ok || !response.body) return response;
-		const [providerBody, inspectionBody] = response.body.tee();
-		const inspection = collectCompactionSse(inspectionBody, { signal: request.signal }).then(
-			(value) => ({ ok: true as const, value }),
-			(error: unknown) => ({ ok: false as const, error }),
-		);
-		inspections.push(inspection);
-		return new Response(providerBody, {
-			status: response.status,
-			statusText: response.statusText,
-			headers: response.headers,
-		});
-	};
-
-	const stream = request.provider.stream(request.model, request.context, {
-		apiKey: request.apiKey,
-		headers: request.headers,
-		env: request.env,
-		signal: request.signal,
-		transport: "sse",
-		cacheRetention: "none",
-		timeoutMs: request.requestTimeoutMs ?? 5 * 60 * 1000,
-		maxRetries: request.maxRetries ?? 2,
-		fetch: inspectedFetch,
-		onPayload: (payload) => {
-			const prepared = prepareRemoteCompactionPayload(payload, request.priorCheckpoint);
-			if (!Array.isArray(prepared.input) || !prepared.input.every(isObject)) {
-				throw new CodexCompactionProtocolError(
-					"Prepared compaction payload has invalid input items",
-				);
-			}
-			sentInput = structuredClone(prepared.input.slice(0, -1)) as JsonObject[];
-			return prepared;
-		},
-	});
-
-	let usage = EMPTY_USAGE;
-	for await (const event of stream) {
-		if (request.signal.aborted) throw abortError();
-		if (event.type === "error") {
-			throw new Error(event.error.errorMessage ?? "Codex remote compaction request failed");
-		}
-		if (event.type === "done") usage = event.message.usage;
-	}
-	if (request.signal.aborted) throw abortError();
-	if (!sentInput)
-		throw new CodexCompactionProtocolError("Provider did not expose a request payload");
-	if (inspections.length === 0) {
-		throw new CodexCompactionProtocolError("Provider response did not expose an SSE body");
-	}
-	const inspection = await inspections.at(-1);
-	if (request.signal.aborted) throw abortError();
-	if (!inspection?.ok) throw inspection?.error ?? new Error("Remote compaction inspection failed");
-	return { item: inspection.value.item, promptInput: sentInput, usage };
+import { requestResponsesCompact } from "./remote-compact.js";
+import type { RemoteCompactionRequest, RemoteCompactionResponse } from "./remote-types.js";
+import { requestRemoteCompactionV2 } from "./remote-v2.js";
+
+export type {
+  PriorCheckpointPayload,
+  RemoteCompactionRequest,
+  RemoteCompactionResponse,
+} from "./remote-types.js";
+
+export function requestRemoteCompaction(request: RemoteCompactionRequest): Promise<RemoteCompactionResponse> {
+  return request.protocol === "responses-compact"
+    ? requestResponsesCompact(request)
+    : requestRemoteCompactionV2(request);
 }