Arquitetura e responsabilidades
AgentRouter mantém o roteamento; Cortex seleciona conhecimento, Skills e especialistas; AgentManager escolhe chat-v4 ou geração direta. Customer360 agrega atividades e continuidade de CustomerCase. A inteligência incremental fornece snapshots. A Livia do dashboard possui um orquestrador separado, com permissões, briefing, oportunidades, histórico, repositório e capturas de tela. Ela não é sinônimo de Customer360. O módulopackages/zappway/lib/cognitive-strategy transforma perfil, configuração e contexto tipados em uma decisão conversacional finita. Consome contexto existente, sem nova chamada de LLM, seleção de agentes ou execução de ferramentas. A auditoria com referências está em docs/audits/cognitive-strategy-layer.md.
Na Livia autenticada: orquestrador → permissões e rollout → grafo autorizado e histórico → estratégia opcional → modelo existente do context-brain → resposta com fontes existentes. Aprovação e execução de ações continuam no fluxo atual.
Contratos e identidade
CognitiveStrategyProfile tem versões imutáveis. CognitiveContext contém identificadores, ações disponíveis e indicadores limitados. CognitiveStrategyDecision contém objetivo, estágio opcional, movimento, foco, códigos de evidência, próxima ação e confiança. Não contém raciocínio privado. A confiança é uma pontuação determinística da política, sem representar probabilidade calibrada ou previsão de conversão.
zappway_livia exige a organização canônica e um ID de agente autorizado, ou a entrada autenticada do context-brain no servidor. Nome copiado, metadados do cliente e payload de Flow não selecionam esse perfil. A Livia do dashboard usa complete_request; agentes Livia provisionados usam ativação por padrão. Perfis genéricos não possuem objetivo comercial padrão. Nenhum perfil armazena preços, ofertas ou alegações de produto.
A interpretação da linguagem natural permanece no LLM existente. Instruções de estratégia são em inglês, preservando idioma de resposta, personalidade e canal. Não há regex ou listas de frases traduzidas para classificar intenção. Sinais explícitos opcionais representam evidência estruturada. O modelo deve reconhecer encerramento e pedido de atendimento humano no idioma da conversa e priorizá-los sobre a orientação consultiva.
Persistência, precedência e herança
Configurações ficam nos JSON existentesAgent.interfaceConfig (interface_config) e Tool.config, validados por Zod. Não há migração Prisma, escrita desnormalizada ou índice novo. A declaração de Flow pertence ao vínculo entre agente e ferramenta. Grafos, versões, serialização e execução em segundo plano do ZappFlux permanecem existentes. Não foi encontrado um motor de Flow exclusivo da Livia; rotinas agendadas de briefing, relatórios e alertas permanecem determinísticas.
Segurança, permissões, regras organizacionais, instruções explícitas do agente, limites de ferramentas e fatos têm precedência. chat-v4 acrescenta um bloco curto após identidade/Cortex, Skills e regras de ferramentas, preservando conhecimento, histórico e mensagens do usuário. Geração direta e Livia usam o mesmo compositor. Texto livre de clientes e snapshots nunca é interpolado nesse bloco.
Delegação carrega referência interna vinculada a organização, conversa e escopo. O filho mantém identidade, ferramentas e Skills privadas; Skills compartilhadas do pai e da organização seguem o resolvedor existente. A configuração do filho pode fornecer objetivo próprio; restrições são unidas. Delegação não promove shadow. A referência não integra DTO público, argumento de ferramenta ou metadados da resposta.
Um Flow acionado com sucesso pode preencher objetivo/estágio ausentes e adicionar restrições no turno atual. Não substitui objetivo do agente nem experimento. Flow em shadow emite decisão sem alterar mensagens ou referência herdada. A orientação anterior é substituída preservando as instruções originais. O estágio não persiste entre turnos e o acionamento não comprova conclusão do trabalho em segundo plano.
Consultas e minimização
O enriquecimento opcional consulta Conversation por ID primário e organizationId; ConversationIntelligenceState por conversationId único e organizationId. CustomerCase vem da relação existente e sua organização é conferida. A projeção de contexto existente interpreta caso/snapshot sem outro agregador de contatos ou pagamentos. O caso canônico permite continuidade entre canais. Snapshots com mais de uma hora não selecionam movimentos de perguntas pendentes ou objeções. O orçamento de enriquecimento é 150 ms. Timeout, ausência e exceções preservam o contexto de entrada. Cache local limitado a 256 decisões e 60 segundos usa organização, conversa, turno/contexto/configuração e hash da mensagem. Não armazena texto bruto nem adiciona chamadas de modelo. O provedor cobra os tokens extras do bloco curto conforme sua política.API e privacidade
PATCH de agente mantémagents.write, assertSameOrganization e formato existente; valida escopo pela identidade do servidor. GET público e externo removem configurações cognitivas da interface e ferramentas Flow. Leituras autorizadas de gestão preservam essas configurações. A sanitização de credenciais HTTP continua ativa.
Não há ferramenta para recuperar configurações. IDs de estratégia, experimentos e decisões não são enviados ao cliente. Orientação visível ao modelo não contém dados sensíveis; instruções de sistema não garantem sigilo do prompt. O módulo não resolve toda injeção de prompt nem remove campos públicos preexistentes sem relação com a estratégia.
Implantação gradual, telemetria e reversão
COGNITIVE_STRATEGY_MODE: disabled, shadow ou enabled. Ausência desativa, salvo adesão explícita do agente. disabled global ou COGNITIVE_STRATEGY_EMERGENCY_DISABLED=true prevalece sobre configurações persistidas. shadow global é um limite de rollout e não pode ser promovido pela configuração do agente. COGNITIVE_STRATEGY_ORGANIZATIONS limita organizações por IDs separados por vírgula; lista vazia não restringe. Livia do dashboard também respeita controles PA existentes e PERSONAL_ASSISTANT_COGNITIVE_STRATEGY_MODE, desativado por padrão. Turbo encaminha essas variáveis exclusivas do servidor.
A telemetria Cortex registra cognitive_strategy.evaluated, applied, shadowed, error e outcome. Inclui decisão/perfil/versão, objetivo/estágio, canal, agente/conversa/turno, Flow/experimento/coorte opcionais, movimento/ação, confiança, cache, latência, caracteres e estimativa de tokens adicionais. Não registra mensagens brutas, prompts, dados sensíveis ou raciocínio privado.
Resultados medidos são geração de resposta, delegação bem-sucedida e erro de geração. Eventos existentes de lead, pagamento e resolução podem ser correlacionados pela conversa em análise posterior; não são conversões comerciais atribuídas. Experimento tem atribuição explícita (id, variant, cohort opcional); controle avalia sem aplicar orientação. Não há plataforma nova de testes A/B. Para reverter, desative globalmente e reinicie/reimplante pelo processo normal, sem migração ou exclusão de dados.