68eaep codex/implementar persistência de contexto baseada em run

.codex/setup.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+NVM_DIR="$HOME/.nvm"
+[ -s "$NVM_DIR/nvm.sh" ] && \ . "$NVM_DIR/nvm.sh"
+nvm use 18
+
+npm ci
+
+if [ ! -f .env.local ] && [ -f .env.example ]; then
+  cp .env.example .env.local
+fi
+
+npm test || true
+npm run lint || true

.env.example

@@ -0,0 +1,4 @@
+OPENAI_API_KEY=your-server-key
+NEXT_PUBLIC_OPENAI_API_KEY=your-client-key
+
+NEXT_PUBLIC_USE_LLM_BACKEND=false

.github/workflows/check-agents.yml

@@ -0,0 +1,17 @@
+name: Check AGENTS documentation
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 18
+      - name: Verify AGENTS documentation updated
+        run: node scripts/check-agents-updated.js

.github/workflows/ci.yml

@@ -0,0 +1,20 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 18
+          cache: 'npm'
+          cache-dependency-path: package-lock.json
+      - run: npm install
+      - run: npm test
+      - run: npm run lint

.gitignore

@@ -30,11 +30,13 @@ yarn-error.log*
 
 # env files (can opt-in for committing if needed)
 .env*
+!.env.example
 
 # vercel
 .vercel
 
 # typescript
 *.tsbuildinfo
 next-env.d.ts
-todo.md
+data/
+todo.md

.nvmrc

@@ -0,0 +1 @@
+18

AGENTS.md

@@ -0,0 +1,77 @@
+# Documentação dos Agentes
+
+## Introdução
+Este projeto é mantido principalmente por um colaborador sem formação formal em desenvolvimento. Este arquivo serve para acumular o conhecimento adquirido sobre o código e registrar sua evolução. Para isso existe a subseção **O que mudou recentemente**, que lista de forma cronológica as alterações mais relevantes.
+
+## Visão Geral
+Este repositório contém uma aplicação demo que simula um atendimento de crédito consignado via voz. A pasta `src/app/simple` apresenta a interface web utilizada durante a conversa e toda a lógica voltada para a agente **Marlene**.
+
+Marlene é um agente de voz configurado em `src/app/agentConfigs/marlene.ts`. Ela interage em português, com fala pausada e linguagem extremamente simples para atender principalmente idosos com baixa literacia digital. O comportamento dela envolve uma máquina de estados conversacional, ferramentas próprias e um backend de simulação de empréstimos.
+
+## O que mudou recentemente
+- Julho/2024: adicionada opcao de pre-commit hook com testes e lint.
+- Agosto/2024: gerenciamento da conversa movido para uma XState machine dedicada.
+- Junho/2024: adicionadas orientacoes de contribuicao em CONTRIBUTING.md.
+- Maio/2024: projeto iniciado como demonstração do agente Marlene e fluxo de concessão de crédito consignado.
+
+
+## Principais Arquivos
+- `src/app/agentConfigs/marlene.ts` – define a personalidade de Marlene, suas ferramentas e como cada chamada de ferramenta processa a conversa.
+- `src/app/agentConfigs/utils.ts` – contém o contexto global da conversa, extração de entidades e funções para avançar a máquina de estados.
+- `src/app/loanSimulator/index.ts` – backend falso que gera dados de benefício e simulações de empréstimo.
+- `src/app/simple/machines/verificationMachine.ts` – máquina de estados para a verificação facial via câmera.
+- `src/app/simple/machines/conversationMachine.ts` – controla o fluxo principal da conversa.
+
+## Máquina de Estados da Conversa
+O fluxo da conversa é guiado por nove estados principais. A cada mensagem do usuário, `processUserInputAsync` extrai entidades (nome, número de benefício, valor desejado etc.) e `conversationMachine` decide para qual estado seguir.
+
+1. **1_greeting** – Marlene cumprimenta e começa a entender a necessidade do cliente.
+2. **2_identify_need** – coleta nome, forma de tratamento preferida e finalidade do empréstimo.
+3. **4_benefit_verification** – confirma o número do benefício e consulta limites.
+4. **5_camera_verification** – verifica identidade por câmera antes de simular valores.
+5. **6_loan_simulation** – apresenta opções de empréstimo conforme os dados coletados.
+6. **7_understanding_check** – usa `verify_understanding` para garantir que o cliente compreendeu as condições.
+7. **8_confirmation** – registra a intenção de contratar e gera documentação acessível.
+8. **9_closing** – encerra o atendimento de forma cordial.
+9. **10_early_exit** – caminho para quando o usuário desiste ou não tem interesse.
+
+`recordStateChange` persiste cada transição no contexto global (em `utils.ts`), permitindo retomar a conversa de onde parou se necessário. A função `resetConversationContext` restaura o estado inicial (`1_greeting`).
+
+## Ferramentas Disponíveis
+Marlene utiliza várias ferramentas declaradas em `marlene.ts`:
+- **animate_loan_value** – destaca valores de empréstimo na interface.
+- **open_camera** / **close_camera** – controla a câmera para verificação de identidade.
+- **verify_understanding** – avalia se o cliente entendeu o impacto do empréstimo.
+- **simplify_financial_explanation** – traduz conceitos complexos para analogias simples.
+- **consult_benefit** – consulta limites de benefício no backend simulado.
+- **create_accessible_documentation** – gera um resumo (áudio, SMS ou impresso) para o cliente.
+
+A lógica de cada ferramenta fica em `toolLogic` dentro do próprio `marlene.ts`.
+
+## Verificação por Câmera
+A verificação facial é controlada por `verificationMachine.ts`, uma máquina de estados XState independente. O fluxo é `idle → preparing → analyzing → verifying → completed`, com transições para `failed` em caso de erro ou se o tempo exceder 15 s em qualquer estágio inicial.
+
+## Backend de Empréstimo
+O arquivo `loanSimulator/index.ts` gera dados fictícios de benefício e simulações. Quando a variável de ambiente `NEXT_PUBLIC_USE_LLM_BACKEND=true` é definida, o simulador passa a chamar `/api/loan/consult`, onde um modelo de linguagem produz respostas mais detalhadas e consistentes. Os resultados são armazenados em `data/llm-benefit-cache.json` para reutilização.
+
+## Executando o Projeto
+Crie um arquivo `.env.local` com as chaves da OpenAI e demais variáveis:
+```
+OPENAI_API_KEY=sk-...
+NEXT_PUBLIC_OPENAI_API_KEY=sk-...
+NEXT_PUBLIC_USE_LLM_BACKEND=true
+```
+Instale as dependências e execute em modo de desenvolvimento:
+```
+npm install
+npm run dev
+```
+A aplicação estará disponível em `http://localhost:3000/`.
+
+Para garantir a qualidade, use:
+```
+npm test      # executa a suíte Jest
+npm run lint  # verifica o código com eslint
+```
+
+Com esta estrutura, Marlene conduz o usuário por todo o processo de crédito consignado de maneira humanizada, utilizando a máquina de estados e o backend de simulação para fornecer respostas coerentes mesmo sem conexão real com sistemas bancários.

