savant-code 0.0.16 → 0.0.19

package/common/src/constants/savant-free-models.ts

@@ -0,0 +1,855 @@
+import {
+  atlasCloudModels,
+  mimoModels,
+  minimaxModels,
+  moonshotModels,
+  openrouterModels,
+} from './model-config'
+import {
+  addDaysToYmd,
+  getUtcForZonedTime,
+  getZonedParts,
+} from '../util/zoned-time'
+
+/**
+ * Models a savant-free user can pick between in the waiting-room model selector.
+ *
+ * Each model has its own queue (server keys queue position by `model`), so the
+ * list here is effectively the set of separate waiting lines. Order is the
+ * order shown in the UI.
+ */
+export interface SavantFreeModel {
+  /** Stable ID used in the wire protocol and DB. Matches the model id passed
+   *  to the chat-completions endpoint. */
+  id: string
+  /** Short label for the selector UI. */
+  displayName: string
+  /** One-line description shown next to the label. */
+  tagline: string
+  /** Availability policy for the selector and server-side admission. */
+  availability: 'always' | 'deployment_hours'
+  /** Optional caveat shown in the picker (e.g. data-collection warning).
+   *  Rendered in the warning/secondary color so users spot it before
+   *  picking the model. */
+  warning?: string
+  /** Premium models carry a per-day usage limit
+   *  (SAVANT_FREE_PREMIUM_SESSION_LIMIT). Surfaced in the UI as a "Premium"
+   *  badge with the limit. Derived from SAVANT_FREE_PREMIUM_MODEL_IDS so the two
+   *  never drift. */
+  premium: boolean
+  /** Whether the model accepts image input. Drives whether uploaded images
+   *  are forwarded as real multimodal content vs. dropped/inlined as text. */
+  multimodal: boolean
+  /** Whether the model is still being trialed and may be unreliable. Surfaced
+   *  in the picker as a "TEST" badge with a tooltip so users know it is not
+   *  yet production-grade. */
+  experimental?: boolean
+}
+
+/** Server-facing fallback copy for APIs and provider errors that can't know
+ *  the caller's local timezone. The CLI should render
+ *  `getSavantFreeDeploymentAvailabilityLabel()` instead. */
+export const SAVANT_FREE_DEPLOYMENT_HOURS_LABEL = '9am ET-5pm PT every day'
+export const SAVANT_FREE_GEMINI_PRO_MODEL_ID = 'google/gemini-3.1-pro-preview'
+export const SAVANT_FREE_DEEPSEEK_V4_PRO_MODEL_ID = 'deepseek/deepseek-v4-pro'
+export const SAVANT_FREE_DEEPSEEK_V4_FLASH_MODEL_ID =
+  'deepseek/deepseek-v4-flash'
+/** DeepSeek V4 Flash served by Fireworks instead of DeepSeek's direct API.
+ *  Used only by savant-free.com/chat, where Fireworks' faster inference is worth
+ *  a slightly less capable serving stack. Not in SUPPORTED_SAVANT_FREE_MODELS or
+ *  the free-mode allowlists — the CLI and web builder keep DeepSeek direct. */
+export const SAVANT_FREE_DEEPSEEK_V4_FLASH_FIREWORKS_MODEL_ID =
+  'fireworks/deepseek-v4-flash'
+export const SAVANT_FREE_KIMI_MODEL_ID = moonshotModels.kimiK27Code
+export const SAVANT_FREE_HY3_OPENROUTER_FREE_MODEL_ID =
+  openrouterModels.openrouter_tencent_hy3_free
+export const SAVANT_FREE_HY3_OPENROUTER_PAID_MODEL_ID =
+  openrouterModels.openrouter_tencent_hy3
+export const SAVANT_FREE_HY3_ATLAS_MODEL_ID = atlasCloudModels.tencentHy3
+export const SAVANT_FREE_HY3_MODEL_ID = SAVANT_FREE_HY3_OPENROUTER_FREE_MODEL_ID
+export const SAVANT_FREE_MINIMAX_M3_MODEL_ID = minimaxModels.minimaxM3
+export const SAVANT_FREE_MIMO_V25_MODEL_ID = mimoModels.mimoV25
+export const SAVANT_FREE_MIMO_V25_PRO_MODEL_ID = mimoModels.mimoV25Pro
+/** GLM 5.2 (Z.ai), served by Fireworks serverless. Unlike the other picker
+ *  models it is NOT freely available — it is unlocked by referring friends.
+ *  Each qualified referral grants one 1-hour GLM session per week (capped at
+ *  SAVANT_FREE_GLM_V52_REFERRAL_CAP). Gated by a per-user weekly session pool whose
+ *  limit equals the caller's GLM referral score (see the free-session quota). */
+export const SAVANT_FREE_GLM_V52_MODEL_ID = 'z-ai/glm-5.2'
+/** UI-only rollout switch. Backend support and free-mode allowlists remain
+ *  wired even when these models are hidden from the SavantFree picker. */
+export const SAVANT_FREE_ENABLE_MIMO_MODELS_IN_UI = true
+/** UI-only rollout switch for the streak indicator in the waiting room. */
+export const SAVANT_FREE_ENABLE_STREAK_IN_UI = true
+/** Local/debug switch: force the localhost free-mode country bypass into
+ *  limited access so the limited SavantFree UX can be exercised without an env
+ *  var. */
+export const SAVANT_FREE_FORCE_LIMITED_MODE = false
+export const SAVANT_FREE_PREMIUM_SESSION_LIMIT = 5
+export const SAVANT_FREE_LIMITED_SESSION_LIMIT = 5
+export const SAVANT_FREE_PREMIUM_SESSION_RESET_TIMEZONE = 'America/Los_Angeles'
+export const SAVANT_FREE_PREMIUM_SESSION_PERIOD = 'pacific_day'
+/** GLM 5.2 referral-reward session pool. Distinct from the premium daily pool:
+ *  GLM sessions reset weekly (Pacific) and the per-user limit is the caller's
+ *  GLM referral score, capped at SAVANT_FREE_GLM_V52_REFERRAL_CAP. */
+export const SAVANT_FREE_WEEKLY_SESSION_PERIOD = 'pacific_week'
+export const SAVANT_FREE_GLM_V52_SESSION_RESET_TIMEZONE =
+  SAVANT_FREE_PREMIUM_SESSION_RESET_TIMEZONE
+export const SAVANT_FREE_GLM_V52_SESSION_WINDOW_HOURS = 24 * 7
+/** Max number of qualified referrals that count toward GLM sessions, i.e. the
+ *  most 1-hour GLM sessions a user can earn per week. */
+export const SAVANT_FREE_GLM_V52_REFERRAL_CAP = 10
+/** Master kill-switch for the GLM 5.2 referral program. While true, qualified
+ *  referrals grant weekly GLM sessions and the CLI advertises the perk. Flip to
+ *  false to wind the program down: entitlement drops to 0 for everyone and the
+ *  CLI stops showing the banner. The perk is intentionally framed as
+ *  limited-time in the UI so turning this off isn't a surprise. */
+export const SAVANT_FREE_GLM_V52_REFERRAL_ENABLED = true
+/** GLM sessions are exactly one hour of wall-clock time, regardless of the
+ *  global free-session length, so the "1 hour per referral per week" promise is
+ *  exact. */
+export const SAVANT_FREE_GLM_V52_SESSION_LENGTH_MS = 60 * 60 * 1000
+export const SAVANT_FREE_LIMITED_SESSION_RESET_TIMEZONE =
+  SAVANT_FREE_PREMIUM_SESSION_RESET_TIMEZONE
+export const SAVANT_FREE_LIMITED_SESSION_PERIOD =
+  SAVANT_FREE_PREMIUM_SESSION_PERIOD
+
+/**
+ * Streak rewards. Once a user reaches a `SAVANT_FREE_STREAK_REWARD_INTERVAL_DAYS`
+ * (7)-day daily streak, they earn:
+ *   - +1 session in their primary daily pool (premium for full-access users,
+ *     limited for limited-access) **every day** the streak stays at 7+; and
+ *   - for full-access users, +1 GLM 5.2 session **each week**, granted on the
+ *     exact 7/14/21… milestone days, on top of any referral entitlement.
+ *
+ * The bonus is implemented by raising the relevant pool's effective session
+ * limit for the period the reward lands in: the daily premium/limited bonus
+ * raises today's cap (re-granted each day the streak holds), and the weekly GLM
+ * bonus raises that Pacific week's cap. Milestones are 7 days apart and the GLM
+ * pool is a Pacific week, so GLM stays exactly one bonus per week — matching the
+ * "+1 GLM session per week" promise.
+ */
+export const SAVANT_FREE_STREAK_REWARD_INTERVAL_DAYS = 7
+/** Master kill-switch for streak rewards. When false, streaks grant nothing
+ *  and effective limits fall back to the base pool limits. */
+export const SAVANT_FREE_STREAK_REWARDS_ENABLED = true
+/** Sub-switch for the full-access GLM 5.2 portion of the streak reward. Lets the
+ *  GLM perk be wound down independently of the premium/limited bonus (and of the
+ *  separate referral-driven GLM program). */
+export const SAVANT_FREE_STREAK_GLM_BONUS_ENABLED = true
+/** Session-units granted per streak-reward grant, per pool. One whole session. */
+export const SAVANT_FREE_STREAK_BONUS_SESSION_UNITS = 1
+
+/** Which session pool a streak bonus credit applies to. `premium` and `limited`
+ *  are the daily pools (full vs limited access); `glm` is the weekly GLM 5.2
+ *  pool (full access only). */
+export type SavantFreeStreakPool = 'premium' | 'limited' | 'glm'
+/** Deprecated wire compatibility field. Session usage now resets at midnight
+ *  Pacific time rather than using a rolling hourly window. */
+export const SAVANT_FREE_PREMIUM_SESSION_WINDOW_HOURS = 24
+export const SAVANT_FREE_LIMITED_SESSION_WINDOW_HOURS =
+  SAVANT_FREE_PREMIUM_SESSION_WINDOW_HOURS
+const SAVANT_FREE_EASTERN_TIMEZONE = 'America/New_York'
+const SAVANT_FREE_PACIFIC_TIMEZONE = 'America/Los_Angeles'
+
+interface LocalTimeFormatOptions {
+  locale?: string
+  timeZone?: string
+}
+
+/** Full-access savant-free models that benefit from spawning the gemini-thinker
+ *  subagent for deeper reasoning. Covers every full-access picker model except
+ *  the two limited-tier ones (DeepSeek V4 Flash, MiMo 2.5). Used by the CLI to
+ *  toggle the gemini-thinker spawnable + prompts based on the user's pick, and
+ *  by the server to admit gemini-thinker child requests against a parent
+ *  session bound to one of these models. */
+export const SAVANT_FREE_GEMINI_THINKER_PARENT_MODELS = new Set<string>([
+  SAVANT_FREE_KIMI_MODEL_ID,
+  SAVANT_FREE_DEEPSEEK_V4_PRO_MODEL_ID,
+  SAVANT_FREE_MIMO_V25_PRO_MODEL_ID,
+  SAVANT_FREE_MINIMAX_M3_MODEL_ID,
+])
+
+export function canSavantFreeModelSpawnGeminiThinker(modelId: string): boolean {
+  return SAVANT_FREE_GEMINI_THINKER_PARENT_MODELS.has(modelId)
+}
+
+/** Single source of truth for "this model collects data for training". A model
+ *  that carries this exact `warning` is both shown the caveat in the picker AND
+ *  has its chat-completion traces stored in free mode (see
+ *  SAVANT_FREE_TRACED_MODEL_IDS, which is derived from it) — the two can't drift. */
+export const SAVANT_FREE_DATA_COLLECTION_WARNING = 'Collects data for training'
+
+const DEEPSEEK_V4_PRO_MODEL = {
+  id: SAVANT_FREE_DEEPSEEK_V4_PRO_MODEL_ID,
+  displayName: 'DeepSeek V4 Pro',
+  tagline: 'Smartest',
+  availability: 'always',
+  warning: SAVANT_FREE_DATA_COLLECTION_WARNING,
+  premium: true,
+  multimodal: false,
+} as const satisfies SavantFreeModel
+
+const MIMO_V25_PRO_MODEL = {
+  id: SAVANT_FREE_MIMO_V25_PRO_MODEL_ID,
+  displayName: 'MiMo 2.5 Pro',
+  tagline: 'Smartest & Slow',
+  availability: 'always',
+  premium: true,
+  multimodal: true,
+} as const satisfies SavantFreeModel
+
+const KIMI_MODEL = {
+  id: SAVANT_FREE_KIMI_MODEL_ID,
+  displayName: 'Kimi K2.7 Code',
+  tagline: 'Best for coding',
+  availability: 'always',
+  premium: true,
+  multimodal: true,
+} as const satisfies SavantFreeModel
+
+const HY3_MODEL = {
+  id: SAVANT_FREE_HY3_MODEL_ID,
+  displayName: 'HY3',
+  tagline: 'Trialing its performance',
+  availability: 'always',
+  premium: true,
+  multimodal: false,
+  experimental: true,
+} as const satisfies SavantFreeModel
+
+const HY3_ATLAS_MODEL = {
+  id: SAVANT_FREE_HY3_ATLAS_MODEL_ID,
+  displayName: 'HY3 Atlas',
+  tagline: 'Direct via Atlas Cloud',
+  availability: 'always',
+  premium: true,
+  multimodal: false,
+  experimental: true,
+} as const satisfies SavantFreeModel
+
+const MIMO_V25_MODEL = {
+  id: SAVANT_FREE_MIMO_V25_MODEL_ID,
+  displayName: 'MiMo 2.5',
+  tagline: 'Multimodal',
+  availability: 'always',
+  premium: false,
+  multimodal: true,
+} as const satisfies SavantFreeModel
+
+const DEEPSEEK_V4_FLASH_MODEL = {
+  id: SAVANT_FREE_DEEPSEEK_V4_FLASH_MODEL_ID,
+  displayName: 'DeepSeek V4 Flash',
+  tagline: 'Smart & Fast',
+  availability: 'always',
+  warning: SAVANT_FREE_DATA_COLLECTION_WARNING,
+  premium: false,
+  multimodal: false,
+} as const satisfies SavantFreeModel
+
+const MINIMAX_M3_MODEL = {
+  id: SAVANT_FREE_MINIMAX_M3_MODEL_ID,
+  displayName: 'MiniMax M3',
+  tagline: 'Smartest & Fastest',
+  availability: 'always',
+  // No data-collection warning: M3 is served by Fireworks (no provider-side
+  // training). Omitting the warning also keeps it out of SAVANT_FREE_TRACED_MODEL_IDS,
+  // so we don't store its traces either.
+  premium: false,
+  multimodal: true,
+} as const satisfies SavantFreeModel
+
+const GLM_V52_MODEL = {
+  id: SAVANT_FREE_GLM_V52_MODEL_ID,
+  displayName: 'GLM 5.2',
+  tagline: 'Unlock by referring friends',
+  availability: 'always',
+  // No data-collection warning: served by Fireworks (no provider-side
+  // training), and omitting it keeps GLM out of SAVANT_FREE_TRACED_MODEL_IDS.
+  // `premium` drives the "Premium" badge styling in the picker; GLM's real
+  // gate is its weekly referral-session pool, not the daily premium pool.
+  premium: true,
+  multimodal: false,
+} as const satisfies SavantFreeModel
+
+export const SUPPORTED_SAVANT_FREE_MODELS = [
+  DEEPSEEK_V4_PRO_MODEL,
+  MIMO_V25_PRO_MODEL,
+  KIMI_MODEL,
+  MINIMAX_M3_MODEL,
+  GLM_V52_MODEL,
+  DEEPSEEK_V4_FLASH_MODEL,
+  MIMO_V25_MODEL,
+] as const satisfies readonly SavantFreeModel[]
+
+// GLM 5.2 is intentionally NOT in SAVANT_FREE_MODELS: it isn't a freely-pickable
+// grid model, it's a referral reward surfaced by the separate referral banner.
+// It stays in SUPPORTED_SAVANT_FREE_MODELS so the session/chat layers accept it as
+// a valid model id once the user's weekly entitlement admits them.
+// Kimi returned to the picker as K2.7 Code: the K2.6 first-token stalls that
+// got Kimi hidden were provider-side; K2.7 Code is served via Infron pinned to
+// Alibaba us/eu (~3s warm-cache TTFT benchmarked).
+export const SAVANT_FREE_MODELS = [
+  MINIMAX_M3_MODEL,
+  DEEPSEEK_V4_PRO_MODEL,
+  KIMI_MODEL,
+  ...(SAVANT_FREE_ENABLE_MIMO_MODELS_IN_UI ? [MIMO_V25_PRO_MODEL] : []),
+  DEEPSEEK_V4_FLASH_MODEL,
+  ...(SAVANT_FREE_ENABLE_MIMO_MODELS_IN_UI ? [MIMO_V25_MODEL] : []),
+] as const satisfies readonly SavantFreeModel[]
+
+export const SAVANT_FREE_PREMIUM_MODEL_IDS = [
+  SAVANT_FREE_DEEPSEEK_V4_PRO_MODEL_ID,
+  SAVANT_FREE_MIMO_V25_PRO_MODEL_ID,
+  SAVANT_FREE_KIMI_MODEL_ID,
+] as const
+
+/** SavantFree Web-only picker/support set. HY3 is intentionally excluded from
+ *  SAVANT_FREE_MODELS and SUPPORTED_SAVANT_FREE_MODELS so CLI/Desktop savant-free
+ *  surfaces do not pick it up during the initial web rollout. */
+export const SAVANT_FREE_WEB_MODELS = [
+  HY3_MODEL,
+  GLM_V52_MODEL,
+  ...SAVANT_FREE_MODELS,
+] as const satisfies readonly SavantFreeModel[]
+
+export const SAVANT_FREE_WEB_GOD_ONLY_MODELS = [
+  HY3_ATLAS_MODEL,
+] as const satisfies readonly SavantFreeModel[]
+
+export const SAVANT_FREE_WEB_ALL_MODELS = [
+  ...SAVANT_FREE_WEB_GOD_ONLY_MODELS,
+  ...SAVANT_FREE_WEB_MODELS,
+] as const satisfies readonly SavantFreeModel[]
+
+export const SAVANT_FREE_WEB_GOD_ONLY_MODEL_IDS = [
+  SAVANT_FREE_HY3_ATLAS_MODEL_ID,
+] as const
+
+export const SAVANT_FREE_WEB_PREMIUM_MODEL_IDS = [
+  ...SAVANT_FREE_PREMIUM_MODEL_IDS,
+  SAVANT_FREE_HY3_MODEL_ID,
+  SAVANT_FREE_HY3_ATLAS_MODEL_ID,
+] as const
+
+/** Models unlocked by referrals, metered by the weekly GLM session pool rather
+ *  than the daily premium pool. Kept separate from SAVANT_FREE_PREMIUM_MODEL_IDS
+ *  so GLM never falls into the shared 5/day premium quota. */
+export const SAVANT_FREE_GLM_V52_MODEL_IDS = [
+  SAVANT_FREE_GLM_V52_MODEL_ID,
+] as const
+
+/** Models that occupy the single per-user "premium-bucket" CONCURRENCY slot in
+ *  SavantFree Desktop's multi-session mode: at most one of these may have an
+ *  active session per user at a time, while unlimited-bucket models (DeepSeek V4
+ *  Flash, MiMo 2.5) may run in any number of concurrent tabs. (On the LIMITED
+ *  access tier the admission path puts EVERY model in the slot regardless of
+ *  this list — limited users get one savant-free tab at a time; see
+ *  `requestDesktopSession`.)
+ *
+ *  This is strictly a CONCURRENCY bucket, NOT a quota bucket. It is intentionally
+ *  a SUPERSET of SAVANT_FREE_PREMIUM_MODEL_IDS: it also includes MiniMax M3 and GLM
+ *  5.2, which are unlimited / weekly for QUOTA purposes but expensive enough that
+ *  we cap them to one concurrent desktop session. Do NOT use this for the daily
+ *  premium quota — that stays on isSavantFreePremiumModelId so M3/GLM never start
+ *  burning the 5/day premium pool. */
+export const SAVANT_FREE_DESKTOP_PREMIUM_BUCKET_MODEL_IDS = [
+  ...SAVANT_FREE_PREMIUM_MODEL_IDS,
+  SAVANT_FREE_MINIMAX_M3_MODEL_ID,
+  SAVANT_FREE_GLM_V52_MODEL_ID,
+] as const
+
+/** True when a desktop tab running `model` under `accessTier` occupies the
+ *  single per-user concurrency slot. On the full tier that's the premium
+ *  bucket; on the LIMITED tier EVERY model occupies it — limited users get one
+ *  savant-free tab at a time. THE shared definition of the one-tab rule: the
+ *  server's admission path and the desktop's picker/soft-gate must both call
+ *  this so the client can't drift from what the server enforces. */
+export function occupiesSavantFreeDesktopSlot(
+  model: string,
+  accessTier: SavantFreeAccessTier | null | undefined,
+): boolean {
+  return (
+    accessTier === 'limited' || isSavantFreeDesktopPremiumBucketModelId(model)
+  )
+}
+
+/** Wire headers for the free-mode session endpoints
+ *  (/api/v1/savant-free/session). Shared so the server handlers and every client
+ *  (CLI, desktop) agree on the exact strings instead of redefining literals. */
+export const SAVANT_FREE_INSTANCE_HEADER = 'x-savant-free-instance-id'
+export const SAVANT_FREE_MODEL_HEADER = 'x-savant-free-model'
+/** Trusted server-to-server header. Only the SavantCode API may honor this when
+ *  the request authenticates as the SavantFree Web service account; browser and
+ *  normal API callers must not be able to select another user's session row. */
+export const SAVANT_FREE_ACTING_USER_HEADER = 'x-savant-free-acting-user-id'
+/** Trusted SavantFree Web/Cloud session-proxy hint. Keeps the normal CLI GET
+ * response compact while letting the browser model picker request zero-usage
+ * quota snapshots so it can render accurate "N of M sessions" labels. */
+export const SAVANT_FREE_INCLUDE_UNUSED_RATE_LIMITS_HEADER =
+  'x-savant-free-include-unused-rate-limits'
+/** Set to '1' by SavantFree Desktop to opt into multi-session mode (concurrent
+ *  per-tab sessions); absent for CLI/web, which keep one session per user. */
+export const SAVANT_FREE_MULTI_SESSION_HEADER = 'x-savant-free-multi-session'
+
+/** Models that accept image input. Used to decide whether uploaded images are
+ *  forwarded to the model as real multimodal content. */
+export const SAVANT_FREE_MULTIMODAL_MODEL_IDS = [
+  SAVANT_FREE_MIMO_V25_MODEL_ID,
+  SAVANT_FREE_MIMO_V25_PRO_MODEL_ID,
+  SAVANT_FREE_MINIMAX_M3_MODEL_ID,
+  SAVANT_FREE_KIMI_MODEL_ID,
+] as const
+
+export const SAVANT_FREE_WEB_MULTIMODAL_MODEL_IDS = [
+  ...SAVANT_FREE_MULTIMODAL_MODEL_IDS,
+] as const
+
+/** Free-mode models whose chat-completion traces we store in our own dataset
+ *  (chat_completion_traces). Derived from the picker's data-collection warning
+ *  so the disclosure and the storage are one fact: a model is traced in free
+ *  mode iff it shows the "Collects data for training" caveat. Every other free
+ *  model (incl. MiniMax M3 on Fireworks) is NOT stored; paid, non-free-mode
+ *  requests are unaffected and traced as usual. */
+export const SAVANT_FREE_TRACED_MODEL_IDS = SUPPORTED_SAVANT_FREE_MODELS.filter(
+  (model: SavantFreeModel) =>
+    model.warning === SAVANT_FREE_DATA_COLLECTION_WARNING,
+).map((model) => model.id)
+
+export type SavantFreeModelId = (typeof SAVANT_FREE_MODELS)[number]['id']
+export type SupportedSavantFreeModelId =
+  (typeof SUPPORTED_SAVANT_FREE_MODELS)[number]['id']
+export type SavantFreePremiumModelId =
+  (typeof SAVANT_FREE_PREMIUM_MODEL_IDS)[number]
+export type SavantFreeWebAllModelId =
+  (typeof SAVANT_FREE_WEB_ALL_MODELS)[number]['id']
+export type SavantFreeWebPremiumModelId =
+  (typeof SAVANT_FREE_WEB_PREMIUM_MODEL_IDS)[number]
+
+/** What new savant-free users see selected in the picker. MiniMax M3 is the
+ *  strongest unlimited model (smartest & multimodal), so new users get good
+ *  quality without burning the 5/day premium quota on routine messages.
+ *  Callers that need a guaranteed-available id for resolution /
+ *  auto-fallbacks should use FALLBACK_SAVANT_FREE_MODEL_ID instead. */
+export const DEFAULT_SAVANT_FREE_MODEL_ID: SavantFreeModelId =
+  SAVANT_FREE_MINIMAX_M3_MODEL_ID
+
+/** Always-available fallback used when the requested model can't be served
+ *  right now (unknown id, deployment hours closed, etc.). Kept distinct from
+ *  DEFAULT_SAVANT_FREE_MODEL_ID so a new user's "preferred default" can be the
+ *  smartest model without auto-flipping anyone to a closed serverless model. */
+export const FALLBACK_SAVANT_FREE_MODEL_ID: SavantFreeModelId =
+  SAVANT_FREE_DEEPSEEK_V4_FLASH_MODEL_ID
+
+export const LIMITED_SAVANT_FREE_MODEL_ID: SavantFreeModelId =
+  SAVANT_FREE_DEEPSEEK_V4_FLASH_MODEL_ID
+export const LIMITED_SAVANT_FREE_MODEL_IDS = [
+  SAVANT_FREE_DEEPSEEK_V4_FLASH_MODEL_ID,
+  SAVANT_FREE_MIMO_V25_MODEL_ID,
+] as const
+export const LIMITED_SAVANT_FREE_MODELS = LIMITED_SAVANT_FREE_MODEL_IDS.map(
+  (modelId) =>
+    SUPPORTED_SAVANT_FREE_MODELS.find((model) => model.id === modelId)!,
+)
+
+export type SavantFreeAccessTier = 'full' | 'limited'
+
+/** Access tier carried in the SavantFree Web Convex JWT. Extends the CLI tier
+ *  with 'blocked' (Tor / corroborated anonymous network): the app still
+ *  loads, but every agent send is rejected server-side. */
+export type SavantFreeWebAccessTier = SavantFreeAccessTier | 'blocked'
+
+/** Temporary project-creation cap for outer-region (limited-tier) SavantFree Web
+ *  users. A new project consumes one slot; the quota resets at midnight
+ *  Pacific time. */
+export const SAVANT_FREE_WEB_LIMITED_PROJECT_DAILY_LIMIT = 3
+
+/** Models available to limited-region SavantFree Web users. They share the
+ * limited-region session pool; every other model remains geo-gated. */
+export const SAVANT_FREE_WEB_GEO_EXEMPT_MODEL_IDS = [
+  SAVANT_FREE_DEEPSEEK_V4_FLASH_MODEL_ID,
+  SAVANT_FREE_MIMO_V25_MODEL_ID,
+] as const
+
+export function isSavantFreeWebGeoExemptModelId(
+  id: string | null | undefined,
+): boolean {
+  if (!id) return false
+  return SAVANT_FREE_WEB_GEO_EXEMPT_MODEL_IDS.some((modelId) => modelId === id)
+}
+
+/** Models a limited-tier SavantFree Web user may select. */
+export const SAVANT_FREE_WEB_LIMITED_MODEL_IDS = [
+  ...new Set<string>([
+    ...SAVANT_FREE_WEB_GEO_EXEMPT_MODEL_IDS,
+    ...LIMITED_SAVANT_FREE_MODEL_IDS,
+  ]),
+]
+
+export function isSavantFreeWebModelAllowedForLimitedTier(
+  id: string | null | undefined,
+): boolean {
+  if (!id) return false
+  return SAVANT_FREE_WEB_LIMITED_MODEL_IDS.some((modelId) => modelId === id)
+}
+
+/** Coerce a limited-tier SavantFree Web selection (premium ids, stale
+ * localStorage values) to the allowed default (DeepSeek V4 Flash). */
+export function resolveSavantFreeWebModelForLimitedTier(
+  id: string | null | undefined,
+): string {
+  return isSavantFreeWebModelAllowedForLimitedTier(id)
+    ? (id as string)
+    : LIMITED_SAVANT_FREE_MODEL_ID
+}
+
+export function getSavantFreeModelsForAccessTier(
+  accessTier: SavantFreeAccessTier | null | undefined,
+): readonly SavantFreeModel[] {
+  if (accessTier === 'limited') return LIMITED_SAVANT_FREE_MODELS
+  return SAVANT_FREE_MODELS
+}
+
+/** The model the picker highlights as the "recommended" hero so a new user can
+ *  start with one Enter press without scanning the full list. Full access →
+ *  MiniMax M3 (the smart, unlimited, multimodal default); limited → the
+ *  always-available flash model. Both are unlimited, so the recommended pick
+ *  never burns the daily premium quota. */
+export function getRecommendedSavantFreeModelId(
+  accessTier: SavantFreeAccessTier | null | undefined,
+): SupportedSavantFreeModelId {
+  return accessTier === 'limited'
+    ? LIMITED_SAVANT_FREE_MODEL_ID
+    : DEFAULT_SAVANT_FREE_MODEL_ID
+}
+
+export function isSavantFreeModelAllowedForAccessTier(
+  model: string | null | undefined,
+  accessTier: SavantFreeAccessTier | null | undefined,
+): boolean {
+  if (!model) return false
+  if (accessTier !== 'limited') return isSupportedSavantFreeModelId(model)
+  return LIMITED_SAVANT_FREE_MODEL_IDS.some((modelId) => modelId === model)
+}
+
+/** Session admission is shared by CLI/Desktop/Web/Cloud. The CLI picker only
+ *  uses SUPPORTED_SAVANT_FREE_MODELS, while Web/Cloud have a small set of
+ *  trial/god-only model ids. Those Web-only ids still draw from the same
+ *  session pools, so the admission layer accepts the union here without
+ *  changing the CLI picker. */
+export function isSavantFreeSessionModelId(
+  id: string | null | undefined,
+): id is SupportedSavantFreeModelId | SavantFreeWebAllModelId {
+  return (
+    isSupportedSavantFreeModelId(id) ||
+    isSavantFreeWebModelId(id, {
+      includeGodOnly: true,
+    })
+  )
+}
+
+export function isSavantFreeSessionModelAllowedForAccessTier(
+  model: string | null | undefined,
+  accessTier: SavantFreeAccessTier | null | undefined,
+): boolean {
+  if (!model) return false
+  if (accessTier !== 'limited') return isSavantFreeSessionModelId(model)
+  return LIMITED_SAVANT_FREE_MODEL_IDS.some((modelId) => modelId === model)
+}
+
+export function isSavantFreeModelId(
+  id: string | null | undefined,
+): id is SavantFreeModelId {
+  if (!id) return false
+  return SAVANT_FREE_MODELS.some((m) => m.id === id)
+}
+
+export function isSavantFreeWebModelId(
+  id: string | null | undefined,
+  options: { includeGodOnly?: boolean } = {},
+): id is SavantFreeWebAllModelId {
+  if (!id) return false
+  const models = options.includeGodOnly
+    ? SAVANT_FREE_WEB_ALL_MODELS
+    : SAVANT_FREE_WEB_MODELS
+  return models.some((m) => m.id === id)
+}
+
+export function isSavantFreeWebGodOnlyModelId(
+  id: string | null | undefined,
+): boolean {
+  if (!id) return false
+  return SAVANT_FREE_WEB_GOD_ONLY_MODEL_IDS.some((modelId) => modelId === id)
+}
+
+export function resolveSavantFreeModel(
+  id: string | null | undefined,
+): SavantFreeModelId {
+  return isSavantFreeModelId(id) ? id : FALLBACK_SAVANT_FREE_MODEL_ID
+}
+
+export function resolveSavantFreeWebModel(
+  id: string | null | undefined,
+  options: { includeGodOnly?: boolean } = {},
+): SavantFreeWebAllModelId {
+  return isSavantFreeWebModelId(id, options)
+    ? id
+    : (FALLBACK_SAVANT_FREE_MODEL_ID as SavantFreeWebAllModelId)
+}
+
+export function resolveSavantFreeModelForAccessTier(
+  id: string | null | undefined,
+  accessTier: SavantFreeAccessTier | null | undefined,
+): SupportedSavantFreeModelId {
+  if (accessTier === 'limited') {
+    return isSavantFreeModelAllowedForAccessTier(id, accessTier)
+      ? (id as SupportedSavantFreeModelId)
+      : LIMITED_SAVANT_FREE_MODEL_ID
+  }
+  const resolved = resolveSupportedSavantFreeModel(id)
+  return isSavantFreeModelAllowedForAccessTier(resolved, accessTier)
+    ? resolved
+    : FALLBACK_SAVANT_FREE_MODEL_ID
+}
+
+export function resolveSavantFreeSessionModelForAccessTier(
+  id: string | null | undefined,
+  accessTier: SavantFreeAccessTier | null | undefined,
+): SupportedSavantFreeModelId | SavantFreeWebAllModelId {
+  if (accessTier === 'limited') {
+    return isSavantFreeSessionModelAllowedForAccessTier(id, accessTier)
+      ? (id as SupportedSavantFreeModelId)
+      : LIMITED_SAVANT_FREE_MODEL_ID
+  }
+  return isSavantFreeSessionModelId(id)
+    ? id
+    : (FALLBACK_SAVANT_FREE_MODEL_ID as SupportedSavantFreeModelId)
+}
+
+export function isSupportedSavantFreeModelId(
+  id: string | null | undefined,
+): id is SupportedSavantFreeModelId {
+  if (!id) return false
+  return SUPPORTED_SAVANT_FREE_MODELS.some((m) => m.id === id)
+}
+
+/**
+ * Match a model id against a base id, tolerating the dated provider snapshot
+ * suffix OpenRouter (and our own routing) appends, e.g.
+ * `google/gemini-3.1-pro-preview-20260219` for base `google/gemini-3.1-pro-preview`.
+ * Mirrors the suffix logic in `isFreeModeAllowedAgentModel` (free-agents.ts) —
+ * the two MUST stay in sync. Only a `-YYYYMMDD`-style suffix matches, so e.g.
+ * `mimo-v2.5-pro` never matches the base `mimo-v2.5`.
+ */
+export function isMatchingModelId(
+  candidate: string | null | undefined,
+  baseId: string,
+): boolean {
+  if (!candidate) return false
+  if (candidate === baseId) return true
+  const prefix = baseId + '-'
+  if (!candidate.startsWith(prefix)) return false
+  return /^\d{6,8}(?:$|[-:])/.test(candidate.slice(prefix.length))
+}
+
+/** Whether the requested model is Gemini Pro, tolerating the dated snapshot
+ *  suffix. Use this instead of `=== SAVANT_FREE_GEMINI_PRO_MODEL_ID` so a caller
+ *  can't dodge a Gemini gate by sending the dated id. */
+export function isSavantFreeGeminiProModelId(
+  id: string | null | undefined,
+): boolean {
+  return isMatchingModelId(id, SAVANT_FREE_GEMINI_PRO_MODEL_ID)
+}
+
+export function isSavantFreePremiumModelId(
+  id: string | null | undefined,
+): id is SavantFreePremiumModelId {
+  if (!id) return false
+  // Suffix-tolerant: a dated variant of a premium id (e.g. a dated Kimi) must
+  // still count as premium so it can't dodge the premium daily rate cap.
+  return SAVANT_FREE_PREMIUM_MODEL_IDS.some((modelId) =>
+    isMatchingModelId(id, modelId),
+  )
+}
+
+export function isSavantFreeWebPremiumModelId(
+  id: string | null | undefined,
+): id is SavantFreeWebPremiumModelId {
+  if (!id) return false
+  return SAVANT_FREE_WEB_PREMIUM_MODEL_IDS.some((modelId) =>
+    isMatchingModelId(id, modelId),
+  )
+}
+
+export function isSavantFreeSessionPremiumModelId(
+  id: string | null | undefined,
+): boolean {
+  return isSavantFreeWebPremiumModelId(id)
+}
+
+/** Whether `model` occupies the one-per-user SavantFree Desktop premium
+ *  CONCURRENCY slot (premium models + MiniMax M3 + GLM 5.2). Suffix-tolerant
+ *  (dated snapshots) like the other model predicates so a dated variant can't
+ *  dodge the cap. Distinct from isSavantFreePremiumModelId, which gates the daily
+ *  premium QUOTA and must NOT include M3/GLM. */
+export function isSavantFreeDesktopPremiumBucketModelId(
+  id: string | null | undefined,
+): boolean {
+  if (!id) return false
+  return SAVANT_FREE_DESKTOP_PREMIUM_BUCKET_MODEL_IDS.some((modelId) =>
+    isMatchingModelId(id, modelId),
+  )
+}
+
+/** Whether the requested model is the GLM 5.2 referral reward, tolerating the
+ *  dated snapshot suffix. GLM is metered by the weekly referral-session pool
+ *  rather than the daily premium pool, so callers branch on this before the
+ *  premium check. */
+export function isSavantFreeGlmV52ModelId(
+  id: string | null | undefined,
+): boolean {
+  return SAVANT_FREE_GLM_V52_MODEL_IDS.some((modelId) =>
+    isMatchingModelId(id, modelId),
+  )
+}
+
+export function isSavantFreeMultimodalModelId(
+  id: string | null | undefined,
+): boolean {
+  if (!id) return false
+  return SAVANT_FREE_MULTIMODAL_MODEL_IDS.some((modelId) => modelId === id)
+}
+
+export function isSavantFreeWebMultimodalModelId(
+  id: string | null | undefined,
+): boolean {
+  if (!id) return false
+  return SAVANT_FREE_WEB_MULTIMODAL_MODEL_IDS.some((modelId) => modelId === id)
+}
+
+/** Whether we store our own chat-completion traces for this free-mode model.
+ *  See SAVANT_FREE_TRACED_MODEL_IDS. */
+export function isSavantFreeTracedModelId(
+  id: string | null | undefined,
+): boolean {
+  if (!id) return false
+  return SAVANT_FREE_TRACED_MODEL_IDS.some((modelId) => modelId === id)
+}
+
+export function resolveSupportedSavantFreeModel(
+  id: string | null | undefined,
+): SupportedSavantFreeModelId {
+  return isSupportedSavantFreeModelId(id) ? id : FALLBACK_SAVANT_FREE_MODEL_ID
+}
+
+export function getSavantFreeModel(id: string): SavantFreeModel {
+  return (
+    SUPPORTED_SAVANT_FREE_MODELS.find((m) => m.id === id) ??
+    SAVANT_FREE_MODELS.find((m) => m.id === FALLBACK_SAVANT_FREE_MODEL_ID)!
+  )
+}
+
+export function getSavantFreeWebModel(id: string): SavantFreeModel {
+  return (
+    SAVANT_FREE_WEB_ALL_MODELS.find((m) => m.id === id) ??
+    SAVANT_FREE_WEB_ALL_MODELS.find(
+      (m) => m.id === FALLBACK_SAVANT_FREE_MODEL_ID,
+    )!
+  )
+}
+
+function getNextSavantFreeDeploymentStart(now: Date): Date {
+  const easternNow = getZonedParts(now, SAVANT_FREE_EASTERN_TIMEZONE)
+  const isBeforeTodayOpen = easternNow.hour < 9
+
+  const offset = isBeforeTodayOpen ? 0 : 1
+
+  return getUtcForZonedTime(
+    addDaysToYmd(easternNow.year, easternNow.month, easternNow.day, offset),
+    SAVANT_FREE_EASTERN_TIMEZONE,
+    9,
+    0,
+  )
+}
+
+function getCurrentSavantFreeDeploymentEnd(now: Date): Date {
+  const pacificNow = getZonedParts(now, SAVANT_FREE_PACIFIC_TIMEZONE)
+  return getUtcForZonedTime(pacificNow, SAVANT_FREE_PACIFIC_TIMEZONE, 17, 0)
+}
+
+function isSameLocalDay(left: Date, right: Date, timeZone?: string): boolean {
+  const formatter = new Intl.DateTimeFormat('en-CA', {
+    timeZone,
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+  })
+  return formatter.format(left) === formatter.format(right)
+}
+
+function formatLocalTime(
+  date: Date,
+  referenceNow: Date,
+  options: LocalTimeFormatOptions = {},
+): string {
+  const shouldShowWeekday = !isSameLocalDay(
+    date,
+    referenceNow,
+    options.timeZone,
+  )
+  return new Intl.DateTimeFormat(options.locale, {
+    timeZone: options.timeZone,
+    weekday: shouldShowWeekday ? 'short' : undefined,
+    hour: 'numeric',
+    minute: '2-digit',
+  }).format(date)
+}
+
+export function getSavantFreeDeploymentAvailabilityLabel(
+  now: Date = new Date(),
+  options: LocalTimeFormatOptions = {},
+): string {
+  if (isSavantFreeDeploymentHours(now)) {
+    const closesAt = getCurrentSavantFreeDeploymentEnd(now)
+    return `until ${formatLocalTime(closesAt, now, options)}`
+  }
+
+  const opensAt = getNextSavantFreeDeploymentStart(now)
+  return `opens ${formatLocalTime(opensAt, now, options)}`
+}
+
+export function isSavantFreeDeploymentHours(now: Date = new Date()): boolean {
+  const eastern = getZonedParts(now, SAVANT_FREE_EASTERN_TIMEZONE)
+  const pacific = getZonedParts(now, SAVANT_FREE_PACIFIC_TIMEZONE)
+  return (
+    eastern.hour * 60 + eastern.minute >= 9 * 60 &&
+    pacific.hour * 60 + pacific.minute < 17 * 60
+  )
+}
+
+export function isSavantFreeModelAvailable(
+  id: string,
+  now: Date = new Date(),
+): boolean {
+  const model = SUPPORTED_SAVANT_FREE_MODELS.find((m) => m.id === id)
+  if (!model) return false
+  return model.availability === 'always' || isSavantFreeDeploymentHours(now)
+}
+
+export function isSavantFreeSessionModelAvailable(
+  id: string,
+  now: Date = new Date(),
+): boolean {
+  const model = getSavantFreeWebModel(id)
+  return model.availability === 'always' || isSavantFreeDeploymentHours(now)
+}
+
+export function resolveAvailableSavantFreeModel(
+  id: string | null | undefined,
+  now: Date = new Date(),
+): SavantFreeModelId {
+  const resolved = resolveSavantFreeModel(id)
+  return isSavantFreeModelAvailable(resolved, now)
+    ? resolved
+    : FALLBACK_SAVANT_FREE_MODEL_ID
+}