Ações de redirecionamento — redirectToBot e returnToFlow

Este documento descreve o funcionamento das ações de redirecionamento entre flows: como o estado da sessão é gerenciado, as regras de segurança aplicadas, os comportamentos dos flags e os cenários de erro.

---

Visão geral

O sistema permite que um flow transfira o controle da sessão para outro flow do mesmo router, usando a ação redirectToBot. O ponto de origem é empilhado em session.redirectHistory, permitindo que o flow destino devolva o controle via returnToFlow.

FlowA  ──[ redirectToBot ]──►  FlowB
                                   │
FlowA  ◄──[ returnToFlow ]────────┘

---

Ação redirectToBot

Campos

Campo	Tipo	Obrigatório	Padrão	Descrição
flowId	string	sim	—	ID do flow destino
blockId	string	não	onboarding do flow destino	Bloco de entrada específico
executeOnEntry	boolean	não	true	Se o bloco destino executa imediatamente
conditions	Condition[]	não	—	A ação só executa se todas as condições passarem
title	string	não	—	Nome de exibição no builder

Fluxo de execução

1. Valida que o flow destino existe no cache.
2. Valida que o flow destino pertence ao mesmo routerId da sessão (cross-router bloqueado).
3. Resolve blockId: usa action.blockId se fornecido, senão usa definition.onboardingBlockId do flow destino.
4. Valida que o bloco destino existe no flow destino.
5. Verifica o contador de hops ctx.redirectHopCount (limite: MAX_REDIRECT_HOPS = 5).
6. Empilha { flowId: session.flowId, blockId: session.currentBlockId } em session.redirectHistory.
7. Atualiza session.flowId e session.currentBlockId para o destino.
8. Retorna imediatamente — ações subsequentes do array não são executadas.

Comportamento de executeOnEntry

Valor	Comportamento
true (padrão)	walkBlocks continua a partir do bloco destino: roda inputActions, publica content, etc.
false	A sessão é posicionada no bloco destino sem executar nada. O usuário precisa enviar uma mensagem para que o bloco seja processado.

---

Ação returnToFlow

Fluxo de execução

1. Valida que session.redirectHistory não está vazia.
2. Faz pop do entry mais recente: { flowId, blockId } do flow de origem.
3. Valida que o flow de origem existe no cache e pertence ao mesmo routerId.
4. Avalia as outputConditions e defaultOutput do bloco de origem — sem re-executar suas ações.
5. Navega diretamente para o próximo bloco (bypass semantics).

Semântica de bypass

returnToFlow não re-entra no bloco de origem. Ele avalia apenas suas condições de saída e navega diretamente para o próximo bloco. Isso evita que o redirectToBot no bloco de origem seja executado novamente.

---

Segurança

Bloqueio cross-router

Tanto redirectToBot quanto returnToFlow verificam se o flow pertence ao mesmo routerId da sessão. Se não pertencer, um erro é lançado e a sessão é congelada (frozenByError), disparando handoff para humano.

Limite de hops

O contador ctx.redirectHopCount é incrementado a cada redirectToBot e verificado antes de cada redirect. Se atingir MAX_REDIRECT_HOPS = 5, a sessão é congelada.

O contador é reiniciado a zero a cada novo evento. returnToFlow não incrementa o contador.

---

Cenários de erro

Cenário	Comportamento
Flow destino não encontrado no cache	Sessão congelada → handoff para humano
Redirect cross-router	Sessão congelada → handoff para humano
Bloco destino não existe no flow destino	Sessão congelada → handoff para humano
Limite de 5 hops atingido	Sessão congelada → handoff para humano
returnToFlow sem histórico	Sessão congelada → handoff para humano
endAttendance via returnToFlow	Sessão deletada normalmente

---

Arquivos relevantes

Arquivo	Papel
packages/flow-ai-types/src/flow-definition.ts	Tipos RedirectToBotAction, ReturnToFlowAction (reexportados via index.ts)
packages/flow-ai-types/src/session.ts	Tipo SessionState (campo redirectHistory)
services/flow-ai-engine/src/runtime/actions.ts	Implementação das ações
services/flow-ai-engine/src/runtime/execute.ts	handleRedirectResult, checks pós-runActions
apps/flow-ai-core-ui/components/studio/actions/RedirectToBotActionEditor.tsx	Editor UI