@remodex/rmx 1.0.2

package/src/lib/admission.ts

@@ -0,0 +1,83 @@
+export const RETAINED_TRUNCATION_MARKER = "\n…[truncated by Remodex]";
+
+export class ResourceAdmissionError extends Error {
+  readonly code: string = "server_busy";
+
+  constructor(readonly resource: string, readonly limit: number) {
+    super(`${resource} capacity reached (${limit})`);
+    this.name = "ResourceAdmissionError";
+  }
+}
+
+export interface AdmissionMetrics {
+  active: number;
+  peak: number;
+  admitted: number;
+  rejected: number;
+  releaseMisses: number;
+}
+
+export interface AdmissionLease {
+  release(): void;
+}
+
+export interface AdmissionReservation<T> extends AdmissionLease {
+  bind(value: T): void;
+}
+
+export function createAdmissionGate(name: string, limit: number): {
+  tryAcquire(): AdmissionLease | null;
+  metrics(): Readonly<AdmissionMetrics>;
+} {
+  if (!Number.isSafeInteger(limit) || limit < 1) throw new RangeError(`${name} admission limit must be positive`);
+  const state: AdmissionMetrics = { active: 0, peak: 0, admitted: 0, rejected: 0, releaseMisses: 0 };
+  return {
+    tryAcquire() {
+      if (state.active >= limit) {
+        state.rejected += 1;
+        return null;
+      }
+      state.active += 1;
+      state.admitted += 1;
+      state.peak = Math.max(state.peak, state.active);
+      let active = true;
+      return {
+        release() {
+          if (!active) {
+            return;
+          }
+          active = false;
+          state.active -= 1;
+        },
+      };
+    },
+    metrics() {
+      return { ...state };
+    },
+  };
+}
+
+export function retainedUtf8Bytes(value: string): number {
+  return new TextEncoder().encode(value).byteLength;
+}
+
+function utf8Prefix(value: string, maxBytes: number): string {
+  if (maxBytes <= 0) return "";
+  let bytes = 0;
+  let result = "";
+  for (const character of value) {
+    const size = retainedUtf8Bytes(character);
+    if (bytes + size > maxBytes) break;
+    result += character;
+    bytes += size;
+  }
+  return result;
+}
+
+export function truncateRetainedUtf8(value: string, maxBytes: number): string {
+  if (!Number.isSafeInteger(maxBytes) || maxBytes < 0) throw new RangeError("maxBytes must be a non-negative integer");
+  if (retainedUtf8Bytes(value) <= maxBytes) return value;
+  const markerBytes = retainedUtf8Bytes(RETAINED_TRUNCATION_MARKER);
+  if (markerBytes > maxBytes) return utf8Prefix(RETAINED_TRUNCATION_MARKER, maxBytes);
+  return utf8Prefix(value, maxBytes - markerBytes) + RETAINED_TRUNCATION_MARKER;
+}

package/src/lib/app-owned-memory-stores.ts

