@bitkyc08/opencodex 2.15.1-preview.20260814 → 2.16.0

package/src/routing/compatibility/lab-evidence-provider.ts

@@ -0,0 +1,130 @@
+/**
+ * Compatibility-evidence provider (Lab-backed).
+ *
+ * Holds every Lab-reaching part of policy candidate evidence: route/protocol subject
+ * construction, the suite catalog snapshot, and the projection read. The core assembler
+ * (`assemble.ts`) keeps capability, health, quota, and cost and consults this only through
+ * the provider slot, so an install that never activates Lab never loads this module.
+ *
+ * This is a relocation of previously inline logic, not a rewrite: `attachCompatibilityEvidence`
+ * below is the original function, and its state arrives entirely through arguments.
+ *
+ * @internal registered by the Lab activation path
+ */
+import type { OcxConfig } from "../../types";
+import type { NormalizedRoutingProfile } from "../profile";
+import {
+  compatibilitySuiteKey,
+  loadCompatibilityCatalogSnapshot,
+  type CompatibilityCatalogSnapshot,
+} from "./catalog";
+import { findVerdictForSuite, loadCompatibilityEvidenceSnapshot } from "./reader";
+import {
+  resolvePolicyCompatibilitySubjects,
+  type ResolvedPolicyCompatibilitySubjects,
+} from "./subject";
+import type { CandidateCompatibilityEvidence } from "./types";
+import type { CoreEvidenceOptions, CompatibilityEvidenceProvider } from "./provider-slot";
+
+/** Lab-side seams, kept off the core options contract. */
+export interface LabCompatibilityProviderOptions extends CoreEvidenceOptions {
+  resolveSubjects?: typeof resolvePolicyCompatibilitySubjects;
+  loadEvidenceSnapshot?: typeof loadCompatibilityEvidenceSnapshot;
+  loadCatalogSnapshot?: typeof loadCompatibilityCatalogSnapshot;
+}
+
+function attachCompatibilityEvidence(
+  resolved: ResolvedPolicyCompatibilitySubjects | undefined,
+  snapshot: ReturnType<typeof loadCompatibilityEvidenceSnapshot>,
+  catalog: CompatibilityCatalogSnapshot,
+  profile: NonNullable<NormalizedRoutingProfile["compatibility"]>,
+): CandidateCompatibilityEvidence {
+  const subjectIds = resolved?.subjectIds ?? {};
+  const suites: CandidateCompatibilityEvidence["suites"] = [];
+
+  for (const requirement of profile.requiredSuites) {
+    const subjectId = subjectIds[requirement.evidenceLayer];
+    if (!subjectId) continue;
+    const metadata = catalog.get(compatibilitySuiteKey(requirement.evidenceLayer, requirement.suiteId));
+    if (!metadata) continue;
+    const row = findVerdictForSuite(
+      snapshot,
+      subjectId,
+      requirement.evidenceLayer,
+      requirement.suiteId,
+      metadata.suiteVersion,
+      metadata.suiteManifestDigest,
+    );
+    if (!row) continue;
+    suites.push({
+      subjectId,
+      suiteId: row.suiteId,
+      evidenceLayer: requirement.evidenceLayer,
+      suiteVersion: row.suiteVersion,
+      suiteManifestDigest: row.suiteManifestDigest,
+      verdict: row.verdict,
+      asOf: row.asOf,
+      maxAgeMs: metadata.maxAgeMs,
+      notes: row.notes,
+    });
+  }
+
+  return {
+    subjectIds: { ...subjectIds },
+    projectionAvailable: snapshot.projectionAvailable,
+    suites,
+  };
+}
+
+/**
+ * Build compatibility evidence for every candidate of one profile.
+ * Keyed `provider/model`; a candidate absent from the map has no compatibility evidence.
+ */
+export const labCompatibilityEvidenceProvider: CompatibilityEvidenceProvider = (
+  config: OcxConfig,
+  profile: NormalizedRoutingProfile,
+  policy: NonNullable<NormalizedRoutingProfile["compatibility"]>,
+  options: CoreEvidenceOptions,
+): Map<string, CandidateCompatibilityEvidence> => {
+  const labOptions = options as LabCompatibilityProviderOptions;
+  const resolveSubjects = labOptions.resolveSubjects ?? resolvePolicyCompatibilitySubjects;
+  const loadCatalog = labOptions.loadCatalogSnapshot ?? loadCompatibilityCatalogSnapshot;
+  const loadEvidence = labOptions.loadEvidenceSnapshot ?? loadCompatibilityEvidenceSnapshot;
+
+  const resolvedByCandidate = new Map<string, ResolvedPolicyCompatibilitySubjects>();
+  const catalog: CompatibilityCatalogSnapshot = loadCatalog(policy.requiredSuites);
+  const subjectIds = new Set<string>();
+
+  for (const candidate of profile.candidates) {
+    const provider = config.providers[candidate.provider];
+    if (!provider) continue;
+    try {
+      const routed = options.routedProviderConfig(candidate.provider, provider);
+      const resolved = resolveSubjects(
+        config,
+        candidate.provider,
+        candidate.model,
+        routed,
+        options.configDir,
+      );
+      resolvedByCandidate.set(`${candidate.provider}/${candidate.model}`, resolved);
+      for (const subjectId of Object.values(resolved.subjectIds)) {
+        if (subjectId) subjectIds.add(subjectId);
+      }
+    } catch {
+      // Subject construction failure is handled per required layer as unknown.
+    }
+  }
+
+  const snapshot = loadEvidence([...subjectIds], options.configDir);
+
+  const byCandidate = new Map<string, CandidateCompatibilityEvidence>();
+  for (const candidate of profile.candidates) {
+    const key = `${candidate.provider}/${candidate.model}`;
+    byCandidate.set(
+      key,
+      attachCompatibilityEvidence(resolvedByCandidate.get(key), snapshot, catalog, policy),
+    );
+  }
+  return byCandidate;
+};

