SDK: parity with bash CLI (stall detection, progressive context, structured files_changed)

[wtthornton]

Summary

TheStudio maintains a vendored copy of the Ralph Python SDK and compared it to the bash CLI (v2.2.0+). The CLI received production fixes that are not yet reflected in the Python SDK (SDK still reported as 2.0.2 in our evaluation). We are implementing P0 items in our vendor tree regardless; this issue tracks upstream parity so all SDK consumers benefit.

Reference (external consumer): TheStudio evaluation with prioritized requests:
https://github.com/wtthornton/TheStudio/blob/master/docs/ralph-sdk-upgrade-evaluation.md
(If the link 404s, path is docs/ralph-sdk-upgrade-evaluation.md on the TheStudio repo.)

P0 — Requested SDK enhancements

1. Stall detection — Port CLI semantics: fast-trip (consecutive fast failures), deferred-test stall (analogous to CB_MAX_DEFERRED_TESTS), consecutive timeouts. Configurable thresholds on circuit_breaker (or equivalent).

2. Progressive context — Trim large fix_plan.md-style inputs to current section + next N unchecked items + token estimate (CLI has lib/context_management.sh).

3. Structured files_changed — Expose reliable files_changed: list[str] on TaskResult from tool use / git diff, not freeform output parsing.

P1 (same doc)

Task decomposition hints, cost tracking, dynamic model routing, completion-indicator decay, documented cancel() semantics, etc. — see evaluation §1.3+ and §2.

Non-goals

Replacing TheStudio-specific integration; this is SDK + API surface only.

Thank you for considering — happy to split into separate issues if you prefer.

[coderabbitai]

🔗 Related PRs

#67 - feat(import): modernize ralph_import.sh with JSON output parsing [merged]
#137 - fix(setup): create .ralphrc with consistent tool permissions [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[github-actions]

Thanks for the detailed write-up, @wtthornton! This has been labeled as an enhancement.

Triage summary: This is a feature request for parity between the Python SDK and the bash CLI (v2.2.0+). The three P0 items identified are:

1. Stall detection — porting circuit-breaker semantics (fast-trip, deferred-test stall, consecutive timeouts) to the SDK.
2. Progressive context — trimming large fix_plan.md-style inputs analogous to lib/context_management.sh in the CLI.
3. Structured files_changed — exposing a reliable list[str] on TaskResult rather than freeform output parsing.

Recommended next steps:

• The maintainer (@frankbria) will review and prioritize these against the current roadmap.
• If you'd like faster iteration, splitting this into one issue per P0 item (as you suggested) would make each easier to track and review independently.
• In the meantime, your vendored implementation details in the linked evaluation doc will be a helpful reference for whoever picks this up upstream.

Generated by Issue Triage Assistant for issue #226