Package com.tnsai.quality.security.harness

Class ReviewAgent

java.lang.Object
com.tnsai.quality.security.harness.ReviewAgent
All Implemented Interfaces:
ReviewAgentSpi
public class ReviewAgent extends Object implements ReviewAgentSpi
Default ReviewAgentSpi backed by an LLMClient (TNS-291).

Builds a structured prompt that includes the file path, the matchers that flagged the file during scan, and the file content. Asks the LLM to emit a JSON array of findings whose shape matches ReviewFinding. Parses the response, tags every finding with the agent's id (matcher = "agent:<agent-id>" and agentBackend = <agent-id>) and returns the list.

Output schema (the prompt asks the LLM for):

 [
   {
     "id": "stable-finding-id",
     "cwe": "CWE-89",
     "severity": "HIGH",
     "startLine": 10, "endLine": 12,
     "title": "...",
     "description": "...",
     "evidence": "code snippet",
     "mitigation": "fix suggestion (optional)"
   }
 ]

If no findings, the LLM returns []. Malformed or partial JSON yields an empty list and a WARN log — the AgentRun's error field captures what went wrong.

Since:
0.10.0 (TNS-291)

  • Constructor Details

    • ReviewAgent

      public ReviewAgent(String id, String version, com.tnsai.llm.LLMClient llmClient)
      Parameters:
      id - stable agent id (used in AgentRun.agentId())
      version - model / agent version (used for cache invalidation)
      llmClient - backing LLM provider

  • Method Details

    • claudeOpus

      public static ReviewAgent claudeOpus(com.tnsai.llm.LLMClient llmClient)
      Convenience factory — id "claude-opus", version derived from LLMClient.getModel().

    • gpt

      public static ReviewAgent gpt(com.tnsai.llm.LLMClient llmClient)
      Convenience factory — id "gpt", version from the LLM client's model.

    • id

      public String id()
      Description copied from interface: ReviewAgentSpi
      Stable id, e.g. "claude-opus-4-7". Used in AgentRun.agentId().
      Specified by:
      id in interface ReviewAgentSpi

    • version

      public String version()
      Description copied from interface: ReviewAgentSpi
      Backend version / model identifier. Stored on each AgentRun so the state store can detect when cached results are stale (e.g. model upgrade invalidates prior runs).
      Specified by:
      version in interface ReviewAgentSpi

    • runOnFile

      public List<ReviewFinding> runOnFile(FileRecord file, ReviewAgentSpi.ReviewContext ctx)
      Description copied from interface: ReviewAgentSpi
      Run the agent on file and return any findings.

      Implementations:

      • MUST NOT mutate file; they receive an immutable record.
      • MUST emit findings whose file equals file.path().
      • SHOULD emit a stable finding id (typically agent-id + "-" + cwe + "-" + line) so re-runs deduplicate cleanly.
      • SHOULD record the agent backend in ReviewFinding.agentBackend() for downstream filtering.
      • MAY return an empty list — "agent saw nothing" is a valid outcome.
      Specified by:
      runOnFile in interface ReviewAgentSpi