package/src/routing/compatibility/provider-slot.ts

@@ -0,0 +1,56 @@
+/**
+ * Slot for the optional compatibility-evidence provider.
+ *
+ * Routing is synchronous and must stay synchronous: `routeModelInternal` is sync, and so
+ * are the subagent-fallback helpers that call `routeModel` (`isNativeModelQuotaExhausted`,
+ * `isModelHealthBlocked`, `selectAvailableSubagentModel`, ...). Making the chain async to
+ * permit a dynamic import would touch hundreds of call sites and break those APIs, so this
+ * is a plain nullable reference rather than an `await import()`.
+ *
+ * The Lab implementation is installed during activation. Installs without
+ * compatibility-gated routing profiles never register one, so the core evidence assembler
+ * never reaches the Lab module graph.
+ *
+ * See devlog/_plan/260814_lab_core_decoupling/030_router_and_startup_activation.md
+ */
+import type { OcxConfig } from "../../types";
+import type { NormalizedRoutingProfile } from "../profile";
+import type { CandidateCompatibilityEvidence } from "./types";
+
+/** Options the core assembler can supply without knowing anything Lab-specific. */
+export interface CoreEvidenceOptions {
+  configDir?: string;
+  routedProviderConfig: (providerName: string, provider: import("../../types").OcxProviderConfig)
+    => import("../../types").OcxProviderConfig;
+}
+
+/**
+ * Produce compatibility evidence per candidate, keyed `provider/model`.
+ * A candidate absent from the map has no compatibility evidence.
+ */
+export type CompatibilityEvidenceProvider = (
+  config: OcxConfig,
+  profile: NormalizedRoutingProfile,
+  policy: NonNullable<NormalizedRoutingProfile["compatibility"]>,
+  options: CoreEvidenceOptions,
+) => Map<string, CandidateCompatibilityEvidence>;
+
+let provider: CompatibilityEvidenceProvider | null = null;
+
+/** Install the provider. Returns a detach function. */
+export function setCompatibilityEvidenceProvider(next: CompatibilityEvidenceProvider): () => void {
+  provider = next;
+  return () => {
+    if (provider === next) provider = null;
+  };
+}
+
+/** The installed provider, or null when no optional subsystem is active. */
+export function resolveCompatibilityEvidenceProvider(): CompatibilityEvidenceProvider | null {
+  return provider;
+}
+
+/** Test-only reset. */
+export function resetCompatibilityEvidenceProviderForTests(): void {
+  provider = null;
+}

