feat: add reflection

[bobrykov]

No description provided.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 7c9c4c23-61f8-4613-b9a4-41cf5b692d01

📥 Commits

Reviewing files that changed from the base of the PR and between b205d78 and 79741b1.

📒 Files selected for processing (1)

• README.md

✅ Files skipped from review due to trivial changes (1)

• README.md

---

📝 Walkthrough

Walkthrough

Adds a pluggable two-layer failure-handling framework: async Reflector analyzes failures into FailureAnalysis; async RecoveryStrategy decides RecoveryAction (Retry/Skip/AskUser/Fail). Includes NoopReflector, ExponentialBackoffRecovery, module docs, crate re-exports, README update, and unit tests.

Changes

Failure Analysis and Recovery Framework

Layer / File(s)	Summary
Module overview and core data types src/core/reflection.rs	FailureSeverity enum (Low/Medium/High/Critical) with serde/display; ReflectionContext for task/attempt state; FailureAnalysis reports recoverability, root cause, severity, optional Correction, and context; ReflectionError for Skipped/Internal; RecoveryAction models Retry(with delay)/Skip/AskUser/Fail with helper accessors and Display.
Reflector and RecoveryStrategy trait contracts src/core/reflection.rs	Reflector async trait analyzes an error, tool metadata, and ReflectionContext into FailureAnalysis or ReflectionError; RecoveryStrategy async trait decides a RecoveryAction from FailureAnalysis and attempt counters.
Reference implementations and tests src/core/reflection.rs	NoopReflector returns non-recoverable analysis; ExponentialBackoffRecovery enforces max retries, computes capped exponential delays, and selects actions by severity/correction presence. Unit tests cover serde/display, helpers, noop and backoff branches, capping, and max-retry exhaustion.
Public API surface and module integration src/core.rs, src/core/reflection.rs, README.md	Core documentation expanded to list new framework types; new reflection module declared public and re-exported at crate root; README modules table updated to include compact row.

Sequence Diagram

sequenceDiagram
  participant Agent
  participant Reflector
  participant RecoveryStrategy
  Agent->>Reflector: analyze(error, tool_name, input, context)
  Reflector->>Agent: FailureAnalysis{severity, is_recoverable, correction}
  Agent->>RecoveryStrategy: decide(analysis, attempt, max_attempts)
  RecoveryStrategy->>Agent: RecoveryAction(Retry|Skip|AskUser|Fail)

Loading

Possibly related PRs

• dch-labs/loopctl#12: Introduces the Correction type used by FailureAnalysis.correction, indicating a code-level dependency.

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat: add reflection' directly describes the main change: introducing a new reflection module with failure-handling framework, which is the primary modification across the changeset.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/reflection

---

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

[coderabbitai]

Actionable comments posted: 1

🤖 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/core/reflection.rs`:
- Around line 630-632: The code treats FailureSeverity::Low by returning
RecoveryAction::Skip, which contradicts the docs that say Low issues are
retryable; change the implementation in the failure-handling branch (the code
checking analysis.severity == FailureSeverity::Low in src/core/reflection.rs) to
return a retry action instead of Skip (e.g., RecoveryAction::Retry with an
appropriate message or retry count) consistent with the documentation, or if
skipping is intended, update the FailureSeverity::Low documentation text to
state these are non-retryable/minor and can be safely skipped; ensure you modify
the branch that currently returns RecoveryAction::Skip(format!("low severity:
{}", analysis.root_cause)) or the corresponding doc comment so behavior and docs
match.

🪄 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: 61552045-ebae-46bd-b042-ae0d12b234d1

📥 Commits

Reviewing files that changed from the base of the PR and between 7ff376b and 05fb7f2.

📒 Files selected for processing (2)

• src/core.rs
• src/core/reflection.rs

[coderabbitai]

🧹 Nitpick comments (1)

src/core/reflection.rs (1)

615-641: 💤 Low value

Consider documenting or using the max_attempts parameter.

The max_attempts parameter (line 620) is ignored in favor of self.max_retries. This could confuse API users who expect their passed value to be respected.

Options to consider:

1. Document in trait/method docs that strategies may ignore max_attempts in favor of their own limits
2. Use max_attempts.min(self.max_retries) to respect whichever is lower
3. Remove max_attempts from the trait signature if strategies are expected to be self-contained

🤖 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 `@src/core/reflection.rs` around lines 615 - 641, The decide implementation on
ExponentialBackoffRecovery ignores the max_attempts parameter and uses
self.max_retries instead; update decide to respect the passed max_attempts
(e.g., compute let allowed = std::cmp::min(max_attempts, self.max_retries) and
compare attempt >= allowed) or, if you prefer the strategy to control limits,
add documentation to the RecoveryStrategy::decide signature and
ExponentialBackoffRecovery::decide explaining that max_attempts may be ignored;
locate the decide method on ExponentialBackoffRecovery and either enforce the
min between max_attempts and self.max_retries or add the explanatory doc comment
mentioning that implementations may ignore max_attempts.

🤖 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.

Nitpick comments:
In `@src/core/reflection.rs`:
- Around line 615-641: The decide implementation on ExponentialBackoffRecovery
ignores the max_attempts parameter and uses self.max_retries instead; update
decide to respect the passed max_attempts (e.g., compute let allowed =
std::cmp::min(max_attempts, self.max_retries) and compare attempt >= allowed)
or, if you prefer the strategy to control limits, add documentation to the
RecoveryStrategy::decide signature and ExponentialBackoffRecovery::decide
explaining that max_attempts may be ignored; locate the decide method on
ExponentialBackoffRecovery and either enforce the min between max_attempts and
self.max_retries or add the explanatory doc comment mentioning that
implementations may ignore max_attempts.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: cd3a43f1-4623-4d80-ac00-4a15ee1bbd14

📥 Commits

Reviewing files that changed from the base of the PR and between 05fb7f2 and b205d78.

📒 Files selected for processing (2)

• src/core.rs
• src/core/reflection.rs

🚧 Files skipped from review as they are similar to previous changes (1)

• src/core.rs