The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
/**
* The rotation's clock: a few minutes into a launch, then hours apart, offer a
* tip if the app happens to be quiet.
*
* On unless the user turned it off (Settings → Appearance). An agent tip
* doesn't come through here at all.
*
* The pacing is a loading-screen tip's, not a notification's. Two clocks have
* to agree: a per-launch settling delay, so opening the app is never met with a
* bubble, and a six-hour cooldown persisted across launches, so quitting and
* reopening isn't a way to farm them. In practice that lands around one tip per
* day of use and takes weeks to walk the catalog, which is the point — ten tips
* in an afternoon is how a nicety turns into a thing people switch off. And the
* walk is one lap: a tip shown once is never offered again (`nextTip`).
*
* Then "quiet" does the rest. A tip is still the app interrupting, so it waits
* for a moment that is genuinely idle — nothing streaming, no dialog, menu or
* tour on screen, the window focused, and a few seconds since the last
* keystroke. Fail any of those and the tick passes; being due only means the
* next quiet moment is eligible, never that one gets taken.
*/
import { useEffect } from 'react'
import { useNavigate } from 'react-router'
import { SETTINGS_ROUTE } from '@/app/routes'
import type { Translations } from '@/i18n/types'
import { resolveTipAnchor } from '@/lib/tips/anchor'
import { TIP_CATALOG } from '@/lib/tips/catalog'
import { nextTip } from '@/lib/tips/rotation'
import { $localModelsEnabled } from '@/store/local-models-flag'
import { onboardingSurfaceActive } from '@/store/onboarding-presence'
import { $awaitingResponse, $busy } from '@/store/session'
import { $activeTip, $lastTipId, $nextTipAt, $retiredTips, $tipsEnabled, $tipShownAt, showTip } from '@/store/tips'
import { checkTutorialLifetime } from '@/store/tutorial-lifetime'
import { offerLocalRuntimeUpdateTip } from './local-runtime-update-offer'
export const TICK_MS = 30_000
const UPDATE_TICK_MS = 1_000
/** Nothing in the first stretch of a launch, however long the cooldown says
* it's been: you opened the app to do a thing, and the tip can wait until
* you've done it. Jittered so it isn't the same beat every time. */
export const SETTLE_MIN_MS = 5 * 60_000
export const SETTLE_SPREAD_MS = 5 * 60_000
/** Typing is the clearest "I'm busy" signal the renderer gets for free. */
const TYPING_GRACE_MS = 5_000
/** Anything on screen a tip would be talking over. `.driver-popover` is the
* tour: two accent-lit bubbles at once is one too many. */
const BLOCKING_SURFACES =
'[role="dialog"],[role="alertdialog"],[role="menu"],[role="listbox"],[data-overlay-surface],.driver-popover'
/** Nothing streaming, no surface open, the window focused and the user not typing: a tip or offer may show. */
export function appIsQuiet(lastTypedAt: number): boolean {
if (document.visibilityState !== 'visible' || !document.hasFocus()) {
return false
}
// First-run onboarding is never a quiet moment.
if ($busy.get() || $awaitingResponse.get() || onboardingSurfaceActive()) {
return false
}
if (Date.now() - lastTypedAt < TYPING_GRACE_MS) {
return false
}
return !document.querySelector(BLOCKING_SURFACES)
}
/** Drive the ambient rotation for as long as the host is mounted. */
export function useTipRotation(copy: Translations['tips']) {
const navigate = useNavigate()
useEffect(() => {
checkTutorialLifetime()
let lastTypedAt = 0
let settledAt = Date.now() + SETTLE_MIN_MS + Math.random() * SETTLE_SPREAD_MS
const noteTyping = () => {
lastTypedAt = Date.now()
}
const isDue = () => {
const nextAt = $nextTipAt.get()
return Date.now() >= settledAt && (nextAt === null || Date.now() >= nextAt)
}
const openLocalModels = () => {
navigate(`${SETTINGS_ROUTE}?tab=providers&pview=local`)
}
// Engine updates use the first quiet chat moment, independently of the tutorial clock.
const offerUpdate = () => {
if (
!$localModelsEnabled.get() ||
!$tipsEnabled.get() ||
$activeTip.get() ||
!appIsQuiet(lastTypedAt) ||
!resolveTipAnchor(document, ['[data-tour="model-pill"]'])
) {
return false
}
return offerLocalRuntimeUpdateTip(copy, openLocalModels)
}
const offer = () => {
checkTutorialLifetime()
if (!$tipsEnabled.get() || $activeTip.get()) {
return
}
if (!isDue() || !appIsQuiet(lastTypedAt)) {
return
}
// The engine-update campaign outranks the walk: it says something about
// THIS machine. It shares the cooldown, so taking the moment still costs
// it the usual hours.
if (offerUpdate()) {
return
}
// Only tips with something on screen to point at are candidates, so the
// rotation never burns a turn on a pane the user isn't showing.
const onScreen = TIP_CATALOG.filter(tip => resolveTipAnchor(document, tip.targets))
const chosen = nextTip(
TIP_CATALOG.map(tip => tip.id),
onScreen.map(tip => tip.id),
// `$tipShownAt` is the seen ledger: every tip that reached the screen
// is in it, so a tip the timer closed is as done as one the ✕ closed.
{ lastShownId: $lastTipId.get(), retired: $retiredTips.get(), seen: Object.keys($tipShownAt.get()) }
)
const tip = onScreen.find(candidate => candidate.id === chosen)
if (!tip) {
return
}
showTip({
keybind: tip.keybind,
side: tip.side,
targets: tip.targets,
text: copy.items[tip.id].text,
tipId: tip.id,
title: copy.items[tip.id].title
})
}
// Turning tips on is its own kind of settled: the delay guards a
// launch you came into with a purpose, and has nothing to say about someone
// who just asked for tips and is owed the sight of one working.
const unbindSwitch = $tipsEnabled.listen(enabled => {
if (enabled) {
settledAt = Date.now()
offerUpdate()
offer()
}
})
const timer = window.setInterval(offer, TICK_MS)
const updateTimer = $localModelsEnabled.get() ? window.setInterval(offerUpdate, UPDATE_TICK_MS) : undefined
offerUpdate()
window.addEventListener('keydown', noteTyping, true)
return () => {
unbindSwitch()
window.clearInterval(timer)
if (updateTimer !== undefined) {
window.clearInterval(updateTimer)
}
window.removeEventListener('keydown', noteTyping, true)
}
}, [copy, navigate])
}