package/src/server/index.ts

@@ -45,12 +45,7 @@ import {
   registerDefaultAppOwnedObservedBuffers,
 } from "../lib/app-owned-memory-stores";
 import { acquireServerBackgroundLifecycle } from "./background-lifecycle";
-import {
-  setLabAutomationDispatchDeps,
-  startLabAutomationScheduler,
-} from "../lab/automation/orchestrator";
-import { loadLabAutomationPolicy } from "../lab/automation/persistence";
-import { createProductionLabRouteExecutor } from "../lib/lab-live-route-production";
+import { activateLab, labActivationRequired } from "../lib/lab-activation";
 import { runOpenAiTierStartupMigration } from "../providers/openai-tier-startup";
 import { runAlibabaRegionStartupMigration } from "../providers/alibaba-region-startup";
 import { runModelRenameStartupMigration } from "../providers/model-rename-startup";
@@ -1735,18 +1730,14 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
   // Opt-in storage policy (default OFF). Never blocks listen; cancellable on shutdown.
   backgroundLifecycle.scheduleStartupRun();
 
+  // Compatibility Lab is optional: wire it only for installs that actually use it -- any
+  // routing profile, or automation enabled on disk. This runs synchronously before
+  // startServer returns, in the same turn as Bun.serve, so a policy route can never be
+  // evaluated before its evidence provider is registered. That ordering is load-bearing:
+  // the subagent-fallback chain routes synchronously and has nowhere to await.
   const labConfigDir = getConfigDir();
