feat: configurable max_turns via agent TOML (closes #66)

[tamish-max]

Closes #66

Changes

• Added max_turns to AgentConfig struct
• Default to 50 when unset (0)
• Validate() rejects negative values
• Updated cmd/run.go to read from config

Summary

This PR makes the agent conversation limit configurable through max_turns in agent TOML files. The default remains 50 turns when unset or zero. Negative values are rejected, and configured limits are displayed and enforced.

Changelog

Added

• max_turns to AgentConfig.
• Max Turns output in axe agents show.
• max_turns to the agent scaffold template.
• Tests for configuration loading, validation, display, and enforcement.

Changed

• Conversation loops now use cfg.MaxTurns with a 50-turn fallback.
• Documentation now describes max_turns and its default.
• README provider documentation now includes Atlas Cloud.
• Scaffold tests now verify the max_turns setting.

Removed

• TestScaffold_IncludesTopLevelTimeout, replaced by max-turns coverage.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: c2388ca9-e226-48b5-a3ac-0d7b9130fd8f

📥 Commits

Reviewing files that changed from the base of the PR and between a54cb65 and d633d38.

📒 Files selected for processing (1)

• README.md

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

• README.md

Included review availability: Your plan provides up to 4 included reviews per hour; 3 remain after this review.

---

📝 Walkthrough

Walkthrough

This PR adds an optional max_turns TOML field for agent configurations. The default remains 50 when unset. Validation, CLI output, runtime loops, tests, scaffolding, and documentation now support the setting.

Changes

Configurable Max Conversation Turns

Layer / File(s)	Summary
AgentConfig schema and validation internal/agent/agent.go, internal/agent/agent_test.go	AgentConfig adds MaxTurns. Validation rejects negative values. Loading and scaffold tests cover the field and its default.
Runtime turn limit resolution internal/tool/tool.go, pkg/runner/run.go	Conversation loops use cfg.MaxTurns when non-zero and use the default limit of 50 when it is zero.
CLI configuration display cmd/agents.go, cmd/agents_test.go	agents show displays Max Turns for positive configured values. The CLI test verifies the output.
Configured runtime behavior tests internal/tool/tool_test.go, pkg/runner/run_test.go	Tests verify that max_turns = 2 limits API calls and returns a maximum-turn error.
Configuration documentation AGENTS.md, README.md	Documentation describes max_turns, its default, the configurable conversation loop, and Atlas Cloud provider settings.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~25 minutes

Merge Risk: ⚪ Minimal · up to d633d

Configured turn limits, the 50-turn default, and invalid-value rejection are consistently handled across the reviewed paths. No actionable merge risk remains.

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Out of Scope Changes check	⚠️ Warning	The README adds an Atlas Cloud provider and documents Atlas Cloud model names. This change has no demonstrated connection to issue #66's configurable conversation-turn requirements. The other document…	Remove the Atlas Cloud provider and model documentation from this pull request, or link that change to a separate issue.
Docstring Coverage	⚠️ Warning	Docstring coverage is 30.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 20 functions across 7 files. (1 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: configurable max_turns through agent TOML.
Linked Issues check	✅ Passed	Issue #66 coding requirements are implemented. AgentConfig adds MaxTurns with toml:"max_turns". Validate() rejects negative values. pkg/runner/run.go uses cfg.MaxTurns and falls back to 50…

Full details: Out of Scope Changes check

Explanation

The README adds an Atlas Cloud provider and documents Atlas Cloud model names. This change has no demonstrated connection to issue #66's configurable conversation-turn requirements. The other documented changes and tests support the issue.

Full details: Docstring Coverage

Explanation

Docstring coverage is 30.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 20 functions across 7 files. (1 skipped: 1 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

_{Fifty turns once stood in stone,
Now each agent sets its own.
TOML guides the loop with care,
Tests count requests through the air,
Configured limits keep things fair.}

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

[coderabbitai]

🧹 Nitpick comments (1)

internal/agent/agent_test.go (1)

172-222: 💤 Low value

Optional: Consider asserting MaxTurns defaults to 0 here.

The TestLoad_MinimalConfig test currently checks that optional fields are zero/nil/empty when unset. Adding an assertion like:

if cfg.MaxTurns != 0 {
    t.Errorf("MaxTurns = %d, want 0", cfg.MaxTurns)
}

would document the "unset" behavior more explicitly. Not critical since zero is already validated in TestValidate_TopLevelMaxTurnsZeroAndPositive, but it'd round out the coverage.

🤖 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 `@internal/agent/agent_test.go` around lines 172 - 222, Add an assertion in
TestLoad_MinimalConfig to explicitly verify the default for MaxTurns is zero:
check cfg.MaxTurns and call t.Errorf("MaxTurns = %d, want 0", cfg.MaxTurns) if
it's non-zero; this goes inside the TestLoad_MinimalConfig function alongside
the other zero-value checks (referencing cfg.MaxTurns in that test).

🤖 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 `@internal/agent/agent_test.go`:
- Around line 172-222: Add an assertion in TestLoad_MinimalConfig to explicitly
verify the default for MaxTurns is zero: check cfg.MaxTurns and call
t.Errorf("MaxTurns = %d, want 0", cfg.MaxTurns) if it's non-zero; this goes
inside the TestLoad_MinimalConfig function alongside the other zero-value checks
(referencing cfg.MaxTurns in that test).

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: b66ab487-cf3d-43ea-ae27-f9f53ccb38ce

📥 Commits

Reviewing files that changed from the base of the PR and between f199404 and a54cb65.

⛔ Files ignored due to path filters (1)

• docs/src/tools/built-in.md is excluded by !docs/**

📒 Files selected for processing (10)

• AGENTS.md
• README.md
• cmd/agents.go
• cmd/agents_test.go
• internal/agent/agent.go
• internal/agent/agent_test.go
• internal/tool/tool.go
• internal/tool/tool_test.go
• pkg/runner/run.go
• pkg/runner/run_test.go