Skip to content

docs(config): note that streaming-block changes need a gateway restart - #134192

Draft
liuhao1024 wants to merge 1 commit into
NousResearch:mainfrom
liuhao1024:liuhao/cron-bugfix-133804
Draft

liuhao1024 wants to merge 1 commit into
NousResearch:mainfrom
liuhao1024:liuhao/cron-bugfix-133804

Conversation

@liuhao1024

Copy link
Copy Markdown

What does this PR do?

The Gateway Streaming section of the configuration guide tells users they can adjust display.platforms.<platform>.streaming toggles from the dashboard's Channels page or directly in ~/.hermes/config.yaml, but it never says when those changes take effect. In reality the two layers behave differently:

  • The whole streaming: block (enabled, transport, edit_interval, buffer_threshold, cursor, fresh_final_after_seconds) is snapshotted once when the gateway runner is constructed (gateway/run.py, self.config = ... load_gateway_config_for_runner()), and every turn reads that snapshot (gateway/run_turn_runner.py, getattr(self._runner.config, 'streaming')). Editing those keys does nothing until the gateway is restarted.
  • The per-platform display.platforms.<platform>.streaming value is resolved per message from a fresh load_user_config_effective() read of config.yaml, so the dashboard Channels toggles and direct config edits apply from the next message without a restart.
  • A per-platform switch can only narrow the master switch (StreamingConfig.enabled_for: globally_enabled and (override is None or bool(override))), so flipping a platform toggle cannot turn streaming on until the master switch is enabled and the gateway has restarted.

This is exactly the trap #133804 hit: the docs describe enabling streaming but omit the restart requirement. This PR documents the actual behavior in the existing "Per-platform streaming defaults" note (option two of the issue's proposal — "document the restart requirement"; the behavior-change option would touch the gateway's config snapshot lifecycle, which is a much larger change). The zh-Hans translation mirrors the same addition.

Related Issue

Fixes #133804

Type of Change

  • 🐛 Bug fix (non-breaking change that fixes an issue)
  • ✨ New feature (non-breaking change that adds functionality)
  • 🔒 Security fix
  • 📝 Documentation update
  • ✅ Tests (adding or improving test coverage)
  • ♻️ Refactor (no behavior change)
  • 🎯 New skill (bundled or hub)

Changes Made

  • website/docs/user-guide/configuration.md: extended the "Per-platform streaming defaults" note in the Gateway Streaming section with the restart requirement for the streaming: block, the no-restart behavior of the per-platform toggles, and the "per-platform can only narrow the master switch" rule
  • website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/configuration.md: mirrored the same three facts in the zh-Hans translation of the note

How to Test

  1. Code-path verification of the documented behavior (observed on current main):
    • gateway/run.py — the runner loads self.config once at construction (load_gateway_config_for_runner()), so streaming: keys are a startup snapshot.
    • gateway/run_turn_runner.py — each turn reads scfg = getattr(getattr(self._runner, 'config', None), 'streaming', None) (the snapshot) but resolves the per-platform value as ctx.resolve_display_setting(ctx.user_config, platform_key, "streaming"), where ctx.user_config comes from a per-message load_user_config_effective() read (_load_gateway_config() is uncached).
    • gateway/config.py — StreamingConfig.enabled_for() shows a per-platform value can only narrow globally_enabled.
  2. python3 website/scripts/check_doc_links.py → Observed result: OK: no route-style links in hand-authored docs. (exit 0)
  3. python3 -m pytest tests/website/ -q → Observed result: 46 passed in 1.74s
  4. Markdown shape unchanged elsewhere: the diff is exactly two modified note lines (EN + zh-Hans), no new anchors or links introduced.

Checklist

Code

Documentation & Housekeeping

  • I've updated relevant documentation (README, docs/, docstrings) — this PR is the documentation update
  • I've updated cli-config.yaml.example if I added/changed config keys — N/A (no config keys added or changed)
  • I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — or N/A
  • I've considered cross-platform impact (Windows, macOS) per the compatibility guide — N/A (docs only)
  • I've updated tool descriptions/schemas if I changed tool behavior — or N/A

The gateway snapshots the whole streaming: block (enabled, transport,
edit_interval, buffer_threshold, cursor, fresh_final_after_seconds) when
the runner is constructed (gateway/run.py), and every turn reads that
snapshot (gateway/run_turn_runner.py), so edits to those keys only take
effect after a restart. Per-platform display.platforms.<plat>.streaming
toggles are re-read from config.yaml on every message and apply without
a restart, but they can only narrow the master switch. The Gateway
Streaming section now states both facts, in EN and zh-Hans.

Fixes NousResearch#133804
@alt-glitch alt-glitch added type/docs Documentation improvements P3 Low — cosmetic, nice to have comp/gateway Gateway runner, session dispatch, delivery area/config Config system, migrations, profiles area/streaming Streaming responses: gateway delivery, provider wire labels Oct 6, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/config Config system, migrations, profiles area/streaming Streaming responses: gateway delivery, provider wire comp/gateway Gateway runner, session dispatch, delivery P3 Low — cosmetic, nice to have type/docs Documentation improvements

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Bug]: Telegram native drafts burst updates and rewrite streamed prefixes [Bug]: Telegram streaming changes require an undocumented gateway restart

2 participants