Adding transaction state

specs/SPEC-002-Agent-Runtime.md

@@ -208,6 +208,21 @@ rag:
 | `RUNTIME_TIMEOUT` | Timeout geral | resposta controlada |
 
 
+
+## Contrato Durável de Estado Transacional
+
+Hosts que utilizam `AgentRuntime` com transações multi-turno DEVEM declarar no `AgentState` os campos `active_transaction` e `last_transaction`. O primeiro é a fonte canônica da transação em andamento e deve sobreviver a checkpoint/resume; o segundo mantém o snapshot da última transação terminal.
+
+```python
+active_transaction: dict[str, Any]
+last_transaction: dict[str, Any]
+```
+
+`selected_tool_call` e `pending_tool_call` são campos auxiliares/compatibilidade e não substituem o latch canônico. Durante `COLLECTING_PARAMETERS`, a retomada da transação e o consumo de parâmetros pendentes têm precedência sobre keyword routing genérico. Uma mudança de intenção só deve interromper a transação quando for inequívoca ou explicitamente solicitada pelo usuário.
+
+O contrato completo, ciclo de vida, precedência de roteamento, checklist e testes regressivos estão em [`docs/TRANSACTION_STATE_DEVELOPER_GUIDE.md`](../docs/TRANSACTION_STATE_DEVELOPER_GUIDE.md).
+
+
 ## Requisitos Não Funcionais
 
 | Categoria | Requisito |
@@ -233,6 +248,8 @@ rag:
 - [ ] Output guardrails executam antes da resposta final.
 - [ ] Judges geram JudgeResult.
 - [ ] Memória e checkpoint são persistidos conforme provider.
+- [ ] Hosts transacionais declaram `active_transaction` e `last_transaction` no `AgentState`.
+- [ ] Durante `COLLECTING_PARAMETERS`, respostas a parâmetros pendentes têm precedência sobre keyword routing genérico.
 - [ ] Erros geram NOC e resposta controlada.
 
 

specs/SPEC-010-Agent-Development.md

@@ -215,6 +215,21 @@ dataset:
           groundedness: 0.70
 ```
 
+
+## Contrato obrigatório para agentes transacionais
+
+Ao criar um agente que usa tools transacionais do framework, o desenvolvedor não deve criar um motor paralelo de coleta/confirmação. Deve reutilizar `AgentRuntime` e garantir que o `AgentState` do host mantenha o latch durável:
+
+```python
+active_transaction: dict[str, Any]
+last_transaction: dict[str, Any]
+```
+
+Durante uma transação ativa, parâmetros já coletados são preservados e novos valores são mesclados incrementalmente. Em `COLLECTING_PARAMETERS`, uma resposta que satisfaz um parâmetro pendente tem precedência sobre keywords genéricas. Mudanças de intenção explícitas e inequívocas continuam permitidas.
+
+Antes de publicar um novo template/host, execute os cenários multi-turno descritos no [`Transaction State Developer Guide`](../docs/TRANSACTION_STATE_DEVELOPER_GUIDE.md).
+
+
 ## Testes
 
 | Teste | Escopo |
@@ -273,6 +288,7 @@ dataset:
 ## Critérios de Aceite
 
 - [ ] Novo agente é criado sem alterar core do framework.
+- [ ] Se houver transações multi-turno, `AgentState` declara `active_transaction` e `last_transaction`.
 - [ ] Configuração ocorre por YAML e `.env`.
 - [ ] Agente usa BusinessContext.
 - [ ] Agente acessa MCP por router/gateway.