The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
/**
* In-app tips — the app pointing at itself, plus the agent doing the same.
*
* Two sources, one bubble, one switch over both of them:
*
* - `$tipsEnabled` is the whole feature, ON with a switch to stop it. A feature
* nobody meets is a feature nobody has, and the pacing is what earns the
* default: minutes into a launch at the earliest, then six hours, which is a
* nicety rather than the nag that would owe you an opt-in.
* - It covers Hermes too. "Off" from someone who has just closed a bubble means
* no bubbles, not "no bubbles unless the agent sends one" — so the switch is
* mirrored to the gateway, where it takes the `tip` tool out of the model's
* schema, and the bridge drops a stray tip on top of that.
* - `$tipShownAt` is the seen ledger: every tip that reached the screen, with
* when. The rotation walks the catalog ONCE against it, so a tip that timed
* out is as finished as one the user closed — a second sighting of "type @
* to attach a file" is the app forgetting it already said that.
* - `$retiredTips` is the hard-close ledger. A ✕ says the same thing louder and
* is the one record a Reset does not need to respect on its own; Settings →
* Reset clears both and starts the lap over.
* - `$activeTip` is what is on screen. Ephemeral by design: a tip is a nicety,
* and one that survives a reload has overstayed.
*
* `$lastTipId` is the rotation's cursor and `$nextTipAt` is its clock. Both are
* persisted, because the alternative is that every relaunch reopens the tour at
* tip one and re-arms a schedule measured in hours.
*/
import { atom, computed } from 'nanostores'
import { Codecs, persistentAtom } from '@/lib/persisted'
import { TIP_CATALOG, type TipSide } from '@/lib/tips/catalog'
import { mirrorDisplayToggle } from '@/store/display-toggles'
import { recordFeatureToggle } from './desktop-metrics'
/** Hours, not minutes. The catalog is ten tips and it should take weeks. */
const COOLDOWN_MS = 6 * 60 * 60_000
/** A tip as the bubble needs it: resolved copy, resolved anchor. */
export interface ActiveTip {
/** A call to action: one button under the text. What separates a campaign
* tip from the rotation's — the rotation teaches, this one offers to DO
* the thing, and the button is the only path (an ambient bubble must
* never make its whole face clickable). Clicking closes the tip. */
action?: { label: string; onSelect: () => void }
/** Keybind action id whose live combo the bubble prints. */
keybind?: string
side: TipSide
/** Candidate anchors, best first — re-resolved while the bubble is up, so a
* tip follows an element that re-renders and leaves when it goes away. */
targets: readonly string[]
text: string
/** Stable id used by the seen and retirement ledgers. */
tipId?: string
title?: string
}
// Key still says `rotation` from when the switch only covered that half.
// Renaming it would read as unset for anyone who had already turned tips off,
// and silently turning them back on is the one outcome worth avoiding here.
const ENABLED_KEY = 'hermes.desktop.tips.rotation.v1'
export const $tipsEnabled = persistentAtom(ENABLED_KEY, true, Codecs.bool)
export const $retiredTips = persistentAtom<string[]>('hermes.desktop.tips.retired.v1', [], Codecs.stringArray)
export const $lastTipId = persistentAtom<null | string>('hermes.desktop.tips.last.v1', null, Codecs.nullableText)
export const $nextTipAt = persistentAtom<null | number>(
'hermes.desktop.tips.next.v1',
null,
Codecs.json(value => (typeof value === 'number' && Number.isFinite(value) ? value : null))
)
export const $activeTip = atom<ActiveTip | null>(null)
/** Agent tips have no catalog entry, so hash their content into a compact durable identity. */
export function agentTipId(selector: string, text: string): string {
let hash = 0xcbf29ce484222325n
const identity = JSON.stringify([selector, text])
// Hash the tuple encoding so neither arbitrary agent copy nor selectors are persisted verbatim.
for (let index = 0; index < identity.length; index += 1) {
hash ^= BigInt(identity.charCodeAt(index))
hash = BigInt.asUintN(64, hash * 0x100000001b3n)
}
return `agent:${hash.toString(16).padStart(16, '0')}`
}
// Off has to reach the agent, not just the renderer: the `tip` tool leaves the
// model's schema entirely rather than staying on offer and being dropped.
mirrorDisplayToggle('display.in_app_tips', ENABLED_KEY, $tipsEnabled)
/** When each tip last showed, by id. The rotation reads it as the seen set
* (a catalog tip shows once); campaign tips (ids outside the catalog) read
* it as a clock and re-offer on their own long schedule. `$retiredTips`
* still owns the hard ✕. */
export const $tipShownAt = persistentAtom<Record<string, number>>(
'hermes.desktop.tips.shownAt.v1',
{},
Codecs.json(value => {
if (!value || typeof value !== 'object' || Array.isArray(value)) {
return {}
}
return Object.fromEntries(
Object.entries(value).filter((entry): entry is [string, number] => typeof entry[1] === 'number')
)
})
)
export function setTipsEnabled(enabled: boolean): void {
recordFeatureToggle('tips', $tipsEnabled.get(), enabled)
if (!enabled) {
// Including whichever one is up: the switch is answering a bubble on
// screen as often as it is answering the idea of them.
$activeTip.set(null)
}
$tipsEnabled.set(enabled)
}
/** Forget every sighting and un-retire everything, and let the rotation start
* a fresh lap from a full deck rather than from wherever a six-hour cooldown
* had left it. */
export function resetTips(): void {
$retiredTips.set([])
$tipShownAt.set({})
$lastTipId.set(null)
$nextTipAt.set(null)
}
/** Catalog tips a Reset would bring back: shown once or ✕'d, counted once. */
export const $spentTipCount = computed([$retiredTips, $tipShownAt], (retired, shownAt) => {
const ids = new Set([...retired, ...Object.keys(shownAt)])
return TIP_CATALOG.filter(def => ids.has(def.id)).length
})
/** Put a tip on screen, replacing whatever was there. */
export function showTip(tip: ActiveTip): void {
if (tip.tipId && $retiredTips.get().includes(tip.tipId)) {
return
}
if (tip.tipId) {
// The cursor belongs to the rotation's walk. A campaign tip (an id the
// catalog doesn't hold) records when it showed but must not move the
// cursor — nextTip treats an unknown id as "start over at the top".
if (TIP_CATALOG.some(def => def.id === tip.tipId)) {
$lastTipId.set(tip.tipId)
}
// Agent tips are unbounded in number and only need the ✕ to persist; keep
// them out of the seen ledger so a chatty agent cannot grow localStorage.
if (!tip.tipId.startsWith('agent:')) {
$tipShownAt.set({ ...$tipShownAt.get(), [tip.tipId]: Date.now() })
}
}
// Any tip starts the cooldown, an agent's included: whoever just pointed at
// something, the user has had their one interruption for a good while.
$nextTipAt.set(Date.now() + COOLDOWN_MS)
$activeTip.set(tip)
}
/** Soft close: this one has had its moment, the rotation carries on. */
export function dismissTip(): void {
$activeTip.set(null)
}
/** Retire tips without showing them (Skip on the first-run intro); Settings → Reset brings them back. */
export function retireTips(ids: readonly string[]): void {
const retired = $retiredTips.get()
const fresh = ids.filter(id => !retired.includes(id))
if (fresh.length > 0) {
$retiredTips.set([...retired, ...fresh])
}
const activeId = $activeTip.get()?.tipId
if (activeId && ids.includes(activeId)) {
$activeTip.set(null)
}
}
/** Hard close (the ✕): retire the identified tip behind the bubble for good. */
export function retireActiveTip(): void {
const tipId = $activeTip.get()?.tipId
if (tipId && !$retiredTips.get().includes(tipId)) {
$retiredTips.set([...$retiredTips.get(), tipId])
}
$activeTip.set(null)
}