pi-openai-codex-compat 0.0.2 → 0.0.4

package/extensions/openai-codex-compat/codex-cache-diagnostics.ts

@@ -0,0 +1,97 @@
+import { createHash } from "node:crypto";
+import { type JsonRecord } from "./codex-protocol.ts";
+import { usesResponsesLite } from "./responses-lite.ts";
+
+type Fingerprint = {
+  bytes: number;
+  sha256: string;
+};
+
+export type CodexCacheDiagnosticContext = {
+  envelope: "responses" | "responses_lite";
+  prewarmMode: "static";
+  fullInputItems: number;
+  staticInputItems: number;
+  staticPrefixBytes: number;
+  staticPrefixSha256: string;
+  staticRequestBytes: number;
+  staticRequestSha256: string;
+  instructionsBytes?: number;
+  instructionsSha256?: string;
+  toolsBytes?: number;
+  toolsSha256?: string;
+};
+
+function jsonFingerprint(value: unknown): Fingerprint {
+  const json = JSON.stringify(value);
+  return {
+    bytes: Buffer.byteLength(json, "utf8"),
+    sha256: createHash("sha256").update(json, "utf8").digest("hex"),
+  };
+}
+
+function textFingerprint(value: string): Fingerprint {
+  return {
+    bytes: Buffer.byteLength(value, "utf8"),
+    sha256: createHash("sha256").update(value, "utf8").digest("hex"),
+  };
+}
+
+function inputLength(payload: JsonRecord): number {
+  return Array.isArray(payload.input) ? payload.input.length : 0;
+}
+
+function staticRequest(payload: JsonRecord): JsonRecord {
+  const result = structuredClone(payload);
+  delete result.client_metadata;
+  delete result.prompt_cache_key;
+  return result;
+}
+
+export function codexCacheDiagnosticContext(
+  ordinaryBody: JsonRecord,
+  fullWireBody: JsonRecord,
+  staticWireBody: JsonRecord,
+  modelId: string,
+  responsesLiteEnabled = true,
+): CodexCacheDiagnosticContext {
+  const lite = usesResponsesLite(modelId, responsesLiteEnabled);
+  const staticPrefix = lite
+    ? (staticWireBody.input ?? [])
+    : {
+        ...("instructions" in ordinaryBody ? { instructions: ordinaryBody.instructions } : {}),
+        ...("tools" in ordinaryBody ? { tools: ordinaryBody.tools } : {}),
+      };
+  const prefixFingerprint = jsonFingerprint(staticPrefix);
+  const requestFingerprint = jsonFingerprint(staticRequest(staticWireBody));
+  const instructionFingerprint =
+    typeof ordinaryBody.instructions === "string"
+      ? textFingerprint(ordinaryBody.instructions)
+      : undefined;
+  const toolsFingerprint = Array.isArray(ordinaryBody.tools)
+    ? jsonFingerprint(ordinaryBody.tools)
+    : undefined;
+
+  return {
+    envelope: lite ? "responses_lite" : "responses",
+    prewarmMode: "static",
+    fullInputItems: inputLength(fullWireBody),
+    staticInputItems: inputLength(staticWireBody),
+    staticPrefixBytes: prefixFingerprint.bytes,
+    staticPrefixSha256: prefixFingerprint.sha256,
+    staticRequestBytes: requestFingerprint.bytes,
+    staticRequestSha256: requestFingerprint.sha256,
+    ...(instructionFingerprint
+      ? {
+          instructionsBytes: instructionFingerprint.bytes,
+          instructionsSha256: instructionFingerprint.sha256,
+        }
+      : {}),
+    ...(toolsFingerprint
+      ? {
+          toolsBytes: toolsFingerprint.bytes,
+          toolsSha256: toolsFingerprint.sha256,
+        }
+      : {}),
+  };
+}

package/extensions/openai-codex-compat/codex-cache-key.ts

@@ -0,0 +1,9 @@
+import { createHash } from "node:crypto";
+
+const OPENAI_PROMPT_CACHE_KEY_MAX_LENGTH = 64;
+
+export function codexCacheKey(sessionId: string | undefined): string | undefined {
+  if (sessionId === undefined) return undefined;
+  if (Array.from(sessionId).length <= OPENAI_PROMPT_CACHE_KEY_MAX_LENGTH) return sessionId;
+  return createHash("sha256").update(sessionId, "utf8").digest("hex");
+}

