feat: add llm reflector

[bobrykov]

No description provided.

[coderabbitai]

Warning

Review limit reached

@bobrykov, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 26 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 0fb05158-b7ad-49a4-b0c8-2d0569f3d58d

📥 Commits

Reviewing files that changed from the base of the PR and between 7cd6eba and 22e90c7.

📒 Files selected for processing (1)

• src/engine/bare/dispatch.rs

📝 Walkthrough

Walkthrough

Adds LlmReflector with structured failure analysis, optional tool-input schema validation, a new Critical severity, and a breaking Reflector::analyze signature update. Recovery now forwards tool schemas, with corresponding tests, feature configuration, documentation, migration notes, and expanded heartbeat and safety-shield API documentation.

Changes

Reflection pipeline

Layer / File(s)	Summary
Reflection contracts and structured analysis src/reflection.rs	Adds Critical, documents reflection and recovery semantics, defines FailureAnalysis structured output, adds RecoveryAction predicates, and adds the optional tool_schema parameter to Reflector::analyze.
LLM reflector and validation src/reflection.rs, src/reflection/llm.rs	Adds LlmReflector, structured API requests, prompt construction, optional modified_input schema validation, and tests for parsing, errors, prompts, and feature-gated validation.
Recovery schema propagation src/engine/bare/dispatch.rs, src/engine/bare.rs	Passes the failing tool’s schema into reflector analysis and updates test reflector implementations for the new interface.
Feature and migration documentation Cargo.toml, README.md, CHANGELOG.md	Adds the optional jsonschema dependency and schema_validation feature, and documents the new reflector and breaking API change.

API documentation

Layer / File(s)	Summary
Heartbeat stream semantics src/stream/heartbeat.rs	Documents polling order, elapsed-time and timeout semantics, callback timing, and timeout scheduling behavior.
Tool safety semantics src/tool/shield.rs	Clarifies safety decisions, risk scoring, history matching, shield lifecycle, builder behavior, and NullShield operation, including is_warn().

Sequence Diagram(s)

sequenceDiagram
  participant ToolRecovery
  participant LlmReflector
  participant ApiClient
  participant ToolSchema
  ToolRecovery->>LlmReflector: Analyze tool failure with schema
  LlmReflector->>ApiClient: Request structured FailureAnalysis
  ApiClient-->>LlmReflector: Return FailureAnalysis
  LlmReflector->>ToolSchema: Validate modified_input when enabled
  LlmReflector-->>ToolRecovery: Return analysis or error

Loading

Possibly related PRs

• dch-labs/loopctl#15: Introduced the ToolSchema type used by the updated reflector pipeline.
• dch-labs/loopctl#26: Introduced the reflection framework extended by this change.
• dch-labs/loopctl#49: Introduced the structured-output framework used by FailureAnalysis.

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly matches the main change: adding the new LlmReflector feature.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 50.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/llm-reflector

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 3

🧹 Nitpick comments (1)

CHANGELOG.md (1)

68-81: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Use one spelling variant consistently.

This entry mixes “analysed” with the API’s “analyze”. Prefer “analyzed” throughout this changelog entry.

Also applies to: 85-94

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@CHANGELOG.md` around lines 68 - 81, Update the changelog entry describing
LlmReflector so the spelling uses “analyzed” consistently, including the
corresponding occurrence in the related entry range.

Source: Linters/SAST tools

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/engine/bare/dispatch.rs`:
- Around line 1052-1060: Update the recovery reflection flow around
reflector.analyze to resolve the schema using the actually executed tool name
from result.resolved_tool_name rather than tc.tool. Use that resolved name to
look up the tool in self.tools, while preserving the existing analysis and
correction behavior.

In `@src/reflection/llm.rs`:
- Around line 147-150: Update build_user_message and its call site in the
surrounding reflection flow to accept the optional tool schema and include it in
the model prompt as a clearly delimited data field. Preserve schema cloning for
post-response validation while ensuring the model receives the same schema used
to validate input_fix generation.
- Around line 214-221: Move the schema_validation-disabled unused-variable
suppression in validate_modified_input to after the modified_input and schema
bindings are declared, or remove it if no longer needed. Ensure the function
compiles when schema_validation is disabled without referencing names before
their bindings.

---

Nitpick comments:
In `@CHANGELOG.md`:
- Around line 68-81: Update the changelog entry describing LlmReflector so the
spelling uses “analyzed” consistently, including the corresponding occurrence in
the related entry range.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 20878dd9-a68c-4f59-8bb2-48e9ee04e364

📥 Commits

Reviewing files that changed from the base of the PR and between 13e36f1 and 829e186.

📒 Files selected for processing (7)

• CHANGELOG.md
• Cargo.toml
• README.md
• src/engine/bare.rs
• src/engine/bare/dispatch.rs
• src/reflection.rs
• src/reflection/llm.rs