CONTRIBUTING.md

@@ -0,0 +1,24 @@
+# Contributing
+
+Thank you for your interest in improving this project! To keep track of changes over time, please follow these guidelines when submitting a pull request.
+
+## Document your changes
+
+Whenever you make a significant modification to any source code or tests, add a short entry under the **O que mudou recentemente** section in [`AGENTS.md`](AGENTS.md). The entry should briefly describe what was changed and the month/year.
+
+## Continuous integration check
+
+The workflow [`check-agents.yml`](.github/workflows/check-agents.yml) verifies that `AGENTS.md` was updated whenever files inside `src/` or `__tests__/` change. If you forget to update the file, your pull request will fail this check with a message reminding you to document your changes.
+
+Run the existing tests and linter with `npm test` and `npm run lint` before opening a PR.
+
+
+## Optional pre-commit hook
+
+A script is available at `scripts/git-hooks/pre-commit` that runs `npm test` and `npm run lint`, the same checks executed in CI. To have it run automatically before each commit, create a symbolic link:
+
+```
+ln -s ../../scripts/git-hooks/pre-commit .git/hooks/pre-commit
+```
+
+This step is optional but recommended for frequent contributors.

README.md

@@ -11,14 +11,49 @@ You should be able to use this repo to prototype your own multi-agent realtime v
 
 ## Setup
 
