hermes - 💡(How to fix) Fix RFC: upgrade feature decisions for behavior-changing features

Summary

Hermes needs a reusable upgrade-time feature decision system for major behavior changes: features that can delight many users but also surprise or disrupt existing workflows if silently enabled or silently left undiscovered.

Instead of choosing a global default and hoping users find the docs, Hermes should support a first-run / first-relevant-use decision point: explain the new feature briefly, present clear UI choices, persist the preference, and avoid asking again unless the user chooses "not now" or resets the preference.

Situation / challenges

Hermes is increasingly used through long-lived gateways and multi-profile bot environments. Major new features can change the user experience in ways that are hard to evaluate from a config diff:

• Discoverability: useful new capabilities remain invisible if they require users to read release notes or config docs.
• Workflow disruption: silently enabling behavior can break established habits or mental models. "Who moved my cheese" features can be good and still feel like regressions.
• Ambiguous defaults: a feature may be obviously right for project bots but wrong for generic assistants, group chats, compliance-heavy deployments, or cost-sensitive users.
• Multi-bot/profile environments: one user may run several Hermes profiles. Asking separately in every bot is spam; applying globally without consent is also wrong.
• Platform differences: CLI, Telegram, Discord, TUI, and API users need equivalent decision flows, but the UI affordance differs.
• Upgrade timing: the right moment may be first startup, first relevant trigger, or first time the old behavior would hurt. A generic mechanism should support those patterns.
• Auditability: users should be able to see which decisions were made, by whom/where, and change them later.

Concrete example: compact session continuity / daily handoff. Some users want a clean daily reset. Others expect a project bot to remember yesterday's work. Turning it on blindly risks stale context and cost; leaving it off silently causes amnesia. The correct UX is a decision prompt.

Proposed solution

Add a reusable upgrade feature decisions framework.

For major behavior-changing features, config starts as unset rather than true/false. When Hermes reaches the appropriate decision point, it prompts the user once:

Tired of losing context overnight? Hermes now supports compact session continuity. Enable it?

Choices should be explicit, for example:

• Enable for this bot/profile
• Enable for all my bots/profiles
• Not now
• Never ask again / keep disabled
• Optional: More info

The framework should then persist the decision and suppress repeated prompts.

Requirements

Data model

Maintain a profile-aware decision registry, e.g. under config/state:

upgrade_decisions:
  session_handoff:
    state: enabled | disabled | deferred | unset
    scope: profile | all_profiles
    decided_at: <timestamp>
    decided_via: cli | telegram | discord | tui | api
    version_introduced: <semver or build id>

Exact storage can differ, but it should be inspectable and editable.

Runtime behavior

• If the feature preference is explicit, obey it.
• If unset, trigger a concise onboarding decision prompt at the feature's first relevant moment.
• If deferred, ask again only after a cooldown or version bump.
• If disabled/never, do not nag.
• In multi-profile environments, support applying the decision to all profiles, but do not do that implicitly.
• Provide a CLI/config path to list and change decisions later.

Platform UI

• CLI/TUI: prompt with numbered choices or native UI.
• Telegram/Discord/etc.: use buttons where available; fall back to commands/text choices.
• API/headless: expose a structured pending decision rather than blocking indefinitely.

Safety and compatibility

• New major behavior should not silently alter existing workflows on upgrade.
• Decision prompts should be short and rare.
• Prompts should explain the user-visible consequence, not implementation detail.
• Features should define their own decision copy, default fallback, and trigger condition.

Candidate first consumer: session handoff

Session handoff answers:

"It is now a new day/session. What should the agent know before interpreting the next user message?"

This is a strong first consumer because it is useful but behavior-changing:

• Some users want clean daily resets.
• Project bots need continuity.
• Full transcript replay is unsafe/expensive.
• A compact handoff is likely better, but should still be opt-in or explicitly chosen.

Open questions

• Where should decisions live: config.yaml, state.db, profile state, or a small dedicated state file?
• How should "apply to all profiles" work when profiles are on different hosts?
• Should decisions sync across profiles automatically or require an explicit local fan-out?
• How do we expose pending decisions in API/headless mode?
• Which existing or planned features should be retrofitted into this framework?

Feedback requested

Would maintainers prefer this as:

1. a small generic decision registry plus one gateway/CLI prompt implementation;
2. a broader onboarding framework;
3. part of setup/config wizard; or
4. a plugin hook that features can register with?

The goal is to make major new features discoverable without surprising users who already rely on current behavior.