@@ -0,0 +1,173 @@
+import {
+  enforceAppOwnedMemoryBudget,
+  registerRetainedStore,
+  registerObservedBuffer,
+  type RetainedStoreRegistration,
+  type RetainedStoreSnapshot,
+} from "./app-owned-memory";
+import { registerStateSweepAfterTick } from "./state-store-sweeper";
+import { debugBufferMetrics, evictOldestDebugEntryForBudget } from "./debug-log-buffer";
+import { injectionBufferMetrics, evictOldestInjectionEntryForBudget } from "./injection-debug-log";
+import { crashRingMetrics, evictOldestCrashTraceForBudget } from "./crash-guard";
+import { claudeInboundDebugMetrics, evictOldestClaudeInboundForBudget } from "../claude/inbound-debug";
+import {
+  evictOldestRequestLogForBudget,
+  requestLogRetainedStoreSnapshot,
+} from "../server/request-log";
+import {
+  anthropicImageNormalizeRetainedStoreSnapshot,
+  evictOldestAnthropicImageNormalizeForBudget,
+} from "../adapters/anthropic-image-normalize";
+import {
+  evictOldestVisionDescriptionForBudget,
+  visionDescriptionRetainedStoreSnapshot,
+} from "../vision";
+import {
+  antigravityReplayRetainedStoreSnapshot,
+  evictOldestAntigravityReplayForBudget,
+} from "../adapters/google-antigravity-replay";
+import {
+  evictOldestModelCacheForBudget,
+  modelCacheRetainedStoreSnapshot,
+} from "../codex/model-cache";
+import {
+  evictOldestUsageSummaryForBudget,
+  usageSummaryRetainedStoreSnapshot,
+} from "../server/management/usage-summary-cache";
+import {
+  cursorBlobRetainedStoreSnapshot,
+  evictOldestCursorBlobForBudget,
+} from "../adapters/cursor/native-exec";
+import {
+  evictOldestResponseContinuationForBudget,
+  responseContinuationRetainedStoreSnapshot,
+} from "../responses/state";
+import { translatorObservedBufferSnapshot } from "./translator-budget";
+import { imageFulfillmentTailSnapshot } from "../images/fulfill";
+import { oauthMutationTailSnapshot } from "../oauth/store";
+import { grokApplyFlightSnapshot } from "../server/management/agent-settings-routes";
+
+function ringSnapshot(metrics: { entries: number; bytes: number; oldestAt: number | null }): RetainedStoreSnapshot {
+  return {
+    count: metrics.entries,
+    bytes: metrics.bytes,
+    evictableBytes: metrics.bytes,
+    pinnedBytes: 0,
+    oldestAt: metrics.oldestAt,
+  };
+}
+
+function providerDebugSnapshot(): RetainedStoreSnapshot {
+  return ringSnapshot(debugBufferMetrics());
+}
+
+function injectionDebugSnapshot(): RetainedStoreSnapshot {
+  return ringSnapshot(injectionBufferMetrics());
+}
+
+function claudeDebugSnapshot(): RetainedStoreSnapshot {
+  return ringSnapshot(claudeInboundDebugMetrics());
+}
+
+function crashRingSnapshot(): RetainedStoreSnapshot {
+  return ringSnapshot(crashRingMetrics());
+}
+
+export const APP_OWNED_RETAINED_STORE_REGISTRATIONS = [
+  {
+    id: "request_log",
+    category: "logs",
+    snapshot: requestLogRetainedStoreSnapshot,
+    evictOldest: evictOldestRequestLogForBudget,
+  },
+  {
+    id: "provider_debug",
+    category: "logs",
+    snapshot: providerDebugSnapshot,
+    evictOldest: evictOldestDebugEntryForBudget,
+  },
+  {
+    id: "injection_debug",
+    category: "logs",
+    snapshot: injectionDebugSnapshot,
+    evictOldest: evictOldestInjectionEntryForBudget,
+  },
+  {
+    id: "claude_debug",
+    category: "logs",
+    snapshot: claudeDebugSnapshot,
+    evictOldest: evictOldestClaudeInboundForBudget,
+  },
+  {
+    id: "crash_ring",
+    category: "logs",
+    snapshot: crashRingSnapshot,
+    evictOldest: evictOldestCrashTraceForBudget,
+  },
+  {
+    id: "image_normalize",
+    category: "caches",
+    snapshot: anthropicImageNormalizeRetainedStoreSnapshot,
+    evictOldest: evictOldestAnthropicImageNormalizeForBudget,
+  },
+  {
+    id: "vision_descriptions",
+    category: "caches",
+    snapshot: visionDescriptionRetainedStoreSnapshot,
+    evictOldest: evictOldestVisionDescriptionForBudget,
+  },
+  {
+    id: "antigravity_replay",
+    category: "caches",
+    snapshot: antigravityReplayRetainedStoreSnapshot,
+    evictOldest: evictOldestAntigravityReplayForBudget,
+  },
+  {
+    id: "model_cache",
+    category: "caches",
+    snapshot: modelCacheRetainedStoreSnapshot,
+    evictOldest: evictOldestModelCacheForBudget,
+  },
+  {
+    id: "usage_summary",
+    category: "caches",
+    snapshot: usageSummaryRetainedStoreSnapshot,
+    evictOldest: evictOldestUsageSummaryForBudget,
+  },
+  {
+    id: "cursor_blobs",
+    category: "blobs",
+    snapshot: cursorBlobRetainedStoreSnapshot,
+    evictOldest: evictOldestCursorBlobForBudget,
+  },
+  {
+    id: "responses_continuation",
+    category: "continuation",
+    snapshot: responseContinuationRetainedStoreSnapshot,
+    evictOldest: evictOldestResponseContinuationForBudget,
+  },
+] as const satisfies readonly RetainedStoreRegistration[];
+
+export function registerDefaultAppOwnedMemoryStores(): void {
+  for (const registration of APP_OWNED_RETAINED_STORE_REGISTRATIONS) {
+    registerRetainedStore(registration);
+  }
+}
+
+export const APP_OWNED_OBSERVED_BUFFER_REGISTRATIONS = [
+  { id: "translator_buffers", category: "translator", snapshot: translatorObservedBufferSnapshot },
+  { id: "image_fulfillment_tail", category: "serialized_tails", snapshot: imageFulfillmentTailSnapshot },
+  { id: "oauth_mutation_tail", category: "serialized_tails", snapshot: oauthMutationTailSnapshot },
+  { id: "grok_apply_flight", category: "serialized_tails", snapshot: grokApplyFlightSnapshot },
+] as const;
+
+export function registerDefaultAppOwnedObservedBuffers(): void {
+  for (const registration of APP_OWNED_OBSERVED_BUFFER_REGISTRATIONS) registerObservedBuffer(registration);
+}
+
+export function registerAppOwnedMemorySweepFallback(): void {
+  registerStateSweepAfterTick({
+    name: "app-owned-memory-budget",
+    afterTick: enforceAppOwnedMemoryBudget,
+  });
+}

