bugfix: route stickness precedences (transaction in the same intent)

agent_framework_oci/tests/test_generic_tool_response_presentation.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+from agent_framework.presentation import register_tool_response_renderer
+from agent_framework.runtime.agent_runtime import AgentRuntimeMixin
+
+
+class _Registry:
+    def __init__(self, responses):
+        self.responses = responses
+
+    def get_tool(self, name):
+        response = self.responses.get(name)
+        if response is None:
+            return None
+        return SimpleNamespace(response=response)
+
+
+class _Runtime(AgentRuntimeMixin):
+    def __init__(self, responses):
+        self.tool_router = SimpleNamespace(registry=_Registry(responses))
+
+    def _mcp_rag_directive(self, results):
+        return False, None
+
+    def _mcp_llm_composition_directive(self, results):
+        return False, None
+
+    def _transactional_action_match(self, text):
+        return None
+
+    def _workflow_payload_from_tool_result(self, item):
+        return None
+
+
+def _result(tool, data):
+    return [{"tool_name": tool, "ok": True, "result": data}]
+
+
+def test_renderer_mode_uses_application_registered_renderer():
+    def renderer(*, tool_name, result, state, agent_label):
+        return f"[{agent_label}] {result['name']} / {state['intent']}"
+
+    register_tool_response_renderer("test.entity", renderer)
+    rt = _Runtime({"consultar_algo": {"mode": "renderer", "renderer": "test.entity"}})
+    answer = rt.build_direct_mcp_answer(
+        {"user_text": "consulta", "intent": "test_intent"},
+        _result("consultar_algo", {"name": "OK"}),
+        agent_label="TestAgent",
+    )
+    assert answer == "[TestAgent] OK / test_intent"
+
+
+def test_missing_renderer_falls_back_without_breaking_runtime():
+    rt = _Runtime({"consultar_plano": {"mode": "renderer", "renderer": "missing.renderer"}})
+    answer = rt.build_direct_mcp_answer(
+        {"user_text": "qual meu plano"},
+        _result("consultar_plano", {"plano": "Controle", "internet_gb": 50, "status": "ATIVO"}),
+        agent_label="ProductAgent",
+    )
+    assert answer == "[ProductAgent] Seu plano é Controle, com 50 GB e status ATIVO."
+
+
+def test_no_declared_response_keeps_legacy_fallback():
+    rt = _Runtime({})
+    answer = rt.build_direct_mcp_answer(
+        {"user_text": "qual meu plano"},
+        _result("consultar_plano", {"plano": "Controle", "internet_gb": 50, "status": "ATIVO"}),
+        agent_label="ProductAgent",
+    )
+    assert answer == "[ProductAgent] Seu plano é Controle, com 50 GB e status ATIVO."

agent_framework_oci/tests/test_mcp_parameter_extraction_runtime.py

@@ -59,3 +59,54 @@ async def test_runtime_extracts_order_id_from_current_message():
     )
     assert result["order_id"] == "123"
     assert result["contract_key"] == "3000131180"
+
+class _ContestExtractLLM:
+    async def ainvoke(self, messages, **kwargs):
+        prompt = messages[0]["content"]
+        if "Campo: subject" in prompt:
+            return {"content": '{"subject": "TIM CTRL Redes Sociais 8.0"}'}
+        if "Campo: valor" in prompt:
+            return {"content": '{"valor": null}'}
+        return {"content": '{}'}
+
+
+class _ContestExtractRouter:
+    def parameter_extract_rules(self, tool_name):
+        return {
+            "subject": {
+                "from": "message",
+                "strategy": "llm",
+                "type": "string",
+                "description": "Extraia o item contestado.",
+            },
+            "valor": {
+                "from": "message",
+                "strategy": "llm",
+                "type": "number",
+                "description": "Extraia o valor explicitamente informado.",
+            },
+        }
+
+
+class _ContestExtractRuntime(AgentRuntimeMixin):
+    def __init__(self):
+        self.tool_router = _ContestExtractRouter()
+        self.llm = _ContestExtractLLM()
+
+
+@pytest.mark.asyncio
+async def test_new_transaction_current_message_overrides_stale_subject_from_context():
+    runtime = _ContestExtractRuntime()
+    result = await runtime._extract_mcp_parameters(
+        "contestar_cobranca",
+        {"subject": "TIM Fashion Mensal", "valor": 10.0},
+        {
+            "user_text": "nao contratei TIM CTRL Redes Sociais 8.0",
+            "sanitized_input": "nao contratei TIM CTRL Redes Sociais 8.0",
+        },
+        overwrite_from_message=True,
+    )
+    assert result["subject"] == "TIM CTRL Redes Sociais 8.0"
+    # null extraction does not destroy a pre-existing value; transaction start
+    # sanitization is about explicit current-message evidence, not blind clearing.
+    assert result["valor"] == 10.0

