// SPDX-License-Identifier: Apache-2.0
// Copyright 2026 alibaba/open-code-review Contributors
package agent
import (
"bytes"
"context"
"crypto/sha256"
"encoding/binary"
"encoding/hex"
"encoding/json"
"errors"
"fmt"
"maps"
"runtime/debug"
"slices"
"sort"
"strconv"
"strings"
"sync"
"sync/atomic"
"time"
"github.com/alibaba/open-code-review/internal/config/rules"
"github.com/alibaba/open-code-review/internal/config/template"
"github.com/alibaba/open-code-review/internal/diff"
"github.com/alibaba/open-code-review/internal/gitcmd"
"github.com/alibaba/open-code-review/internal/llm"
"github.com/alibaba/open-code-review/internal/llmloop"
"github.com/alibaba/open-code-review/internal/model"
"github.com/alibaba/open-code-review/internal/reviewtask"
"github.com/alibaba/open-code-review/internal/session"
"github.com/alibaba/open-code-review/internal/stdout"
"github.com/alibaba/open-code-review/internal/telemetry"
"github.com/alibaba/open-code-review/internal/tool"
"go.opentelemetry.io/otel/attribute"
"go.opentelemetry.io/otel/codes"
)
// AgentWarning is re-exported from llmloop for backwards compatibility with
// existing callers (cmd/opencodereview/output.go).
type AgentWarning = llmloop.AgentWarning
// CommentWorkerPool is re-exported from reviewtask for backwards compatibility.
type CommentWorkerPool = reviewtask.CommentWorkerPool
// NewCommentWorkerPool delegates to reviewtask.NewCommentWorkerPool.
func NewCommentWorkerPool(workerCount int) *CommentWorkerPool {
return reviewtask.NewCommentWorkerPool(workerCount)
}
// Args holds all dependencies and configuration needed to run a review session.
type Args struct {
// RepoDir is the root of the git repository.
RepoDir string
// From and To define the diff range (e.g., "main..feature-branch").
From string
To string
// Commit is a single commit hash to review (vs its parent).
Commit string
// ReviewMode is one of "workspace", "range", or "commit".
// When empty, it is derived from From/To/Commit at session creation time.
// Full-scan reviews are owned by internal/scan and never reach this Args.
ReviewMode string
// Template loaded from YAML config file.
Template template.Template
// SystemRule holds path-based review rules loaded from a JSON config.
SystemRule rules.Resolver
// FileFilter holds user-configured include/exclude path patterns from rule.json.
// When nil, only the default extension and path filters apply.
FileFilter *rules.FileFilter
// LLM client for model inference.
LLMClient llm.LLMClient
// Tool registry mapping tool aliases to implementations.
Tools *tool.Registry
PlanToolDefs []llm.ToolDef
MainToolDefs []llm.ToolDef
// CommentWorkerPool — separate goroutine pool for running asynchronous
// comment post-processing tasks (tracking, re-tracking, reflection,
// suggestion validation). It executes the CODE_COMMENT tool off the
// critical path so that the main LLM tool-use loop can continue issuing
// requests while comments are being processed in the background.
//
// When nil (the default), comment processing happens synchronously inside
// executeToolCall instead of via a separate worker pool.
CommentWorkerPool *CommentWorkerPool
// Concurrency limit for per-group subtasks. MaxConcurrency <= 0 defaults to 8.
MaxConcurrency int
// Concurrent task timeout in minutes. 0 means no timeout.
ConcurrentTaskTimeout int
// CommentCollector collects review comments generated by the code_comment tool.
CommentCollector *tool.CommentCollector
// Background is an optional requirement/business context string
// injected into plan and main_task prompts via {{requirement_background}}.
Background string
// Model is the resolved model name used by every LLM request this run
// makes. The template carries no per-phase model override, so plan,
// main_task, memory compression, re-location and review filter all send
// this value.
Model string
// Provider is the configured provider name (e.g. "openai", "anthropic", or a
// custom-provider key) recorded in the manifest's execution.provider. It is a
// non-secret label; empty when the endpoint was resolved from environment
// variables with no named provider.
Provider string
// EndpointSource is the non-secret label for the configuration source that
// resolved the endpoint. It is persisted with the session for diagnostics.
EndpointSource string
// GitRunner limits the total number of concurrent git subprocesses.
// When nil, subprocesses are spawned without a global limit.
GitRunner *gitcmd.Runner
// Session is an optional session history instance for collecting conversation records.
// When nil, a default one is created automatically with git branch auto-detected from repoDir.
Session *session.SessionHistory
// Resume is an optional read-only checkpoint index from a previous review session.
Resume *session.ResumeState
// SealedInput pins this run to commit endpoints a pre-flight resolve already
// froze, instead of resolving From/To/Commit or workspace HEAD again. Admission
// and code tools must use the same immutable endpoints as the diff.
SealedInput *diff.InputResolution
// MaxTokensBudget caps the aggregate token usage (input+output) across the
// whole run; dispatch stops once the running total + a per-group look-ahead
// would exceed it. 0 = unlimited. Mirrors scan.Args.MaxTokensBudget.
MaxTokensBudget int64
// SkipFilter disables the REVIEW_FILTER_TASK even when the template
// defines one. Set via the --no-filter CLI flag.
SkipFilter bool
// RuntimeConfig carries the non-secret, allowlisted runtime settings that
// identify how this run was configured, for the manifest's
// runtime_config_sha256. It is populated by the cmd layer from the resolved
// LLM endpoint and app config; a zero value simply omits those fields from
// the hash input.
RuntimeConfig RuntimeConfig
}
// RuntimeConfig captures the allowlisted, non-secret runtime settings that
// identify how a run was configured, for the manifest's runtime_config_sha256.
// It deliberately excludes every secret: no token, and only the endpoint host
// (scheme, embedded credentials, path and query stripped) — never the full URL.
// Model and concurrency are not duplicated here; the hash folds them in from
// Args.Model and Args.MaxConcurrency.
type RuntimeConfig struct {
Protocol string // LLM wire protocol (canonical name, e.g. "anthropic")
EndpointHost string // endpoint host[:port] only, credential- and path-free
Language string // configured review output language
Timeout time.Duration // per-request timeout (0 means client default)
}
// Agent orchestrates the AI-powered code review. LLM tool-use loop / memory
// compression / token aggregation now live in internal/llmloop.Runner; this
// struct holds the diff-side state and orchestrates per-group subtasks.
type Agent struct {
args Args
diffs []model.Diff // parsed diffs
totalInsertions int64
totalDeletions int64
currentDate string
session *session.SessionHistory
subtaskFailed int64 // count of failed subtasks, accessed atomically
runner *reviewtask.Runner
resumeInfo *ResumeInfo
budgetExceeded atomic.Bool // set when a token/tool-call budget gate stopped dispatch
fileGroups []FileGroup // semantic grouping result, stored for JSON output
// inputResolution holds this run's frozen commit endpoints (resolved_base/
// head/exact_range), and repoRemoteIdentity the credential-free repository
// identity. Both are captured from git during loadDiffs (which has a context)
// and consumed by finalizeManifest to fill the manifest input/repository.
inputResolution diff.InputResolution
repoRemoteIdentity string
}
// ResumeInfo summarizes file-level reuse for a resumed review.
type ResumeInfo = session.ResumeInfo
// New creates a new Agent from the given arguments.
func New(args Args) *Agent {
if args.Tools == nil {
args.Tools = tool.NewRegistry()
}
if args.CommentCollector == nil {
args.CommentCollector = tool.NewCommentCollector()
}
if args.Session == nil {
gitBranch := detectGitBranch(context.Background(), args.RepoDir)
mode := args.ReviewMode
if mode == "" {
mode = reviewModeString(args.From, args.To, args.Commit)
}
args.Session = session.New(args.RepoDir, gitBranch, args.Model, session.SessionOptions{
ReviewMode: mode,
DiffFrom: args.From,
DiffTo: args.To,
DiffCommit: args.Commit,
ResumedFrom: resumedFromSession(args.Resume),
Operation: session.OperationReview,
LLMSource: args.EndpointSource,
})
}
a := &Agent{
args: args,
session: args.Session,
}
a.initManifest()
// DiffLookup closure captures a so the runner can resolve per-file
// model.Diff records lazily (a.diffs is only populated by loadDiffs,
// after New returns).
a.runner = reviewtask.NewRunner(reviewtask.Deps{
LLMClient: args.LLMClient,
Model: args.Model,
Template: args.Template,
Tools: args.Tools,
MainToolDefs: args.MainToolDefs,
CommentCollector: args.CommentCollector,
CommentWorkerPool: args.CommentWorkerPool,
Session: args.Session,
DiffLookup: a.findDiff,
AllDiffs: a.allDiffs,
// Non-nil only here: the same Runner serves scan, whose requests must
// stay out of the retry report. See newRequestMeta.
NewRequestMeta: a.newRequestMeta,
MaxTokensBudget: args.MaxTokensBudget,
})
return a
}
// newRequestMeta builds the retry-report identity for one logical LLM request.
//
// It is the single place provider and model are read for that purpose — the
// llmloop Runner receives it as Deps.NewRequestMeta, and the two agent-local
// requests (plan, review filter) call it directly — so the two values cannot
// drift apart between the five review request types.
//
// filePath must be the same string passed to GetOrCreateFileSession and
// requestNo the RequestNo of the record created there, because those three
// fields plus taskType are how the report joins against the session JSONL.
// Provider is intentionally passed through as-is: empty is the real value for an
// unnamed endpoint, and must not be replaced by the protocol.
func (a *Agent) newRequestMeta(filePath string, taskType session.TaskType, requestNo int) llm.RequestMeta {
return llm.RequestMeta{
Provider: a.args.Provider,
Model: a.args.Model,
FilePath: filePath,
TaskType: string(taskType),
RequestNo: requestNo,
}
}
// Run executes the full review pipeline: parse diffs -> group -> plan per group -> LLM tool-loop -> collect comments.
func (a *Agent) Run(ctx context.Context) ([]model.LlmComment, error) {
// Base prompt-cache affinity key for any LLM request in this run that a task doesn't re-scope.
// Each task conversation (plan, per-group main loop, compression, ...) refines it with llm.SessionTaskKey where it starts,
// so affinity keys stay per-conversation, the granularity provider prompt caches actually reuse prefixes at.
ctx = llm.ContextWithSessionKey(ctx, a.SessionID())
// Keep later review work under the incoming parent, not the short-lived parse span.
parseCtx, diffSpan := telemetry.StartSpan(ctx, "diff.parse")
if err := a.loadDiffs(parseCtx); err != nil {
diffSpan.End()
// The builder already exists (agent.New created session + manifest), but
// no item was selected yet. Record the run-level input failure at this
// trigger point, then finalize and persist so the run still emits a
// session_end with a failed manifest instead of looking aborted.
if b := a.session.Manifest(); b != nil {
_ = b.SetRunFailure(session.RunFailureInput, "failed to resolve review input")
}
manifestErr := a.finalizeManifest()
// Keep the load failure as the primary cause, but never drop a persistence
// failure: a run that could not even write its failed session_end must
// report both rather than silently prefer one.
loadErr := fmt.Errorf("load diffs: %w", err)
if ferr := a.session.Finalize(); ferr != nil {
manifestErr = errors.Join(manifestErr, fmt.Errorf("finalize session: %w", ferr))
}
if manifestErr != nil {
return nil, errors.Join(loadErr, manifestErr)
}
return nil, loadErr
}
telemetry.SetAttr(diffSpan, "files.changed", len(a.diffs))
telemetry.SetAttr(diffSpan, "lines.inserted", int64(a.totalInsertions))
telemetry.SetAttr(diffSpan, "lines.deleted", int64(a.totalDeletions))
diffSpan.End()
// Build the read-only DiffMap from ALL parsed diffs (before filtering)
// so the LLM can query diffs of related but filtered-out files.
a.injectDiffMap()
a.args.Tools.Freeze()
// Apply the one pre-dispatch selection — the same call `--preview` makes —
// so the set reported here is the set registerCoverage seals below.
decisions := a.selectFiles(a.diffs)
kept, counts := summarizeSelection(decisions)
totalChanged := len(a.diffs)
reviewCount := counts.Selected
fmt.Fprintf(stdout.Writer(), "[ocr] %d file(s) changed, reviewing %d in %s\n", totalChanged, reviewCount, a.args.RepoDir)
a.logExclusions(decisions)
// Register before the early return so skipped runs also explain exclusions.
// A missing exclusion record must not fail the selected review.
if err := a.registerExclusions(decisions); err != nil {
a.recordWarning("manifest_error", "", err.Error())
}
a.diffs = kept
// One run-level skip signal, keyed on the selected set rather than on what
// the run keeps: deletions are retained for prompt context but never
// reviewed, so a deletion-only changeset is skipped too. The cause goes in an
// attribute because no event name is accurate on its own — a size-gated skip
// can coexist with statically filtered files — and the reasons are ordered
// most-actionable first.
if counts.Selected == 0 {
skipReason := "no_supported_files"
switch {
case counts.TooLarge > 0:
skipReason = "too_large"
case len(kept) > 0:
skipReason = "deleted"
}
telemetry.Event(ctx, "review.skipped",
telemetry.AnyToAttr("reason", skipReason),
telemetry.AnyToAttr("file.count", totalChanged),
telemetry.AnyToAttr("too_large.count", counts.TooLarge))
}
if len(a.diffs) == 0 {
// no.files.changed keeps firing for the case it always covered, so existing
// consumers are unaffected; it stayed silent when the size gate emptied the
// set, which is the reading review.skipped adds.
if counts.TooLarge > 0 {
fmt.Fprintf(stdout.Writer(), "[ocr] %d file(s) exceeded the token size limit; nothing left to review. Skipping review.\n", counts.TooLarge)
} else {
fmt.Fprintln(stdout.Writer(), "[ocr] No supported files changed. Skipping review.")
telemetry.Event(ctx, "no.files.changed")
}
// No item was ever selected: finalize yields a skipped manifest (no
// run_failure), which is the correct terminal state for "nothing to do".
// A persistence failure here is still a delivery error — a clean skip
// cannot be claimed if its session_end never reached disk.
manifestErr := a.finalizeManifest()
if ferr := a.session.Finalize(); ferr != nil {
manifestErr = errors.Join(manifestErr, fmt.Errorf("finalize session: %w", ferr))
}
if manifestErr != nil {
return []model.LlmComment{}, manifestErr
}
return []model.LlmComment{}, nil
}
a.currentDate = time.Now().Format("2006-01-02 15:04")
telemetry.Event(ctx, "review.started",
telemetry.AnyToAttr("file.count", totalChanged),
telemetry.AnyToAttr("review.count", reviewCount),
telemetry.AnyToAttr("repo.dir", a.args.RepoDir))
// Record file count metric.
telemetry.RecordFilesReviewed(ctx, int64(reviewCount))
// Pre-run cost projection so users aren't surprised by a large review.
// Non-blocking warn-only: the estimate is order-of-magnitude and cannot
// account for agent tool-use inflation, so it is a floor; real usage is
// reported from the API after the run.
//
// Gated behind MaxTokensBudget so users who never opt into a budget see no
// new output line (the estimate is only useful to budget-setters comparing
// projected cost against their cap). Keeps the prior text-mode output
// unchanged for the common unlimited path.
if a.args.MaxTokensBudget > 0 {
est := estimateDiffCost(a.diffs)
fmt.Fprintf(stdout.Writer(), "[ocr] estimated cost: %s\n", est)
fmt.Fprintf(stdout.Writer(), "[ocr] token budget: %s (dispatch stops once exceeded)\n", humanTokens(a.args.MaxTokensBudget))
if est.TotalTokens > a.args.MaxTokensBudget {
fmt.Fprintf(stdout.Writer(), "[ocr] WARNING: estimate (%s) exceeds token budget (%s); review will stop partway\n",
humanTokens(est.TotalTokens), humanTokens(a.args.MaxTokensBudget))
}
}
// Record which run this one continued, before any item is dispatched, so the
// lineage is on disk even if the review then fails outright. It is written
// once per run and only for an accepted resume — admission was already
// decided by the command layer, which rejects before a session exists.
a.session.RecordResumeLineage(session.NewResumeLineage(
a.args.Resume, a.session.SessionID, a.args.Provider, a.args.Model))
// Step 2: Dispatch per-group subtasks concurrently
comments, err := a.dispatchSubtasks(ctx)
if len(comments) > 0 {
telemetry.RecordCommentsGenerated(ctx, int64(len(comments)))
}
// Join background memory compression before anything freezes run-level
// state. Those jobs are cancelled rather than awaited when a conversation
// ends, so their LLM request can still be in flight here; a retry report
// frozen at the command boundary would then see an un-finalized request
// and be discarded wholesale. Cheap in the normal case — every job has
// already been cancelled by now.
a.runner.WaitBackground()
// Freeze coverage into the immutable manifest before session_end embeds it,
// so the CLI and the persisted session serialize the identical object. A
// persistence failure is a delivery error in its own right: when the review
// also failed, both facts are reported (errors.Join) rather than letting the
// review error hide the fact that session_end never reached disk.
if manifestErr := a.finalizeManifest(); manifestErr != nil {
err = errors.Join(err, manifestErr)
}
if ferr := a.session.Finalize(); ferr != nil {
finalizeErr := fmt.Errorf("finalize session: %w", ferr)
if err != nil {
err = errors.Join(err, finalizeErr)
} else {
err = finalizeErr
}
}
return comments, err
}
// Session returns the session history associated with this Agent.
func (a *Agent) Session() *session.SessionHistory {
return a.session
}
// SessionID returns the current review's resumable session ID. It returns an
// empty string when the session file could not be created, so callers do not
// advertise a retry target that does not exist.
func (a *Agent) SessionID() string {
if a == nil || a.session == nil || !a.session.HasPersistence() {
return ""
}
return a.session.SessionID
}
// RunManifest returns the immutable coverage snapshot produced for this review,
// or nil when manifest construction failed. The scan path deliberately returns
// nil because scan is outside the v1 manifest scope.
func (a *Agent) RunManifest() *session.RunManifest {
if a == nil || a.session == nil {
return nil
}
return a.session.FinalManifest()
}
// ResumeInfo returns resume metadata for output. Nil means this was not a resume run.
func (a *Agent) ResumeInfo() *ResumeInfo {
if a.resumeInfo == nil {
return nil
}
info := *a.resumeInfo
return &info
}
// FilesReviewed returns the number of dispatchable files included in this review.
func (a *Agent) FilesReviewed() int64 {
return countDispatchable(a.diffs)
}
// Diffs returns the parsed diffs loaded by the agent.
func (a *Agent) Diffs() []model.Diff {
return a.diffs
}
// FileGroups returns the semantic grouping result for JSON output.
func (a *Agent) FileGroups() []FileGroupInfo {
if len(a.fileGroups) == 0 {
return nil
}
result := make([]FileGroupInfo, len(a.fileGroups))
for i, g := range a.fileGroups {
files := make([]string, len(g.Diffs))
for j, d := range g.Diffs {
files[j] = d.NewPath
}
result[i] = FileGroupInfo{Label: g.Label, Files: files}
}
return result
}
// TotalTokensUsed returns PromptTokens + CompletionTokens across all LLM calls.
// For Anthropic, PromptTokens already includes cache read/write tokens.
func (a *Agent) TotalTokensUsed() int64 { return a.runner.TotalTokensUsed() }
// TotalInputTokens returns the accumulated input/prompt tokens from all LLM calls.
func (a *Agent) TotalInputTokens() int64 { return a.runner.TotalInputTokens() }
// TotalOutputTokens returns the accumulated completion tokens from all LLM calls.
func (a *Agent) TotalOutputTokens() int64 { return a.runner.TotalOutputTokens() }
// TotalCacheReadTokens returns the accumulated cache read tokens from all LLM calls.
func (a *Agent) TotalCacheReadTokens() int64 { return a.runner.TotalCacheReadTokens() }
// TotalCacheWriteTokens returns the accumulated cache write tokens from all LLM calls.
func (a *Agent) TotalCacheWriteTokens() int64 { return a.runner.TotalCacheWriteTokens() }
// ProjectSummary returns the markdown project-level summary. Always empty
// for the diff-review path; defined so *Agent satisfies the
// cmd/opencodereview.ResultProvider interface that scan.Agent also implements.
func (a *Agent) ProjectSummary() string { return "" }
// Warnings returns a copy of non-fatal warnings recorded during review.
func (a *Agent) Warnings() []AgentWarning { return a.runner.Warnings() }
// ToolCalls returns per-tool call counts accumulated during review.
func (a *Agent) ToolCalls() map[string]int64 { return a.runner.ToolCalls() }
// ToolFailures returns failed registered-tool calls accumulated during review.
func (a *Agent) ToolFailures() []llmloop.ToolFailureDetail { return a.runner.ToolFailures() }
// BudgetExceeded reports whether the aggregate token budget gate stopped
// dispatch before all files were reviewed. The run still returns the partial
// comments collected up to that point (and a nil error), so those results are
// published before the exit status is decided.
//
// This is a diagnostic signal, not a terminal state. The stop records a pending
// failure cause (not a run_failure), so the manifest attributes the undispatched
// items to failed(budget) and its coverage alone determines the terminal state:
// partial whenever anything was covered, failed when the cap left nothing
// covered. The CLI keeps a budget-only partial at exit 0. Exhausting a per-file
// token or tool-round budget does NOT set this flag — it is an item-level
// failed(budget) outcome instead.
func (a *Agent) BudgetExceeded() bool { return a.budgetExceeded.Load() }
// recordWarning adds a non-fatal warning to the agent's warning list.
func (a *Agent) recordWarning(warningType, file, message string) {
a.runner.RecordWarning(warningType, file, message)
}
// newDiffProvider resolves the configured input to a diff provider.
func (a *Agent) newDiffProvider() *diff.Provider {
// A sealed input substitutes the commit SHAs a pre-flight resolve already froze
// for the refs the user typed. Both loads then read the same immutable objects,
// which is what makes this run's input provably the admitted one: a ref moving
// after admission can no longer change what gets reviewed. Neither mode's
// semantics shift under the substitution — range keeps its merge-base, because
// the sealed base already is that merge-base and merge-base(base, head) is base
// whenever base is an ancestor of head; commit mode keeps its first-parent
// comparison, which is derived from the commit rather than from its spelling.
// Workspace mode seals only its base and keeps reading the live working tree.
from, to, commit := a.args.From, a.args.To, a.args.Commit
if s := a.args.SealedInput; s != nil && s.ResolvedHead != "" {
switch {
case commit != "":
commit = s.ResolvedHead
case s.ResolvedBase != "":
from, to = s.ResolvedBase, s.ResolvedHead
}
}
switch {
case commit != "":
return diff.NewCommitProvider(a.args.RepoDir, commit, a.args.GitRunner)
case from != "" && to != "":
return diff.NewProvider(a.args.RepoDir, from, to, a.args.GitRunner)
default:
if a.args.SealedInput != nil {
return diff.NewWorkspaceProviderWithBase(a.args.RepoDir, *a.args.SealedInput, a.args.GitRunner)
}
return diff.NewWorkspaceProvider(a.args.RepoDir, a.args.GitRunner)
}
}
// loadDiffs populates the diff-related fields used by normal review runs.
func (a *Agent) loadDiffs(ctx context.Context) error {
provider := a.newDiffProvider()
parsed, err := provider.GetDiff(ctx)
if err != nil {
return fmt.Errorf("get diffs: %w", err)
}
a.diffs = parsed
// Freeze this run's real commit endpoints and repository identity while the
// git-backed provider and a live context are in hand; finalizeManifest reads
// these (never re-resolving) so the manifest records the input as it was at
// dispatch time, even on a later skipped or failed path.
a.inputResolution = provider.ResolveInput(ctx)
a.repoRemoteIdentity = provider.RemoteIdentity(ctx)
for i := range a.diffs {
d := &a.diffs[i]
a.totalInsertions += d.Insertions
a.totalDeletions += d.Deletions
}
return nil
}
// injectDiffMap builds a read-only DiffMap from parsed diffs and sets it
// on the FileReadDiffProvider. Must be called after loadDiffs and before
// any concurrent access to the registry.
func (a *Agent) injectDiffMap() {
m := make(map[string]string, len(a.diffs))
for i := range a.diffs {
d := &a.diffs[i]
m[effectivePath(*d)] = d.Diff
}
dm := tool.NewDiffMap(m)
if p, ok := a.args.Tools.Get(tool.FileReadDiff.Name()); ok {
if frd, ok := p.(*tool.FileReadDiffProvider); ok {
frd.SetDiffMap(dm)
}
}
}
// dispatchSubtasks runs the Plan + Main phases for each file group concurrently.
func (a *Agent) dispatchSubtasks(ctx context.Context) ([]model.LlmComment, error) {
startTime := time.Now()
defer func() {
telemetry.RecordReviewDuration(ctx, time.Since(startTime))
}()
// Pre-dispatch pass: freeze the coverage denominator before any reuse or
// concurrent dispatch. Register every non-deleted planned item (reused and
// to-run alike) into the selected set, then seal it. Must run before
// applyResume so reused items are part of the same frozen denominator.
if err := a.registerCoverage(a.diffs); err != nil {
// Registration/seal only fails on an internal invariant violation. The
// coverage denominator is then untrustworthy, so mark the run failed
// internally but continue: findings are still produced and persisted.
a.recordWarning("manifest_error", "", err.Error())
if b := a.session.Manifest(); b != nil {
_ = b.SetRunFailure(session.RunFailureInternal, "coverage registration failed")
}
}
toDispatch := a.applyResume(a.diffs)
// Filter out deleted files before grouping.
var nonDeleted []model.Diff
for _, d := range toDispatch {
if !d.IsDeleted {
nonDeleted = append(nonDeleted, d)
}
}
// Group files semantically via LLM.
groupResult := groupDiffs(ctx, nonDeleted, a.args.LLMClient, a.args.Model,
a.args.Template, llmloop.PromptTokenLimit(a.args.Template.MaxTokens),
&groupingSessionOpts{session: a.session, provider: a.args.Provider, model: a.args.Model})
groups := groupResult.groups
a.fileGroups = groups
if groupResult.usage != nil {
a.runner.RecordUsage(groupResult.usage)
}
var wg sync.WaitGroup
concurrency := a.args.MaxConcurrency
if concurrency <= 0 {
concurrency = 8
}
sem := make(chan struct{}, concurrency)
timeout := time.Duration(a.args.ConcurrentTaskTimeout) * time.Minute * time.Duration(a.args.Template.ReviewRounds())
var dispatched int64
dispatchLoop:
for gi := range groups {
group := groups[gi]
// Per-group budget look-ahead, checked BEFORE acquiring the semaphore:
// if tokens already spent plus an estimate of this group's cost would
// exceed the budget, stop scheduling further groups. Any group already
// in flight is allowed to finish — overrun is bounded by in-flight
// count (≤ concurrency).
if a.args.MaxTokensBudget > 0 {
used := a.runner.TotalTokensUsed()
var groupEst int64
for _, d := range group.Diffs {
groupEst += estimateDiffFileTokens(d)
}
projected := used + groupEst
if projected > a.args.MaxTokensBudget {
firstPath := group.Diffs[0].NewPath
fmt.Fprintf(stdout.Writer(), "[ocr] token budget reached (used %s + group est %s = projected %s > budget %s) — skipping group %q and remaining\n",
humanTokens(used), humanTokens(groupEst), humanTokens(projected), humanTokens(a.args.MaxTokensBudget), group.Label)
a.recordWarning("token_budget_reached", firstPath,
fmt.Sprintf("stopped dispatch: used %d tokens + group estimate %d = projected %d exceeds budget %d", used, groupEst, projected, a.args.MaxTokensBudget))
a.budgetExceeded.Store(true)
// Deliberately NOT SetRunFailure: budget exhaustion is a controlled
// coverage truncation, not a run-level failure. SetRunFailure would
// force terminal_state=failed regardless of coverage, and claim the
// single first-wins slot blocking genuine run-level causes (deadline,
// cancellation). Record a pending failure cause instead — Finalize
// attributes undispatched items to failed(budget) while the terminal
// state stays coverage-derived.
if b := a.session.Manifest(); b != nil {
if err := b.SetPendingFailureCause(session.FailureBudget, "aggregate token budget reached before dispatch completed"); err != nil {
a.recordWarning("manifest_error", "", err.Error())
}
}
break
}
}
select {
case sem <- struct{}{}: // acquire semaphore
case <-ctx.Done():
break dispatchLoop
}
if ctx.Err() != nil {
<-sem // release the slot acquired concurrently with cancellation
break dispatchLoop
}
dispatched += int64(len(group.Diffs))
wg.Add(1)
go func(g FileGroup) {
defer wg.Done()
defer func() { <-sem }() // release
// A panic while reviewing one group must be isolated exactly like an
// error return: counted in subtaskFailed and recorded as a warning,
// so other groups still complete and the all-failed rollup stays correct.
defer func() {
if r := recover(); r != nil {
atomic.AddInt64(&a.subtaskFailed, int64(len(g.Diffs)))
for _, d := range g.Diffs {
fingerprint := reviewItemFingerprint(a.reviewMode(), d)
a.markFailed(d, session.FailurePanic, "subtask panicked during review")
a.session.RecordReviewItemFailed(d.NewPath, d.OldPath, d.NewPath, fingerprint, fmt.Sprintf("panic: %v", r))
}
fmt.Fprintf(stdout.Writer(), "[ocr] Subtask panic for group %q: %v\n%s\n", g.Label, r, debug.Stack())
telemetry.ErrorEvent(ctx, "subtask.panic", fmt.Errorf("panic: %v", r),
telemetry.AnyToAttr("group.label", g.Label))
a.recordWarning("subtask_error", g.Label, fmt.Sprintf("panic: %v", r))
}
}()
var groupCtx context.Context
var cancel context.CancelFunc
if timeout > 0 {
groupCtx, cancel = context.WithTimeout(ctx, timeout)
defer cancel()
} else {
groupCtx = ctx
}
completed, stop, err := a.executeGroupSubtask(groupCtx, g)
if err != nil {
atomic.AddInt64(&a.subtaskFailed, int64(len(g.Diffs)))
class, reason := classifyItemError(err)
for _, d := range g.Diffs {
fingerprint := reviewItemFingerprint(a.reviewMode(), d)
a.markFailed(d, class, reason)
a.session.RecordReviewItemFailed(d.NewPath, d.OldPath, d.NewPath, fingerprint, err.Error())
}
fmt.Fprintf(stdout.Writer(), "[ocr] Subtask error for group %q: %v\n", g.Label, err)
telemetry.ErrorEvent(groupCtx, "subtask.error", err,
telemetry.AnyToAttr("group.label", g.Label))
a.recordWarning("subtask_error", g.Label, err.Error())
return
}
if !completed {
if stop != nil {
// A group that stopped short of task_done may still have produced
// usable output for some of its files before the round/token
// budget ran out. Classify per file rather than per group so a
// file that already has comments lands in Completed instead of
// Failed — otherwise a single stuck file drags its whole group
// (and, when nothing else was dispatched, the whole run) down to
// terminal_state=failed even though real coverage exists.
var failedCount int64
for _, d := range g.Diffs {
fingerprint := reviewItemFingerprint(a.reviewMode(), d)
if comments := a.args.CommentCollector.CommentsForPath(d.NewPath); len(comments) > 0 {
a.markCompleted(d)
a.session.RecordReviewItemDone(d.NewPath, d.OldPath, d.NewPath, fingerprint, comments)
continue
}
a.markFailed(d, stop.class, stop.reason)
if stop.checkpoint != "" {
a.session.RecordReviewItemFailed(d.NewPath, d.OldPath, d.NewPath, fingerprint, stop.checkpoint)
}
failedCount++
}
// subtaskFailed must count only the files actually marked failed
// above, not the whole group — a group can mix Completed and
// Failed files, and reportAsError itself is a group-level signal
// (any file with comments suppresses it) that must not be assumed
// to imply failedCount == len(g.Diffs).
if stop.reportAsError && failedCount > 0 {
atomic.AddInt64(&a.subtaskFailed, failedCount)
stopErr := errors.New(stop.checkpoint)
fmt.Fprintf(stdout.Writer(), "[ocr] Subtask error for group %q: %v\n", g.Label, stopErr)
telemetry.ErrorEvent(groupCtx, "subtask.error", stopErr,
telemetry.AnyToAttr("group.label", g.Label))
a.recordWarning("subtask_error", g.Label, stopErr.Error())
}
}
return
}
for _, d := range g.Diffs {
fingerprint := reviewItemFingerprint(a.reviewMode(), d)
comments := a.args.CommentCollector.CommentsForPath(d.NewPath)
a.markCompleted(d)
a.session.RecordReviewItemDone(d.NewPath, d.OldPath, d.NewPath, fingerprint, comments)
}
}(group)
}
wg.Wait()
// All subtasks finished — collect comments from the global collector once.
if a.args.CommentWorkerPool != nil {
a.args.CommentWorkerPool.Await()
}
if ctxErr := ctx.Err(); ctxErr != nil {
a.recordContextFailure(ctxErr)
return a.args.CommentCollector.Comments(), ctxErr
}
if dispatched == 0 {
return a.args.CommentCollector.Comments(), nil
}
failed := atomic.LoadInt64(&a.subtaskFailed)
reused := int64(0)
if a.resumeInfo != nil {
reused = a.resumeInfo.ReusedFiles
}
// A resumed run can still have usable coverage when every newly dispatched
// subtask hard-fails. Preserve the dispatcher-level all-failed error only when
// there is no reused result; otherwise the manifest is partial and the CLI
// decides the process status from the recorded failure classifications.
if failed > 0 && failed == dispatched && reused == 0 {
// Even when all subtasks failed, some may have produced comments before
// hitting the error. Return those comments instead of discarding them.
if comments := a.args.CommentCollector.Comments(); len(comments) > 0 {
return comments, nil
}
return nil, fmt.Errorf("all %d file review(s) failed — check your LLM configuration and API key", dispatched)
}
return a.args.CommentCollector.Comments(), nil
}
func (a *Agent) recordContextFailure(err error) {
if b := a.session.Manifest(); b != nil {
var setErr error
if errors.Is(err, context.DeadlineExceeded) {
// A deadline truncates pending coverage without overriding completed items.
setErr = b.SetPendingFailureCause(session.FailureTimeout, "review deadline exceeded")
} else {
// Explicit cancellation stops the run itself, not just its pending items.
setErr = b.SetRunFailure(session.RunFailureCancelled, "review was cancelled")
}
if setErr != nil {
a.recordWarning("manifest_error", "", setErr.Error())
}
}
}
func (a *Agent) applyResume(diffs []model.Diff) []model.Diff {
resume := a.args.Resume
if resume == nil {
return diffs
}
mode := a.reviewMode()
toDispatch := make([]model.Diff, 0, len(diffs))
var reused int64
for _, d := range diffs {
if d.IsDeleted {
toDispatch = append(toDispatch, d)
continue
}
fingerprint := reviewItemFingerprint(mode, d)
// ReusableItem, not Item: coverage lives in the parent manifest, so a
// checkpoint line the parent's manifest did not settle as completed or
// reused is not evidence of anything and its file is reviewed again.
item, ok := resume.ReusableItem(fingerprint)
if !ok {
toDispatch = append(toDispatch, d)
continue
}
for _, cm := range item.Comments {
a.args.CommentCollector.Add(cm)
}
a.session.RecordReviewItemReused(effectivePath(d), d.OldPath, d.NewPath, fingerprint, resume.SessionID, item.Comments)
a.markReused(d)
reused++
}
rerun := countDispatchable(toDispatch)
a.resumeInfo = &ResumeInfo{
ResumedFrom: resume.SessionID,
ReusedFiles: reused,
RerunFiles: rerun,
PreviousModel: resume.Model,
CurrentModel: a.args.Model,
}
fmt.Fprintf(stdout.Writer(), "[ocr] Resume %s: reusing %d file(s), reviewing %d file(s)\n", resume.SessionID, reused, rerun)
return toDispatch
}
func countDispatchable(diffs []model.Diff) int64 {
var n int64
for _, d := range diffs {
if !d.IsDeleted {
n++
}
}
return n
}
func (a *Agent) reviewMode() string {
if a.args.ReviewMode != "" {
return a.args.ReviewMode
}
return reviewModeString(a.args.From, a.args.To, a.args.Commit)
}
func reviewItemFingerprint(mode string, d model.Diff) string {
// The patch splitter can leave extra line endings on the final file in a
// multi-file patch. Unified diff content lines always carry a marker, so
// trimming CR/LF here removes only that position-dependent delimiter.
diffText := strings.TrimRight(d.Diff, "\r\n")
sum := sha256.Sum256([]byte(mode + "\x00" + d.OldPath + "\x00" + d.NewPath + "\x00" + diffText))
return fmt.Sprintf("%x", sum)
}
// initManifest seeds the run manifest with this run's input identity and
// execution provenance. It is nil-safe (the builder is absent on the delegate
// preview path, which never runs a review) and records the direct parent run for
// a resume. The resolved commit SHAs, source-artifact and config hashes, and
// repository identity are filled by a later phase; the mandatory input.mode is
// set here so the manifest is always constructible.
func (a *Agent) initManifest() {
b := a.session.Manifest()
if b == nil {
return
}
if parent := resumedFromSession(a.args.Resume); parent != "" {
b.SetParentRunID(parent)
}
b.SetInput(a.manifestInput())
b.SetExecution(session.ManifestExecution{
OCRVersion: llm.AppVersion,
Provider: a.args.Provider,
Model: a.args.Model,
ConfiguredConcurrency: a.args.MaxConcurrency,
MaxToolRequestTimes: a.args.Template.MaxToolRequestTimes,
RuleConfigSHA256: a.ruleConfigSHA256(),
RuntimeConfigSHA256: a.runtimeConfigSHA256(),
})
}
// manifestMode maps the review to the manifest input mode. It derives purely
// from From/To/Commit so the value is always one of the three valid input modes
// and stays stable across a resume chain (independent of an explicit ReviewMode
// label). It is also the mode component of every item_id.
func (a *Agent) manifestMode() string {
return reviewModeString(a.args.From, a.args.To, a.args.Commit)
}
// manifestInput builds the frozen input identity per the input-mode field
// matrix: range carries both requested refs, commit carries only the requested
// head, workspace carries neither.
func (a *Agent) manifestInput() session.ManifestInput {
in := session.ManifestInput{Mode: a.manifestMode()}
switch in.Mode {
case session.InputModeRange:
in.RequestedFrom = a.args.From
in.RequestedHead = a.args.To
case session.InputModeCommit:
in.RequestedHead = a.args.Commit
}
return in
}
// applyInputIdentity fills the manifest's frozen input identity and repository
// identity, then hands them to the builder through its single setters. It is the
// one authoritative assembly point (called from finalizeManifest, which runs on
// every terminal path): requested refs and mode come from manifestInput, the
// resolved commit endpoints from the git resolution captured in loadDiffs, and
// source_artifact_sha256 from the current selected set — so a skipped or failed
// run still records the real input it was given. Caller ensures b != nil.
func (a *Agent) applyInputIdentity(b *session.ManifestBuilder) {
in := a.manifestInput()
in.ResolvedBase = a.inputResolution.ResolvedBase
in.ResolvedHead = a.inputResolution.ResolvedHead
in.ExactRange = a.inputResolution.ExactRange
in.SourceArtifactSHA256 = a.sourceArtifactSHA256()
b.SetInput(in)
if id := a.repoRemoteIdentity; id != "" {
sum := sha256.Sum256([]byte(id))
b.SetRepository(session.ManifestRepository{IdentitySHA256: hex.EncodeToString(sum[:])})
}
}
// sourceArtifactSHA256 is the deterministic content identity of this run's
// selected input: for every diff it pairs the content-independent item_id with
// the raw diff fingerprint, sorts by item_id, and folds each field into SHA-256
// with an unambiguous 8-byte big-endian length prefix so no two distinct field
// sequences can collide. The empty selected set yields the canonical empty-input
// digest. It uses the raw fingerprint (not item_id) so a content change to the
// same logical file changes the artifact — exactly what a resume needs to detect
// a moved ref's new input.
//
// Range and commit reviews skip deleted diffs because their comparison endpoints
// already seal the old side: a deletion cannot appear between two fixed commits
// without one of the endpoints changing. Workspace reviews have no such seal, so
// they include deleted diffs in the identity: deleting an otherwise-unchanged
// tracked file changes the review context (an imported symbol can disappear) even
// though the deleted file itself is not dispatched as a review item. Including it
// here makes workspace admission and the persisted identity agree on that input
// change, so a resumed session fails closed instead of silently reviewing a
// different workspace.
//
// Items are deduplicated by item_id (first wins) so the hash denominator matches
// the sealed selected set — RegisterSelected ignores a duplicate item_id, so two
// diffs that normalize to the same (mode, old, new) contribute one selected item
// and must contribute one artifact entry too, keeping the two in lockstep and the
// digest deterministic regardless of diff iteration order.
func (a *Agent) sourceArtifactSHA256() string {
type pair struct{ id, fingerprint string }
pairs := make([]pair, 0, len(a.diffs))
seen := make(map[string]struct{}, len(a.diffs))
workspace := a.reviewMode() == session.ReviewModeWorkspace
for _, d := range a.diffs {
if d.IsDeleted && !workspace {
continue
}
id := a.manifestItemID(d)
if _, dup := seen[id]; dup {
continue // first wins, matching RegisterSelected's dedup
}
seen[id] = struct{}{}
pairs = append(pairs, pair{id, reviewItemFingerprint(a.reviewMode(), d)})
}
sort.SliceStable(pairs, func(i, j int) bool { return pairs[i].id < pairs[j].id })
fields := make([]string, 0, len(pairs)*2)
for _, p := range pairs {
fields = append(fields, p.id, p.fingerprint)
}
return hashFields(fields...)
}
// ruleConfigSHA256 is the deterministic identity of the resolved rule
// configuration this run operates with: the resolver's effective rule-text
// layers (custom > project > global > system, order preserved) plus the applied
// include/exclude file filter. It asks the resolver for its canonical field list
// through an optional interface — a resolver that does not expose one contributes
// only the file filter — and folds everything with the same length-prefixed
// framing as source_artifact, so any change to any layer or filter changes the
// digest. Rule order is significant (first match wins) and never sorted.
func (a *Agent) ruleConfigSHA256() string {
var fields []string
if cc, ok := a.args.SystemRule.(interface{ CanonicalConfig() []string }); ok {
fields = append(fields, cc.CanonicalConfig()...)
}
if f := a.args.FileFilter; f != nil {
for _, inc := range f.Include {
fields = append(fields, "include", inc)
}
for _, exc := range f.Exclude {
fields = append(fields, "exclude", exc)
}
}
return hashFields(fields...)
}
// runtimeConfigSHA256 is the deterministic identity of the allowlisted, non-secret
// runtime settings: protocol, model, sanitized endpoint host, language, per-request
// timeout, configured concurrency and the aggregate token budget. Every field is
// tagged so structurally different configs cannot collide once length-prefixed. No
// secret ever reaches this hash — RuntimeConfig carries only the credential-free
// host, never the token or full URL.
//
// max_tokens_budget participates because it changes what coverage a run can even
// attempt: two otherwise-identical runs with different budgets are not
// interchangeable when auditing why one stopped short.
func (a *Agent) runtimeConfigSHA256() string {
r := a.args.RuntimeConfig
return hashFields(
"protocol", r.Protocol,
"model", a.args.Model,
"host", r.EndpointHost,
"language", r.Language,
"timeout", r.Timeout.String(),
"concurrency", strconv.Itoa(a.args.MaxConcurrency),
"max_tokens_budget", strconv.FormatInt(a.args.MaxTokensBudget, 10),
)
}
// hashFields folds a sequence of string fields into one SHA-256 digest, writing an
// unambiguous 8-byte big-endian length prefix before each field so no two distinct
// field sequences can collide at a boundary. The empty sequence yields the
// canonical empty-input SHA-256. Returns the lowercase hex digest.
func hashFields(fields ...string) string {
h := sha256.New()
var lenBuf [8]byte
for _, f := range fields {
binary.BigEndian.PutUint64(lenBuf[:], uint64(len(f)))
h.Write(lenBuf[:])
_, _ = h.Write([]byte(f))
}
return hex.EncodeToString(h.Sum(nil))
}
// manifestPaths returns the old/new paths for identity derivation with the
// "/dev/null" sentinel (added/deleted files) collapsed to empty, so it never
// pollutes an item_id or a displayed path.
func manifestPaths(d model.Diff) (oldPath, newPath string) {
oldPath, newPath = d.OldPath, d.NewPath
if oldPath == "/dev/null" {
oldPath = ""
}
if newPath == "/dev/null" {
newPath = ""
}
return oldPath, newPath
}
// manifestItemID derives the content-independent item_id for a diff, keyed on
// operation, input mode and the normalized old/new paths. RegisterSelected and
// every Mark* must go through this one helper so a mismatched key can never
// silently no-op a transition.
func (a *Agent) manifestItemID(d model.Diff) string {
oldPath, newPath := manifestPaths(d)
return session.ItemID(session.OperationReview, a.manifestMode(), oldPath, newPath)
}
// coverageItem builds the selected-set entry for a diff: the content-independent
// item_id, the display path, the old path only on a rename, and the raw diff
// fingerprint retained for checkpoint cross-referencing.
func (a *Agent) coverageItem(d model.Diff) session.CoverageItem {
oldPath, newPath := manifestPaths(d)
item := session.CoverageItem{
ItemID: a.manifestItemID(d),
Path: effectivePath(d),
Fingerprint: reviewItemFingerprint(a.reviewMode(), d),
}
if oldPath != "" && oldPath != newPath {
item.OldPath = oldPath
}
return item
}
// markCompleted/markReused/markFailed are nil-safe manifest transitions. A
// non-nil error here is an internal invariant violation (a mis-keyed or
// duplicate transition), never an expected outcome, so it is surfaced as a
// warning rather than silently dropped; Finalize's validation is the backstop.
func (a *Agent) markCompleted(d model.Diff) {
b := a.session.Manifest()
if b == nil {
return
}
if err := b.MarkCompleted(a.manifestItemID(d)); err != nil {
a.recordWarning("manifest_error", d.NewPath, err.Error())
}
}
func (a *Agent) markReused(d model.Diff) {
b := a.session.Manifest()
if b == nil {
return
}
if err := b.MarkReused(a.manifestItemID(d)); err != nil {
a.recordWarning("manifest_error", d.NewPath, err.Error())
}
}
func (a *Agent) markFailed(d model.Diff, class session.FailureClass, reason string) {
b := a.session.Manifest()
if b == nil {
return
}
if err := b.MarkFailed(a.manifestItemID(d), class, reason); err != nil {
a.recordWarning("manifest_error", d.NewPath, err.Error())
}
}
// errMainTaskEmpty is returned when the review template carries no main_task
// messages. It is a sentinel so callers classify it with errors.Is instead of
// matching error text, which silently breaks the moment the wording changes.
var errMainTaskEmpty = errors.New("main_task.messages is empty in template")
// classifyItemError maps a subtask error to a stable item failure class and a
// safe, generic reason. It never returns the raw error text (which may embed a
// provider payload, credentials or absolute paths); the full error is persisted
// separately in the session checkpoint. Context deadline/cancel are recognized
// via errors.Is, and the
// empty-template precondition is a configuration failure.
func classifyItemError(err error) (session.FailureClass, string) {
switch {
case errors.Is(err, llm.ErrRequestTimeout):
return session.FailureTimeout, "LLM request timed out; configure OCR_LLM_TIMEOUT or provider timeout_sec"
case errors.Is(err, context.DeadlineExceeded):
return session.FailureTimeout, "file review exhausted its task deadline (--timeout)"
case errors.Is(err, context.Canceled):
return session.FailureCancelled, "file review was cancelled"
case errors.Is(err, errMainTaskEmpty):
return session.FailureConfiguration, "review template main_task is empty"
default:
return session.FailureProvider, "provider or subtask request failed"
}
}
// classifyMainLoopStop maps a non-error, non-completed main-loop stop to an item
// failure class and a safe reason. Only the configured limits — the
// max-tool-request rounds and the aggregate token budget — are declared budget
// stops, so only they may use the budget classification; every other stop keeps
// the unknown class, because the FailureClass taxonomy has no category that fits
// an empty-round or compression exit. Stating that as "not a declared limit"
// rather than case-by-case is deliberate: a stop added to the enum later must
// default to the honest catch-all class, never inherit "budget".
//
// The reason text comes from stop.Reason(), shared with the scan path so the
// same stop cannot read differently in the two commands' output. In --format
// json runs the progress lines that would say why an item stopped are discarded,
// so that string is the only stop diagnostic that leaves a CI runner.
func classifyMainLoopStop(stop llmloop.MainLoopStop) (session.FailureClass, string) {
if stop == llmloop.StopMaxRounds || stop == llmloop.StopTokenBudget {
return session.FailureBudget, stop.Reason()
}
return session.FailureUnknown, stop.Reason()
}
// subtaskStop is the structured, non-error reason a single-file review stopped
// short of task_done. It lets the dispatcher classify manifest coverage from an
// explicit cause recorded at the trigger point, instead of re-parsing free text
// or ctx state. class + reason feed the manifest MarkFailed; checkpoint is the
// detailed human-facing text preserved for the legacy RecordReviewItemFailed
// resume record (unchanged behavior).
type subtaskStop struct {
class session.FailureClass
reason string
checkpoint string
reportAsError bool
}
// registerCoverage freezes the coverage denominator before any reuse or
// concurrent dispatch: it registers every non-deleted diff as a selected item
// and seals the set. Deleted files are excluded — they are never dispatched, so
// a registered item that never received a Mark* would be swept to a bogus
// failure at Finalize. Nil-safe (no-op without a builder). It returns the first
// registration or seal error so the caller can flag the denominator as
// untrustworthy.
func (a *Agent) registerCoverage(diffs []model.Diff) error {
b := a.session.Manifest()
if b == nil {
return nil
}
for _, d := range diffs {
if d.IsDeleted {
continue
}
if err := b.RegisterSelected(a.coverageItem(d)); err != nil {
return err
}
}
return b.SealSelected()
}
// registerExclusions records selection exclusions, including deletions.
func (a *Agent) registerExclusions(decisions []fileDecision) error {
b := a.session.Manifest()
if b == nil {
return nil
}
var errs []error
for _, dec := range decisions {
if dec.selected() {
continue
}
oldPath, newPath := manifestPaths(dec.Diff)
item := session.ExcludedItem{
ItemID: a.manifestItemID(dec.Diff),
Path: effectivePath(dec.Diff),
ExcludeReason: dec.Reason,
}
if oldPath != "" && newPath != "" && oldPath != newPath {
item.OldPath = oldPath
}
if err := b.RegisterExcluded(item); err != nil {
errs = append(errs, err)
}
}
return errors.Join(errs...)
}
// finalizeManifest freezes the run's coverage builder and stores the immutable
// manifest on the session for persistence and CLI consumption. Nil-safe. A
// construction (validation) failure leaves the stored manifest nil — session_end
// then persists in legacy form — and is returned as a delivery error so the CLI
// cannot report a manifest-enabled review as successful without a valid snapshot.
// Elapsed is measured from the session start so both outlets report the same duration.
func (a *Agent) finalizeManifest() error {
b := a.session.Manifest()
if b == nil {
return nil
}
// Freeze the input/repository identity from this run's captured resolution and
// current selected set before the manifest closes. Done here (not in New) so
// the git-resolved endpoints and the post-filter source artifact are both
// available, and so every terminal path records the same identity.
a.applyInputIdentity(b)
m, err := b.Finalize(time.Since(a.session.StartTime))
if err != nil {
a.recordWarning("manifest_error", "", err.Error())
return fmt.Errorf("finalize run manifest: %w", err)
}
a.session.SetFinalManifest(&m)
return nil
}
func resumedFromSession(resume *session.ResumeState) string {
if resume == nil {
return ""
}
return resume.SessionID
}
// buildMainTaskMessages renders the MAIN_TASK messages for one review round.
// planResult is "" for round 2+ (stripped via stripEmptyPlanBlock).
// confirmed is "" on round 1 (stripped via stripEmptyConfirmedBlock).
func (a *Agent) buildMainTaskMessages(rule, changeFiles, diffs, planResult, confirmed string) []llm.Message {
rawMsgs := a.args.Template.MainTask.Messages
messages := make([]llm.Message, 0, len(rawMsgs))
for _, m := range rawMsgs {
content := m.Content
content = strings.ReplaceAll(content, "{{current_system_date_time}}", a.currentDate)
content = strings.ReplaceAll(content, "{{system_rule}}", rule)
content = strings.ReplaceAll(content, "{{change_files}}", changeFiles)
content = strings.ReplaceAll(content, "{{diffs}}", diffs)
content = strings.ReplaceAll(content, "{{requirement_background}}", a.args.Background)
if planResult == "" {
content = stripEmptyPlanBlock(content)
}
content = strings.ReplaceAll(content, "{{plan_guidance}}", planResult)
if confirmed == "" {
content = stripEmptyConfirmedBlock(content)
}
content = strings.ReplaceAll(content, "{{confirmed_comments}}", confirmed)
messages = append(messages, llm.NewTextMessage(m.Role, content))
}
return messages
}
// checkPromptBudget validates that the rendered messages fit within the token
// limit. Returns a *subtaskStop when they do not, nil otherwise.
func (a *Agent) checkPromptBudget(ctx context.Context, messages []llm.Message, groupKey string, round int) *subtaskStop {
tokenCount := llmloop.CountMessagesTokens(messages)
maxAllowed := a.args.Template.MaxTokens
tokenLimit := llmloop.PromptTokenLimit(maxAllowed)
if tokenCount <= tokenLimit {
return nil
}
msg := fmt.Sprintf("prompt tokens (%d) exceed %d%% of max_tokens(%d) [round %d]", tokenCount, 80, maxAllowed, round)
fmt.Fprintf(stdout.Writer(), "[ocr] WARNING: %s for group %q\n", msg, groupKey)
a.recordWarning("token_threshold_exceeded", groupKey, msg)
telemetry.Event(ctx, "token.threshold.exceeded",
telemetry.AnyToAttr("group.label", groupKey),
telemetry.AnyToAttr("tokens", tokenCount),
telemetry.AnyToAttr("max_tokens", maxAllowed),
telemetry.AnyToAttr("round", round))
return &subtaskStop{
class: session.FailureBudget,
reason: "prompt exceeded the configured token budget",
checkpoint: msg,
}
}
// groupHasComments reports whether any file in the group has comments.
func (a *Agent) groupHasComments(g FileGroup) bool {
for _, d := range g.Diffs {
if len(a.args.CommentCollector.CommentsForPath(d.NewPath)) > 0 {
return true
}
}
return false
}
// diffsChurn returns the set's aggregate churn and its largest single-file
// churn. Both feed Template.PlanRequired; the aggregate alone feeds
// Template.GroupingPlan, which runs before any FileGroup exists and so takes
// the diffs directly.
func diffsChurn(diffs []model.Diff) (total, maxFile int64) {
for _, d := range diffs {
changed := d.Insertions + d.Deletions
total += changed
if changed > maxFile {
maxFile = changed
}
}
return total, maxFile
}
// executeGroupSubtask performs the Plan Phase + Main Loop for a file group. It
// returns (completed, stop, err): a hard Go error (err) for provider/config/ctx
// failures the caller classifies via classifyItemError, or a structured *stop
// for a non-error early exit (token budget, main-loop stop) carrying the manifest
// class recorded at its trigger point. A completed review returns (true, nil, nil).
func (a *Agent) executeGroupSubtask(ctx context.Context, g FileGroup) (bool, *subtaskStop, error) {
groupKey := fileGroupKey(g.Diffs)
ctx, span := telemetry.StartSpan(ctx, "subtask.execute.group."+groupKey)
defer span.End()
totalChanged, maxFileChanged := diffsChurn(g.Diffs)
telemetry.SetAttr(span, "group.label", groupKey)
telemetry.SetAttr(span, "group.file_count", len(g.Diffs))
telemetry.SetAttr(span, "lines.changed", totalChanged)
telemetry.SetAttr(span, "lines.changed.max_file", maxFileChanged)
if ctx.Err() != nil {
return false, nil, ctx.Err()
}
// Build concatenated diffs as per-file XML elements
concatenatedDiffs := buildConcatenatedDiffs(g.Diffs)
// Build change-files list excluding all group members
changeFilesExcludingGroup := a.buildChangeFilesExceptGroup(g.Diffs)
// Merge system rules for all files in the group
rule := a.resolveGroupSystemRule(g.Diffs)
// Phase 1: Plan (skip when changes are below threshold)
planEnabled := a.args.Template.PlanTask != nil && len(a.args.Template.PlanTask.Messages) > 0
planRequired := a.args.Template.PlanRequired(len(g.Diffs), totalChanged, maxFileChanged)
var planResult string
switch {
case !planEnabled:
// No plan task configured.
case planRequired:
var err error
planResult, err = a.executeGroupPlanPhase(ctx, g, concatenatedDiffs, changeFilesExcludingGroup, rule)
if err != nil {
fmt.Fprintf(stdout.Writer(), "[ocr] Plan phase failed for group %q: %v (continuing without plan)\n", groupKey, err)
telemetry.Eventf(ctx, "plan.failed", err.Error(),
telemetry.AnyToAttr("group.label", groupKey))
planResult = ""
}
default:
fmt.Fprintf(stdout.Writer(), "[ocr] Skipping plan phase for group %q (%d file(s), max %d lines, total %d lines)\n",
groupKey, len(g.Diffs), maxFileChanged, totalChanged)
telemetry.Event(ctx, "plan.skipped",
telemetry.AnyToAttr("group.label", groupKey),
telemetry.AnyToAttr("group.file_count", len(g.Diffs)),
telemetry.AnyToAttr("lines.changed", totalChanged),
telemetry.AnyToAttr("lines.changed.max_file", maxFileChanged),
telemetry.AnyToAttr("threshold", a.args.Template.PlanModeLineThreshold),
telemetry.AnyToAttr("threshold.group", a.args.Template.PlanModeGroupLineThreshold))
}
// Phase 2: Main task loop (multi-round)
if len(a.args.Template.MainTask.Messages) == 0 {
return false, nil, errMainTaskEmpty
}
maxRounds := a.args.Template.ReviewRounds()
// Per-path baselines for concurrency-safe round-delta computation.
baseline := make(map[string]int, len(g.Diffs))
for _, d := range g.Diffs {
baseline[d.NewPath] = len(a.args.CommentCollector.CommentsForPath(d.NewPath))
}
var (
confirmed []model.LlmComment
lastStop *subtaskStop
completed bool
)
for round := 1; round <= maxRounds; round++ {
if ctx.Err() != nil {
return false, nil, ctx.Err()
}
if round > 1 && a.args.MaxTokensBudget > 0 && (a.budgetExceeded.Load() || a.runner.TotalTokensUsed() > a.args.MaxTokensBudget) {
fmt.Fprintf(stdout.Writer(), "[ocr] Aggregate budget exceeded, skipping round %d for group %q\n", round, groupKey)
// A group can finish a round over budget with no other gate noticing,
// so record it here too or the run would report the budget as intact.
if a.budgetExceeded.CompareAndSwap(false, true) {
a.recordWarning("token_budget_reached", g.Diffs[0].NewPath,
fmt.Sprintf("skipped round %d of group %q: used %d tokens exceeds budget %d", round, groupKey, a.runner.TotalTokensUsed(), a.args.MaxTokensBudget))
}
break
}
// Round 2+ strips the plan to avoid it acting as a coverage ceiling.
roundPlan := planResult
if round > 1 {
roundPlan = ""
}
confirmedText := buildConfirmedCommentsBlock(confirmed)
messages := a.buildMainTaskMessages(rule, changeFilesExcludingGroup, concatenatedDiffs, roundPlan, confirmedText)
if stop := a.checkPromptBudget(ctx, messages, groupKey, round); stop != nil {
if round == 1 {
return false, stop, nil
}
break
}
mainCompleted, mainStop, err := func() (bool, llmloop.MainLoopStop, error) {
ctx, mainSpan := telemetry.StartSpan(ctx, "main.loop")
defer mainSpan.End()
telemetry.SetAttr(mainSpan, "group.label", groupKey)
telemetry.SetAttr(mainSpan, "round", round)
completed, stop, err := a.runner.RunMainTask(ctx, messages, groupKey)
if err != nil {
mainSpan.SetStatus(codes.Error, err.Error())
mainSpan.RecordError(err)
return false, stop, err
}
return completed, stop, nil
}()
if err != nil {
if round == 1 {
return false, nil, err
}
a.recordWarning("review_round_failed", groupKey, fmt.Sprintf("round %d: %v", round, err))
fmt.Fprintf(stdout.Writer(), "[ocr] Round %d failed for group %q: %v (keeping earlier findings)\n", round, groupKey, err)
break
}
// Drain async comment workers before computing deltas.
if a.args.CommentWorkerPool != nil {
a.args.CommentWorkerPool.AwaitKey(groupKey)
}
a.executeGroupReviewFilter(ctx, g, baseline)
// Compute newly confirmed comments from this round.
var newlyConfirmed []model.LlmComment
for _, d := range g.Diffs {
all := a.args.CommentCollector.CommentsForPath(d.NewPath)
if b := baseline[d.NewPath]; len(all) > b {
newlyConfirmed = append(newlyConfirmed, all[b:]...)
}
baseline[d.NewPath] = len(all)
}
confirmed = append(confirmed, newlyConfirmed...)
if !mainCompleted {
if mainStop == llmloop.StopTokenBudget {
// The runner stopped this conversation on the aggregate budget. Surface
// it the same way the dispatch gate does, so BudgetExceeded() and the
// warning list agree with the item's failed(budget) classification.
if a.budgetExceeded.CompareAndSwap(false, true) {
a.recordWarning("token_budget_reached", g.Diffs[0].NewPath,
fmt.Sprintf("stopped group %q mid-review: used %d tokens exceeds budget %d", groupKey, a.runner.TotalTokensUsed(), a.args.MaxTokensBudget))
}
}
class, reason := classifyMainLoopStop(mainStop)
lastStop = &subtaskStop{
class: class,
reason: reason,
checkpoint: fmt.Sprintf("main_task did not complete before stopping (round %d/%d)", round, maxRounds),
reportAsError: !a.groupHasComments(g),
}
break
}
completed = true
if len(newlyConfirmed) == 0 {
fmt.Fprintf(stdout.Writer(), "[ocr] Round %d/%d added no new findings for group %q; stopping early\n", round, maxRounds, groupKey)
break
}
if len(confirmed) >= confirmedCap {
fmt.Fprintf(stdout.Writer(), "[ocr] Group %q reached %d confirmed findings; skipping further rounds\n", groupKey, len(confirmed))
break
}
}
if lastStop != nil {
return false, lastStop, nil
}
return completed, nil, nil
}
// filterTools defines the two mutually exclusive tools for the review filter.
// The model MUST call exactly one: either report incorrect comments, or approve all.
var filterTools = []llm.ToolDef{
{
Type: "function",
Function: llm.FunctionDef{
Name: "report_incorrect_comments",
Description: "Report review comments that this diff proves to be factually wrong: either the code they target is absent from the diff, " +
"or one diff line literally contradicts their central claim. For every id listed you must be able to name that line. " +
"Do not use this for comments you merely find unconvincing, unverifiable, or low-value, nor for comments about memory safety, " +
"concurrency, linkage consistency, unused parameters, or behavioral changes.",
// Field order matters and is load-bearing. Go serializes these
// properties alphabetically, so "analysis" is emitted before
// "comment_ids" and the model reasons before it commits. With the
// order reversed it picks ids first and cannot retract them: replaying
// recorded sessions showed it writing "this is a protected subject, I
// should not remove it" in the later field while the id stayed in the
// earlier one. Do not rename these fields into a different relative
// order.
Parameters: map[string]any{
"type": "object",
"properties": map[string]any{
"analysis": map[string]any{
"type": "array",
"description": "Work through every candidate comment BEFORE deciding. One entry per candidate: its id, " +
"whether its subject hits the protected-subject veto (Step 1) or the value veto (Step 2), " +
"the exact diff line that refutes it if any, and your final call. " +
"Only ids you conclude here as removable may appear in comment_ids.",
"items": map[string]any{"type": "string"},
},
"comment_ids": map[string]any{
"type": "array",
"description": "IDs concluded removable in analysis, e.g. [\"c-0\", \"c-2\"]. Must not be empty.",
"items": map[string]any{"type": "string"},
},
},
"required": []any{"analysis", "comment_ids"},
},
},
},
{
Type: "function",
Function: llm.FunctionDef{
Name: "approve_all_comments",
Description: "Keep every review comment. Call this whenever no comment clears the removal bar — including when comments look doubtful, " +
"cannot be verified from the diff alone, or seem minor. This is the expected outcome for most files.",
Parameters: map[string]any{
"type": "object",
"properties": map[string]any{},
},
},
},
}
// buildConcatenatedDiffs formats all diffs in the group as per-file XML elements.
func buildConcatenatedDiffs(diffs []model.Diff) string {
var sb strings.Builder
for i, d := range diffs {
sb.WriteString("\n")
sb.WriteString(d.Diff)
sb.WriteString("\n")
if i < len(diffs)-1 {
sb.WriteString("\n\n")
}
}
return sb.String()
}
// formatDiffEntry renders one changed file as STATUS path (+N/-M). It is the
// shared shape for both the grouping file list and the other-changed-files
// block, so every prompt that enumerates files presents them identically.
func formatDiffEntry(d model.Diff) string {
status := "MODIFIED"
switch {
case d.IsNew:
status = "ADDED"
case d.IsDeleted:
status = "DELETED"
case d.IsRenamed:
status = "RENAMED"
}
return fmt.Sprintf("%s %s (+%d/-%d)", status, effectivePath(d), d.Insertions, d.Deletions)
}
// buildChangeFilesExceptGroup returns a formatted list of changed files excluding all group members.
func (a *Agent) buildChangeFilesExceptGroup(groupDiffs []model.Diff) string {
exclude := make(map[string]bool, len(groupDiffs))
for _, d := range groupDiffs {
exclude[d.NewPath] = true
exclude[d.OldPath] = true
}
var sb strings.Builder
for _, d := range a.diffs {
if d.IsBinary || exclude[d.NewPath] || exclude[d.OldPath] {
continue
}
// Separator before the entry, conditional on something already being
// written, rather than after it conditional on the a.diffs index: the loop
// skips binaries and group members, so an index-based test emits a trailing
// newline whenever the final diff is one of the skipped ones. Excluding a
// whole group makes that the common case rather than the rare one.
if sb.Len() > 0 {
sb.WriteString("\n")
}
sb.WriteString(formatDiffEntry(d))
}
return sb.String()
}
// resolveGroupSystemRule merges the rules for every file in a group. Files that
// resolve to identical rule text share one block.
//
// When the group spans more than one distinct rule set, each block is tagged with
// the files it was resolved for. Bare concatenation cannot express that mapping:
// the model would receive, say, the Go checklist immediately followed by the XML
// one with nothing saying which file each governs — and a group holding exactly
// that mix is what the grouping prompt asks for (interface plus implementation,
// i18n/config variants of one resource). The framing matches
// the / convention already used for the diffs.
//
// A group covered by a single rule set — every single-file group, and every group
// whose files share a language — returns that rule text bare, so the rendered
// prompt stays byte-identical to the untagged form.
func (a *Agent) resolveGroupSystemRule(diffs []model.Diff) string {
if a.args.SystemRule == nil {
return ""
}
// Sorted by path so both block order and the paths inside a block are
// deterministic. diffs arrives in the grouping LLM's response order, which
// varies between runs and would otherwise churn the prompt prefix that
// provider caches reuse. Clone first: the caller's slice is shared state.
sorted := slices.Clone(diffs)
slices.SortStableFunc(sorted, func(x, y model.Diff) int {
return strings.Compare(x.NewPath, y.NewPath)
})
type ruleBlock struct {
rule string
paths []string
}
var blocks []ruleBlock
index := make(map[string]int, len(sorted))
for _, d := range sorted {
r := a.args.SystemRule.Resolve(d.NewPath)
if r == "" {
continue
}
if i, ok := index[r]; ok {
blocks[i].paths = append(blocks[i].paths, d.NewPath)
continue
}
index[r] = len(blocks)
blocks = append(blocks, ruleBlock{rule: r, paths: []string{d.NewPath}})
}
if len(blocks) == 0 {
return ""
}
if len(blocks) == 1 {
return blocks[0].rule
}
var sb strings.Builder
for i, b := range blocks {
if i > 0 {
sb.WriteString("\n")
}
sb.WriteString("\n")
sb.WriteString(b.rule)
sb.WriteString("\n")
}
return sb.String()
}
// executeGroupPlanPhase runs the plan phase for a file group.
func (a *Agent) executeGroupPlanPhase(ctx context.Context, g FileGroup, concatenatedDiffs, changeFiles, rule string) (string, error) {
ctx, span := telemetry.StartSpan(ctx, "plan.execute")
defer span.End()
telemetry.SetAttr(span, "group.label", g.Label)
pt := a.args.Template.PlanTask
messages := make([]llm.Message, 0, len(pt.Messages))
for _, m := range pt.Messages {
content := m.Content
content = strings.ReplaceAll(content, "{{current_system_date_time}}", a.currentDate)
content = strings.ReplaceAll(content, "{{system_rule}}", rule)
content = strings.ReplaceAll(content, "{{change_files}}", changeFiles)
content = strings.ReplaceAll(content, "{{diffs}}", concatenatedDiffs)
content = strings.ReplaceAll(content, "{{requirement_background}}", a.args.Background)
content = strings.ReplaceAll(content, "{{plan_tools}}", formatToolDefs(a.args.PlanToolDefs))
messages = append(messages, llm.NewTextMessage(m.Role, content))
}
gk := fileGroupKey(g.Diffs)
fs := a.session.GetOrCreateFileSession(gk)
rec := fs.AppendTaskRecord(session.PlanTask, messages)
ctx = llm.ContextWithSessionKey(ctx,
llm.SessionTaskKey(a.session.SessionID, string(session.PlanTask), gk))
startTime := time.Now()
reqCtx := llm.WithRequestMeta(ctx, a.newRequestMeta(gk, session.PlanTask, rec.RequestNo))
_, llmSpan := telemetry.StartLLMSpan(ctx, a.args.Model)
resp, err := a.args.LLMClient.CompletionsWithCtx(reqCtx, llm.ChatRequest{
Model: a.args.Model,
Messages: messages,
MaxTokens: a.args.Template.CompletionTokenLimit(),
})
duration := time.Since(startTime)
if err != nil {
telemetry.RecordLLMResult(llmSpan, duration, 0, err)
llmSpan.End()
rec.SetError(err, duration)
span.SetStatus(codes.Error, err.Error())
span.RecordError(err)
return "", fmt.Errorf("plan request: %w", err)
}
var totalTokens int64
if resp.Usage != nil {
totalTokens = resp.Usage.TotalTokens
}
telemetry.RecordLLMResult(llmSpan, duration, totalTokens, nil)
llmSpan.End()
rec.SetResponse(resp, duration)
a.runner.RecordUsage(resp.Usage)
fmt.Fprintf(stdout.Writer(), "[ocr] Plan completed for group %q\n", gk)
return resp.Content(), nil
}
// executeGroupReviewFilter runs the REVIEW_FILTER_TASK for a file group.
// When from is non-nil, only comments at indices >= from[path] for each path
// are candidates for filtering (per-round isolation). When from is nil, all
// comments for the group's paths are filtered (legacy full-group behavior).
func (a *Agent) executeGroupReviewFilter(ctx context.Context, g FileGroup, from map[string]int) {
groupKey := fileGroupKey(g.Diffs)
ctx, span := telemetry.StartSpan(ctx, "review_filter.execute")
defer span.End()
telemetry.SetAttr(span, "group.label", groupKey)
ft := a.args.Template.ReviewFilterTask
if ft == nil || len(ft.Messages) == 0 {
return
}
if a.args.SkipFilter {
telemetry.SetAttr(span, "skipped", true)
fmt.Fprintf(stdout.Writer(), "[ocr] Review filter skipped for group %q (--no-filter)\n", groupKey)
return
}
// Collect candidate comments with their true per-path indices.
type filterCandidate struct {
cm model.LlmComment
pathIdx int
}
var candidates []filterCandidate
for _, d := range g.Diffs {
all := a.args.CommentCollector.CommentsForPath(d.NewPath)
start := 0
if from != nil {
start = from[d.NewPath]
if start > len(all) {
start = len(all)
}
}
for i := start; i < len(all); i++ {
candidates = append(candidates, filterCandidate{cm: all[i], pathIdx: i})
}
}
if len(candidates) == 0 {
return
}
telemetry.SetAttr(span, "comments.before", len(candidates))
// Build the comment list for the filter prompt.
candidateComments := make([]model.LlmComment, len(candidates))
for i, c := range candidates {
candidateComments[i] = c.cm
}
commentsJSON := buildGroupFilterCommentsJSON(candidateComments)
concatenatedDiffs := buildConcatenatedDiffs(g.Diffs)
messages := make([]llm.Message, 0, len(ft.Messages))
for _, m := range ft.Messages {
content := m.Content
content = strings.ReplaceAll(content, "{{path}}", groupKey)
content = strings.ReplaceAll(content, "{{diff}}", concatenatedDiffs)
content = strings.ReplaceAll(content, "{{comments}}", commentsJSON)
messages = append(messages, llm.NewTextMessage(m.Role, content))
}
fs := a.session.GetOrCreateFileSession(groupKey)
rec := fs.AppendTaskRecord(session.ReviewFilterTask, messages)
ctx = llm.ContextWithSessionKey(ctx,
llm.SessionTaskKey(a.session.SessionID, string(session.ReviewFilterTask), groupKey))
startTime := time.Now()
reqCtx := llm.WithRequestMeta(ctx, a.newRequestMeta(groupKey, session.ReviewFilterTask, rec.RequestNo))
_, llmSpan := telemetry.StartLLMSpan(ctx, a.args.Model)
resp, err := a.args.LLMClient.CompletionsWithCtx(reqCtx, llm.ChatRequest{
Model: a.args.Model,
Messages: messages,
Tools: filterTools,
MaxTokens: a.args.Template.CompletionTokenLimit(),
})
duration := time.Since(startTime)
if err != nil {
telemetry.RecordLLMResult(llmSpan, duration, 0, err)
llmSpan.End()
rec.SetError(err, duration)
fmt.Fprintf(stdout.Writer(), "[ocr] Review filter failed for group %q: %v\n", groupKey, err)
span.SetStatus(codes.Error, err.Error())
span.RecordError(err)
return
}
var totalTokens int64
if resp.Usage != nil {
totalTokens = resp.Usage.TotalTokens
}
telemetry.RecordLLMResult(llmSpan, duration, totalTokens, nil)
llmSpan.End()
rec.SetResponse(resp, duration)
a.runner.RecordUsage(resp.Usage)
indices := parseFilterToolCalls(resp.ToolCalls(), len(candidates))
if indices == nil {
indices = parseFilterResponse(resp.Content(), len(candidates))
}
telemetry.SetAttr(span, "comments.filtered", len(indices))
if len(indices) == 0 {
telemetry.Event(ctx, "review_filter.completed",
attribute.String("group.label", groupKey),
attribute.Int("total_comments", len(candidates)),
attribute.Int("removed", 0))
return
}
// Map candidate indices to per-path removals using the true pathIdx.
perPath := make(map[string]map[int]struct{})
for i, c := range candidates {
if _, remove := indices[i]; !remove {
continue
}
if perPath[c.cm.Path] == nil {
perPath[c.cm.Path] = make(map[int]struct{})
}
perPath[c.cm.Path][c.pathIdx] = struct{}{}
}
var totalRemoved int
for path, idxSet := range perPath {
a.args.CommentCollector.RemoveByPathAndIndices(path, idxSet)
totalRemoved += len(idxSet)
}
telemetry.Event(ctx, "review_filter.completed",
attribute.String("group.label", groupKey),
attribute.Int("total_comments", len(candidates)),
attribute.Int("removed", totalRemoved))
fmt.Fprintf(stdout.Writer(), "[ocr] Review filter removed %d comment(s) for group %q\n", totalRemoved, groupKey)
}
// buildGroupFilterCommentsJSON serializes comments with path info for group-level filtering.
func buildGroupFilterCommentsJSON(comments []model.LlmComment) string {
type filterComment struct {
ID string `json:"id"`
Path string `json:"path"`
Content string `json:"content"`
ExistingCode string `json:"existing_code,omitempty"`
}
items := make([]filterComment, len(comments))
for i, cm := range comments {
items[i] = filterComment{
ID: fmt.Sprintf("c-%d", i),
Path: cm.Path,
Content: cm.Content,
ExistingCode: cm.ExistingCode,
}
}
data, _ := json.Marshal(items)
return string(data)
}
// parseFilterToolCalls extracts comment indices from the filter tool call response.
// Returns nil if no matching tool call is found, allowing fallback to text-based parsing.
// Returns an empty map (non-nil) for approve_all_comments or an empty comment_ids list.
func parseFilterToolCalls(calls []llm.ToolCall, total int) map[int]struct{} {
var indices map[int]struct{}
for _, call := range calls {
switch call.Function.Name {
case "approve_all_comments":
if indices == nil {
indices = make(map[int]struct{})
}
case "report_incorrect_comments":
var args struct {
CommentIDs []string `json:"comment_ids"`
}
if err := json.Unmarshal([]byte(call.Function.Arguments), &args); err != nil {
fmt.Fprintf(stdout.Writer(), "[ocr] Review filter: failed to parse tool call arguments: %v\n", err)
continue
}
if indices == nil {
indices = make(map[int]struct{})
}
for _, id := range args.CommentIDs {
var idx int
if _, err := fmt.Sscanf(id, "c-%d", &idx); err == nil && idx >= 0 && idx < total {
indices[idx] = struct{}{}
}
}
}
}
return indices
}
// parseFilterResponse extracts comment indices from the LLM filter response.
// Returns a set of 0-based indices. Invalid IDs or out-of-range indices are ignored.
func parseFilterResponse(raw string, total int) map[int]struct{} {
raw = llmloop.StripMarkdownFences(raw)
var ids []string
if err := json.Unmarshal([]byte(raw), &ids); err != nil {
preview := raw
if len(preview) > 200 {
preview = preview[:200] + "..."
}
fmt.Fprintf(stdout.Writer(), "[ocr] Review filter: failed to parse LLM response: %v, raw: %s\n", err, preview)
return nil
}
indices := make(map[int]struct{})
for _, id := range ids {
var idx int
if _, err := fmt.Sscanf(id, "c-%d", &idx); err == nil && idx >= 0 && idx < total {
indices[idx] = struct{}{}
}
}
return indices
}
// logExclusions reports the files the selection dropped: the static gates
// first with their rollup, then the size gate with its own, so the two groups
// stay distinguishable in the log. Deletions are not reported — they are
// excluded from review but not dropped from the run, as before.
func (a *Agent) logExclusions(decisions []fileDecision) {
staticSkipped := 0
for _, dec := range decisions {
// Listed exhaustively rather than defaulted, so a reason added later
// cannot silently inherit the path/extension wording.
switch dec.Reason {
case ExcludeBinary:
fmt.Fprintf(stdout.Writer(), "[ocr] Skipping %s — binary file\n", effectivePath(dec.Diff))
case ExcludeSecret:
fmt.Fprintf(stdout.Writer(), "[ocr] Skipping %s — matches a built-in secret path\n", effectivePath(dec.Diff))
case ExcludeUserRule, ExcludeExtension, ExcludeDefaultPath:
fmt.Fprintf(stdout.Writer(), "[ocr] Skipping %s — filtered by path/extension rules\n", effectivePath(dec.Diff))
default:
continue
}
staticSkipped++
}
if staticSkipped > 0 {
fmt.Fprintf(stdout.Writer(), "[ocr] Filtered %d file(s) by include/exclude rules\n", staticSkipped)
}
tooLarge := 0
for _, dec := range decisions {
if dec.Reason != ExcludeTooLarge {
continue
}
fmt.Fprintf(stdout.Writer(), "[ocr] Skipping %s (~%d tokens exceeds 80%% of max_tokens(%d))\n",
dec.Diff.NewPath, dec.DiffTokens, a.args.Template.MaxTokens)
tooLarge++
}
if tooLarge > 0 {
fmt.Fprintf(stdout.Writer(), "[ocr] Pre-filtered %d file(s) exceeding 80%% of max_tokens\n", tooLarge)
}
}
// extFromPath returns the file extension with leading dot, lowercased.
func (a *Agent) extFromPath(path string) string {
basename := path
if idx := strings.LastIndex(path, "/"); idx >= 0 {
basename = path[idx+1:]
}
dot := strings.LastIndex(basename, ".")
if dot <= 0 {
return ""
}
return strings.ToLower(basename[dot:])
}
// formatToolDefs renders tool definitions as human-readable text for embedding in prompts.
func formatToolDefs(toolDefs []llm.ToolDef) string {
if len(toolDefs) == 0 {
return ""
}
var sb strings.Builder
sb.WriteString("### Available Tools (reference only — do not call)\n")
for _, td := range toolDefs {
fn := &td.Function
sb.WriteString(fmt.Sprintf("- **%s**: %s\n", fn.Name, fn.Description))
if orderedParams, ok := orderedToolParameters(fn.RawDefinition); ok {
sb.WriteString(" Parameters:\n")
for _, p := range orderedParams {
suffix := ""
if p.Required {
suffix = " (required)"
}
sb.WriteString(fmt.Sprintf(" - %s: %s%s\n", p.Name, p.Description, suffix))
}
continue
}
if params, ok := fn.Parameters["properties"].(map[string]any); ok && len(params) > 0 {
sb.WriteString(" Parameters:\n")
required := make(map[string]bool)
if reqList, ok := fn.Parameters["required"].([]any); ok {
for _, r := range reqList {
if s, ok := r.(string); ok {
required[s] = true
}
}
}
for _, name := range slices.Sorted(maps.Keys(params)) {
p := params[name]
suffix := ""
if required[name] {
suffix = " (required)"
}
if pm, ok := p.(map[string]any); ok {
desc, _ := pm["description"].(string)
sb.WriteString(fmt.Sprintf(" - %s: %s%s\n", name, desc, suffix))
} else {
sb.WriteString(fmt.Sprintf(" - %s%s\n", name, suffix))
}
}
}
}
return sb.String()
}
type orderedToolParameter struct {
Name string
Description string
Required bool
}
func orderedToolParameters(raw json.RawMessage) ([]orderedToolParameter, bool) {
if len(raw) == 0 {
return nil, false
}
var def struct {
Parameters struct {
Required []string `json:"required"`
Properties json.RawMessage `json:"properties"`
} `json:"parameters"`
}
if err := json.Unmarshal(raw, &def); err != nil || len(def.Parameters.Properties) == 0 {
return nil, false
}
required := make(map[string]bool, len(def.Parameters.Required))
for _, name := range def.Parameters.Required {
required[name] = true
}
dec := json.NewDecoder(bytes.NewReader(def.Parameters.Properties))
tok, err := dec.Token()
if err != nil {
return nil, false
}
if delim, ok := tok.(json.Delim); !ok || delim != '{' {
return nil, false
}
var params []orderedToolParameter
for dec.More() {
keyTok, err := dec.Token()
if err != nil {
return nil, false
}
name, ok := keyTok.(string)
if !ok {
return nil, false
}
var meta struct {
Description string `json:"description"`
}
if err := dec.Decode(&meta); err != nil {
return nil, false
}
params = append(params, orderedToolParameter{
Name: name,
Description: meta.Description,
Required: required[name],
})
}
if _, err := dec.Token(); err != nil {
return nil, false
}
if len(params) == 0 {
return nil, false
}
return params, true
}
// allDiffs exposes the reviewed diff set for cross-file comment re-filing.
// It is read-only and safe to call from the per-group subtask goroutines: every
// mutation of a.diffs (the selection Run applies) completes before dispatch
// begins, so the slice is stable for the rest of the run.
func (a *Agent) allDiffs() []model.Diff {
return a.diffs
}
// findDiff returns the Diff for the given file path, or nil if not found.
func (a *Agent) findDiff(path string) *model.Diff {
for i := range a.diffs {
if a.diffs[i].NewPath == path || a.diffs[i].OldPath == path {
return &a.diffs[i]
}
}
return nil
}