// 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 }