package/extensions/openai-codex-compat/codex-installation.ts

@@ -0,0 +1,51 @@
+import { randomUUID } from "node:crypto";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+export const CODEX_INSTALLATION_ID_FILE = "openai-codex-compat-installation-id";
+
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+function readInstallationId(path: string): string {
+  const value = readFileSync(path, "utf8").trim();
+  if (!UUID_PATTERN.test(value)) {
+    throw new Error(`Invalid Codex installation id in ${path}`);
+  }
+  return value;
+}
+
+export function resolveCodexInstallationId(agentDir = getAgentDir()): string {
+  const path = join(agentDir, CODEX_INSTALLATION_ID_FILE);
+  try {
+    return readInstallationId(path);
+  } catch (error) {
+    if (
+      !(error instanceof Error) ||
+      !("code" in error) ||
+      (error as NodeJS.ErrnoException).code !== "ENOENT"
+    ) {
+      throw error;
+    }
+  }
+
+  mkdirSync(agentDir, { recursive: true });
+  const installationId = randomUUID();
+  try {
+    writeFileSync(path, `${installationId}\n`, {
+      encoding: "utf8",
+      flag: "wx",
+      mode: 0o644,
+    });
+    return installationId;
+  } catch (error) {
+    if (
+      error instanceof Error &&
+      "code" in error &&
+      (error as NodeJS.ErrnoException).code === "EEXIST"
+    ) {
+      return readInstallationId(path);
+    }
+    throw error;
+  }
+}

package/extensions/openai-codex-compat/codex-metadata.ts

