Package com.tnsai.quality.security.harness

Interface ReviewAgentSpi

All Known Implementing Classes:
ReviewAgent
public interface ReviewAgentSpi
SPI for an agent backend that analyses a FileRecord and returns structured ReviewFindings (TNS-291).

The pipeline's process stage iterates over candidate files (those flagged by at least one MatcherSpi) and invokes the configured agent on each. Multiple agents can run in sequence — the revalidate stage cross-checks findings via a different backend.

Implementations are typically backed by an LLM provider (Claude, OpenAI, Gemini, …) routed through tnsai-llm's LLMClient. The agent is responsible for emitting findings that match the ReviewFinding schema.

Since:
0.10.0 (TNS-291)

  • Method Details

    • id

      String id()
      Stable id, e.g. "claude-opus-4-7". Used in AgentRun.agentId().

    • version

      String version()
      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).

    • runOnFile

      List<ReviewFinding> runOnFile(FileRecord file, ReviewAgentSpi.ReviewContext ctx)
      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.