package/src/lib/app-owned-memory.ts

@@ -0,0 +1,265 @@
+export type AppOwnedRetainedCategory = "logs" | "caches" | "blobs" | "continuation";
+export type AppOwnedObservedCategory = "translator" | "serialized_tails";
+
+export interface RetainedStoreSnapshot {
+  count: number;
+  bytes: number;
+  evictableBytes: number;
+  pinnedBytes: number;
+  oldestAt: number | null;
+}
+
+export interface RetainedStoreRegistration {
+  id: string;
+  category: AppOwnedRetainedCategory;
+  snapshot(): RetainedStoreSnapshot;
+  evictOldest(): number;
+}
+
+export interface ObservedBufferRegistration {
+  id: string;
+  category: AppOwnedObservedCategory;
+  snapshot(): { currentBytes: number; highWaterBytes: number; active: number };
+}
+
+export interface AppOwnedBytesSnapshot {
+  budgetBytes: number;
+  retainedBytes: number;
+  evictableBytes: number;
+  pinnedBytes: number;
+  overBudgetBytes: number;
+  stores: Record<string, RetainedStoreSnapshot>;
+  observedInFlight: Record<string, { currentBytes: number; highWaterBytes: number; active: number }>;
+  enforcement: {
+    runs: number;
+    entriesDemoted: number;
+    bytesReleased: number;
+    noEvictableCandidate: number;
+    snapshotFailures: number;
+    oldestAtContractViolations: number;
+  };
+}
+
+export const DEFAULT_APP_OWNED_MEMORY_BUDGET_BYTES = 256 * 1024 * 1024;
+/**
+ * The budget above is an eviction target, not a hard resident limit: active/pinned
+ * state may temporarily keep retained bytes above it. Every pin-capable owner has
+ * its own finite admission cap; their documented aggregate must remain below this
+ * process-owned hard ceiling.
+ */
+export const APP_OWNED_WORST_CASE_PINNED_BYTES = 512 * 1024 * 1024;
+export const MIN_APP_OWNED_MEMORY_BUDGET_MB = 64;
+export const MAX_APP_OWNED_MEMORY_BUDGET_MB = 4_096;
+
+const CATEGORY_ORDER: readonly AppOwnedRetainedCategory[] = [
+  "logs",
+  "caches",
+  "blobs",
+  "continuation",
+];
+const WARN_INTERVAL_MS = 60_000;
+const ZERO_RETAINED_SNAPSHOT: RetainedStoreSnapshot = {
+  count: 0,
+  bytes: 0,
+  evictableBytes: 0,
+  pinnedBytes: 0,
+  oldestAt: null,
+};
+const ZERO_OBSERVED_SNAPSHOT = { currentBytes: 0, highWaterBytes: 0, active: 0 };
+
+const retainedStores = new Map<string, RetainedStoreRegistration>();
+const observedBuffers = new Map<string, ObservedBufferRegistration>();
+let budgetBytes = DEFAULT_APP_OWNED_MEMORY_BUDGET_BYTES;
+let lastSaturationWarningAt = Number.NEGATIVE_INFINITY;
+const enforcementCounters = {
+  runs: 0,
+  entriesDemoted: 0,
+  bytesReleased: 0,
+  noEvictableCandidate: 0,
+  snapshotFailures: 0,
+  oldestAtContractViolations: 0,
+};
+let isEnforcing = false;
+
+export function resolveAppOwnedMemoryBudgetBytes(value: unknown): number {
+  return typeof value === "number"
+    && Number.isInteger(value)
+    && value >= MIN_APP_OWNED_MEMORY_BUDGET_MB
+    && value <= MAX_APP_OWNED_MEMORY_BUDGET_MB
+    ? value * 1024 * 1024
+    : DEFAULT_APP_OWNED_MEMORY_BUDGET_BYTES;
+}
+
+export function registerRetainedStore(registration: RetainedStoreRegistration): () => void {
+  retainedStores.set(registration.id, registration);
+  return () => {
+    if (retainedStores.get(registration.id) === registration) retainedStores.delete(registration.id);
+  };
+}
+
+export function registerObservedBuffer(registration: ObservedBufferRegistration): () => void {
+  observedBuffers.set(registration.id, registration);
+  return () => {
+    if (observedBuffers.get(registration.id) === registration) observedBuffers.delete(registration.id);
+  };
+}
+
+export function configureAppOwnedMemoryBudget(bytes: number): void {
+  budgetBytes = bytes;
+}
+
+function retainedSnapshot(registration: RetainedStoreRegistration): RetainedStoreSnapshot {
+  try {
+    return registration.snapshot();
+  } catch {
+    enforcementCounters.snapshotFailures += 1;
+    return { ...ZERO_RETAINED_SNAPSHOT };
+  }
+}
+
+function observedSnapshot(
+  registration: ObservedBufferRegistration,
+): { currentBytes: number; highWaterBytes: number; active: number } {
+  try {
+    return registration.snapshot();
+  } catch {
+    enforcementCounters.snapshotFailures += 1;
+    return { ...ZERO_OBSERVED_SNAPSHOT };
+  }
+}
+
+export function appOwnedBytesSnapshot(): AppOwnedBytesSnapshot {
+  return appOwnedBytesSnapshotFrom(retainedSnapshots().stores);
+}
+
+function appOwnedBytesSnapshotFrom(
+  retained: ReadonlyMap<string, RetainedStoreSnapshot>,
+): AppOwnedBytesSnapshot {
+  const stores: Record<string, RetainedStoreSnapshot> = {};
+  let retainedBytes = 0;
+  let evictableBytes = 0;
+  let pinnedBytes = 0;
+  for (const registration of retainedStores.values()) {
+    const snapshot = retained.get(registration.id) ?? ZERO_RETAINED_SNAPSHOT;
+    stores[registration.id] = snapshot;
+    retainedBytes += snapshot.bytes;
+    evictableBytes += snapshot.evictableBytes;
+    pinnedBytes += snapshot.pinnedBytes;
+  }
+
+  const observedInFlight: AppOwnedBytesSnapshot["observedInFlight"] = {};
+  for (const registration of observedBuffers.values()) {
+    observedInFlight[registration.id] = observedSnapshot(registration);
+  }
+
+  return {
+    budgetBytes,
+    retainedBytes,
+    evictableBytes,
+    pinnedBytes,
+    overBudgetBytes: Math.max(0, retainedBytes - budgetBytes),
+    stores,
+    observedInFlight,
+    enforcement: { ...enforcementCounters },
+  };
+}
+
+function nextCandidate(
+  snapshots: ReadonlyMap<string, RetainedStoreSnapshot>,
+  ineligible: Set<string>,
+): RetainedStoreRegistration | undefined {
+  for (const category of CATEGORY_ORDER) {
+    let candidate: RetainedStoreRegistration | undefined;
+    let candidateAt = Number.POSITIVE_INFINITY;
+    for (const registration of retainedStores.values()) {
+      if (registration.category !== category || ineligible.has(registration.id)) continue;
+      const snapshot = snapshots.get(registration.id);
+      if (!snapshot || snapshot.evictableBytes <= 0) continue;
+      const oldestAt = snapshot.oldestAt;
+      if (oldestAt === null || !Number.isFinite(oldestAt)) {
+        enforcementCounters.oldestAtContractViolations += 1;
+        ineligible.add(registration.id);
+        continue;
+      }
+      if (!candidate || oldestAt < candidateAt) {
+        candidate = registration;
+        candidateAt = oldestAt;
+      }
+    }
+    if (candidate) return candidate;
+  }
+  return undefined;
+}
+
+function retainedSnapshots(): { total: number; stores: Map<string, RetainedStoreSnapshot> } {
+  const stores = new Map<string, RetainedStoreSnapshot>();
+  let total = 0;
+  for (const registration of retainedStores.values()) {
+    const snapshot = retainedSnapshot(registration);
+    stores.set(registration.id, snapshot);
+    total += snapshot.bytes;
+  }
+  return { total, stores };
+}
+
+function warnPinnedSaturation(): void {
+  const at = Date.now();
+  if (at - lastSaturationWarningAt < WARN_INTERVAL_MS) return;
+  lastSaturationWarningAt = at;
+  console.warn("[app-owned-memory] retained state remains over budget with no evictable candidate");
+}
+
+export function enforceAppOwnedMemoryBudget(): AppOwnedBytesSnapshot {
+  if (isEnforcing) return appOwnedBytesSnapshot();
+  isEnforcing = true;
+  enforcementCounters.runs += 1;
+  try {
+    const ineligible = new Set<string>();
+    const current = retainedSnapshots();
+    while (current.total > budgetBytes) {
+      const candidate = nextCandidate(current.stores, ineligible);
+      if (!candidate) {
+        enforcementCounters.noEvictableCandidate += 1;
+        warnPinnedSaturation();
+        break;
+      }
+
+      let reportedReleased = 0;
+      try {
+        reportedReleased = candidate.evictOldest();
+      } catch {
+        ineligible.add(candidate.id);
+        continue;
+      }
+      const previousSnapshot = current.stores.get(candidate.id) ?? ZERO_RETAINED_SNAPSHOT;
+      const nextSnapshot = retainedSnapshot(candidate);
+      current.stores.set(candidate.id, nextSnapshot);
+      const nextTotal = Math.max(0, current.total - previousSnapshot.bytes + nextSnapshot.bytes);
+      const actualReleased = Math.max(0, current.total - nextTotal);
+      if (reportedReleased <= 0 || actualReleased <= 0) {
+        ineligible.add(candidate.id);
+      } else {
+        enforcementCounters.entriesDemoted += 1;
+        enforcementCounters.bytesReleased += actualReleased;
+      }
+      current.total = nextTotal;
+    }
+    return appOwnedBytesSnapshotFrom(current.stores);
+  } finally {
+    isEnforcing = false;
+  }
+}
+
+export function resetAppOwnedMemoryForTests(): void {
+  retainedStores.clear();
+  observedBuffers.clear();
+  budgetBytes = DEFAULT_APP_OWNED_MEMORY_BUDGET_BYTES;
+  lastSaturationWarningAt = Number.NEGATIVE_INFINITY;
+  enforcementCounters.runs = 0;
+  enforcementCounters.entriesDemoted = 0;
+  enforcementCounters.bytesReleased = 0;
+  enforcementCounters.noEvictableCandidate = 0;
+  enforcementCounters.snapshotFailures = 0;
+  enforcementCounters.oldestAtContractViolations = 0;
+  isEnforcing = false;
+}