new feature: Multi-Intent

IMPLEMENTACAO_MULTI_INTENT.md

@@ -0,0 +1,75 @@
+# Implementação Multi-Intent
+
+## Entregas
+
+- Planejador determinístico no framework, limitado às intents, agents e tools
+  cadastrados no `routing.yaml`.
+- Priorização automática pela natureza das tools em `tool_policies.yaml`, sem
+  política por combinação.
+- Persistência padrão em `pending_topics` e histórico em `handled_topics`.
+- Tratamento de confirmação composta (`sim e ...`) sem provocar troca de intent
+  durante uma transação aberta.
+- Composição das mensagens controladas das operações secundárias antes dos
+  guardrails de saída.
+- Tratamento do cancelamento de Tamboro combinado com segunda via ou assunto
+  realmente fora do escopo.
+- Desambiguação de cobranças repetidas por seleção relativa, incluindo
+  `as duas mais caras`, alimentando o batch já suportado pelo workflow de
+  cancelamento.
+- Guias em português e inglês em `agent_framework_oci/docs/features`.
+- Integração propagada às dez variantes de backend existentes em
+  `agent_framework_oci/Tuning-Performance`, sem criar um exemplo artificial.
+- Script idempotente `agent_framework_oci/scripts/sync_pending_topics_to_tuning.py`
+  para manter as cópias sincronizadas.
+
+## Testes adicionados
+
+- `agent_framework_oci/tests/unit/test_multi_intent_planner.py`
+- `tests/migration/test_multi_intent_contas.py`
+- `agent_framework_oci/tests/unit/test_tuning_pending_topics_sync.py`
+
+## Evidências recuperadas do Contas antigo
+
+O documento antigo `docs/PENDING_TOPICS_CAMADA.md` descrevia explicitamente:
+
+- cancelamento simples;
+- cancelamento + pergunta conceitual sobre outro serviço;
+- cancelamento + solicitação fora do contexto, como alteração de CNPJ;
+- drenagem de tópicos pendentes antes da confirmação ou finalização;
+- manutenção do tópico para retry quando não fosse produzida resposta útil.
+
+Esses comportamentos foram usados como referência. A segunda via não é tratada
+como fora de escopo quando a versão atual do Contas possui uma intent/tool para
+ela; nesse caso ela é executada como consulta secundária. Somente uma solicitação
+sem capability registrada vira `off_context`.
+
+## Resultado da validação
+
+O recorte de 23 testes do planejador e das integrações transacionais afetadas
+passa integralmente. A execução ampla de `agent_framework_oci/tests/unit` e
+`tests/migration` resultou em 946 testes aprovados e 33 falhas já presentes em
+áreas fora desta alteração (principalmente checkpoints, runtime legado de
+workflows, guardrails e paridade histórica).
+
+## Limite de execução
+
+Consultas secundárias conhecidas são executadas e consolidadas. Assuntos sem
+capability são tratados como `off_context`. Uma segunda ação mutável permanece
+pendente e requer confirmação própria ou um workflow transacional coordenador.
+
+## Correção de isolamento da operação secundária
+
+O teste real `cancelar Tamboro + segunda via` revelou que o agent secundário
+herdava o snapshot operacional da transação primária. Isso fazia o
+`FaturasAgent` reutilizar `selected_tool_call=cancelar_vas_avulso` e repetir a
+confirmação do cancelamento. O estado filho agora limpa integralmente transação,
+tool selecionada/pendente, workflow, parâmetros ausentes, resultados MCP,
+`next_state`, `workflow_id` e usa a cláusula secundária também como
+`sanitized_input`. O teste `test_pending_topics_isolation.py` protege essa regra.
+
+Uma segunda execução real mostrou outro campo de roteamento que precisava ser
+isolado: `mcp_tools` permanecia com a allowlist da operação primária. O runtime
+usa esse campo de primeiro nível como fonte de verdade, portanto o
+`FaturasAgent` ainda selecionava o cancelamento. O estado filho agora sobrescreve
+`domain`, `mcp_tools` e `available_mcp_tools` exclusivamente com a capability do
+tópico secundário.