agent_framework_oci/tests/test_route_stickiness_transaction_shift.py

@@ -1,3 +1,4 @@
+import pytest
 from types import SimpleNamespace
 
 from agent_framework.routing.enterprise_router import EnterpriseRouter
@@ -12,3 +13,84 @@ def test_explicit_keyword_shift_preempts_stickiness():
 def test_short_generic_keyword_does_not_preempt():
     d = RouteDecision(route="x", agent="x", intent="x", method="keyword", metadata={"matched_keyword": "id"})
     assert EnterpriseRouter._is_explicit_intent_shift(d) is False
+
+
+def test_same_agent_explicit_intent_shift_must_preempt_stickiness():
+    router = object.__new__(EnterpriseRouter)
+    router.intents = []
+    # This test documents the key regression: changing from a read-only intent
+    # to a transactional intent handled by the SAME agent must still be treated
+    # as an explicit intent shift. The route() integration tests exercise the
+    # full async path; here we lock the explicitness predicate itself.
+    d = RouteDecision(
+        route="orders_agent",
+        agent="orders_agent",
+        intent="retail_order_cancel",
+        method="keyword",
+        metadata={"matched_keyword": "cancelar pedido"},
+    )
+    assert EnterpriseRouter._is_explicit_intent_shift(d) is True
+
+@pytest.mark.asyncio
+async def test_same_agent_transaction_keyword_preempts_continuity(monkeypatch):
+    """Regression: tracking -> cancelar pedido must not reuse tracking intent."""
+    from agent_framework.routing.models import IntentDefinition
+
+    class _Continuity:
+        async def evaluate(self, state, *, intents):
+            raise AssertionError("continuity must be preempted by explicit intent shift")
+
+    router = object.__new__(EnterpriseRouter)
+    router.state_policies = []
+    router.intents = [
+        IntentDefinition(
+            name="retail_order_cancel",
+            domain="retail",
+            agent="orders_agent",
+            description="cancelamento",
+            priority=20,
+            mcp_tools=["consultar_pedido", "cancelar_pedido"],
+            keywords=["cancelar pedido"],
+            examples=[],
+            enabled=True,
+        ),
+        IntentDefinition(
+            name="retail_order_tracking",
+            domain="retail",
+            agent="orders_agent",
+            description="tracking",
+            priority=30,
+            mcp_tools=["consultar_pedido", "consultar_entrega"],
+            keywords=["pedido"],
+            examples=[],
+            enabled=True,
+        ),
+    ]
+    router.continuity = _Continuity()
+    router.enable_llm_router = False
+    router.llm = None
+    router.telemetry = None
+    router.fallback_agent = "billing_agent"
+
+    decision = await router.route({
+        "user_text": "quero cancelar pedido",
+        "sanitized_input": "quero cancelar pedido",
+        "active_agent": "orders_agent",
+        "intent": "retail_order_tracking",
+        "route_decision": {
+            "route": "orders_agent",
+            "agent": "orders_agent",
+            "intent": "retail_order_tracking",
+            "domain": "retail",
+            "mcp_tools": ["consultar_pedido", "consultar_entrega"],
+        },
+        "context": {"session": {}},
+    })
+
+    assert decision.agent == "orders_agent"
+    assert decision.intent == "retail_order_cancel"
+    assert decision.method == "keyword"
+    assert decision.mcp_tools == ["consultar_pedido", "cancelar_pedido"]
+    assert decision.metadata["route_stickiness_preempted"] is True
+    assert decision.metadata["previous_agent"] == "orders_agent"
+    assert decision.metadata["previous_intent"] == "retail_order_tracking"

agent_framework_oci/tests/test_transactional_tool_flow.py

@@ -88,3 +88,202 @@ async def test_transaction_waits_then_executes_after_confirmation():
     assert runtime.calls[-1][0] == "solicitar_devolucao"
     assert runtime.calls[-1][1]["confirmed"] is True
     assert second[-1]["ok"] is True