@@ -0,0 +1,139 @@
+import { uuidv7 } from "@earendil-works/pi-ai";
+import { isObject, type JsonRecord } from "./codex-protocol.ts";
+
+export const CODEX_TURN_METADATA_HEADER = "x-codex-turn-metadata";
+export const CODEX_INSTALLATION_ID_METADATA_KEY = "x-codex-installation-id";
+export const CODEX_WINDOW_ID_HEADER = "x-codex-window-id";
+
+export type CodexRequestKind = "turn" | "prewarm" | "compaction";
+
+export type CodexCompactionMetadata = {
+  trigger: "manual" | "auto";
+  reason: "user_requested" | "context_limit" | "model_downshift" | "comp_hash_changed";
+  implementation: "responses" | "responses_compaction_v2" | "responses_compact";
+  phase: "standalone_turn" | "pre_turn" | "mid_turn";
+  strategy: "memento" | "prefix_compaction";
+};
+
+export type CodexMetadataRequest =
+  | { kind: "turn" | "prewarm" }
+  | { kind: "compaction"; compaction: CodexCompactionMetadata };
+
+export type CodexMetadataIdentity = {
+  installationId: string;
+  threadId?: string;
+  forkedFromThreadId?: string;
+  windowNumber?: number;
+  turnStartedAtUnixMs?: number;
+  threadSource?: string;
+  sandbox?: string;
+};
+
+const EPHEMERAL_METADATA_IDENTITY: CodexMetadataIdentity = { installationId: uuidv7() };
+
+type CodexClientMetadata = {
+  [CODEX_INSTALLATION_ID_METADATA_KEY]: string;
+  session_id: string;
+  thread_id: string;
+  turn_id: string;
+  [CODEX_WINDOW_ID_HEADER]: string;
+  [CODEX_TURN_METADATA_HEADER]: string;
+};
+
+export function responsesCompactionV2Metadata(
+  trigger: CodexCompactionMetadata["trigger"],
+  reason: CodexCompactionMetadata["reason"],
+  phase: CodexCompactionMetadata["phase"],
+): CodexCompactionMetadata {
+  return {
+    trigger,
+    reason,
+    implementation: "responses_compaction_v2",
+    phase,
+    strategy: "memento",
+  };
+}
+
+function windowId(sessionId: string, identity: CodexMetadataIdentity): string {
+  return `${identity.threadId ?? sessionId}:${identity.windowNumber ?? 0}`;
+}
+
+function turnMetadata(
+  sessionId: string,
+  turnId: string,
+  request: CodexMetadataRequest,
+  identity: CodexMetadataIdentity,
+): string {
+  const threadId = identity.threadId ?? sessionId;
+  return JSON.stringify({
+    installation_id: identity.installationId,
+    session_id: sessionId,
+    thread_id: threadId,
+    turn_id: turnId,
+    window_id: windowId(sessionId, identity),
+    request_kind: request.kind,
+    ...(identity.forkedFromThreadId ? { forked_from_thread_id: identity.forkedFromThreadId } : {}),
+    ...(identity.threadSource ? { thread_source: identity.threadSource } : {}),
+    ...(identity.sandbox ? { sandbox: identity.sandbox } : {}),
+    ...(identity.turnStartedAtUnixMs === undefined
+      ? {}
+      : { turn_started_at_unix_ms: identity.turnStartedAtUnixMs }),
+    ...(request.kind === "compaction" ? { compaction: request.compaction } : {}),
+  });
+}
+
+export function codexClientMetadata(
+  sessionId: string | undefined,
+  request: CodexMetadataRequest,
+  turnId = uuidv7(),
+  identity: CodexMetadataIdentity = EPHEMERAL_METADATA_IDENTITY,
+): CodexClientMetadata | undefined {
+  if (!sessionId) return undefined;
+  const threadId = identity.threadId ?? sessionId;
+  return {
+    [CODEX_INSTALLATION_ID_METADATA_KEY]: identity.installationId,
+    session_id: sessionId,
+    thread_id: threadId,
+    turn_id: turnId,
+    [CODEX_WINDOW_ID_HEADER]: windowId(sessionId, identity),
+    [CODEX_TURN_METADATA_HEADER]: turnMetadata(sessionId, turnId, request, identity),
+  };
+}
+
+export function withCodexRequestMetadata(
+  payload: JsonRecord,
+  sessionId: string | undefined,
+  request: CodexMetadataRequest,
+  turnId?: string,
+  identity: CodexMetadataIdentity = EPHEMERAL_METADATA_IDENTITY,
+): JsonRecord {
+  const metadata = codexClientMetadata(sessionId, request, turnId, identity);
+  if (!metadata) {
+    const result = structuredClone(payload);
+    delete result["client_metadata"];
+    return result;
+  }
+  const existing = isObject(payload["client_metadata"]) ? payload["client_metadata"] : {};
+  return {
+    ...payload,
+    client_metadata: {
+      ...existing,
+      ...metadata,
+    },
+  };
+}
+
+export function applyCodexMetadataHeaders(headers: Headers, payload: JsonRecord): void {
+  const metadata = payload["client_metadata"];
+  if (!isObject(metadata)) return;
+
+  if (typeof metadata["thread_id"] === "string") {
+    headers.set("thread-id", metadata["thread_id"]);
+  }
+  if (typeof metadata[CODEX_WINDOW_ID_HEADER] === "string") {
+    headers.set(CODEX_WINDOW_ID_HEADER, metadata[CODEX_WINDOW_ID_HEADER]);
+  }
+  if (typeof metadata[CODEX_TURN_METADATA_HEADER] === "string") {
+    headers.set(CODEX_TURN_METADATA_HEADER, metadata[CODEX_TURN_METADATA_HEADER]);
+  }
+}

package/extensions/openai-codex-compat/codex-protocol.ts

@@ -28,6 +28,7 @@ export interface JsonRecord {
   prompt_cache_key?: unknown;
   tools?: unknown;
   service_tier?: unknown;
+  client_metadata?: unknown;
   chatgpt_account_id?: unknown;
   message?: unknown;
   item?: unknown;
@@ -269,7 +270,7 @@ export function remoteCompactionPayload(options: {
   modelId: string;
   history: readonly ResponsesItem[];
   instructions: string;
-  sessionId: string;
+  sessionId?: string | undefined;
   fallbackTools?: unknown[] | undefined;
   priority: boolean;
 }): JsonRecord {
@@ -290,7 +291,8 @@ export function remoteCompactionPayload(options: {
     typeof payload.parallel_tool_calls === "boolean" ? payload.parallel_tool_calls : true;
   payload.tool_choice ??= "auto";
   payload.include = [...new Set([...include, "reasoning.encrypted_content"])];
-  payload.prompt_cache_key = options.sessionId;
+  if (options.sessionId) payload.prompt_cache_key = options.sessionId;
+  else delete payload.prompt_cache_key;
   payload.text =
     isObject(payload.text) && typeof payload.text.verbosity === "string"
       ? { verbosity: payload.text.verbosity }