improve reflection loop and add cache

src/agents/auditor/agent.ts

@@ -24,11 +24,12 @@ import {
   GATHER_CONTEXT_PROMPT,
   JUDGE_FINDINGS_PROMPT,
   RANK_FILES_PROMPT,
+  REFINE_VULNERABILITIES_PROMPT,
 } from "./prompts.ts";
 import { AuditorState, CandidateFindingSchema, FileRankingSchema, JudgeReviewSchema } from "./state.ts";
 import { buildRepoTree } from "./tools/repo-tree/tool.ts";
 import { analyzeSolidityFile } from "./tools/solidity-analyzer/tool.ts";
-import { matchLines } from "./utils.ts";
+import { buildReviewBlocks, matchLines } from "./utils.ts";
 
 const llmHaiku = createLLM("anthropic", { model: "claude-haiku-4-5", maxTokens: 20000 });
 const llmOpus = createLLM("anthropic", { model: "claude-opus-4-8", temperature: null, maxTokens: 20000 });
@@ -85,9 +86,9 @@ const defineScope: GraphNode<typeof AuditorState> = async (state) => {
   const rankingModel = llmHaiku.withStructuredOutput(RankFilesSchema);
 
   const { rankings } = await rankingModel.invoke([
-    new SystemMessage(RANK_FILES_PROMPT),
+    new SystemMessage({ content: [{ type: "text", text: RANK_FILES_PROMPT, cache_control: { type: "ephemeral" } }] }),
     new HumanMessage(
-      `File tree:\n\`\`\`\n${fileTree}\n\`\`\`\n\nSolidity files to rank:\n${solFiles.map((f) => `- ${f}`).join("\n")}`,
+      `Árvore de arquivos:\n\`\`\`\n${fileTree}\n\`\`\`\n\nArquivos Solidity para classificar:\n${solFiles.map((f) => `- ${f}`).join("\n")}`,
     ),
   ]);
 
@@ -136,21 +137,24 @@ const gatherContext: GraphNode<typeof AuditorState> = async (state) => {
   const parts: string[] = [];
 
   if (docEntries.length > 0) {
-    parts.push("## Documentation\n");
+    parts.push("## Documentação\n");
     for (const { filePath, content } of docEntries) {
       parts.push(`### ${filePath}\n${content}`);
     }
   }
 
-  parts.push(`## File Tree\n\n\`\`\`\n${state.fileTree}\n\`\`\``);
+  parts.push(`## Árvore de Arquivos\n\n\`\`\`\n${state.fileTree}\n\`\`\``);
 
-  parts.push("## Structural Analysis\n");
+  parts.push("## Análise Estrutural\n");
   for (const { analysis } of solidityEntries) {
     parts.push(analysis);
   }
 
   const model = llmHaiku.withStructuredOutput(z.object({ context: z.string() }));
-  const result = await model.invoke([new SystemMessage(GATHER_CONTEXT_PROMPT), new HumanMessage(parts.join("\n\n"))]);
+  const result = await model.invoke([
+    new SystemMessage({ content: [{ type: "text", text: GATHER_CONTEXT_PROMPT, cache_control: { type: "ephemeral" } }] }),
+    new HumanMessage(parts.join("\n\n")),
+  ]);
 
   const fileTreeBlock = `## Árvore de Arquivos\n\n\`\`\`\n${state.fileTree}\n\`\`\``;
   const structuralBlock = `## Análise Estrutural dos Contratos\n\n${solidityEntries.map(({ analysis }) => analysis).join("\n\n---\n\n")}`;
@@ -166,20 +170,14 @@ const gatherContext: GraphNode<typeof AuditorState> = async (state) => {
 const findVulnerabilities: GraphNode<typeof AuditorState> = async (state) => {
   const model = llmOpus.withStructuredOutput(z.object({ findings: z.array(CandidateFindingSchema) }));
 
-  const previousFeedback =
-    state.judgeReviews.length > 0
-      ? state.judgeReviews
-          .map((r, i) => {
-            const title = state.candidateFindings[i]?.title ?? `Finding ${i + 1}`;
-            return `- "${title}": ${r.isFalsePositive ? "FALSE POSITIVE" : "TRUE POSITIVE"}\n  Judge: ${r.review}`;
-          })
-          .join("\n")
-      : null;
+  const isReflection = state.judgeReviews.length > 0;
 
   logger.info(
     `findVulnerabilities: invoking LLM for ${state.scope.length} file(s) in parallel (iteration ${state.reflectionCount + 1})`,
   );
 
+  const cachedContext = { type: "text" as const, text: `Contexto do Protocolo:\n${state.repoContext}`, cache_control: { type: "ephemeral" as const } };
+
   const allFindings = await Promise.all(
     state.scope.map(async (filePath) => {
       let source: string;
@@ -190,16 +188,23 @@ const findVulnerabilities: GraphNode<typeof AuditorState> = async (state) => {
       }
       if (!source) return [];
 
-      let userMessage = `Contract (${filePath}):\n\n${source}\n\nProtocol Context:\n${state.repoContext}`;
-      if (previousFeedback) {
-        userMessage += `\n\nJudge feedback from previous iteration (iteration ${state.reflectionCount}):\n${previousFeedback}\n\nRevise your findings accordingly.`;
-      }
+      const fileEntries = isReflection
+        ? state.candidateFindings
+            .map((f, i) => ({ finding: f, review: state.judgeReviews[i] }))
+            .filter(({ finding }) => finding.path === filePath)
+        : [];
+
+      const isRefinement = fileEntries.length > 0;
+      const promptText = isRefinement ? REFINE_VULNERABILITIES_PROMPT : FIND_VULNERABILITIES_PROMPT;
+      const contractText = isRefinement
+        ? `Contrato (${filePath}):\n\n${source}\n\n${buildReviewBlocks(fileEntries, state.reflectionCount)}`
+        : `Contrato (${filePath}):\n\n${source}`;
 
       logger.debug(`findVulnerabilities: processing ${filePath}`);
 
       const result = await model.invoke([
-        new SystemMessage(FIND_VULNERABILITIES_PROMPT),
-        new HumanMessage(userMessage),
+        new SystemMessage({ content: [{ type: "text", text: promptText, cache_control: { type: "ephemeral" } }] }),
+        new HumanMessage({ content: [cachedContext, { type: "text", text: contractText }] }),
       ]);
 
       return result.findings.map((finding: any) => ({
@@ -231,6 +236,8 @@ const judgeFindings: GraphNode<typeof AuditorState> = async (state) => {
 
   logger.info(`judgeFindings: reviewing ${state.candidateFindings.length} candidate finding(s) in parallel`);
 
+  const cachedContext = { type: "text" as const, text: `Contexto do Protocolo:\n${state.repoContext}`, cache_control: { type: "ephemeral" as const } };
+
   const reviews = await Promise.all(
     state.candidateFindings.map(async (finding, i) => {
       let source: string;
@@ -240,14 +247,17 @@ const judgeFindings: GraphNode<typeof AuditorState> = async (state) => {
         source = "";
       }
 
-      const findingText = `[Finding ${i + 1}] ${finding.title}\nSeverity: ${finding.severity}\nDescription: ${finding.description}\nLocation: ${finding.path} lines ${finding.location}\nCode:\n\`\`\`solidity\n${finding.codeSnippet}\n\`\`\``;
+      const findingText = `[Achado ${i + 1}] ${finding.title}\nSeveridade: ${finding.severity}\nDescrição: ${finding.description}\nLocalização: ${finding.path} linhas ${finding.location}\nCódigo:\n\`\`\`solidity\n${finding.codeSnippet}\n\`\`\``;
 
       logger.debug(`judgeFindings: reviewing finding ${i + 1}: ${finding.title}`);
       return model.invoke([
-        new SystemMessage(JUDGE_FINDINGS_PROMPT),
-        new HumanMessage(
-          `Contract (${finding.path}):\n\n${source}\n\nProtocol Context:\n${state.repoContext}\n\nFinding to Review:\n\n${findingText}`,
-        ),
+        new SystemMessage({ content: [{ type: "text", text: JUDGE_FINDINGS_PROMPT, cache_control: { type: "ephemeral" } }] }),
+        new HumanMessage({
+          content: [
+            cachedContext,
+            { type: "text", text: `Contrato (${finding.path}):\n\n${source}\n\nAchado para Revisão:\n\n${findingText}` },
+          ],
+        }),
       ]);
     }),
   );

src/agents/auditor/prompts.ts

@@ -80,14 +80,32 @@ Para cada vulnerabilidade encontrada, forneça OBRIGATORIAMENTE todos os campos
 
 ## Regra de completude
 
-Reporte vulnerabilidades mesmo que não sejam imediatamente exploráveis. Vulnerabilidades podem ser de segurança, inconsistências de design, desalinhamentos econômicos ou falhas de observabilidade. Se nenhuma vulnerabilidade for encontrada, retorne um array vazio.
+Reporte vulnerabilidades mesmo que não sejam imediatamente exploráveis. Vulnerabilidades podem ser de segurança, inconsistências de design, desalinhamentos econômicos ou falhas de observabilidade. Se nenhuma vulnerabilidade for encontrada, retorne um array vazio.`;
 
-## Processamento de feedback de revisão
+export const REFINE_VULNERABILITIES_PROMPT = `Você é um auditor sênior de segurança de smart contracts refinando seus próprios achados com base no feedback de um revisor especialista independente.
 
-Se feedback de uma iteração anterior for fornecido:
-- Remova todos os achados marcados como falso positivo com confiança ≥ 80%.
-- Para achados marcados como falso positivo com confiança < 80%, reavalie e inclua apenas se houver argumento novo.
-- Adicione novos achados se o feedback apontar superfícies de ataque não cobertas.`;
+Na iteração anterior, você analisou um contrato Solidity e gerou uma lista de vulnerabilidades candidatas. Um revisor especialista avaliou cada achado e forneceu: veredicto (verdadeiro ou falso positivo), análise técnica detalhada, nível de confiança e caminhos de exploit ou razões de bloqueio.
+
+**Sua tarefa**: produzir uma lista final e refinada de vulnerabilidades incorporando o feedback do revisor.
+
+## Regras de refinamento
+
+1. **Falso positivo com confiança ≥ 80%**: remova o achado sem exceção.
+2. **Falso positivo com confiança < 80%**: reavalie com base na análise do revisor. Mantenha apenas se encontrar evidência nova ou argumento técnico que o revisor não considerou — e reflita isso na descrição.
+3. **Verdadeiro positivo**: mantenha o achado. Incorpore melhorias sugeridas pelo revisor (descrição mais precisa, snippet mais completo, recomendação mais específica, caminhos de exploit detalhados).
+4. **Novos achados**: se o revisor apontou superfícies de ataque não cobertas em seus achados originais, investigue o código-fonte e adicione novos achados para elas.
+5. Não adicione achados que não sejam suportados pelo código-fonte ou pelo feedback do revisor.
+
+## Formato de saída
+
+Idêntico ao da análise inicial. Para cada vulnerabilidade:
+- **title**: nome curto e preciso
+- **description**: (a) comportamento esperado, (b) comportamento observado, (c) impacto concreto — mínimo 3 frases, máximo 5
+- **recommendation**: correção específica e acionável com referência ao padrão correto
+- **severity**: \`"high"\` / \`"medium"\` / \`"low"\`
+- **codeSnippet**: trecho exato e completo copiado literalmente do código-fonte, sem omissões, reticências ou pseudocódigo
+
+Se nenhuma vulnerabilidade restar após o refinamento, retorne um array vazio.`;
 
 export const JUDGE_FINDINGS_PROMPT = `Você é um revisor rigoroso de segurança de smart contracts com profundo conhecimento em Solidity, execução EVM e design de protocolos. Avalie cada vulnerabilidade candidata submetida pelo auditor e determine se é um verdadeiro positivo ou um falso positivo.
 

src/agents/auditor/utils.ts

@@ -34,3 +34,49 @@ export const matchLines = (fileContent: string, codeSnippet: string): string | n
 
   return null;
 };
+
+type ReviewEntry = {
+  finding: {
+    title: string;
+    severity: string;
+    location: string;
+    description: string;
+    codeSnippet: string;
+  };
+  review: {
+    isFalsePositive: boolean;
+    confidence: number;
+    review: string;
+    exploitablePaths: string[];
+  };
+};
+
+export const buildReviewBlocks = (fileEntries: ReviewEntry[], iterationCount: number): string => {
+  const blocks = fileEntries.map(({ finding, review }, i) => {
+    const verdict = review.isFalsePositive
+      ? `FALSO POSITIVO (confiança: ${review.confidence}/100)`
+      : `VERDADEIRO POSITIVO (confiança: ${review.confidence}/100)`;
+    const pathsLabel = review.isFalsePositive ? "Razão de Bloqueio" : "Caminhos de Exploração";
+    const pathsContent =
+      review.exploitablePaths.length > 0
+        ? review.exploitablePaths.map((p) => `  - ${p}`).join("\n")
+        : "  (nenhum fornecido)";
+
+    return `[Achado ${i + 1}/${fileEntries.length}] ${finding.title}
+Severidade: ${finding.severity}
+Localização: linhas ${finding.location}
+Descrição: ${finding.description}
+
+Código:
+\`\`\`solidity
+${finding.codeSnippet}
+\`\`\`
+
+Veredito do Revisor: ${verdict}
+Análise do Revisor: ${review.review}
+${pathsLabel}:
+${pathsContent}`;
+  });
+
+  return `=== Iteração ${iterationCount} — Achados e Revisões do Especialista (${fileEntries.length} achado(s)) ===\n\n${blocks.join("\n\n---\n\n")}`;
+};