-  const productionLabRouteExecutor = createProductionLabRouteExecutor({
-    configDir: labConfigDir,
-    loadConfig: () => config,
-  });
-  setLabAutomationDispatchDeps({
-    configDir: labConfigDir,
-    loadConfig: () => config,
-    routeExecutor: productionLabRouteExecutor,
-  });
-  if (loadLabAutomationPolicy(labConfigDir).enabled) {
-    startLabAutomationScheduler(labConfigDir);
+  if (labActivationRequired(config, labConfigDir)) {
+    activateLab(config, labConfigDir);
   }
 
   return server;

package/src/server/lifecycle.ts

@@ -7,7 +7,7 @@ import {
 } from "../storage/policy-job";
 import { abortRestoreTrashJobAsync } from "../storage/restore-job";
 import { stopStorageCleanupScheduler } from "../storage/policy-scheduler";
-import { stopLabAutomationScheduler, requestLabAutomationShutdown } from "../lab/automation/orchestrator";
+import { runOptionalShutdownHooks } from "../lib/optional-shutdown-hooks";
 import { stopStateStoreSweeper } from "../lib/state-store-sweeper";
 import {
   cancelQueuedStorageWorkerSpawns,
@@ -452,8 +452,10 @@ export async function drainAndShutdown(
     // Abort each job independently so one wedged join cannot skip the other,
     // then drain leftovers; failures must not prevent `server.stop`.
     stopStorageCleanupScheduler();
-    requestLabAutomationShutdown();
-    stopLabAutomationScheduler();
+    // Optional subsystems (Compatibility Lab today, anything added later) tear themselves
+    // down through hooks registered at activation. A process that never activated one runs
+    // nothing here and never loads its module graph.
+    runOptionalShutdownHooks();
     stopStateStoreSweeper();
     // The overlay reconciler is owner-scoped: the startServer stop override
     // releases THIS server's lease through runListenerShutdown →

package/src/server/management/routing-profile-routes.ts

@@ -17,9 +17,10 @@ import {
 } from "../../routing/profile";
 import { evaluatePolicyProfile, type PolicyCandidateEvidence, type PolicyRequestEvidence } from "../../routing/evaluator";
 import { assemblePolicyCandidateEvidence } from "../../routing/compatibility/assemble";
+import { activateLab, labActivationRequired } from "../../lib/lab-activation";
 import { quotaEvidenceForCandidate } from "../../routing/quota";
 import { routedProviderConfig } from "../../router";
-import { saveConfigPreservingClaudeCode } from "../../config";
+import { saveConfigPreservingClaudeCode, getConfigDir } from "../../config";
 import { reconcileLiveStateStores } from "../../lib/state-store-registrations";
 import { isPlainRecord } from "./shared";
 import { readManagementJsonBody, rethrowManagementBodyTooLarge } from "./body";
@@ -289,6 +290,9 @@ export async function handleRoutingProfileRoutes(ctx: ManagementContext): Promis
     const nextProfiles = { ...(config.routingProfiles ?? {}) };
     nextProfiles[id] = storedProfile(id, body.profile as OcxRoutingProfileConfig);
     config.routingProfiles = nextProfiles;
+    // Creating the first profile on a process started profile-less must install the
+    // compatibility provider now; activation is synchronous and idempotent per configDir.
+    if (labActivationRequired(config, getConfigDir())) activateLab(config, getConfigDir());
     // An alias change on update renames the public model id; rewrite config
     // references (disabledModels, subagentModels, injectionModel,
     // shadowCallIntercept, claudeCode) so they follow the new alias.
@@ -358,6 +362,10 @@ export async function handleRoutingProfileRoutes(ctx: ManagementContext): Promis
     // One clock read for both assembly and evaluation keeps freshness, health,
     // and trace timestamps mutually consistent with the production router.
     const now = Date.now();
+    // R3-1: dry-run assembles candidate evidence independently of the startup gate, so an
+    // operator preview on a process started without profiles would silently omit
+    // compatibility evidence and disagree with production. Activate first.
+    if (labActivationRequired(config, getConfigDir())) activateLab(config, getConfigDir());
     const candidateEvidence = body.candidates === undefined
       ? assembleCandidateEvidence(config, resolvedProfile, now)
       : parseCandidateEvidence(body.candidates);

package/src/server/management-api.ts

@@ -61,15 +61,12 @@ import { handleConfigRoutes } from "./management/config-routes";
 import { handleLogsUsageRoutes } from "./management/logs-usage-routes";
 import { handleRequestHistoryRoutes } from "./management/request-history-routes";
 import { handleRoutingAnalyticsRoutes } from "./management/routing-analytics-routes";
-import { handleRoutingProfileRoutes } from "./management/routing-profile-routes";
 import { handleProviderRoutes } from "./management/provider-routes";
 import { handleModelRoutes } from "./management/model-routes";
 import { handleAgentSettingsRoutes } from "./management/agent-settings-routes";
 import { handleOauthAccountRoutes } from "./management/oauth-account-routes";
 import { handleComboRoutes } from "./management/combo-routes";
 import { handleSystemRoutes } from "./management/system-routes";
-import { handleLabRoutes } from "./management/lab-routes";
-import { handleLabAutomationRoutes } from "./management/lab-automation-routes";
 import { handleSidebarRoutes } from "./management/sidebar-routes";
 import { handleIntegrationRoutes } from "./management/integration-routes";
 import { handleNativeIntegrationRoutes } from "./management/native-integration-routes";
@@ -96,6 +93,41 @@ const managementConvergenceBindings = new WeakMap<object, Readonly<{
   converge: ConvergeCodex;
 }>>();
 
+/**
+ * Namespace match for management route prefixes: exact hit or a child path, never a
+ * prefix collision (`/api/labfoo` must not match `/api/lab`).
+ */
+function pathInManagementNamespace(pathname: string, prefix: string): boolean {
+  return pathname === prefix || pathname.startsWith(`${prefix}/`);
+}
+
+/**
+ * Routing-profile and Compatibility Lab handlers statically import the Lab module graph,
+ * so mounting them eagerly would pull ~70 `src/lab/` modules into every management
+ * request -- including installs that never opted into Lab. Loading them per namespace
+ * keeps `management-api.ts` on the same footing as the three protected core files.
+ *
+ * Cherry-picked from @Wibias's PR #1676, which solved this before the boundary work
+ * reached it. See devlog/_plan/260814_lab_core_decoupling/.
+ */
+async function handleRoutingProfileRoutesOnDemand(ctx: ManagementContext): Promise<Response | null> {
+  if (!pathInManagementNamespace(ctx.url.pathname, "/api/routing-profiles")) return null;
+  const { handleRoutingProfileRoutes } = await import("./management/routing-profile-routes");
+  return handleRoutingProfileRoutes(ctx);
+}
+
+async function handleLabRoutesOnDemand(ctx: ManagementContext): Promise<Response | null> {
+  if (!pathInManagementNamespace(ctx.url.pathname, "/api/lab")) return null;
+  // Automation is checked first so its narrower namespace keeps its own handler, matching
+  // the eager chain's ordering.
+  if (pathInManagementNamespace(ctx.url.pathname, "/api/lab/automation")) {
+    const { handleLabAutomationRoutes } = await import("./management/lab-automation-routes");
+    return handleLabAutomationRoutes(ctx);
+  }
+  const { handleLabRoutes } = await import("./management/lab-routes");
+  return handleLabRoutes(ctx);
+}
+
 export async function handleManagementAPI(
   req: Request,
   url: URL,
@@ -180,7 +212,7 @@ export async function handleManagementAPI(
     ??     (await handleLogsUsageRoutes(ctx))
     ??     (await handleRequestHistoryRoutes(ctx))
     ??     (await handleRoutingAnalyticsRoutes(ctx))
-    ??     (await handleRoutingProfileRoutes(ctx))
+    ??     (await handleRoutingProfileRoutesOnDemand(ctx))
     ??     (await handleProviderRoutes(ctx))
     ??     (await handleModelRoutes(ctx))
     ??     (await handleIntegrationRoutes(ctx))
@@ -189,8 +221,7 @@ export async function handleManagementAPI(
     ??     (await handleOauthAccountRoutes(ctx))
     ??     (await handleComboRoutes(ctx))
     ??     (await handleSystemRoutes(ctx))
-    ??     (await handleLabAutomationRoutes(ctx))
-    ??     (await handleLabRoutes(ctx))
+    ??     (await handleLabRoutesOnDemand(ctx))
       ?? (await handleSidebarRoutes(ctx));
   } catch (error) {
     const tooLarge = managementBodyTooLargeResponse(error, req, config);

package/src/server/passive-route-linker.ts

@@ -0,0 +1,66 @@
+/**
+ * Optional per-attempt route-identity linker.
+ *
+ * Compatibility Lab attaches an opaque route-subject digest to request attempts so its
+ * passive-production surface (CL-09) can correlate them later. That is an opt-in
+ * subsystem, so the core request path holds only a slot: null on installs that never
+ * activate Lab, which is every install without a routing profile.
+ *
+ * Contract for any registered implementation: synchronous, free of side effects with
+ * respect to the request, and non-throwing. The upstream request must never be delayed,
+ * retried, or altered by identity linkage. The try/catch lives here rather than at the
+ * call site so the guarantee belongs to the mechanism instead of being restated by every
+ * caller.
+ *
+ * See devlog/_plan/260814_lab_core_decoupling/020_request_path_gate.md
+ */
+import type { OcxConfig, OcxProviderConfig } from "../types";
+import type { InboundWire } from "../providers/registry";
+
+export type PassiveRouteLinker = (
+  config: OcxConfig,
+  providerName: string,
+  modelId: string,
+  routed: OcxProviderConfig,
+  inboundWire: InboundWire,
+) => string | null;
+
+let linker: PassiveRouteLinker | null = null;
+
+/** Install the linker. Returns a detach function. */
+export function setPassiveRouteLinker(next: PassiveRouteLinker): () => void {
+  linker = next;
+  return () => {
+    // Only detach our own registration: a later activation may have replaced it.
+    if (linker === next) linker = null;
+  };
+}
+
+/**
+ * Resolve the attempt identity, or null when no subsystem is active.
+ * Never throws: linkage is best-effort metadata and must not affect the request.
+ */
+export function resolvePassiveRouteSubjectId(
+  config: OcxConfig,
+  providerName: string,
+  modelId: string,
+  routed: OcxProviderConfig,
+  inboundWire: InboundWire,
+): string | null {
+  if (!linker) return null;
+  try {
+    return linker(config, providerName, modelId, routed, inboundWire);
+  } catch {
+    return null;
+  }
+}
+
+/** True when an optional subsystem has installed a linker. Test/diagnostic use. */
+export function hasPassiveRouteLinker(): boolean {
+  return linker !== null;
+}
+
+/** Test-only reset. */
+export function resetPassiveRouteLinkerForTests(): void {
+  linker = null;
+}

package/src/server/responses/core.ts

@@ -33,7 +33,7 @@ import {
   type RouteResult,
 } from "../../router";
 import { evidenceFromBody } from "../../routing/request-evidence";
-import { resolveProductionRouteSubject } from "../../routing/compatibility/subject";
+import { resolvePassiveRouteSubjectId } from "../passive-route-linker";
 import {
   advanceComboAfterFailure,
   comboDefaultEffort,
@@ -228,7 +228,7 @@ import {
   payloadRewriteAsBlockRewrite,
   relaySseWithBlockRewrite,
 } from "../sse-payload-rewrite";
-import { collectRoutedCustomToolNames, restoreRoutedCustomCallsInJson } from "../../responses/custom-tool-compat";
+import { restoreRoutedCustomCallsInJson } from "../../responses/custom-tool-compat";
 import { createRoutedCustomToolRestoreBlockRewrite } from "../responses-custom-tool-repair";
 import { createGithubCopilotResponsesBlockRewrite } from "../github-copilot-responses-repair";
 import { responsesJsonToSseStream } from "../responses-json-events";
@@ -1991,22 +1991,19 @@ async function handleResponsesInner(
     (logCtx.attempts ??= []).push(attempt);
   }
   sealRequestAttemptIdentity(logCtx.activeAttempt, logCtx.provider, adapter.name, logCtx.accountLogLabel);
-  // CL-09: attach only the opaque exact route-subject identity to the attempt.
-  // This is best-effort passive metadata: no Lab state is created and failure
-  // must never alter, retry, or delay the upstream request.
+  // Optional route-identity linkage for attempt correlation (CL-09 consumes it). The slot
+  // resolves to null unless an opt-in subsystem registered a linker, so an install without
+  // routing profiles does no work here and loads no additional module. The non-throwing
+  // guarantee lives in the slot helper.
   if (logCtx.activeAttempt && !logCtx.activeAttempt.labRouteSubjectId) {
-    try {
-      const passiveSubject = resolveProductionRouteSubject(
-        config,
-        route.providerName,
-        route.modelId,
-        route.provider,
-        inboundWire,
-      );
-      if (passiveSubject) logCtx.activeAttempt.labRouteSubjectId = passiveSubject.subjectId;
-    } catch {
-      // Omit passive linkage when exact subject construction is unavailable.
-    }
+    const passiveSubjectId = resolvePassiveRouteSubjectId(
+      config,
+      route.providerName,
+      route.modelId,
+      route.provider,
+      inboundWire,
+    );
+    if (passiveSubjectId) logCtx.activeAttempt.labRouteSubjectId = passiveSubjectId;
   }
   const isPassthrough = "passthrough" in adapter && !!adapter.passthrough;
 
@@ -2130,9 +2127,7 @@ async function handleResponsesInner(
     const imageGenCallAliases = route.provider.authMode === "forward"
       ? new Map<string, { namespace: string; name: string }>()
       : imageGenToolCallAliases(toolBridgeMaps.toolNsMap, parsed._rawBody, translatorBudget);
-    const routedCustomToolNames = route.provider.authMode === "forward"
-      ? new Set<string>()
-      : collectRoutedCustomToolNames(parsed._rawBody);
+    const routedCustomToolNames = new Set<string>();
     // Local continuation cache for the ChatGPT passthrough. Codex WS turns chain with
     // previous_response_id, ocx converts them to internal HTTP requests, and the ChatGPT Codex
     // REST backend rejects the parameter — the adapter strips it in forward mode, so the ONLY
@@ -2161,6 +2156,11 @@ async function handleResponsesInner(
       releaseCodexAuthContextProbeLease(authCtx);
       throw error;
     }
+    if (route.provider.authMode !== "forward") {
+      for (const name of request.convertedRoutedCustomToolNames ?? []) {
+        if (toolBridgeMaps.freeformToolNames.has(name)) routedCustomToolNames.add(name);
+      }
+    }
     recordAdapterReasoning(logCtx, request);
     const actualHostKey = upstreamHostHealthKey(
       route.providerName,

package/src/types.ts

@@ -1450,6 +1450,16 @@ export interface OcxProviderConfig {
    * only on explicit `true`. See devlog/_plan/260709_parallel_tool_calls.
    */
   parallelToolCalls?: boolean;
+  /**
+   * Opt-in: when `parallelToolCalls` is `false`, actually send `parallel_tool_calls: false`
+   * on the `/chat/completions` wire for this provider. By default an opted-out provider only
+   * OMITS the field (strict OpenAI-compatible hosts reject unknown knobs), and the NVIDIA NIM
+   * baseUrl is the sole built-in exception that pins the wire bit. Some self-hosted gateways
+   * (Kimi/GLM-family, vLLM, etc.) do honor `parallel_tool_calls` and keep emitting concurrent
+   * tool calls unless it is present; enable this to pin the bit without hardcoding their URL.
+   * No effect unless `parallelToolCalls === false`; ignored by non-`openai-chat` adapters.
+   */
+  pinParallelToolCallsFalse?: boolean;
   /**
    * Opt-in: forward `prompt_cache_key` to the upstream `/chat/completions` body.
    * OpenAI-specific extension; strict backends (Groq, Cerebras, etc.) reject unknown

package/src/usage/expected-prices.ts

@@ -52,6 +52,10 @@ const DAYBREAK_RED: Cost4 = { input: 12.5, output: 75, cacheRead: 1.25, cacheWri
 const GPT56_TERRA: Cost4 = { input: 2, output: 12, cacheRead: 0.2, cacheWrite: 2.5 };
 const GPT56_LUNA: Cost4 = { input: 0.2, output: 1.2, cacheRead: 0.02, cacheWrite: 0.25 };
 const GEMINI_36_FLASH: Cost4 = { input: 1.5, output: 7.5, cacheRead: 0.15, cacheWrite: 0 };
+// Gemini 3.7 Flash launch promotion: Google publishes $0.75 in / $3.75 out per 1M
+// through 2026-12-31, stepping up to $1.50 / $7.50 on 2027-01-01. Revisit this row
+// then — the promotional rate is dated on the pricing page, not open-ended.
+const GEMINI_37_FLASH: Cost4 = { input: 0.75, output: 3.75, cacheRead: 0.075, cacheWrite: 0 };
 const MINIMAX_M21_HIGHSPEED: Cost4 = { input: 0.6, output: 2.4, cacheRead: 0.03, cacheWrite: 0.375 };
 const KIMI_K3: Cost4 = { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3 };
 const KIMI_K27_CODE: Cost4 = { input: 0.95, output: 4, cacheRead: 0.19, cacheWrite: 0.95 };
@@ -70,6 +74,7 @@ const CLAUDE_OPUS_5_DERIVED_SOURCE =
 const ANTHROPIC_PRICING = "https://platform.claude.com/docs/en/about-claude/pricing (official; 5m cache-write tier)";
 
 const GEMINI_PRICING = "https://ai.google.dev/gemini-api/docs/pricing (2026-07-22); cacheWrite=0: storage is billed per-hour, not per-token";
+const GEMINI_37_PRICING = "https://ai.google.dev/gemini-api/docs/pricing (2026-08-14); promotional rate through 2026-12-31, rises to 1.50/7.50 on 2027-01-01; cacheWrite=0: storage is billed per-hour, not per-token";
 const MINIMAX_PRICING = "https://platform.minimax.io/docs/guides/pricing-paygo";
 const OPENAI_GPT56_PRICING = "https://developers.openai.com/api/docs/pricing";
 const DEEPSEEK_PRICING = "https://api-docs.deepseek.com/quick_start/pricing-details-usd; V4 Flash alias transition scheduled 2026-07-24 — re-verify after";
@@ -102,6 +107,12 @@ export const EXPECTED_PRICE_OVERLAYS: readonly ExpectedPriceOverlay[] = [
   // Google Antigravity effort-suffix variants — derived from the verified base-model
   // price (Google does not publish per-suffix prices; Agent inference bills at the
   // base model's standard rate per the official Billing FAQ).
+  // 3.7 Flash rides CCA, whose billing equivalence to the Developer API list price is
+  // not published, so this is `verified-derived` rather than `verified`: the number is
+  // proven, the claim that Antigravity charges it is inferred.
+  { provider: "google-antigravity", modelId: "gemini-3.7-flash", cost4: GEMINI_37_FLASH, source: `derived: Gemini 3.7 Flash promotional rate through 2026-12-31 ${GEMINI_37_PRICING}`, verifiedAt: "2026-08-14", status: "verified-derived" },
+  // Retained after the 3.6 retirement: historical usage.jsonl rows still carry these
+  // ids, and dropping the row would silently zero the cost of requests already made.
   { provider: "google-antigravity", modelId: "gemini-3.6-flash", cost4: GEMINI_36_FLASH, source: `collapsed base ID ${GEMINI_PRICING}`, verifiedAt: "2026-07-22", status: "verified" },
   { provider: "google-antigravity", modelId: "gemini-3.1-pro", cost4: GEMINI_31_PRO, source: `collapsed base ID ${GEMINI_PRICING}`, verifiedAt: "2026-07-22", status: "verified" },
   // OpenAI GPT-5.6 `-pro` virtual selections. The virtual resolver keeps the SELECTED id in
@@ -130,6 +141,8 @@ export const EXPECTED_PRICE_OVERLAYS: readonly ExpectedPriceOverlay[] = [
   { provider: "google-antigravity", modelId: "gemini-3-flash-agent", cost4: GEMINI_36_FLASH, source: `compat alias -> gemini-3.6-flash-high ${GEMINI_PRICING}`, verifiedAt: "2026-07-22", status: "verified-derived" },
   // Direct Google Gemini API current model (verified — published table).
   { provider: "google", modelId: "gemini-3.6-flash", cost4: GEMINI_36_FLASH, source: GEMINI_PRICING, verifiedAt: "2026-07-22", status: "verified" },
+  // Developer API row: the price IS published for this surface, so `verified`.
+  { provider: "google", modelId: "gemini-3.7-flash", cost4: GEMINI_37_FLASH, source: GEMINI_37_PRICING, verifiedAt: "2026-08-14", status: "verified" },
   { provider: "google-antigravity", modelId: "gemini-3.1-pro-preview", cost4: GEMINI_31_PRO, source: GEMINI_PRICING, verifiedAt: "2026-07-20", status: "verified" },
   // Antigravity-bundled third-party models — derived from the underlying vendor's
   // official API price (Antigravity itself bills via subscription quota).