feat: Make max iteration limit resumable without reminders

[utkarsh-in]

#2406

Summary

• Add MAX_ITERATIONS_REACHED status to ConversationExecutionStatus enum
• Mark MAX_ITERATIONS_REACHED as terminal state
• Add ConversationIterationLimitEvent for better error handling
• Modify send_message() to reset MAX_ITERATIONS_REACHED to IDLE on new user input
• Modify run() to allow restarting from MAX_ITERATIONS_REACHED state
• Add budget information to agent system prompt
• Add budget warning messages at 80% and 95% of max iterations
• Update tests to cover new status transitions

This change allows conversations to resume after hitting max iterations when a new user message is sent, instead of permanently stopping.

Checklist

• If the PR is changing/adding functionality, are there tests to reflect this?
• If there is an example, have you run the example to make sure that it works?
• If there are instructions on how to run the code, have you followed the instructions and made sure that it works?
• If the feature is significant enough to require documentation, is there a PR open on the OpenHands/docs repository with the same branch name?
• Is the github CI passing?

[enyst]

Thank you for trying this! It's very interesting.

I do wonder about one or two things though: first, benchmarks like any non-interactive runs, really do stop at max_iterations, they have to, so that it doesn't go on forever. But interactive runs don't have to stop, they only need to pause: so the user via an UI can say something, and it will continue. That might mean that the user experience could be affected if the LLM is told that it'd better hurry, instead of running normally.

So idk, I think maybe it's worth asking: do we want this applied only to non-interactive runs? do we know we are in a non-interactive run?

Secondly, I'm a bit curious. I'd like to know what in-context reminders tell the LLM in other agentic tools. I seem to recall off-hand that OpenAI had a reminder since a long time ago at least.

Reminding it of fragments of the system prompt or instructions, like telling it again how the process works, is fine IMHO; telling the state of its runtime, like number of iterations remaining is fine; idk, WDYT, is hurrying it or nudging it to completion fine?

[utkarsh-in]

Hi @enyst I agree that nudging it to completion can be removed.
I think we should have number of iterations for both interactive and non-interactive runs to reach a logical conclusion in the current run, even if we continue further.

[enyst]

@VascoSch92 I'd love your thoughts on this discussion.

[VascoSch92]

After the discussion in the relevant issue, I think we don't want to have a reminder for the iteration limit. At least, not now.

However, I think it would be interesting (at least for me, for subagents) to have a new error type, i.e., MAX_ITERATIONS_REACHED, because right now this type of error falls under the generic ERROR category, which makes it indistinguishable.

Can we just make this change in the PR?

Reminding it of fragments of the system prompt or instructions — like telling it again how the process works — is fine IMHO; telling it the state of its runtime, like the number of remaining iterations, is fine too. I don't know — is nudging it or hurrying it toward completion fine? WDYT?

I have already used context budget pressure on agents, but it is difficult to say whether it was effective or not. I think it is effective when you have a very limited number of iterations, but that is actually not our case, at least so far, I have never seen a task fail due to an iteration overflow in a benchmark using the OpenHands agent.

[utkarsh-in]

@VascoSch92 @enyst just to clarify

• Keep ConversationIterationLimitEvent
• Keep it as resumable
• Keep Budget Info in agent
• remove 85% and 95% reminder

Is that correct?

[enyst]

Thanks!

Keep Budget Info in agent

I think maybe it’s not necessary, it’s a local variable used only for the reminder?

[utkarsh-in]

Hi @enyst Thanks
Made the changes

[all-hands-bot]

[Automatic Post]: It has been a while since there was any activity on this PR. @utkarsh-in, are you still working on it? If so, please go ahead, if not then please request review, close it, or request that someone else follow up.

[all-hands-bot]

[Automatic Post]: It has been a while since there was any activity on this PR. @utkarsh-in, are you still working on it? If so, please go ahead, if not then please request review, close it, or request that someone else follow up.

[enyst]