+
+class _ContestPolicyRouter:
+    def __init__(self):
+        from types import SimpleNamespace
+        self.registry = SimpleNamespace(
+            tools={"contestar_cobranca": object()},
+            get_tool=lambda name: SimpleNamespace(selection_keywords=["contestar", "não contratei", "nao contratei"]),
+        )
+
+    def resolve_execution_policy(self, tool_name, arguments=None):
+        return {
+            "operation_type": "transactional",
+            "require_confirmation": True,
+            "requires": ["subject", "valor"],
+            "policy_source": "test",
+        }
+
+    def validate_execution_policy(self, tool_name, arguments=None):
+        policy = self.resolve_execution_policy(tool_name, arguments)
+        return True, None, policy
+
+
+class _ContestRuntime(AgentRuntimeMixin):
+    def __init__(self):
+        self.tool_router = _ContestPolicyRouter()
+        self.calls = []
+
+    async def _call_mcp_tool(self, tool_name, arguments, state):
+        self.calls.append((tool_name, dict(arguments)))
+        return {"ok": True, "tool_name": tool_name, "result": {"status": "OPENED"}}
+
+
+@pytest.mark.asyncio
+async def test_collecting_parameters_does_not_replace_collected_subject_with_stale_context():
+    """A later value-only turn must not replace an already collected subject.
+
+    Regression reproduced from Contas: subject was collected as TIM CTRL, while
+    context/tool_arguments still exposed TIM Fashion from another transaction.
+    When the user supplied only R$ 71,99, the stale context used to overwrite
+    the collected subject before confirmation.
+    """
+    runtime = _ContestRuntime()
+    state = {
+        "user_text": "R$ 71,99",
+        "sanitized_input": "R$ 71,99",
+        "route": "contestacao_agent",
+        "intent": "state:COLLECTING_CONTESTACAO_PARAMETERS",
+        "transaction_status": "COLLECTING_PARAMETERS",
+        "selected_tool_call": {
+            "tool_name": "contestar_cobranca",
+            "arguments": {
+                "subject": "TIM CTRL Redes Sociais 8.0",
+                "motivo": "não contratei",
+            },
+        },
+        # Simulates stale contextual arguments left by another action/session turn.
+        "context": {
+            "tool_arguments": {
+                "subject": "TIM Fashion Mensal",
+                "valor": 71.99,
+            }
+        },
+    }
+
+    result = await runtime.execute_tools_for_intent(state, tools=[])
+
+    assert result[-1]["transaction_status"] == "AWAITING_CONFIRMATION"
+    assert state["pending_tool_call"]["arguments"]["subject"] == "TIM CTRL Redes Sociais 8.0"
+    assert state["pending_tool_call"]["arguments"]["valor"] == 71.99
+    assert state["pending_tool_call"]["arguments"]["motivo"] == "não contratei"
+    assert state["pending_tool_call"]["arguments"]["query"] == "R$ 71,99"
+    assert runtime.calls == []
+
+class _InitialContestLLM:
+    async def ainvoke(self, messages, **kwargs):
+        prompt = messages[0]["content"]
+        if "Campo: subject" in prompt:
+            return {"content": '{"subject": "TIM CTRL Redes Sociais 8.0"}'}
+        if "Campo: valor" in prompt:
+            return {"content": '{"valor": null}'}
+        if "Campo: motivo" in prompt:
+            return {"content": '{"motivo": "não contratei"}'}
+        return {"content": '{}'}
+
+
+class _InitialContestRouter(_ContestPolicyRouter):
+    def resolve_execution_policy(self, tool_name, arguments=None):
+        return {
+            "operation_type": "transactional",
+            "require_confirmation": True,
+            "requires": ["subject"],
+            "policy_source": "test",
+        }
+
+    def parameter_extract_rules(self, tool_name):
+        return {
+            "subject": {"from": "message", "strategy": "llm", "type": "string", "description": "item"},
+            "valor": {"from": "message", "strategy": "llm", "type": "number", "description": "valor"},
+            "motivo": {"from": "message", "strategy": "llm", "type": "string", "description": "motivo"},
+        }
+
+
+class _InitialContestRuntime(AgentRuntimeMixin):
+    def __init__(self):
+        self.tool_router = _InitialContestRouter()
+        self.llm = _InitialContestLLM()
+        self.calls = []
+
+    async def _call_mcp_tool(self, tool_name, arguments, state):
+        self.calls.append((tool_name, dict(arguments)))
+        return {"ok": True, "tool_name": tool_name, "result": {"status": "OPENED"}}
+
+
+@pytest.mark.asyncio
+async def test_new_contestation_does_not_inherit_subject_or_value_from_previous_transaction():
+    runtime = _InitialContestRuntime()
+    state = {
+        "user_text": "nao contratei TIM CTRL Redes Sociais 8.0",
+        "sanitized_input": "nao contratei TIM CTRL Redes Sociais 8.0",
+        "mcp_tools": ["contestar_cobranca"],
+        "route": "contestacao_agent",
+        "intent": "contas_contestation",
+        "context": {
+            "tool_arguments": {
+                "subject": "TIM Fashion Mensal",
+                "valor": 10.0,
+                "motivo": "contestação antiga",
+            }
+        },
+    }
+
+    result = await runtime.execute_tools_for_intent(state)
+    pending = state["pending_tool_call"]["arguments"]
+    assert result[-1]["transaction_status"] == "AWAITING_CONFIRMATION"
+    assert pending["subject"] == "TIM CTRL Redes Sociais 8.0"
+    assert pending["motivo"] == "não contratei"
+    assert "valor" not in pending
+    assert runtime.calls == []
+
+@pytest.mark.asyncio
+async def test_closed_transaction_is_not_operational_context_for_next_turn():
+    runtime = _InitialContestRuntime()
+    state = {
+        "user_text": "nao contratei TIM CTRL Redes Sociais 8.0",
+        "sanitized_input": "nao contratei TIM CTRL Redes Sociais 8.0",
+        "mcp_tools": ["contestar_cobranca"],
+        "route": "contestacao_agent",
+        "intent": "contas_contestation",
+        # Historical/closed transaction must never feed the new one.
+        "transaction_status": "COMPLETED",
+        "selected_tool_call": {
+            "tool_name": "cancelar_vas_avulso",
+            "arguments": {"subject": "TIM Fashion Mensal", "valor": 10.0},
+        },
+        "pending_tool_call": {},
+        "context": {
+            "tool_arguments": {
+                "subject": "TIM Fashion Mensal",
+                "valor": 10.0,
+            }
+        },
+    }
+
+    result = await runtime.execute_tools_for_intent(state)
+
+    assert result[-1]["transaction_status"] == "AWAITING_CONFIRMATION"
+    assert state["active_transaction"]["tool_name"] == "contestar_cobranca"
+    assert state["active_transaction"]["arguments"]["subject"] == "TIM CTRL Redes Sociais 8.0"
+    assert state["pending_tool_call"]["tool_name"] == "contestar_cobranca"
+    assert state["pending_tool_call"]["arguments"]["subject"] == "TIM CTRL Redes Sociais 8.0"
+    assert state["last_transaction"]["tool_name"] == "cancelar_vas_avulso"
+    assert state["last_transaction"]["arguments"]["subject"] == "TIM Fashion Mensal"
+
+
+@pytest.mark.asyncio
+async def test_terminal_confirmation_closes_active_transaction_and_clears_latches():
+    runtime = _Runtime()
+    state = {
+        "user_text": "Quero devolver o pedido 123 porque me arrependi",
+        "sanitized_input": "Quero devolver o pedido 123 porque me arrependi",
+        "mcp_tools": ["consultar_pedido", "solicitar_devolucao"],
+        "route": "support_agent",
+        "intent": "retail_support_exchange_return",
+    }
+    await runtime.execute_tools_for_intent(state)
+    assert state["active_transaction"]["status"] == "AWAITING_CONFIRMATION"
+
+    state["user_text"] = "sim"
+    state["sanitized_input"] = "sim"
+    await runtime.execute_tools_for_intent(state)
+
+    assert state["transaction_status"] == "COMPLETED"
+    assert state["active_transaction"] is None
+    assert state["selected_tool_call"] == {}
+    assert state["pending_tool_call"] == {}
+    assert state["missing_parameters"] == []
+    assert state["next_state"] is None
+    assert state["last_transaction"]["tool_name"] == "solicitar_devolucao"
+    assert state["last_transaction"]["status"] == "COMPLETED"