@koreanhole/opencodex 2.96.0 → 2.98.0

package/src/adapters/cli-agent/gemini/live-models.ts

@@ -12,6 +12,13 @@ import {
   probeGeminiAcpSupport,
   stageGeminiAcpWorkspace,
 } from "./acp";
+import { discoverGeminiModelMetadata, mergeGeminiModelDescriptors } from "./model-metadata";
+import {
+  getGeminiRuntime,
+  recordGeminiCompressionThreshold,
+  recordGeminiInitialize,
+} from "./runtime";
+import type { OcxProviderModel } from "../../../types";
 
 export type GeminiLiveModelsFailure = "not_found" | "unsupported" | "auth_required" | "backoff" | "transport";
 
@@ -19,9 +26,11 @@ export type GeminiLiveModelsResult =
   | {
       ok: true;
       models: string[];
+      modelInfo: OcxProviderModel[];
       source: "models" | "default";
       fingerprint: string;
       stale?: true;
+      metadataWarning?: string;
     }
   | {
       ok: false;
@@ -34,16 +43,20 @@ export interface GeminiLiveModelsOptions {
   binary?: string;
   env?: NodeJS.ProcessEnv;
   deps?: AcpDeps;
+  packageRoot?: string;
   ttlMs?: number;
+  forceRefresh?: boolean;
   failureBackoffMs?: number;
   now?: () => number;
 }
 
 interface CacheEntry {
   models: string[];
+  modelInfo: OcxProviderModel[];
   source: "models" | "default";
   fetchedAt: number;
   lastFailureAt?: number;
+  metadataWarning?: string;
 }
 
 const cache = new Map<string, CacheEntry>();
@@ -59,6 +72,10 @@ function staleResult(fingerprint: string, entry: CacheEntry | undefined): Gemini
   return {
     ok: true,
     models: [...entry.models],
+    modelInfo: entry.modelInfo.map(model => ({
+      ...model,
+      supportedReasoningLevels: [...(model.supportedReasoningLevels ?? [])],
+    })),
     source: entry.source,
     fingerprint,
     stale: true,
@@ -79,8 +96,8 @@ export async function discoverGeminiLiveModels(options: GeminiLiveModelsOptions
   const fingerprint = geminiBinaryFingerprintSync(binary);
   const current = cache.get(fingerprint);
   const timestamp = now();
-  if (current && timestamp - current.fetchedAt < ttlMs) {
-    return { ok: true, models: [...current.models], source: current.source, fingerprint };
+  if (!options.forceRefresh && current && timestamp - current.fetchedAt < ttlMs) {
+    return { ok: true, models: [...current.models], modelInfo: current.modelInfo, source: current.source, fingerprint, ...(current.metadataWarning ? { metadataWarning: current.metadataWarning } : {}) };
   }
   const lastFailure = failureCache.get(fingerprint) ?? current?.lastFailureAt;
   if (lastFailure !== undefined && timestamp - lastFailure < failureBackoffMs) {
@@ -96,8 +113,12 @@ export async function discoverGeminiLiveModels(options: GeminiLiveModelsOptions
     return staleResult(fingerprint, current)
       ?? { ok: false, reason: "unsupported", detail: "Gemini --help does not advertise --acp.", fingerprint };
   }
-  const workspace = await stageGeminiAcpWorkspace();
-  const sessionEnv = { ...env, GEMINI_CLI_SYSTEM_SETTINGS_PATH: workspace.settingsPath };
+  const workspace = await stageGeminiAcpWorkspace([], undefined, { sourceEnv });
+  const sessionEnv = {
+    ...env,
+    GEMINI_CLI_HOME: workspace.geminiHome,
+    GEMINI_CLI_SYSTEM_SETTINGS_PATH: workspace.settingsPath,
+  };
   let client: AcpClient | undefined;
   try {
     client = await AcpClient.connect({
@@ -108,12 +129,40 @@ export async function discoverGeminiLiveModels(options: GeminiLiveModelsOptions
       label: "Gemini ACP",
       fallbackAllowed: false,
     }, options.deps);
+    if (client.initializeResult) await recordGeminiInitialize(fingerprint, client.initializeResult, sourceEnv);
     const session = await client.newSession({ cwd: workspace.cwd, mcpServers: [] });
     const models = geminiModelIds(session);
+    const metadata = await discoverGeminiModelMetadata({
+      binary,
+      env: sourceEnv,
+      ...(options.packageRoot ? { packageRoot: options.packageRoot } : {}),
+      ...(options.now ? { now: options.now } : {}),
+      ...(options.forceRefresh ? { ttlMs: 0 } : {}),
+    });
+    await recordGeminiCompressionThreshold(fingerprint, metadata.compressionThreshold, sourceEnv);
+    const runtime = await getGeminiRuntime(fingerprint, sourceEnv);
+    const modelInfo = mergeGeminiModelDescriptors(session.availableModels, metadata).map(model => {
+      const observed = runtime.models[model.id];
+      const contextWindow = observed?.contextSize ?? model.contextWindowTokens;
+      return {
+        ...model,
+        ...(contextWindow !== undefined
+          ? { contextWindowTokens: contextWindow, maxContextWindowTokens: contextWindow }
+          : {}),
+        ...(runtime.compressionThreshold !== undefined
+          ? { compressionThreshold: runtime.compressionThreshold }
+          : {}),
+        inputModalities: [
+          "text" as const,
+          ...(runtime.prompt.image ? ["image" as const] : []),
+        ],
+        loadSession: runtime.loadSession,
+      };
+    });
     const source = session.availableModels.length > 0 ? "models" : "default";
-    cache.set(fingerprint, { models, source, fetchedAt: timestamp });
+    cache.set(fingerprint, { models, modelInfo, source, fetchedAt: timestamp, ...(metadata.warning ? { metadataWarning: metadata.warning } : {}) });
     failureCache.delete(fingerprint);
-    return { ok: true, models, source, fingerprint };
+    return { ok: true, models, modelInfo, source, fingerprint, ...(metadata.warning ? { metadataWarning: metadata.warning } : {}) };
   } catch (error) {
     failureCache.set(fingerprint, timestamp);
     if (current) current.lastFailureAt = timestamp;

package/src/adapters/cli-agent/gemini/model-metadata.ts

@@ -0,0 +1,387 @@
+import { readFile, readdir, realpath, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import type { OcxProviderModel, OcxReasoningLevel } from "../../../types";
+
+const DEFAULT_METADATA_TTL_MS = 5 * 60_000;
+
+export interface GeminiThinkingConfig {
+  thinkingLevel?: string;
+  thinkingBudget?: number;
+  includeThoughts?: boolean;
+}
+
+export interface GeminiReasoningLevel extends OcxReasoningLevel {
+  thinkingConfig: GeminiThinkingConfig;
+  originalEffort: string;
+}
+
+export interface GeminiModelCapability {
+  thinkingSupported: boolean;
+  reasoningLevels: GeminiReasoningLevel[];
+  defaultReasoningLevel?: string;
+}
+
+export interface GeminiMetadataResult {
+  packageRoot?: string;
+  settingsPath?: string;
+  capabilities: Record<string, GeminiModelCapability>;
+  tokenLimits: Record<string, number>;
+  defaultTokenLimit?: number;
+  compressionThreshold?: number;
+  warning?: string;
+}
+
+export interface GeminiMetadataOptions {
+  binary: string;
+  env?: NodeJS.ProcessEnv;
+  packageRoot?: string;
+  ttlMs?: number;
+  now?: () => number;
+}
+
+interface CachedMetadata extends GeminiMetadataResult {
+  fetchedAt: number;
+}
+
+const metadataCache = new Map<string, CachedMetadata>();
+
+export function resetGeminiMetadataCacheForTests(): void {
+  metadataCache.clear();
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : undefined;
+}
+
+function stringValue(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function extractDefaultJsonValue(markdown: string, property: string): unknown {
+  const marker = `- **\`modelConfigs.${property}\`**`;
+  const start = markdown.indexOf(marker);
+  if (start < 0) return undefined;
+  const fenceStart = markdown.indexOf("```json", start);
+  if (fenceStart < 0) return undefined;
+  const bodyStart = markdown.indexOf("\n", fenceStart) + 1;
+  const fenceEnd = markdown.indexOf("```", bodyStart);
+  if (bodyStart <= 0 || fenceEnd < 0) return undefined;
+  try {
+    return JSON.parse(markdown.slice(bodyStart, fenceEnd).trim()) as unknown;
+  } catch {
+    return undefined;
+  }
+}
+
+function extractDefaultJson(markdown: string, property: string): Record<string, unknown> | undefined {
+  return asRecord(extractDefaultJsonValue(markdown, property));
+}
+
+async function findPackageRoot(binary: string): Promise<string | undefined> {
+  let current: string;
+  try {
+    current = dirname(await realpath(binary));
+  } catch {
+    current = dirname(resolve(binary));
+  }
+  for (let depth = 0; depth < 10; depth++) {
+    try {
+      const manifest = JSON.parse(await readFile(join(current, "package.json"), "utf8")) as { name?: unknown };
+      if (manifest.name === "@google/gemini-cli") return current;
+    } catch {
+      // Keep walking toward the package root.
+    }
+    const parent = dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return undefined;
+}
+
+async function readThinkingLevels(packageRoot: string): Promise<Array<{ effort: string; original: string }>> {
+  let files: string[];
+  try {
+    files = (await readdir(join(packageRoot, "bundle"))).filter(name => name.endsWith(".js"));
+  } catch {
+    return [];
+  }
+  const candidates = await Promise.all(files.map(async name => {
+    const path = join(packageRoot, "bundle", name);
+    const info = await stat(path).catch(() => undefined);
+    return info ? { path, size: info.size } : undefined;
+  }));
+  candidates.sort((left, right) => (left?.size ?? Infinity) - (right?.size ?? Infinity));
+  for (const candidate of candidates) {
+    if (!candidate) continue;
+    const text = await readFile(candidate.path, "utf8").catch(() => "");
+    if (!text.includes("ThinkingLevel2[\"LOW\"]")) continue;
+    const levels = [...text.matchAll(/ThinkingLevel2\["([A-Z0-9_]+)"\]/g)]
+      .map(match => match[1]!)
+      .filter(level => level !== "THINKING_LEVEL_UNSPECIFIED");
+    return [...new Set(levels)].map(level => ({ effort: level.toLowerCase(), original: level }));
+  }
+  return [];
+}
+
+interface RuntimeLimits {
+  tokenLimits: Record<string, number>;
+  defaultTokenLimit?: number;
+  compressionThreshold?: number;
+}
+
+function numericLiteral(value: string): number | undefined {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : undefined;
+}
+
+function functionBody(text: string, name: string): string | undefined {
+  const start = text.indexOf(`function ${name}(`);
+  if (start < 0) return undefined;
+  const open = text.indexOf("{", start);
+  if (open < 0) return undefined;
+  let depth = 0;
+  for (let index = open; index < text.length; index++) {
+    if (text[index] === "{") depth++;
+    else if (text[index] === "}" && --depth === 0) return text.slice(open + 1, index);
+  }
+  return undefined;
+}
+
+async function readRuntimeLimits(packageRoot: string): Promise<RuntimeLimits> {
+  let files: string[];
+  try {
+    files = (await readdir(join(packageRoot, "bundle"))).filter(name => name.endsWith(".js"));
+  } catch {
+    return { tokenLimits: {} };
+  }
+  const candidates = await Promise.all(files.map(async name => {
+    const path = join(packageRoot, "bundle", name);
+    const info = await stat(path).catch(() => undefined);
+    return info ? { path, size: info.size } : undefined;
+  }));
+  candidates.sort((left, right) => (left?.size ?? Infinity) - (right?.size ?? Infinity));
+  for (const candidate of candidates) {
+    if (!candidate) continue;
+    const text = await readFile(candidate.path, "utf8").catch(() => "");
+    if (!text.includes("DEFAULT_TOKEN_LIMIT")) continue;
+    const defaultMatch = text.match(/var DEFAULT_TOKEN_LIMIT = ([0-9.e+]+);/);
+    const defaultTokenLimit = defaultMatch ? numericLiteral(defaultMatch[1]!) : undefined;
+    if (!defaultTokenLimit) continue;
+    const gemmaMatch = text.match(/var GEMMA_4_TOKEN_LIMIT = ([0-9.e+]+);/);
+    const gemmaLimit = gemmaMatch ? numericLiteral(gemmaMatch[1]!) : undefined;
+    const thresholdMatch = text.match(/var DEFAULT_COMPRESSION_TOKEN_THRESHOLD = ([0-9.]+);/);
+    const compressionThreshold = thresholdMatch ? Number(thresholdMatch[1]) : undefined;
+    const constants = new Map<string, string>();
+    for (const match of text.matchAll(/var ([A-Z][A-Z0-9_]*) = "([^"]+)";/g)) {
+      constants.set(match[1]!, match[2]!);
+    }
+    const body = functionBody(text, "tokenLimit");
+    const tokenLimits: Record<string, number> = {};
+    if (body) {
+      const groups = [...body.matchAll(/case ([A-Z][A-Z0-9_]*):([\s\S]*?)(?=case |default:|$)/g)];
+      for (const group of groups) {
+        const modelId = constants.get(group[1]!);
+        const returned = group[2]!.match(/return ([A-Z][A-Z0-9_]*|[0-9.e+]+);/)?.[1];
+        if (!modelId || !returned) continue;
+        const limit = returned === "DEFAULT_TOKEN_LIMIT"
+          ? defaultTokenLimit
+          : returned === "GEMMA_4_TOKEN_LIMIT"
+            ? gemmaLimit
+            : numericLiteral(returned);
+        if (limit) tokenLimits[modelId] = limit;
+      }
+    }
+    return {
+      tokenLimits,
+      defaultTokenLimit,
+      ...(compressionThreshold !== undefined && compressionThreshold > 0 && compressionThreshold <= 1
+        ? { compressionThreshold }
+        : {}),
+    };
+  }
+  return { tokenLimits: {} };
+}
+
+function mergeConfig(target: Record<string, unknown>, source: Record<string, unknown>): Record<string, unknown> {
+  const out = { ...target };
+  for (const [key, value] of Object.entries(source)) {
+    const targetRecord = asRecord(out[key]);
+    const sourceRecord = asRecord(value);
+    out[key] = targetRecord && sourceRecord ? mergeConfig(targetRecord, sourceRecord) : value;
+  }
+  return out;
+}
+
+function resolveAlias(
+  id: string,
+  aliases: Record<string, unknown>,
+  seen = new Set<string>(),
+): Record<string, unknown> {
+  if (seen.has(id)) return {};
+  seen.add(id);
+  const alias = asRecord(aliases[id]);
+  if (!alias) return {};
+  const parent = stringValue(alias.extends);
+  const inherited = parent ? resolveAlias(parent, aliases, seen) : {};
+  return mergeConfig(inherited, asRecord(alias.modelConfig) ?? {});
+}
+
+function capabilitiesFromMetadata(
+  definitions: Record<string, unknown>,
+  aliases: Record<string, unknown>,
+  levels: Array<{ effort: string; original: string }>,
+  overrides: readonly unknown[],
+): Record<string, GeminiModelCapability> {
+  const capabilities: Record<string, GeminiModelCapability> = {};
+  for (const [modelId, rawDefinition] of Object.entries(definitions)) {
+    const definition = asRecord(rawDefinition);
+    const features = asRecord(definition?.features);
+    const thinkingSupported = features?.thinking === true;
+    if (!thinkingSupported) {
+      capabilities[modelId] = { thinkingSupported: false, reasoningLevels: [] };
+      continue;
+    }
+    let generateContentConfig = asRecord(resolveAlias(modelId, aliases).generateContentConfig) ?? {};
+    for (const rawOverride of overrides) {
+      const override = asRecord(rawOverride);
+      if (stringValue(asRecord(override?.match)?.model) !== modelId) continue;
+      generateContentConfig = mergeConfig(generateContentConfig, asRecord(asRecord(override?.modelConfig)?.generateContentConfig) ?? {});
+    }
+    const config = asRecord(generateContentConfig.thinkingConfig);
+    const configuredLevel = stringValue(config?.thinkingLevel)?.toLowerCase();
+    const includeThoughts = config?.includeThoughts === true;
+    const reasoningLevels = levels.map(level => ({
+      effort: level.effort,
+      originalEffort: level.original,
+      description: `Gemini CLI ${level.original} thinking level`,
+      thinkingConfig: {
+        thinkingLevel: level.original,
+        ...(includeThoughts ? { includeThoughts: true } : {}),
+      },
+    }));
+    const defaultReasoningLevel = reasoningLevels.some(level => level.effort === configuredLevel)
+      ? configuredLevel
+      : reasoningLevels.find(level => level.effort === "high")?.effort ?? reasoningLevels[0]?.effort;
+    capabilities[modelId] = {
+      thinkingSupported: true,
+      reasoningLevels,
+      ...(defaultReasoningLevel ? { defaultReasoningLevel } : {}),
+    };
+  }
+  return capabilities;
+}
+
+async function loadMetadata(options: GeminiMetadataOptions): Promise<GeminiMetadataResult> {
+  const env = options.env ?? process.env;
+  const packageRoot = options.packageRoot ?? await findPackageRoot(options.binary);
+  if (!packageRoot) return { capabilities: {}, tokenLimits: {}, warning: "Gemini CLI package metadata was not found." };
+  const runtimeLimits = await readRuntimeLimits(packageRoot);
+  const docsPath = join(packageRoot, "bundle", "docs", "reference", "configuration.md");
+  let markdown: string;
+  try {
+    markdown = await readFile(docsPath, "utf8");
+  } catch {
+    return { packageRoot, capabilities: {}, ...runtimeLimits, warning: "Gemini CLI model configuration documentation was not found." };
+  }
+  const defaultAliases = extractDefaultJson(markdown, "aliases");
+  const defaultDefinitions = extractDefaultJson(markdown, "modelDefinitions");
+  const defaultOverrides = extractDefaultJsonValue(markdown, "overrides");
+  if (!defaultAliases || !defaultDefinitions) {
+    return { packageRoot, capabilities: {}, ...runtimeLimits, warning: "Gemini CLI model configuration metadata could not be parsed." };
+  }
+
+  const home = stringValue(env.GEMINI_CLI_HOME) ?? stringValue(env.HOME) ?? stringValue(env.USERPROFILE) ?? homedir();
+  const settingsPath = join(home, ".gemini", "settings.json");
+  let userSettings: Record<string, unknown> = {};
+  try {
+    userSettings = asRecord(JSON.parse(await readFile(settingsPath, "utf8"))) ?? {};
+  } catch {
+    // User settings are optional; absence is not a metadata failure.
+  }
+  const modelConfigs = asRecord(userSettings.modelConfigs) ?? {};
+  const aliases = mergeConfig(
+    mergeConfig(defaultAliases, asRecord(modelConfigs.customAliases) ?? {}),
+    asRecord(modelConfigs.aliases) ?? {},
+  );
+  const definitions = mergeConfig(defaultDefinitions, asRecord(modelConfigs.modelDefinitions) ?? {});
+  const overrides = [
+    ...(Array.isArray(defaultOverrides) ? defaultOverrides : []),
+    ...(Array.isArray(modelConfigs.overrides) ? modelConfigs.overrides : []),
+    ...(Array.isArray(modelConfigs.customOverrides) ? modelConfigs.customOverrides : []),
+  ];
+  const levels = await readThinkingLevels(packageRoot);
+  if (levels.length === 0) {
+    return { packageRoot, settingsPath, capabilities: {}, ...runtimeLimits, warning: "Gemini CLI thinking-level metadata was not found." };
+  }
+  return {
+    packageRoot,
+    settingsPath,
+    capabilities: capabilitiesFromMetadata(definitions, aliases, levels, overrides),
+    ...runtimeLimits,
+  };
+}
+
+export async function discoverGeminiModelMetadata(options: GeminiMetadataOptions): Promise<GeminiMetadataResult> {
+  const env = options.env ?? process.env;
+  const key = [
+    options.packageRoot ?? "auto",
+    resolve(options.binary),
+    stringValue(env.GEMINI_CLI_HOME) ?? stringValue(env.HOME) ?? stringValue(env.USERPROFILE) ?? homedir(),
+  ].join("\n");
+  const now = options.now ?? Date.now;
+  const ttlMs = options.ttlMs ?? DEFAULT_METADATA_TTL_MS;
+  const cached = metadataCache.get(key);
+  if (cached && now() - cached.fetchedAt < ttlMs) return cached;
+  const result = await loadMetadata(options);
+  const entry: CachedMetadata = { ...result, fetchedAt: now() };
+  metadataCache.set(key, entry);
+  return entry;
+}
+
+export function mergeGeminiModelDescriptors(
+  advertised: readonly { modelId: string; name?: string; description?: string }[],
+  metadata: GeminiMetadataResult,
+): OcxProviderModel[] {
+  return advertised.map(model => {
+    const capability = metadata.capabilities[model.modelId];
+    const reasoningLevels = capability?.reasoningLevels.map(level => ({
+      effort: level.effort,
+      description: level.description,
+    })) ?? [];
+    return {
+      id: model.modelId,
+      ...(model.name ? { name: model.name } : {}),
+      ...(model.description ? { description: model.description } : {}),
+      supportedReasoningLevels: reasoningLevels,
+      ...(capability?.defaultReasoningLevel ? { defaultReasoningLevel: capability.defaultReasoningLevel } : {}),
+      ...(metadata.tokenLimits[model.modelId] !== undefined
+        ? {
+            contextWindowTokens: metadata.tokenLimits[model.modelId],
+            maxContextWindowTokens: metadata.tokenLimits[model.modelId],
+          }
+        : metadata.defaultTokenLimit !== undefined
+          ? {
+              contextWindowTokens: metadata.defaultTokenLimit,
+              maxContextWindowTokens: metadata.defaultTokenLimit,
+            }
+          : {}),
+      ...(metadata.compressionThreshold !== undefined ? { compressionThreshold: metadata.compressionThreshold } : {}),
+    };
+  });
+}
+
+export function reasoningLevelForEffort(
+  capability: GeminiModelCapability | undefined,
+  effort: string | undefined,
+): GeminiReasoningLevel | undefined {
+  if (!capability?.thinkingSupported || capability.reasoningLevels.length === 0) return undefined;
+  const wanted = effort?.trim().toLowerCase();
+  if (!wanted) {
+    return capability.reasoningLevels.find(level => level.effort === capability.defaultReasoningLevel)
+      ?? capability.reasoningLevels[0];
+  }
+  return capability.reasoningLevels.find(level => level.effort === wanted);
+}

package/src/adapters/cli-agent/gemini/runtime.ts

@@ -0,0 +1,183 @@
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { getConfigDir } from "../../../config";
+import type { AcpInitialize } from "../acp-client";
+
+export interface GeminiModelRuntime {
+  contextSize?: number;
+  usedTokens?: number;
+  promptChars?: number;
+  charsPerToken?: number;
+  observedAt: number;
+}
+
+export interface GeminiRuntime {
+  loadSession: boolean;
+  prompt: {
+    image: boolean;
+    audio: boolean;
+    embeddedContext: boolean;
+  };
+  compressionThreshold?: number;
+  models: Record<string, GeminiModelRuntime>;
+}
+
+const runtimeCache = new Map<string, GeminiRuntime>();
+let loadedFromDisk = false;
+
+function positive(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : undefined;
+}
+
+function nonNegative(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+
+function runtimePath(env: NodeJS.ProcessEnv): string {
+  return join(getConfigDir(env), "gemini", "capabilities.json");
+}
+
+function emptyRuntime(): GeminiRuntime {
+  return {
+    loadSession: false,
+    prompt: { image: false, audio: false, embeddedContext: false },
+    models: {},
+  };
+}
+
+function parseRuntime(value: unknown): GeminiRuntime | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const row = value as Record<string, unknown>;
+  const prompt = row.prompt && typeof row.prompt === "object" && !Array.isArray(row.prompt)
+    ? row.prompt as Record<string, unknown>
+    : {};
+  const models: Record<string, GeminiModelRuntime> = {};
+  if (row.models && typeof row.models === "object" && !Array.isArray(row.models)) {
+    for (const [modelId, raw] of Object.entries(row.models as Record<string, unknown>)) {
+      if (!raw || typeof raw !== "object" || Array.isArray(raw)) continue;
+      const item = raw as Record<string, unknown>;
+      models[modelId] = {
+        ...(positive(item.contextSize) !== undefined ? { contextSize: positive(item.contextSize) } : {}),
+        ...(nonNegative(item.usedTokens) !== undefined ? { usedTokens: nonNegative(item.usedTokens) } : {}),
+        ...(nonNegative(item.promptChars) !== undefined ? { promptChars: nonNegative(item.promptChars) } : {}),
+        ...(positive(item.charsPerToken) !== undefined ? { charsPerToken: positive(item.charsPerToken) } : {}),
+        observedAt: nonNegative(item.observedAt) ?? 0,
+      };
+    }
+  }
+  const threshold = positive(row.compressionThreshold);
+  return {
+    loadSession: row.loadSession === true,
+    prompt: {
+      image: prompt.image === true,
+      audio: prompt.audio === true,
+      embeddedContext: prompt.embeddedContext === true,
+    },
+    ...(threshold !== undefined && threshold <= 1 ? { compressionThreshold: threshold } : {}),
+    models,
+  };
+}
+
+async function readDisk(env: NodeJS.ProcessEnv): Promise<void> {
+  if (loadedFromDisk) return;
+  loadedFromDisk = true;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(await readFile(runtimePath(env), "utf8"));
+  } catch {
+    return;
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return;
+  for (const [fingerprint, value] of Object.entries(parsed as Record<string, unknown>)) {
+    const runtime = parseRuntime(value);
+    if (runtime) runtimeCache.set(fingerprint, runtime);
+  }
+}
+
+async function persist(env: NodeJS.ProcessEnv): Promise<void> {
+  const path = runtimePath(env);
+  await mkdir(join(getConfigDir(env), "gemini"), { recursive: true, mode: 0o700 });
+  const limit = Number(env.OPENCODEX_GEMINI_CAPABILITY_MAX ?? "") || 8;
+  if (runtimeCache.size > limit) {
+    const oldest = [...runtimeCache.entries()]
+      .sort((left, right) => {
+        const leftAt = Math.max(0, ...Object.values(left[1].models).map(model => model.observedAt));
+        const rightAt = Math.max(0, ...Object.values(right[1].models).map(model => model.observedAt));
+        return leftAt - rightAt;
+      });
+    for (const [fingerprint] of oldest.slice(0, Math.max(0, runtimeCache.size - limit))) {
+      runtimeCache.delete(fingerprint);
+    }
+  }
+  const payload = Object.fromEntries(runtimeCache);
+  const temporary = `${path}.${crypto.randomUUID()}.tmp`;
+  await writeFile(temporary, JSON.stringify(payload, null, 2) + "\n", { encoding: "utf8", mode: 0o600 });
+  await rename(temporary, path);
+}
+
+export async function getGeminiRuntime(
+  fingerprint: string,
+  env: NodeJS.ProcessEnv = process.env,
+): Promise<GeminiRuntime> {
+  await readDisk(env);
+  return runtimeCache.get(fingerprint) ?? emptyRuntime();
+}
+
+export async function recordGeminiInitialize(
+  fingerprint: string,
+  initialize: AcpInitialize,
+  env: NodeJS.ProcessEnv = process.env,
+): Promise<void> {
+  await readDisk(env);
+  const current = runtimeCache.get(fingerprint) ?? emptyRuntime();
+  runtimeCache.set(fingerprint, {
+    ...current,
+    loadSession: initialize.capabilities.loadSession,
+    prompt: { ...initialize.capabilities.prompt },
+  });
+  await persist(env).catch(() => undefined);
+}
+
+export async function recordGeminiUsage(
+  fingerprint: string,
+  modelId: string,
+  usedTokens: number,
+  contextSize: number,
+  promptChars: number,
+  env: NodeJS.ProcessEnv = process.env,
+): Promise<void> {
+  if (!positive(contextSize) || !nonNegative(usedTokens) || !nonNegative(promptChars)) return;
+  await readDisk(env);
+  const current = runtimeCache.get(fingerprint) ?? emptyRuntime();
+  const previous = current.models[modelId];
+  const charsPerToken = usedTokens > 0 && promptChars > 0
+    ? promptChars / usedTokens
+    : previous?.charsPerToken;
+  current.models[modelId] = {
+    contextSize,
+    usedTokens,
+    promptChars,
+    ...(charsPerToken !== undefined ? { charsPerToken } : {}),
+    observedAt: Date.now(),
+  };
+  runtimeCache.set(fingerprint, current);
+  await persist(env).catch(() => undefined);
+}
+
+export async function recordGeminiCompressionThreshold(
+  fingerprint: string,
+  threshold: number | undefined,
+  env: NodeJS.ProcessEnv = process.env,
+): Promise<void> {
+  if (threshold === undefined || !positive(threshold) || threshold > 1) return;
+  await readDisk(env);
+  const current = runtimeCache.get(fingerprint) ?? emptyRuntime();
+  current.compressionThreshold = threshold;
+  runtimeCache.set(fingerprint, current);
+  await persist(env).catch(() => undefined);
+}
+
+export function resetGeminiRuntimeCacheForTests(): void {
+  runtimeCache.clear();
+  loadedFromDisk = false;
+}