fix(widget+voice): carry, run & persist chat session-state across CHAT↔VOICE

Three related correctness fixes so a widget CHAT↔VOICE flip keeps the session's
reducer-built state (cart_id, checkout_id, client-pushed facts) instead of
silently dropping it. Before this, voice had ZERO state-reducer /
tool_arg_injection code, so a template's state config worked in chat and
silently no-op'd on the actual voice call.

1. CARRY (CHAT→VOICE seed). The widget voice resume seed carried prior_history
   + start_node but NOT agent_session_state. Read it into the seed
   (widget/handlers.py) and merge into the voice runtime's template_vars
   (only_if_missing) so chat-built identifiers thread through voice's existing
   {placeholder} resolution. The voice agent now holds self.agent_state, seeded
   from the resume.

2. RUN (SessionStatePolicy on voice). inject_tool_args runs before each voice
   tool and apply_state_reducers after it, reading/writing bot.agent_state —
   the same pure engines chat runs in _cycle_loop — at BOTH voice tool seams:
   global functions (_make_global_wrapper) and MCP tools (the mcp loader's
   _state_wrap_mcp_handler, applied outside the approval gate). Gated by a new
   handles_state_externally flag: chat sets it (wrapper skips, chat does it
   itself — no double-application); voice doesn't. The two voice-state helpers
   live in session_state.py next to the pure engines so both seams share them.
   No-op for templates with no state config.

3. PERSIST (VOICE→CHAT drain). end_conversation writes the voice-accumulated
   agent_state back to the chat_session, so a later chat turn sees what voice
   changed — completing the round-trip.

The principled completion of the agent_state seed-fix: voice now READS and
UPDATES the shared state via the chat engines, for global functions AND MCP
tools, with no new state machinery.

Tests: tests/test_voice_session_state.py (global-function hook + gating) and
tests/test_mcp_approval.py (MCP state wrap). pyrefly 0 errors; full suite 452
passed.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: swaroopvarma2359

app/ai/voice/agents/breeze_buddy/agent/__init__.py

@@ -189,6 +189,13 @@ def __init__(
         # at start_node with prior_history pre-loaded into LLM context.
         self._widget_resume_seed: Optional[Dict[str, Any]] = None
 
+        # Reducer-built session state (cart_id/checkout_id/client facts),
+        # the voice counterpart of ChatAgent.agent_state. Seeded from a
+        # widget-resume (below), accumulated via state_reducers during the
+        # call by the global-function wrapper, and drained back to the
+        # chat_session on end_conversation. Empty {} for fresh/telephony calls.
+        self.agent_state: Dict[str, Any] = {}
+
         # HITL approval channel — daily mode only, set alongside
         # _rtvi_processor. None on telephony bots (no approval surface) and
         # when RTVI is unavailable; the gate in template/approval.py treats
@@ -332,11 +339,20 @@ async def _setup_daily_transport(self, runner_args: RunnerArguments) -> None:
                 "start_node": meta.get("start_node"),
                 "prior_history": list(meta.get("prior_history") or []),
                 "seed_message_count": int(meta.get("seed_message_count", 0) or 0),
+                # Reducer-built chat state (cart_id/checkout_id/...) carried
+                # across the CHAT->VOICE flip; merged into template_vars below.
+                "agent_state": dict(meta.get("agent_state") or {}),
             }
