Fix/docs consistency

[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: 35 minutes

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

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: fd02bec3-ac04-47ab-8fee-1ca9c0585832

📥 Commits

Reviewing files that changed from the base of the PR and between 1eca460 and 29ff20b.

📒 Files selected for processing (5)

• CHANGELOG.md
• src/api.rs
• src/config.rs
• src/engine/bare.rs
• src/engine/bare/dispatch.rs

📝 Walkthrough

Walkthrough

Changes

The PR updates retry, API, and machine-state documentation. It adds a parallel-dispatch regression test for retry observer notifications and records the changes in CHANGELOG.md.

Retry documentation and validation

Layer / File(s)	Summary
Parallel retry observer validation src/engine/bare/dispatch.rs	Adds coverage for three parallel tool attempts, paired PRE/POST observer notifications, two retries, and final soft failure.
Runtime contract documentation src/config.rs, src/engine/bare.rs	Documents retry side effects in both execution modes and describes the pre-run machine as empty with no history or pending messages.
API examples and release notes src/api.rs, CHANGELOG.md	Updates examples to pass borrowed StreamRequest values and records the versioning, documentation, API, and lint-contract changes.

Possibly related PRs

• dch-labs/loopctl#34: Related to BareLoop retry execution and per-attempt observer notifications.
• dch-labs/loopctl#59: Introduced related ApiClient and StreamRequest method signature changes.
• dch-labs/loopctl#65: Related to tool execution, retry, and observer behavior.

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately identifies documentation consistency fixes, which represent the main change in the pull request.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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 docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/docs-consistency

---

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]

🧹 Nitpick comments (3)

src/engine/bare/dispatch.rs (3)

1500-1528: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Extract the repeated AlwaysRecoverable reflector into a shared test helper.

This struct definition duplicates the identical AlwaysRecoverable already defined at Line 1405 (recovery_backoff_cancelled_promptly) and again at Line 1611 (execute_tool_call_runs_recovery_on_failure). Three identical copies now exist in this test module. Extract one module-level AlwaysRecoverable and reuse it across the three tests to reduce duplication.

🤖 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/engine/bare/dispatch.rs` around lines 1500 - 1528, Extract the identical
AlwaysRecoverable implementation from the affected test into a single
module-level test helper, then remove the duplicate definitions in
recovery_backoff_cancelled_promptly and
execute_tool_call_runs_recovery_on_failure so all three tests reuse that shared
reflector.

---

1589-1590: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Discarding the dispatch result with .ok() hides unexpected hard failures.

bare.dispatch_tools(&calls, 0).await.ok() silently swallows any Err (for example an unexpected LoopError::Cancelled or a dispatch bug). If dispatch fails for a reason unrelated to the retry logic, the test would still proceed to the count assertions, which could produce a confusing failure message instead of a clear one pointing at the actual dispatch error.

🤖 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/engine/bare/dispatch.rs` around lines 1589 - 1590, Update the test call
to bare.dispatch_tools(&calls, 0).await so unexpected dispatch errors are
propagated or explicitly asserted, rather than converted to None with .ok().
Preserve the test’s intended handling of the expected error_tool outcome while
ensuring failures such as LoopError::Cancelled surface directly from the
dispatch operation.

---

1486-1603: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Tighten the assertion to the exact deterministic attempt count.

RetryTwice::decide retries while attempt < 2 and skips at attempt == 2. Combined with the loop in execute_tool_call, this setup deterministically produces exactly 3 full attempts (2 retries + 1 skip), matching the comment at Line 1530: "Retry the first two attempts, then give up with a soft error." The assertion at Line 1594 only checks pres >= 2 && posts >= 2. This under-verifies the contract: a regression that drops one attempt (2 instead of 3) would still pass this test.

Use assert_eq!(pres, 3) and assert_eq!(posts, 3) to pin the exact, deterministic value.

♻️ Proposed tightening

-        let pres = pre_count.load(Ordering::Relaxed);
-        let posts = post_count.load(Ordering::Relaxed);
-        assert!(
-            pres >= 2 && posts >= 2,
-            "parallel retried call must fire side-effects per attempt; got pre={pres} post={posts}"
-        );
-        assert_eq!(
-            pres, posts,
-            "every PRE must have a matching POST (pairing invariant)"
-        );
+        let pres = pre_count.load(Ordering::Relaxed);
+        let posts = post_count.load(Ordering::Relaxed);
+        assert_eq!(
+            pres, 3,
+            "expected exactly 3 attempts (2 retries + 1 skip); got pre={pres}"
+        );
+        assert_eq!(
+            pres, posts,
+            "every PRE must have a matching POST (pairing invariant)"
+        );

🤖 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/engine/bare/dispatch.rs` around lines 1486 - 1603, In
parallel_retried_call_fires_side_effects_per_attempt, replace the lower-bound
assertion on pre_count and post_count with exact assertions that both pres and
posts equal 3, matching RetryTwice’s two retries followed by the final skipped
attempt. Preserve the existing PRE/POST pairing assertion.

🤖 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/engine/bare/dispatch.rs`:
- Around line 1500-1528: Extract the identical AlwaysRecoverable implementation
from the affected test into a single module-level test helper, then remove the
duplicate definitions in recovery_backoff_cancelled_promptly and
execute_tool_call_runs_recovery_on_failure so all three tests reuse that shared
reflector.
- Around line 1589-1590: Update the test call to bare.dispatch_tools(&calls,
0).await so unexpected dispatch errors are propagated or explicitly asserted,
rather than converted to None with .ok(). Preserve the test’s intended handling
of the expected error_tool outcome while ensuring failures such as
LoopError::Cancelled surface directly from the dispatch operation.
- Around line 1486-1603: In
parallel_retried_call_fires_side_effects_per_attempt, replace the lower-bound
assertion on pre_count and post_count with exact assertions that both pres and
posts equal 3, matching RetryTwice’s two retries followed by the final skipped
attempt. Preserve the existing PRE/POST pairing assertion.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: caf12f07-4069-486b-a1b2-6e184432ddc1

📥 Commits

Reviewing files that changed from the base of the PR and between 9b97ca4 and 1eca460.

📒 Files selected for processing (5)

• CHANGELOG.md
• src/api.rs
• src/config.rs
• src/engine/bare.rs
• src/engine/bare/dispatch.rs