# Runtime Settings TODO

Status as of 2026-05-15: first-pass reasoning runtime settings are implemented.
The broader runtime settings surface and shared command parser are still deferred.

This note tracks runtime-configurable settings that should not be implemented in
the first pass. The first pass only supports session-persisted reasoning display
and reasoning effort.

## Implemented first

- `/reasoning on|off`: session-level override for whether provider reasoning is
  sent back to the chat.
- `/reasoning effort <low|medium|high|max|default>`: session-level override for
  request-time reasoning effort. `default` removes the override and falls back
  to the provider/config default.
- `/reasoning reset`: removes the session-level reasoning runtime metadata.
- `/status`: displays the effective session reasoning display/effort values.

Runtime values live in session metadata under `runtime`. `config.yaml` remains
the startup/default source.

Implementation notes:

- `nahida_bot/core/runtime_settings.py` owns parsing and merge semantics.
- `SessionRunner` loads runtime settings into `current_runtime_settings` for each run.
- DeepSeek and OpenAI Responses providers read runtime reasoning effort from that context var.
- `MessageRouter` resolves reasoning display from session runtime metadata before sending responses.
- Command handling is still ad hoc string splitting in the built-in commands plugin.

## Later runtime settings

- Reasoning display length, currently `router.reasoning_max_chars`.
- Context reasoning replay policy, currently `context.reasoning_policy` and
  `context.max_reasoning_tokens`.
- Agent loop limits such as `agent.max_steps`.
- Multimodal behavior such as `multimodal.image_fallback_mode`,
  `multimodal.media_context_policy`, and `multimodal.max_images_per_turn`.
- Memory retrieval budgets such as `memory.retrieval.max_injected_items` and
  `memory.retrieval.max_injected_chars`.
- Group context behavior such as `router.group_context.enabled`, max messages,
  TTL, and character budget.

Avoid moving startup resources into runtime settings without a lifecycle design:
provider definitions, API keys, base URLs, plugin paths, channel connection
settings, database paths, and server host/port should stay config-only for now.

## Command Parser TODO

The current command handling is simple command-name matching plus per-command
string splitting. That is acceptable for `/reasoning`, but it will not scale
well once runtime commands gain nested subcommands, typed arguments, validation,
aliases, and generated help.

Future design questions:

- Should runtime commands converge under `/settings`, while compatibility aliases
  like `/reasoning` remain?
- Should parser definitions be declarative so plugins can register subcommands
  and validation schemas?
- How should parser errors be localized and shown consistently across channels?
- Should permission checks happen at command, subcommand, or argument level?
- How should parser behavior interact with channel-specific prefixes and group
  mention handling?