-- This is a Next.js typescript app
-- Install dependencies with `npm i`
-- Add your `OPENAI_API_KEY` to your env
-- Start the server with `npm run dev`
-- Open your browser to [http://localhost:3000](http://localhost:3000) to see the app. It should automatically connect to the `simpleExample` Agent Set.
-
-## Configuring Agents
-Configuration in `src/app/agentConfigs/simpleExample.ts`
+### Requisitos
+- Node.js >=18 <21.
+- Este projeto é uma aplicação Next.js com TypeScript.
+
+### Instalação
+- Execute `npm install` para instalar as dependências.
+
+### Configuração do ambiente
+- Copie `.env.example` para `.env.local` e preencha as variáveis abaixo:
+  - `OPENAI_API_KEY` – chave usada pelo backend.
+  - `NEXT_PUBLIC_OPENAI_API_KEY` – chave visível no frontend.
+  - `NEXT_PUBLIC_USE_LLM_BACKEND` – quando `true` o backend utiliza o LLM para gerar dados fictícios; nesse caso o diretório `data/` será criado automaticamente para armazenar `llm-benefit-cache.json`.
+- Após editar `package.json`, rode `npm install` novamente caso novas dependências (como `encoding`) tenham sido adicionadas.
+
+### Servidor de desenvolvimento
+- Inicie com `npm run dev` e acesse [http://localhost:3000](http://localhost:3000). O app conecta automaticamente ao Agent Set `simpleExample`.
+- Para testar somente a interface, sem precisar de conexão com a API, use [http://localhost:3000/playground](http://localhost:3000/playground). Esse modo roda offline e serve para experimentos de UI.
+
+### Loan simulator backend
+Marlene consome o backend falso em `src/app/loanSimulator`. Rodar `npm run dev` com o Agent Set padrão (`marlene`) utiliza essas funções para simulações de empréstimo e ofertas Itaú.
+Com `NEXT_PUBLIC_USE_LLM_BACKEND=true`, o simulador passa a chamar `/api/loan/consult`, gerando dados consistentes via modelo OpenAI. O resultado fica em `data/llm-benefit-cache.json` e o diretório `data/` é criado automaticamente se ainda não existir.
+
+## Testes e lint
+- `npm test` executa a suíte Jest.
+- `npm run lint` roda o linter do projeto.
+
+## Build para produção
+- Gere o build com `npm run build`.
+- Em seguida inicie o servidor com `npm start`.
+
+## Integração contínua
+Este repositório possui um workflow de CI em `.github/workflows/ci.yml` que instala as dependências,
+executa `npm test` e `npm run lint` usando Node.js 18. O fluxo utiliza o cache do `actions/setup-node`
+para agilizar as execuções.
+
+Além disso, o workflow `.github/workflows/check-agents.yml` garante que qualquer mudança em arquivos de
+código seja acompanhada de uma atualização no `AGENTS.md`. Caso o arquivo de documentação não seja
+alterado quando arquivos em `src/` ou `__tests__/` forem modificados, o PR falhará com uma mensagem
+orientando a atualizar o `AGENTS.md`.
+
+## Configurando agentes
+Escolha um dos arquivos em `src/app/agentConfigs` para definir o comportamento dos agentes ou crie o seu próprio.
+O exemplo abaixo mostra a configuração em `src/app/agentConfigs/simpleExample.ts`:
 ```javascript
 import { AgentConfig } from "@/app/types";
 import { injectTransferTools } from "./utils";
@@ -54,8 +89,8 @@ This fully specifies the agent set that was used in the interaction shown in the
 - [frontDeskAuthentication](src/app/agentConfigs/frontDeskAuthentication) Guides the user through a step-by-step authentication flow, confirming each value character-by-character, authenticates the user with a tool call, and then transfers to another agent. Note that the second agent is intentionally "bored" to show how to prompt for personality and tone.
 - [customerServiceRetail](src/app/agentConfigs/customerServiceRetail) Also guides through an authentication flow, reads a long offer from a canned script verbatim, and then walks through a complex return flow which requires looking up orders and policies, gathering user context, and checking with `o1-mini` to ensure the return is eligible. To test this flow, say that you'd like to return your snowboard and go through the necessary prompts!
 
-### Defining your own agents
-- You can copy these to make your own multi-agent voice app! Once you make a new agent set config, add it to `src/app/agentConfigs/index.ts` and you should be able to select it in the UI in the "Scenario" dropdown menu.
+### Definindo seus próprios agentes
+- Você pode copiar esses exemplos para criar seu próprio voice app multiagente! Após criar uma nova configuração, adicione-a em `src/app/agentConfigs/index.ts` para que ela apareça no menu "Scenario" da interface.
 - To see how to define tools and toolLogic, including a background LLM call, see [src/app/agentConfigs/customerServiceRetail/returns.ts](src/app/agentConfigs/customerServiceRetail/returns.ts)
 - To see how to define a detailed personality and tone, and use a prompt state machine to collect user information step by step, see [src/app/agentConfigs/frontDeskAuthentication/authentication.ts](src/app/agentConfigs/frontDeskAuthentication/authentication.ts)
 - To see how to wire up Agents into a single Agent Set, see [src/app/agentConfigs/frontDeskAuthentication/index.ts](src/app/agentConfigs/frontDeskAuthentication/index.ts)
@@ -70,3 +105,6 @@ This fully specifies the agent set that was used in the interaction shown in the
 ## Core Contributors
 - Noah MacCallum - [noahmacca](https://x.com/noahmacca)
 - Ilan Bigio - [ibigio](https://github.com/ibigio)
+
+## Contributing
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on documenting your code changes and running the checks. Frequent contributors may want to install the optional pre-commit hook described there.

__tests__/conversationMachine.test.ts

@@ -0,0 +1,34 @@
+import { conversationMachine } from '@/app/simple/machines/conversationMachine';
+
+describe('conversationMachine', () => {
+  test('benefit and value from greeting jumps to loan simulation', () => {
+    let state = conversationMachine.initialState;
+    state = conversationMachine.transition(state, { type: 'BENEFIT_AND_VALUE_PROVIDED' });
+    expect(state.value).toBe('6_loan_simulation');
+  });
+
+  test('name leads to identify_need', () => {
+    let state = conversationMachine.initialState;
+    state = conversationMachine.transition(state, { type: 'NAME_DETECTED' });
+    expect(state.value).toBe('2_identify_need');
+  });
+
+  test('benefit confirmed without camera goes to camera verification', () => {
+    let state = {
+      value: '4_benefit_verification',
+      context: { cameraVerified: false }
+    } as any;
+    state = conversationMachine.transition(state, { type: 'BENEFIT_CONFIRMED' });
+    expect(state.value).toBe('5_camera_verification');
+  });
+
+  test('camera verification completes flow', () => {
+    let state = {
+      value: '5_camera_verification',
+      context: { cameraVerified: false }
+    } as any;
+    state = conversationMachine.transition(state, { type: 'CAMERA_VERIFIED' });
+    expect(state.value).toBe('6_loan_simulation');
+    expect(state.context.cameraVerified).toBe(true);
+  });
+});

__tests__/conversationUtils.test.ts

@@ -0,0 +1,50 @@
+import { processUserInput, exportContext, resetConversationContext, setCameraVerified } from '@/app/agentConfigs/utils';
+
+beforeEach(() => {
+  resetConversationContext();
+});
+
+describe('processUserInput', () => {
+  test('extracts entities and updates context', () => {
+    const phrase = 'Meu nome é Joao. Meu benefício é 123456. Quero um empréstimo de R$ 50.000 para reforma. Estou com meu filho.';
+    const result = processUserInput(phrase);
+
+    expect(result.entities).toEqual(expect.objectContaining({
+      name: 'Joao',
+      benefitNumber: '123456',
+      requestedAmount: 'R$ 50.000',
+      purpose: 'reforma',
+      hasCompanion: true,
+      companionType: 'filho(a)'
+    }));
+    expect(result.recommendedState).toBe('6_loan_simulation');
+
+    const context = exportContext();
+    expect(context.name).toBe('Joao');
+    expect(context.benefitNumber).toBe('123456');
+    expect(context.requestedAmount).toBe('R$ 50.000');
+    expect(context.purpose).toBe('reforma');
+    expect(context.hasCompanion).toBe(true);
+    expect(context.companionType).toBe('filho(a)');
+    expect(context.confirmedEntities.has('benefitNumber')).toBe(true);
+  });
+
+  test('recommends loan simulation when camera is verified', () => {
+    setCameraVerified(true);
+    const phrase = 'Meu benefício é 654321 e quero um empréstimo de R$ 10.000';
+    const result = processUserInput(phrase);
+    expect(result.recommendedState).toBe('6_loan_simulation');
+  });
+
+  test('context persists across multiple inputs', () => {
+    processUserInput('Meu nome é Maria');
+    let context = exportContext();
+    expect(context.name).toBe('Maria');
+    expect(context.benefitNumber).toBeUndefined();
+
+    processUserInput('Número do benefício 111222');
+    context = exportContext();
+    expect(context.name).toBe('Maria');
+    expect(context.benefitNumber).toBe('111222');
+  });
+});