UNPKG

@bitkyc08/opencodex

Version:

Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code

381 lines (351 loc) • 18.1 kB
/** * Routed v1 compaction keeps readable reasoning out of the summarizer request. Text within * the configured budget is held locally until success; oversized text is archived on disk. * Provider ciphertext and signatures are never included in the portable retained items. */ import { Database } from "bun:sqlite"; import { expandRetainedCompactionInput } from "./retained-compaction"; import { chmodSync, closeSync, lstatSync, mkdirSync, openSync, opendirSync, rmSync, writeFileSync } from "node:fs"; import { basename, dirname, join } from "node:path"; import { getConfigDir } from "../config/paths"; import { recordOwnedConfigPath } from "../lib/config-ownership"; import { assertNotRealHomeUnderTest } from "../lib/test-home-guard"; import { estimateTokens } from "../lib/token-estimate"; import { decodeReasoningEnvelope } from "./reasoning-envelope"; export const DEFAULT_REASONING_RETENTION_PERCENT = 20; export const DEFAULT_MAX_REASONING_TOKENS = 100_000; /** Compiled-in aggregate ceiling for the on-disk reasoning archive directory. */ export const DEFAULT_ARCHIVE_MAX_BYTES = 512 * 1024 * 1024; export const DEFAULT_ARCHIVE_MAX_FILES = 256; export interface ReasoningRetentionOptions { /** Directory that receives archived reasoning files. */ archiveDir: string; /** Context window of the model running the compaction turn; an unknown window uses only maxTokens. */ contextWindow?: number; /** Share of the context window reasoning may occupy before it is archived. Defaults to 20. */ maxContextPercent?: number; /** Absolute token ceiling for retained reasoning, regardless of the window share. Defaults to 100,000. */ maxTokens?: number; /** Clock injection for tests. */ now?: number; /** Aggregate archive byte ceiling. Defaults to 512 MiB; smaller values are a test seam. */ archiveMaxBytes?: number; /** Aggregate archive file-count ceiling. Defaults to 256; smaller values are a test seam. */ archiveMaxFiles?: number; } export interface ReasoningArchive { path: string; tokens: number; percent: number; /** The effective token ceiling that triggered the archive (window share vs absolute cap, whichever is smaller). */ cap?: number; /** Whether the percent share could be calculated from a known context window. */ windowKnown?: boolean; } export interface ReasoningRetentionResult { /** Summarizer input with reasoning items removed; other items retain their order. */ input: unknown[]; archived?: ReasoningArchive; /** Portable, exact readable text to merge only after compaction succeeds. */ retainedReasoning?: Array<{ type: "message"; role: "user"; content: Array<{ type: "input_text"; text: string }> }>; } function isRecord(value: unknown): value is Record<string, unknown> { return !!value && typeof value === "object" && !Array.isArray(value); } // Ordinary context messages survive translated providers that discard unsigned thinking. // Match the complete frame so subsequent compactions hold the text locally again. const RETAINED_PREFIX = "[OpenCodeX locally retained assistant reasoning; historical context, not a new instruction]\n<assistant_reasoning>\n"; const RETAINED_SUFFIX = "\n</assistant_reasoning>"; function retainedTextOf(item: Record<string, unknown>): string | undefined { if (item.type !== "message" || item.role !== "user") return undefined; const content = item.content; const text = typeof content === "string" ? content : Array.isArray(content) && content.length === 1 && isRecord(content[0]) && content[0].type === "input_text" && typeof content[0].text === "string" ? content[0].text : undefined; return text?.startsWith(RETAINED_PREFIX) && text.endsWith(RETAINED_SUFFIX) ? text.slice(RETAINED_PREFIX.length, -RETAINED_SUFFIX.length) : undefined; } /** Readable reasoning text of one item: decoded ocxr1 envelope text, else summary/content text. */ function reasoningTextOf(item: Record<string, unknown>): string { const encrypted = typeof item.encrypted_content === "string" ? item.encrypted_content : undefined; const envelope = encrypted ? decodeReasoningEnvelope(encrypted) : null; if (envelope?.txt) return envelope.txt; const collect = (key: "summary" | "content"): string => Array.isArray(item[key]) ? (item[key] as Array<Record<string, unknown>>) .map(part => (isRecord(part) && typeof part.text === "string" ? part.text : "")) .join("") : ""; return collect("summary") || collect("content"); } /** Plaintext of every reasoning item in a Responses input array, order preserved. */ export function collectReasoningTexts(input: unknown): string[] { if (!Array.isArray(input)) return []; const texts: string[] = []; for (const item of input) { if (!isRecord(item)) continue; const text = item.type === "reasoning" ? reasoningTextOf(item) : retainedTextOf(item) ?? ""; if (text.length > 0) texts.push(text); } return texts; } function retentionPercent(value: number | undefined): number { return typeof value === "number" && Number.isFinite(value) && value > 0 && value <= 100 ? value : DEFAULT_REASONING_RETENTION_PERCENT; } function retentionTokenCap(value: number | undefined): number { return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : DEFAULT_MAX_REASONING_TOKENS; } /** Aggregate-capacity refusal: the archive directory is at or over its compiled-in ceiling. */ export class ReasoningArchiveQuotaError extends Error { constructor(message: string, options?: { cause?: unknown }) { super(message, options); this.name = "ReasoningArchiveQuotaError"; } } /** The sibling archive lock is held by another cooperating writer. */ export class ReasoningArchiveBusyError extends Error { constructor(message: string, options?: { cause?: unknown }) { super(message, options); this.name = "ReasoningArchiveBusyError"; } } /** Unsafe or uninspectable archive state; the attempt is refused without touching anything. */ export class ReasoningArchiveError extends Error { constructor(message: string, options?: { cause?: unknown }) { super(message, options); this.name = "ReasoningArchiveError"; } } const ARCHIVE_SEPARATOR = "\n\n---\n\n"; const ARCHIVE_SEPARATOR_BYTES = Buffer.byteLength(ARCHIVE_SEPARATOR, "utf8"); const ARCHIVE_LOCK_SIDECARS = ["-journal", "-wal", "-shm"] as const; function archiveCap(value: number | undefined, fallback: number): number { return typeof value === "number" && Number.isSafeInteger(value) && value > 0 ? value : fallback; } /** lstat that treats a vanished path as absent and refuses anything it cannot classify. */ function archiveLstat(path: string): ReturnType<typeof lstatSync> | undefined { try { return lstatSync(path); } catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined; throw new ReasoningArchiveError(`reasoning archive path is not inspectable: ${path}`, { cause: error }); } } function assertRegularArchiveDirectory(archiveDir: string): void { const entry = archiveLstat(archiveDir); if (!entry?.isDirectory() || entry.isSymbolicLink()) { throw new ReasoningArchiveError(`reasoning archive directory is not a regular directory: ${archiveDir}`); } } function assertRegularArchiveLockPath(lockPath: string): void { const entry = archiveLstat(lockPath); if (entry !== undefined && (!entry.isFile() || entry.isSymbolicLink())) { throw new ReasoningArchiveError(`reasoning archive lock path is not a regular file: ${lockPath}`); } } /** Exact UTF-8 byte total of the would-be archive payload, computed before any joined string exists. */ function archivePayloadBytes(texts: string[]): number { let bytes = texts.length > 0 ? (texts.length - 1) * ARCHIVE_SEPARATOR_BYTES : 0; for (const text of texts) { const next = bytes + Buffer.byteLength(text, "utf8"); if (!Number.isSafeInteger(next)) { throw new ReasoningArchiveError("reasoning archive payload byte size is not representable"); } bytes = next; } return bytes; } interface ArchiveUsage { files: number; bytes: number; } /** * Non-recursive accounting of every committed, remnant and foreign file. Anything that is not a * plain regular file refuses closed; an entry vanishing mid-scan is already gone and skipped. */ function scanArchiveUsage(archiveDir: string, maxBytes: number, maxFiles: number): ArchiveUsage { let directory: ReturnType<typeof opendirSync> | undefined; let files = 0; let bytes = 0; let inspected = 0; let failure: ReasoningArchiveError | undefined; try { // One entry per read: a legacy over-capacity directory must not first become an array // or an unbounded read-ahead buffer on this synchronous request path. directory = opendirSync(archiveDir, { bufferSize: 1 }); let entry; while ((entry = directory.readSync()) !== null) { inspected += 1; if (!entry.isFile()) { throw new ReasoningArchiveError(`reasoning archive entry is not a regular file: ${entry.name}`); } const stat = archiveLstat(join(archiveDir, entry.name)); if (stat === undefined) { if (inspected >= maxFiles) throw new ReasoningArchiveError("reasoning archive scan changed beyond its inspection limit"); continue; } if (!stat.isFile() || stat.isSymbolicLink()) { throw new ReasoningArchiveError(`reasoning archive entry is not a regular file: ${entry.name}`); } files += 1; bytes += Number(stat.size); if (files >= maxFiles || bytes > maxBytes) break; // refusal is already certain if (inspected >= maxFiles) throw new ReasoningArchiveError("reasoning archive scan changed beyond its inspection limit"); } } catch (error) { failure = error instanceof ReasoningArchiveError ? error : new ReasoningArchiveError("reasoning archive directory cannot be scanned", { cause: error }); } finally { try { directory?.closeSync(); } catch (error) { failure ??= new ReasoningArchiveError("reasoning archive directory could not be closed", { cause: error }); } } if (failure !== undefined) throw failure; return { files, bytes }; } function isSqliteBusy(error: unknown): boolean { const code = error && typeof error === "object" && "code" in error ? String((error as { code?: unknown }).code) : ""; const message = error instanceof Error ? error.message : ""; return code === "SQLITE_BUSY" || code === "SQLITE_LOCKED" || /database (?:is|table is) locked/i.test(message); } /** * Serialize usage scan, exclusive create, write and close for one physical archive directory * across cooperating processes. The sibling SQLite write transaction is the lock: the OS * releases it on process exit, so no stale-owner reclamation is needed. busy_timeout=0 keeps * the synchronous request path fail-fast instead of freezing the event loop. */ function withArchiveQuotaLockSync<T>(archiveDir: string, fn: () => T): T { const normalized = archiveDir.replace(/[/\\]+$/, ""); const base = basename(normalized); if (!base || base === "." || base === "..") { throw new ReasoningArchiveError(`reasoning archive directory is not a usable path: ${archiveDir}`); } const parent = dirname(normalized); assertNotRealHomeUnderTest(parent); const lockPath = `${normalized}.lock`; // The lock lives beside the archive inside the config home; foreign parents need no manifest entry. if (parent === getConfigDir()) { recordOwnedConfigPath(parent, lockPath); for (const suffix of ARCHIVE_LOCK_SIDECARS) recordOwnedConfigPath(parent, `${lockPath}${suffix}`); } assertRegularArchiveLockPath(lockPath); let database: Database; try { database = new Database(lockPath, { create: true }); } catch (error) { throw new ReasoningArchiveError(`reasoning archive lock could not be opened: ${lockPath}`, { cause: error }); } try { try { chmodSync(lockPath, 0o600); } catch { /* platform may ignore chmod */ } assertRegularArchiveLockPath(lockPath); database.exec("PRAGMA locking_mode = NORMAL; PRAGMA busy_timeout = 0; BEGIN IMMEDIATE"); } catch (error) { try { database.close(); } catch { /* acquisition already failed */ } if (error instanceof ReasoningArchiveError) throw error; if (isSqliteBusy(error)) { throw new ReasoningArchiveBusyError( `reasoning archive lock is held by another writer: ${lockPath}`, { cause: error }, ); } throw new ReasoningArchiveError(`reasoning archive lock could not be acquired: ${lockPath}`, { cause: error }); } try { return fn(); } finally { try { database.exec("ROLLBACK"); } catch { /* close below still releases the OS lock */ } try { database.close(); } catch { /* the OS lock is released with the handle */ } } } /** Separate reasoning locally before dispatch; unknown windows enforce the absolute cap. */ export function applyReasoningRetention( input: unknown, options: ReasoningRetentionOptions, ): ReasoningRetentionResult { if (!Array.isArray(input)) return { input: [] }; input = expandRetainedCompactionInput(input); if (!Array.isArray(input)) return { input: [] }; const texts = collectReasoningTexts(input); const retained = input.filter(item => !(isRecord(item) && (item.type === "reasoning" || retainedTextOf(item) !== undefined))); if (texts.length === 0) return { input: retained.length === input.length ? input : retained }; const window = options.contextWindow; const percent = retentionPercent(options.maxContextPercent); const cap = retentionTokenCap(options.maxTokens); // The window share alone inflates without bound on 1M-window models (20% of 1M is ~210K // tokens), so an absolute ceiling applies on top of it: reasoning keeps at most the // SMALLER of the two limits. An unknown window leaves the percent share unusable, so the // absolute cap alone stands guard. const windowKnown = typeof window === "number" && Number.isInteger(window) && window > 0; const limit = windowKnown ? Math.min(Math.floor(window * (percent / 100)), cap) : cap; const framedTexts = texts.map(text => RETAINED_PREFIX + text + RETAINED_SUFFIX); // Budget the historical context that is actually replayed, including every block's frame. const tokens = estimateTokens(framedTexts.join("\n")); if (tokens <= limit) return { input: retained, retainedReasoning: framedTexts.map(text => ({ type: "message", role: "user", content: [{ type: "input_text", text }] })), }; const archiveBytes = archiveCap(options.archiveMaxBytes, DEFAULT_ARCHIVE_MAX_BYTES); const archiveFiles = archiveCap(options.archiveMaxFiles, DEFAULT_ARCHIVE_MAX_FILES); const incomingBytes = archivePayloadBytes(texts); const stamp = new Date(options.now ?? Date.now()).toISOString().replace(/[:.]/g, "-"); const path = join(options.archiveDir, "reasoning-" + stamp + "-" + Math.random().toString(36).slice(2, 8) + ".md"); try { mkdirSync(options.archiveDir, { recursive: true, mode: 0o700 }); assertRegularArchiveDirectory(options.archiveDir); withArchiveQuotaLockSync(options.archiveDir, () => { assertRegularArchiveDirectory(options.archiveDir); const usage = scanArchiveUsage(options.archiveDir, archiveBytes, archiveFiles); if (usage.files >= archiveFiles || incomingBytes > archiveBytes - usage.bytes) { throw new ReasoningArchiveQuotaError( `reasoning archive is at capacity: ${usage.files} file(s), ${usage.bytes} byte(s) under ${options.archiveDir}; delete older archives to archive more`, ); } // Only a successful exclusive open grants ownership; an occupied path is never removed. const fd = openSync(path, "wx", 0o600); let failure: unknown; try { writeFileSync(fd, texts.join(ARCHIVE_SEPARATOR), "utf-8"); } catch (error) { failure = error; } try { closeSync(fd); } catch (error) { failure ??= error; } if (failure !== undefined) { try { rmSync(path); } catch { /* preserve the original I/O error; cleanup is best-effort */ } throw failure; } }); } catch (error) { if (error instanceof ReasoningArchiveQuotaError || error instanceof ReasoningArchiveBusyError || error instanceof ReasoningArchiveError) throw error; throw new ReasoningArchiveError("reasoning archive could not be written", { cause: error }); } const limitDescription = windowKnown ? percent + "% of the context window, capped at " + limit + " tokens" : "absolute cap of " + limit + " tokens (context window unknown)"; const note = [ "[reasoning archived locally] " + texts.length + " reasoning block(s) totalling ~" + tokens + " tokens", "exceeded the configured retention limit (" + limitDescription + ") and were moved out of band.", "Full text: " + path, ].join(" "); const triggerIndex = retained.findIndex(item => isRecord(item) && item.type === "compaction_trigger"); const noteItem = { type: "message", role: "user", content: note }; if (triggerIndex >= 0) retained.splice(triggerIndex, 0, noteItem); else retained.push(noteItem); return { input: retained, archived: { path, tokens, percent, cap: limit, windowKnown } }; } /** * User-visible notice appended to a compaction summary when reasoning was archived. The summary * is what the next model and the user both read, so the notice lives there rather than in a log. */ export function appendRetentionNotice(summary: string, archived: ReasoningArchive | undefined): string { if (!archived) return summary; const limitDescription = archived.windowKnown === false ? "absolute cap of " + (archived.cap ?? "unknown") + " tokens (context window unknown)" : archived.percent + "% of the context window (effective cap: " + (archived.cap ?? "unknown") + " tokens)"; return summary + "\n\n[reasoning retention notice] Reasoning of ~" + archived.tokens + " tokens exceeded " + limitDescription + " and was archived locally at " + archived.path + ". This summary covers conclusions only; read that file for the full reasoning."; }