Skip to content

The agent that grows with you

7.8 KB
Raw Blame
/**
 * 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)
}