"""Per-turn, request-scoped state shared between the bridge, the reply engine and tools — without threading extra parameters through the whole engine call chain (run_reply_engine -> run_tool_with_retries -> execute_tool -> execute). Flask serves each HTTP request on its own thread and the reply engine + tools run synchronously on that thread, so a ``threading.local`` cleanly scopes a single turn. Anything that can't see the thread-local (a worker thread, an eval, a unit test) just reads ``None`` and the caller falls back to its default. Fields ------ broadcasting : Optional[bool] The live screen-share (Go-Live) state the bot sends with the request. The webSearch routing reads it to pick on-screen Chrome (live) vs the normal chain (off). broadcast_action : Optional[str] A directive ("start"/"stop") recorded by the setBroadcast tool for the bridge to return to the bot, which owns the actual broadcast. user : Optional[str] v2: the Discord user ID of the person asking, set by the voice worker's brain. Tools that keep personal data (meals) store and read it under this person. None is v1's single user. chat : Optional[object] v2: the chat channel backend for this turn (chat_channels.spec.md). None means the chatChannels tool is not offered. schedule : Optional[object] v2: the asker's reminders and scheduled tasks for this turn (schedule.spec.md). None means the schedule tool is not offered (v1, evals, and scheduled tasks themselves). notes : Optional[object] v2: the asker's standing instructions backend (personal_notes.spec.md). None means the personalNotes tool is not offered. screen : Optional[object] v2: the app's screen backend for the asker (screen_view.spec.md). None means the screenView tool is not offered. trace : Optional[list] v2: where the engine writes down how it made this answer (history.spec.md, "Traces"): the tools it was given, the plan, the model's thinking and each tool call. None records nothing. """ from __future__ import annotations import threading from typing import Optional _state = threading.local() def reset() -> None: """Clear per-turn state. Call at the start of each request.""" _state.broadcasting = None _state.broadcast_action = None _state.user = None _state.chat = None _state.schedule = None _state.notes = None _state.screen = None _state.trace = None def set_trace(steps: Optional[list]) -> None: _state.trace = steps def get_trace() -> Optional[list]: return getattr(_state, "trace", None) def trace(kind: str, **data) -> None: """Add one step to this turn's trace, if one is kept.""" steps = get_trace() if steps is not None: steps.append({"kind": kind, **data}) def set_screen(backend) -> None: _state.screen = backend def get_screen(): return getattr(_state, "screen", None) def set_notes(backend) -> None: _state.notes = backend def get_notes(): return getattr(_state, "notes", None) def set_schedule(backend) -> None: _state.schedule = backend def get_schedule(): return getattr(_state, "schedule", None) def set_chat(backend) -> None: _state.chat = backend def get_chat(): return getattr(_state, "chat", None) def set_user(user_id: Optional[str]) -> None: _state.user = user_id def get_user() -> Optional[str]: return getattr(_state, "user", None) def set_broadcasting(value: Optional[bool]) -> None: _state.broadcasting = value def get_broadcasting() -> Optional[bool]: return getattr(_state, "broadcasting", None) def request_broadcast(action: str) -> None: """Record a broadcast directive. ``action`` is "start" or "stop".""" _state.broadcast_action = action def get_broadcast_action() -> Optional[str]: return getattr(_state, "broadcast_action", None)