UNPKG

@bitkyc08/opencodex

Version:

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

602 lines (543 loc) • 21.4 kB
/** * Phase 3 opt-in auto-cleanup policy (issue #42). * * Default OFF — never enabled implicitly. Selects oldest archived sessions via * Phase 2 helpers and runs `executeArchivedCleanup` in quarantine/permanent mode. * On `codex_busy`, defers (updates `nextRun`) without mutating archives. * * Privacy: logs never include host paths, digests of file contents, or secrets. */ import { resolveCodexHomeDir } from "../codex/home"; import { loadConfig, mutatePersistedConfig, saveConfigPreservingClaudeCode } from "../config"; import type { StorageCleanupPolicy } from "../types"; import { computePreviewDigest, executeArchivedCleanup, filterCandidatesExcludingPinned, listArchivedCandidates, previewExactArchivedCleanup, selectOldestPercentSkippingPendingRestore, selectReduceToBytesSkippingPendingRestore, type CleanupMode, type CleanupResult, type ExecuteCleanupOptions, } from "./cleanup"; export const DEFAULT_ARCHIVED_BYTES_OVER = 5 * 1024 ** 3; // 5 GiB export const DEFAULT_REMOVE_OLDEST_PERCENT = 25; export const BUSY_DEFER_MS = 15 * 60 * 1000; /** Optional sink so background policy writes stay synced with the live server config. */ let livePolicySink: ((policy: StorageCleanupPolicy) => void) | undefined; export function setStorageCleanupPolicyLiveSink( sink: ((policy: StorageCleanupPolicy) => void) | null, ): void { livePolicySink = sink ?? undefined; } export type PolicySchedule = StorageCleanupPolicy["schedule"]; export type PolicyRunReason = "startup" | "schedule" | "manual"; export type PolicyMetadataPersistenceError = "missing" | "invalid" | "conflict" | "write_failed"; export type PolicySkipReason = | "disabled" | "not_due" | "under_threshold" | "nothing_selected"; export interface PolicyRunResult { ok: boolean; skipped?: PolicySkipReason; deferred?: "codex_busy"; error?: CleanupResult["error"]; mode?: CleanupMode; freedBytes?: number; removed?: number; trashDir?: string; metadataPersistenceError?: PolicyMetadataPersistenceError; policy: StorageCleanupPolicy; } export interface PolicyRunDeps { now?: number; reason: PolicyRunReason; codexHome?: string; /** Bypass due-window checks (tests / explicit force). Still respects enabled. */ force?: boolean; loadPolicy?: () => StorageCleanupPolicy; savePolicy?: (policy: StorageCleanupPolicy) => void; execute?: (options: ExecuteCleanupOptions) => CleanupResult; busyTimeoutMs?: number; /** * Test-only: block after the start-of-job policy load so a concurrent PUT can * land before completion merges run metadata. */ holdAfterLoadMs?: number; /** Test-only Worker barrier: 0=pending, 1=policy loaded, 2=released. */ holdAfterLoadGate?: Int32Array; } /** Canonical defaults — enabled is always false. */ export function defaultStorageCleanupPolicy(): StorageCleanupPolicy { return { enabled: false, trigger: { archivedBytesOver: DEFAULT_ARCHIVED_BYTES_OVER }, target: { removeOldestPercent: DEFAULT_REMOVE_OLDEST_PERCENT }, schedule: "manual", mode: "quarantine", }; } function isFiniteNonNegInt(n: unknown): n is number { return typeof n === "number" && Number.isFinite(n) && n >= 0 && Math.floor(n) === n; } function isFinitePositiveInt(n: unknown): n is number { return typeof n === "number" && Number.isFinite(n) && n > 0 && Math.floor(n) === n; } /** True when target has exactly one of reduceToBytes / removeOldestPercent. */ export function isValidPolicyTarget(target: StorageCleanupPolicy["target"]): boolean { if (!target || typeof target !== "object") return false; const reduce = (target as { reduceToBytes?: unknown }).reduceToBytes; const percent = (target as { removeOldestPercent?: unknown }).removeOldestPercent; const hasReduce = reduce !== undefined; const hasPercent = percent !== undefined; if (hasReduce === hasPercent) return false; // none or both if (hasReduce) return isFiniteNonNegInt(reduce); return typeof percent === "number" && Number.isFinite(percent) && percent > 0 && percent <= 100; } /** * Normalize a partial/unknown policy into a complete StorageCleanupPolicy. * Never flips enabled to true unless the input explicitly sets enabled: true. */ export function normalizeStorageCleanupPolicy(raw: unknown): StorageCleanupPolicy { const base = defaultStorageCleanupPolicy(); if (!raw || typeof raw !== "object" || Array.isArray(raw)) return base; const o = raw as Record<string, unknown>; // only explicit true enables — and never when a present target is malformed let enabled = o.enabled === true; let archivedBytesOver = base.trigger.archivedBytesOver; if (o.trigger && typeof o.trigger === "object" && !Array.isArray(o.trigger)) { const t = (o.trigger as { archivedBytesOver?: unknown }).archivedBytesOver; if (isFiniteNonNegInt(t)) archivedBytesOver = t; } let target: StorageCleanupPolicy["target"] = base.target; if (Object.prototype.hasOwnProperty.call(o, "target")) { if (o.target && typeof o.target === "object" && !Array.isArray(o.target)) { const candidate = o.target as StorageCleanupPolicy["target"]; if (isValidPolicyTarget(candidate)) { const reduce = (candidate as { reduceToBytes?: number }).reduceToBytes; const percent = (candidate as { removeOldestPercent?: number }).removeOldestPercent; target = reduce !== undefined ? { reduceToBytes: reduce } : { removeOldestPercent: Math.min(100, Math.max(1, Math.floor(percent!))) }; } else { // Fail closed: malformed persisted target must not become delete-oldest 25%. enabled = false; } } else { enabled = false; } } const schedule: PolicySchedule = o.schedule === "startup" || o.schedule === "daily" || o.schedule === "weekly" || o.schedule === "manual" ? o.schedule : base.schedule; const mode: CleanupMode = o.mode === "permanent" ? "permanent" : "quarantine"; let lastRun: StorageCleanupPolicy["lastRun"]; if (o.lastRun && typeof o.lastRun === "object" && !Array.isArray(o.lastRun)) { const lr = o.lastRun as Record<string, unknown>; if ( isFinitePositiveInt(lr.at) && isFiniteNonNegInt(lr.freedBytes) && isFiniteNonNegInt(lr.removed) ) { lastRun = { at: lr.at, freedBytes: lr.freedBytes, removed: lr.removed }; } } let nextRun: number | undefined; if (o.nextRun === undefined || o.nextRun === null) { nextRun = undefined; } else if (isFinitePositiveInt(o.nextRun)) { nextRun = o.nextRun; } return { enabled, trigger: { archivedBytesOver }, target, schedule, mode, ...(lastRun ? { lastRun } : {}), ...(nextRun !== undefined ? { nextRun } : {}), }; } /** * Validate a PUT body. Returns a normalized policy or an error string. * Does not invent enabled=true. */ export function parseStorageCleanupPolicyInput( raw: unknown, previous?: StorageCleanupPolicy, ): { ok: true; policy: StorageCleanupPolicy } | { ok: false; error: string } { if (!raw || typeof raw !== "object" || Array.isArray(raw)) { return { ok: false, error: "body must be a JSON object" }; } const o = raw as Record<string, unknown>; const prev = previous ?? defaultStorageCleanupPolicy(); if (o.enabled !== undefined && typeof o.enabled !== "boolean") { return { ok: false, error: "enabled must be a boolean" }; } if (o.mode !== undefined && o.mode !== "quarantine" && o.mode !== "permanent") { return { ok: false, error: "mode must be quarantine or permanent" }; } if ( o.schedule !== undefined && o.schedule !== "startup" && o.schedule !== "daily" && o.schedule !== "weekly" && o.schedule !== "manual" ) { return { ok: false, error: "schedule must be startup, daily, weekly, or manual" }; } const merged: Record<string, unknown> = { ...prev, ...o, trigger: o.trigger !== undefined ? o.trigger : prev.trigger, target: o.target !== undefined ? o.target : prev.target, // Preserve run metadata unless the client explicitly sends replacements. lastRun: o.lastRun !== undefined ? o.lastRun : prev.lastRun, nextRun: o.nextRun !== undefined ? o.nextRun : prev.nextRun, }; if (o.trigger !== undefined) { if (!o.trigger || typeof o.trigger !== "object" || Array.isArray(o.trigger)) { return { ok: false, error: "trigger must be an object" }; } const bytes = (o.trigger as { archivedBytesOver?: unknown }).archivedBytesOver; if (!isFiniteNonNegInt(bytes)) { return { ok: false, error: "trigger.archivedBytesOver must be a non-negative integer" }; } } if (o.target !== undefined) { if (!isValidPolicyTarget(o.target as StorageCleanupPolicy["target"])) { return { ok: false, error: "target must set exactly one of reduceToBytes (non-negative int) or removeOldestPercent (1-100)", }; } } // Clients must not clear lastRun/nextRun via null unless intentional — accept omit only. const policy = normalizeStorageCleanupPolicy(merged); // Recompute nextRun only when schedule newly becomes timed, or no valid nextRun exists. // Do not reset nextRun on every PUT that merely re-sends an unchanged schedule. if ( (policy.schedule === "daily" || policy.schedule === "weekly") && o.nextRun === undefined && (policy.nextRun === undefined || (o.schedule !== undefined && o.schedule !== prev.schedule)) ) { policy.nextRun = computeNextRun(policy.schedule, Date.now()); } if (policy.schedule === "manual" || policy.schedule === "startup") { if (o.nextRun === undefined) delete policy.nextRun; } return { ok: true, policy }; } export function readStorageCleanupPolicyFromConfig(): StorageCleanupPolicy { return normalizeStorageCleanupPolicy(loadConfig().storageCleanupPolicy); } export function writeStorageCleanupPolicyToConfig(policy: StorageCleanupPolicy): StorageCleanupPolicy { const normalized = normalizeStorageCleanupPolicy(policy); const config = loadConfig(); config.storageCleanupPolicy = normalized; saveConfigPreservingClaudeCode(config); livePolicySink?.(normalized); return normalized; } /** Wall-clock next run for daily/weekly. Startup/manual → undefined. */ export function computeNextRun(schedule: PolicySchedule, now: number): number | undefined { if (schedule === "daily") return now + 24 * 60 * 60 * 1000; if (schedule === "weekly") return now + 7 * 24 * 60 * 60 * 1000; return undefined; } export function isPolicyDue( policy: StorageCleanupPolicy, now: number, reason: PolicyRunReason, ): boolean { if (!policy.enabled) return false; if (reason === "manual") return true; if (policy.schedule === "manual") return false; if (policy.schedule === "startup") { if (reason === "startup") return true; // Honor deferred nextRun (e.g. codex_busy at launch) on later scheduler ticks. return reason === "schedule" && policy.nextRun !== undefined && now >= policy.nextRun; } // daily / weekly: due when nextRun unset or elapsed if (policy.nextRun === undefined) return true; return now >= policy.nextRun; } /** Oldest-first until archived total would drop to `reduceToBytes`. */ export function selectReduceToBytes( candidates: ReturnType<typeof listArchivedCandidates>, reduceToBytes: number, ): ReturnType<typeof listArchivedCandidates> { if (!Number.isFinite(reduceToBytes) || reduceToBytes < 0) return []; const total = candidates.reduce((sum, c) => sum + c.bytes, 0); if (total <= reduceToBytes) return []; const need = total - reduceToBytes; const out: typeof candidates = []; let freed = 0; for (const c of candidates) { out.push(c); freed += c.bytes; if (freed >= need) break; } return out; } /** * Minimal percent in 1..100 such that `selectOldestPercent` returns at least `n` of `m`. * Returns 0 when n<=0, 100 when n>=m. */ export function percentForAtLeastCount(totalCount: number, selectedCount: number): number { if (selectedCount <= 0 || totalCount <= 0) return 0; if (selectedCount >= totalCount) return 100; for (let pct = 1; pct <= 100; pct++) { const got = Math.max(1, Math.floor((totalCount * pct) / 100)); if (got >= selectedCount) return pct; } return 100; } export interface PolicySelection { archivedBytes: number; percent: number; count: number; bytes: number; digest: string; /** Present when selection is an exact candidate list (reduceToBytes). */ candidateRelPaths?: string[]; } /** Build a Phase-2-compatible preview for the active policy target. */ export function selectPolicyPreview( policy: StorageCleanupPolicy, codexHome: string = resolveCodexHomeDir(), ): PolicySelection { const all = listArchivedCandidates(codexHome); const archivedBytes = all.reduce((sum, c) => sum + c.bytes, 0); const reduceTo = (policy.target as { reduceToBytes?: number }).reduceToBytes; const removePct = (policy.target as { removeOldestPercent?: number }).removeOldestPercent; if (reduceTo !== undefined) { // Exact candidate set — do not approximate via percent (would over-delete). const desired = selectReduceToBytesSkippingPendingRestore(all, reduceTo, codexHome); const preview = previewExactArchivedCleanup(desired, codexHome); return { archivedBytes, percent: 0, count: preview.count, bytes: preview.bytes, digest: preview.digest, candidateRelPaths: preview.candidates.map(c => c.relPath), }; } // Reuse the already-listed candidates — avoid a second archive directory walk. const percent = Math.min(100, Math.max(0, Math.floor(removePct ?? 0))); const selected = selectOldestPercentSkippingPendingRestore( filterCandidatesExcludingPinned(all, codexHome), percent, codexHome, ); return { archivedBytes, percent, count: selected.length, bytes: selected.reduce((sum, c) => sum + c.bytes, 0), digest: computePreviewDigest(selected, percent), }; } function advanceNextRun(policy: StorageCleanupPolicy, now: number): StorageCleanupPolicy { const next = { ...policy }; const nextRun = computeNextRun(policy.schedule, now); if (nextRun === undefined) delete next.nextRun; else next.nextRun = nextRun; return next; } function deferBusy(policy: StorageCleanupPolicy, now: number): StorageCleanupPolicy { return { ...policy, nextRun: now + BUSY_DEFER_MS }; } export type PolicyRunMetadataPatch = { now: number; /** Advance nextRun from the *latest* schedule, or defer on codex_busy. */ nextRun: "advance" | "defer_busy"; lastRun?: StorageCleanupPolicy["lastRun"]; }; /** Apply only run-owned fields while preserving the supplied policy settings. */ function applyPolicyRunMetadata( policy: StorageCleanupPolicy, patch: PolicyRunMetadataPatch, ): StorageCleanupPolicy { let next = patch.nextRun === "defer_busy" ? deferBusy(policy, patch.now) : advanceNextRun(policy, patch.now); if (patch.lastRun) { next = { ...next, lastRun: patch.lastRun }; } return next; } /** * Reload the latest persisted policy and write only run-owned metadata * (`lastRun` / `nextRun`). Preserves concurrent edits to enabled, trigger, * target, schedule, and mode that landed while a long run was in flight. */ export function commitPolicyRunMetadata( load: () => StorageCleanupPolicy, save: (policy: StorageCleanupPolicy) => void, patch: PolicyRunMetadataPatch, ): StorageCleanupPolicy { const latest = normalizeStorageCleanupPolicy(load()); const next = applyPolicyRunMetadata(latest, patch); save(next); return next; } type PolicyRunMetadataCommit = { policy: StorageCleanupPolicy; persistenceError?: PolicyMetadataPersistenceError; }; /** Attach the durable metadata outcome without replacing cleanup status or metrics. */ function withMetadataCommit( result: Omit<PolicyRunResult, "policy" | "metadataPersistenceError">, committed: PolicyRunMetadataCommit, ): PolicyRunResult { return { ...result, policy: committed.policy, ...(committed.persistenceError ? { metadataPersistenceError: committed.persistenceError } : {}), }; } /** Recompute run-owned metadata from the latest config inside the mutation lock. */ function commitPolicyRunMetadataToConfig( patch: PolicyRunMetadataPatch, fallbackPolicy: StorageCleanupPolicy, ): PolicyRunMetadataCommit { const unavailable = (reason: PolicyMetadataPersistenceError): PolicyRunMetadataCommit => { console.warn(`[storage-policy] metadata_persist_failed reason=${reason}`); return { policy: applyPolicyRunMetadata(fallbackPolicy, patch), persistenceError: reason, }; }; try { const outcome = mutatePersistedConfig(config => { const next = applyPolicyRunMetadata( normalizeStorageCleanupPolicy(config.storageCleanupPolicy), patch, ); config.storageCleanupPolicy = next; return { changed: true, value: next }; }); if (outcome.status === "unavailable") return unavailable(outcome.reason); livePolicySink?.(outcome.value); return { policy: outcome.value }; } catch { return unavailable("write_failed"); } } function logPolicyEvent(message: string): void { console.log(`[storage-policy] ${message}`); } /** * Evaluate and optionally execute the storage cleanup policy. * Disabled / under-threshold / not-due paths never call execute. */ export function runStorageCleanupPolicy(deps: PolicyRunDeps): PolicyRunResult { const now = deps.now ?? Date.now(); const load = deps.loadPolicy ?? readStorageCleanupPolicyFromConfig; const save = deps.savePolicy ?? writeStorageCleanupPolicyToConfig; const execute = deps.execute ?? executeArchivedCleanup; const policy = normalizeStorageCleanupPolicy(load()); // Injected stores retain the existing load/save contract. The production path // recomputes metadata from the latest persisted policy inside the config lock. const commitMetadata = deps.loadPolicy !== undefined || deps.savePolicy !== undefined ? (patch: PolicyRunMetadataPatch): PolicyRunMetadataCommit => ({ policy: commitPolicyRunMetadata(load, save, patch), }) : (patch: PolicyRunMetadataPatch) => commitPolicyRunMetadataToConfig(patch, policy); if (deps.holdAfterLoadGate) { Atomics.compareExchange(deps.holdAfterLoadGate, 0, 0, 1); Atomics.notify(deps.holdAfterLoadGate, 0); if (Atomics.wait(deps.holdAfterLoadGate, 0, 1, 10_000) === "timed-out") { throw new Error("policy_test_load_gate_timeout"); } } if (typeof deps.holdAfterLoadMs === "number" && Number.isFinite(deps.holdAfterLoadMs) && deps.holdAfterLoadMs > 0) { Bun.sleepSync(Math.floor(deps.holdAfterLoadMs)); } if (!policy.enabled) { return { ok: true, skipped: "disabled", policy }; } if (!deps.force && !isPolicyDue(policy, now, deps.reason)) { return { ok: true, skipped: "not_due", policy }; } const selection = selectPolicyPreview(policy, deps.codexHome); if (selection.archivedBytes <= policy.trigger.archivedBytesOver) { const committed = commitMetadata({ now, nextRun: "advance" }); logPolicyEvent("skip under_threshold"); return withMetadataCommit({ ok: true, skipped: "under_threshold" }, committed); } if (selection.count === 0) { const committed = commitMetadata({ now, nextRun: "advance" }); logPolicyEvent("skip nothing_selected"); return withMetadataCommit({ ok: true, skipped: "nothing_selected" }, committed); } const result = execute({ percent: selection.percent, mode: policy.mode, digest: selection.digest, ...(selection.candidateRelPaths ? { candidateRelPaths: selection.candidateRelPaths } : {}), ...(deps.codexHome ? { codexHome: deps.codexHome } : {}), ...(deps.busyTimeoutMs !== undefined ? { busyTimeoutMs: deps.busyTimeoutMs } : {}), now, }); if (!result.ok && result.error === "codex_busy") { const committed = commitMetadata({ now, nextRun: "defer_busy" }); logPolicyEvent("defer codex_busy"); return withMetadataCommit({ ok: false, deferred: "codex_busy", error: "codex_busy", }, committed); } if (!result.ok) { // Non-busy failure: still advance schedule so we do not tight-loop. const committed = commitMetadata({ now, nextRun: "advance" }); logPolicyEvent(`fail ${result.error ?? "cleanup_failed"}`); return withMetadataCommit({ ok: false, error: result.error, mode: result.mode, ...(result.trashDir ? { trashDir: result.trashDir } : {}), }, committed); } const committed = commitMetadata({ now, nextRun: "advance", lastRun: { at: now, freedBytes: result.bytes, removed: result.count, }, }); logPolicyEvent( `ok mode=${result.mode} removed=${result.count} freedBytes=${result.bytes}`, ); return withMetadataCommit({ ok: true, mode: result.mode, freedBytes: result.bytes, removed: result.count, ...(result.trashDir ? { trashDir: result.trashDir } : {}), }, committed); } /** Startup / schedule tick entry — swallows unexpected errors. */ export function maybeRunDueStorageCleanupPolicy( reason: PolicyRunReason, deps?: Omit<PolicyRunDeps, "reason">, ): PolicyRunResult | null { try { return runStorageCleanupPolicy({ ...deps, reason }); } catch { logPolicyEvent("error evaluation_failed"); return null; } }