+            # Seed the live agent_state from the chat session so voice tool
+            # calls inject/update it (tool_arg_injection + state_reducers via
+            # the global-function wrapper) and the final state drains back on
+            # end_conversation.
+            self.agent_state = dict(self._widget_resume_seed["agent_state"])
             logger.info(
                 f"Widget voice resume: chat_session={widget_session_id} "
                 f"start_node={self._widget_resume_seed['start_node']!r} "
-                f"prior_msgs={len(self._widget_resume_seed['prior_history'])}"
+                f"prior_msgs={len(self._widget_resume_seed['prior_history'])} "
+                f"agent_state_keys={sorted(self.agent_state)}"
             )
 
         logger.info(
@@ -361,6 +377,22 @@ async def _setup_daily_transport(self, runner_args: RunnerArguments) -> None:
             logger.error(f"Failed to load template config for Daily mode: {e}")
             raise
 
+        # Widget resume: thread the chat session's accumulated agent_state
+        # (cart_id/checkout_id/client-pushed facts) into template_vars so
+        # {placeholder} resolution in the resumed voice flow uses the
+        # chat-built identifiers instead of losing them on the flip.
+        # only_if_missing — never clobber an explicitly-rendered call var.
+        if self._widget_resume_seed:
+            resumed_state = self._widget_resume_seed.get("agent_state") or {}
+            merged_keys = [k for k in resumed_state if k not in self.template_vars]
+            for k in merged_keys:
+                self.template_vars[k] = resumed_state[k]
+            if merged_keys:
+                logger.info(
+                    f"Widget voice resume: merged {len(merged_keys)} agent_state "
+                    f"var(s) into template_vars: {sorted(merged_keys)}"
+                )
+
         # Synthesize and cache the initial greeting in Redis so it can be
         # played out on client-connect. Idempotent: if the dispatch worker
         # pre-synthesized the audio at dispatch time (outbound), this is a

app/ai/voice/agents/breeze_buddy/chat/agent.py

@@ -174,6 +174,11 @@ def __init__(
         # global-function adapters receive bot_instance=self and would
         # otherwise double-gate.
         self.handles_approval_externally = True
+        # Chat runs inject_tool_args / apply_state_reducers itself inside
+        # _cycle_loop; this flag tells the shared global-function wrapper NOT
+        # to re-apply them (voice has no such loop, so it lets the wrapper do
+        # it). Prevents double-application of the SessionStatePolicy.
+        self.handles_state_externally = True
         # function name -> ApprovalConfig for every gated global function.
         self._approval_map = build_approval_map(self.template.flow or {})
 

app/ai/voice/agents/breeze_buddy/handlers/internal/end_conversation.py

@@ -19,6 +19,7 @@
 from app.core.logger.context import clear_log_context
 from app.database.accessor.breeze_buddy.chat_session import (
     drain_voice_into_chat_session,
+    upsert_agent_session_state,
 )
 
 callback_map = {
@@ -149,6 +150,15 @@ async def end_conversation(context: TemplateContext, args, transition_to=None):
                     new_messages=new_messages,
                     final_node=final_node,
                 )
+                # Persist voice-accumulated agent_state back to the chat
+                # session so a later chat turn sees cart_id/etc. that voice
+                # updated (mirror of the seed carried in on /voice/connect).
+                voice_state = getattr(context.bot, "agent_state", None)
+                if voice_state:
+                    await upsert_agent_session_state(
+                        chat_session_id=str(widget_session_id),
+                        data=voice_state,
+                    )
             except Exception as drain_err:
                 logger.error(
                     f"widget drain: failed for chat_session "

app/ai/voice/agents/breeze_buddy/mcp/__init__.py

@@ -28,6 +28,10 @@
 # others; the latent handlers<->template cycle the note below describes is
 # pre-existing and unchanged by this import.)
 from app.ai.voice.agents.breeze_buddy.template.approval import gate_call
+from app.ai.voice.agents.breeze_buddy.template.session_state import (
+    _inject_voice_state,
+    _reduce_voice_state,
+)
 
 # Template types FIRST — fully loads the `template` package (whose
 # __init__ eagerly pulls in http_handler / http_requester / hooks /
@@ -98,6 +102,33 @@ async def execute() -> Any:
     return gated_handler
 
 
+def _state_wrap_mcp_handler(handler: Any, bot_instance: Any, tool_name: str) -> Any:
+    """Apply the voice SessionStatePolicy to an MCP tool handler.
+
+    The MCP counterpart of ``_make_global_wrapper``'s state hook: inject
+    state-driven args before the call and lift identifiers off the result
+    after it, so a template's ``tool_arg_injection`` / ``state_reducers`` reach
+    MCP tools on voice (chat already runs them in its ``_cycle_loop``). No-op
+    without a bot, and skipped when the bot sets ``handles_state_externally``
+    (chat). ``tool_name`` is the REGISTERED name the LLM calls — the name that
+    injection/reducer rules target. Applied OUTSIDE the approval gate, so a
+    denied call's bare ``{status, reason}`` simply finds no matching reducer
+    paths (no-op), while an approved call reduces its real result.
+    """
+    if bot_instance is None:
+        return handler
+
+    async def state_handler(args: Dict[str, Any], flow_manager: Any) -> Any:
+        if getattr(bot_instance, "handles_state_externally", False):
+            return await handler(args, flow_manager)
+        injected = _inject_voice_state(bot_instance, tool_name, args)
+        result = await handler(injected, flow_manager)
+        _reduce_voice_state(bot_instance, tool_name, result)
+        return result
+
+    return state_handler
+
+
 def _deep_merge_defaults(
     args: Dict[str, Any], defaults: Dict[str, Any]
 ) -> Dict[str, Any]:
@@ -641,6 +672,7 @@ async def _load_server_tools(
                 tool_name,
                 tool_approval,
             )
+            handler = _state_wrap_mcp_handler(handler, bot_instance, tool_name)
             schema_kwargs: Dict[str, Any] = {}
             if tool_approval is not None:
                 schema_kwargs["timeout_secs"] = _mcp_approval_timeout_secs(
@@ -698,6 +730,7 @@ async def _load_server_tools(
             tool_name,
             tool_approval,
         )
+        handler = _state_wrap_mcp_handler(handler, bot_instance, tool_name)
         schema_kwargs: Dict[str, Any] = {}
         if tool_approval is not None:
             schema_kwargs["timeout_secs"] = _mcp_approval_timeout_secs(tool_approval)

app/ai/voice/agents/breeze_buddy/template/global_function.py

@@ -22,6 +22,10 @@
 from app.ai.voice.agents.breeze_buddy.template.func_action_handlers import (
     execute_func_post_actions,
 )
+from app.ai.voice.agents.breeze_buddy.template.session_state import (
+    _inject_voice_state,
+    _reduce_voice_state,
+)
 from app.ai.voice.agents.breeze_buddy.template.types import (
     BaseGlobalFunction,
     GlobalBuiltinFunction,
@@ -94,17 +98,32 @@ def _make_global_wrapper(
     """
 
     async def wrapper_handler(llm_args, flow_manager):
+        # SessionStatePolicy (voice): inject state-driven args before the
+        # handler runs and lift identifiers off the result after it — the
+        # same reducers / tool_arg_injection chat applies. Chat sets
+        # handles_state_externally and does this in its own _cycle_loop, so
+        # skip here to avoid double-application.
+        manages_state = not getattr(bot_instance, "handles_state_externally", False)
+        effective_args = (
+            _inject_voice_state(bot_instance, func.name, llm_args)
+            if manages_state
+            else llm_args
+        )
+
         async def execute() -> Any:
             await _run_filler_and_music(bot_instance, func)
             try:
                 result = await wrapped_handler(
-                    llm_args,
+                    effective_args,
                     function_config=func,
                 )
             finally:
                 # Always stop music even if handler errors
                 await _stop_music(bot_instance, func)
 
+            if manages_state:
+                _reduce_voice_state(bot_instance, func.name, result)
+
             if func.func_post_actions and bot_instance:
                 asyncio.create_task(
                     execute_func_post_actions(
@@ -116,7 +135,7 @@ async def execute() -> Any:
                 )
             return result
 
-        return await gate_global_function(bot_instance, func, llm_args, execute)
+        return await gate_global_function(bot_instance, func, effective_args, execute)
 
     return wrapper_handler
 

app/ai/voice/agents/breeze_buddy/template/session_state.py

@@ -329,6 +329,74 @@ def _is_tool_success(tool_result: Any) -> bool:
     return True
 
 
+# ---------------------------------------------------------------------------
+# Voice SessionStatePolicy — bot-aware application of the engines above.
+#
+# Chat runs inject_tool_args / apply_state_reducers itself inside
+# ChatAgent._cycle_loop. Voice has no such loop, so these helpers are applied
+# at the voice tool seams — global functions (template/global_function.py's
+# _make_global_wrapper) and MCP tools (mcp/__init__.py's loader). bot_instance
+# is duck-typed via getattr so this stays import-light (no agent import).
+# ---------------------------------------------------------------------------
+
+
+def _voice_state_session_id(bot_instance: Any) -> str:
+    """Best-effort session id for inject_tool_args' eval context (voice path).
+
+    Prefers the widget chat_session id (widget-resume), falls back to the
+    lead id / call_sid. Used only for the ``{session_id}`` eval var + the
+    idempotency-hash discriminator — never a correctness key on voice.
+    """
+    seed = getattr(bot_instance, "_widget_resume_seed", None)
+    if isinstance(seed, dict) and seed.get("widget_session_id"):
+        return str(seed["widget_session_id"])
+    lead = getattr(bot_instance, "lead", None)
+    if lead is not None and getattr(lead, "id", None):
+        return str(lead.id)
+    return str(getattr(bot_instance, "call_sid", "") or "")
+
+
+def _inject_voice_state(
+    bot_instance: Any, tool_name: str, llm_args: Dict[str, Any]
+) -> Dict[str, Any]:
+    """Voice SessionStatePolicy (read): fill state-driven tool args.
+
+    Mirrors what ``ChatAgent._cycle_loop`` does for chat — so a template's
+    ``tool_arg_injection`` rules (e.g. thread ``cart_id`` from session state
+    into ``update_cart``) work on voice too. Applied to both voice global
+    functions and voice MCP tools. No-op when no injection rules are declared.
+    """
+    configs = getattr(bot_instance, "configurations", None)
+    injections = getattr(configs, "tool_arg_injection", None) if configs else None
+    if not injections:
+        return llm_args
+    state = getattr(bot_instance, "agent_state", None) or {}
+    return inject_tool_args(
+        tool_name=tool_name,
+        args=llm_args,
+        state_data=state,
+        chat_session_id=_voice_state_session_id(bot_instance),
+        injections=injections,
+    )
+
+
+def _reduce_voice_state(bot_instance: Any, tool_name: str, result: Any) -> None:
+    """Voice SessionStatePolicy (write): lift identifiers off a tool result
+    into ``bot_instance.agent_state`` via the template's ``state_reducers``.
+    No-op when no reducers are declared or the bot carries no agent_state.
+    """
+    configs = getattr(bot_instance, "configurations", None)
+    reducers = getattr(configs, "state_reducers", None) if configs else None
+    if not reducers:
+        return
+    state = getattr(bot_instance, "agent_state", None)
+    if state is None:
+        return
+    bot_instance.agent_state = apply_state_reducers(
+        state_data=state, tool_name=tool_name, tool_result=result, reducers=reducers
+    )
+
+
 __all__ = [
     "apply_state_reducers",
     "inject_tool_args",

app/api/routers/breeze_buddy/widget/handlers.py

@@ -600,6 +600,16 @@ async def voice_connect_handler(
             "widget_config_id": cfg.id,
             "source": "widget",
         }
+        # Carry the chat session's accumulated agent_state (reducer-built
+        # identifiers like cart_id / checkout_id, plus client-pushed facts)
+        # into the voice seed so they survive the CHAT->VOICE flip. Without
+        # this, a voice continuation of a chat that already built a cart
+        # loses the cart_id and would silently act on a fresh cart.
+        agent_state_row = await get_agent_session_state(session_id)
+        agent_state_data: Dict[str, Any] = (
+            dict(agent_state_row.data) if agent_state_row else {}
+        )
+
         # ``meta_data`` carries the voice-runtime seed (read by the
         # agent's _setup_*_transport). The widget_session_id back-link
         # is what the end_conversation drain uses to find the
@@ -611,6 +621,7 @@ async def voice_connect_handler(
             "start_node": session.current_node,
             "prior_history": prior_history,
             "seed_message_count": seed_message_count,
+            "agent_state": agent_state_data,
         }
         template_name = getattr(template, "name", None) or "widget"