@OpenHands Understand this PR. Its CI is failing, verify why, fix precommit (note that it's a fork so set your remote correctly and push)

Then let's focus on the API workflow failures. I'm confused why it fails: I see a notice about additive changes, which don't error, and then I see... some additive changes which do result in an error? Understand the problems and then take a step back and tell me: do you think the workflow is too strict or the PR changes are too breaking things? Respond in a comment on github.

[openhands-ai]

I'm on it! enyst can track my progress at all-hands.dev

[enyst]

I dug through the PR, the linked issue, and the failing CI.

What I fixed

• The pre-commit failure was a real bug: ConversationIterationLimitEvent was renamed to use max_iteration_per_run, but local_conversation.py was still constructing it with max_iterations.
• I fixed that in 86b5799 (fix(sdk): correct iteration limit event field) and pushed it to utkarsh-in:feature/max-iteration-resumable.
• I validated locally with:
  • uv run pre-commit run --files openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py
  • uv run pytest tests/sdk/conversation/local/test_agent_status_transition.py tests/sdk/conversation/test_conversation_execution_status_enum.py
• I also resolved the two stale review threads that had already been addressed in earlier commits, so the review-thread gate should stop failing once checks run again.

Why the fresh CI is not showing results yet

Because this PR comes from a fork, the newly triggered workflow runs on the updated SHA are currently landing in action_required, so they still need to be approved / re-run from GitHub before we get fresh results.

REST API workflow: what is actually failing?

The confusing part is the log output.

The ConversationIterationLimitEvent additions to response oneOf lists are not the reason the workflow fails. That part is already explicitly downgraded to a notice in .github/scripts/check_agent_server_rest_api_breakage.py.

What is actually fatal is the addition of the new max_iterations_reached value to the public execution_status response enum.

So the workflow is effectively saying:

1. Allowed / informational: additive response-union expansion (ConversationIterationLimitEvent added to oneOf)
2. Still breaking: response enum expansion (execution_status can now return max_iterations_reached)

The reason it looks contradictory is that after printing the notice, the script still prints the full raw oasdiff change list under Breaking REST API changes detected, so the allowed oneOf additions show up there again alongside the real failures.

My take

I think the messaging is too confusing, but the workflow itself is not too strict here.

Adding a new response enum value is a real REST contract break for clients that generated closed enums from the OpenAPI schema or otherwise assume the documented value set is exhaustive. Since execution_status is part of the public agent-server REST surface, this PR is changing that contract in place.

So my read is:

• the oneOf event addition is fine
• the new execution_status enum member is the real compatibility problem
• the workflow output should probably be improved so the non-fatal oneOf notices are not repeated in the fatal summary
• a package version bump alone would not solve this anyway, because this workflow is enforcing the 5-minor-release REST compatibility policy, not just SemVer labeling

If we want MAX_ITERATIONS_REACHED internally/SDK-side but not as an immediate REST break, I think the fix should be a compatibility strategy in the public API rather than weakening the checker.

This comment was created by an AI assistant (OpenHands) on behalf of @enyst.

[enyst]

Hi, I'm OpenHands-GPT-5.4. I wanted to make the compatibility concern more concrete, because I think the key point is easy to miss from the raw workflow output.

Why can adding a new enum value be a breaking change?

Because once an API schema says a field is an enum, many clients reasonably assume that the documented value set is exhaustive. In other words, they treat it as a closed set, not just as an arbitrary string.

That happens in a few common ways:

• Generated SDKs often turn the field into a language enum or a closed string union
  • TypeScript: "idle" | "running" | "paused" | ...
  • Java / Kotlin / Swift / C#: actual enum types
• Deserializers may reject unknown enum members at parse time
• Application logic often uses exhaustive branching, like a switch / match over the documented values
• State-machine assumptions get encoded from the published set of statuses

So even though adding a value looks "additive" from the server side, it is not always additive from the client side.

Why that matters specifically for execution_status here

This is not just adding a decorative label. max_iterations_reached changes the meaning of a public state-machine field that clients may already interpret.

Clients can easily have logic like:

• if status is running, keep polling
• if status is finished, stop and show success
• if status is error, show failure
• if status is stuck, show a retry / recovery action

A client built against the old schema may not know what to do with max_iterations_reached. Depending on the implementation, it might:

• fail to deserialize the response entirely
• hit a default / impossible-state error path
• keep polling because it does not know the new value is terminal-ish
• incorrectly bucket it as a generic failure
• fail to show the right UI affordance, e.g. a "resume by sending a new message" flow

And in this PR, that new value is semantically important:

• it is distinct from error
• it affects how clients classify the outcome
• it affects what UI / retry / resume behavior makes sense

So I think the right interpretation is:

• adding ConversationIterationLimitEvent to a response oneOf is fine for this workflow and is already treated as allowed
• adding a new execution_status enum member is a real REST compatibility change, because older consumers may have encoded the previous enum as exhaustive

Put differently: the workflow output is a bit confusing, but the underlying concern is legitimate.

This comment was created by an AI assistant (OpenHands) on behalf of @enyst.

[enyst]

Hi, I'm OpenHands-GPT-5.4. Since I think this is a real REST compatibility break, here are the practical options I see.

1. Keep the new SDK/internal status, but preserve the current REST contract

This looks like the best short-term option to me.

Idea

• Internally / SDK-side, keep MAX_ITERATIONS_REACHED
• In the public REST API, keep execution_status returning only the old documented values
• Expose the richer meaning somewhere additive instead, for example:
  • termination_reason: "max_iterations_reached"
  • or error_code: "max_iterations_reached"
  • or resume_reason: "iteration_limit"
  • or rely on the additive ConversationIterationLimitEvent where appropriate

Why it works

• No enum expansion on the public REST field
• Older clients that only understand the old execution_status set keep working
• Newer clients can opt into the richer signal

Tradeoff

• There is a translation layer between internal state and public REST representation
• The REST contract is slightly less direct than the internal model

My recommendation for this PR: this is probably the best path.

2. Add a new additive field now, deprecate the old semantics, migrate over 5 minors

This feels like the cleanest policy-perfect migration path.

Idea

Keep current execution_status stable, and add a new field such as:

• detailed_execution_status
• stop_reason
• terminal_reason

For example:

• execution_status = "error" or whatever remains backward-compatible
• stop_reason = "max_iterations_reached"

Then:

• document that clients should migrate to the new field
• after 5 minor releases, the old contract can be changed or retired safely

Why it works

• Fully compatible with the repository's REST deprecation policy
• Provides a clear migration path for consumers

Tradeoff

• Slower rollout
• Temporary duplication in the API surface

3. Version the REST contract

This makes sense if we really want execution_status itself to change.

Idea

Introduce a versioned API shape, e.g. a v2 route or versioned response contract.

• In v1: keep the old enum
• In v2: allow execution_status = "max_iterations_reached"

Why it works

• Clean and explicit contract separation
• No ambiguity for clients

Tradeoff

• Heavyweight for a single status change
• Probably overkill unless more breaking API changes are already planned

4. Treat this as a deliberate breaking API change and do the full deprecation runway

This is policy-compliant, but it is slower and in practice usually collapses into option 2 or 3.

Idea

If we really want execution_status to grow a new enum member in the public REST API, then:

• deprecate the old contract first
• document the scheduled removal/change
• preserve compatibility for 5 minor releases
• only then make the new contract mandatory

Problem

For a field-level response change, this usually still means introducing either:

• a parallel field, or
• a versioned contract

So while this is conceptually valid, it usually turns into option 2 or option 3 in implementation.

5. Relax the CI checker to allow enum additions

This is possible, but I would not recommend doing it globally.

Why not

If the checker learns that "adding enum values is fine", we weaken protection exactly where strongly-typed generated clients are most vulnerable.

Narrow version that might be acceptable

The only version I would seriously consider is something explicit and narrow, e.g. only allowing enum additions for fields intentionally marked as extensible in OpenAPI (for example via a vendor extension like x-extensible-enum: true).

That would make the compatibility intent explicit instead of silently weakening the rule for every enum.

Tradeoff

• More complexity in the checker
• Requires API design discipline going forward

What I would do here

My recommendation for this PR would be:

1. keep MAX_ITERATIONS_REACHED internally
   • SDK
   • conversation runtime
   • tests
   • events
2. do not add it to the public REST execution_status enum yet
3. expose the distinction additively instead
   • ideally through a new field like stop_reason = "max_iterations_reached"
   • or through the additive ConversationIterationLimitEvent if that is sufficient for downstream consumers

That gets us:

• the internal correctness we want
• resumability behavior
• better observability
• and no immediate public REST break

So my summary is:

• smallest safe option now: option 1
• cleanest migration path: option 2
• true contract redesign: option 3
• workflow relaxation: only a very narrow version of option 5, if at all

This comment was created by an AI assistant (OpenHands) on behalf of @enyst.

[all-hands-bot]

[Automatic Post]: It has been a while since there was any activity on this PR. @utkarsh-in, are you still working on it? If so, please go ahead, if not then please request review, close it, or request that someone else follow up.

[all-hands-bot]

[Automatic Post]: It has been a while since there was any activity on this PR. @utkarsh-in, are you still working on it? If so, please go ahead, if not then please request review, close it, or request that someone else follow up.