fix: Fix broken converstaion with orphaned toolUse

[Unshure]

Description

This pr fixes previously broken sessions with orphaned toolUses, and applies a fix for this issue going forward.

The issue was that when a session is stopped with ToolUse as the latest message (i.e. a tools execution is stopped), the session is persisted in a state where the conversation is no longer valid.

User: text("Use the weather tool")
Assistant: toolUse("weather_tool")
// runtime stops, no "toolResult" added

In this case, when customers restore an agent from session, they try to invoke it again, leading to a conversation that looks like this:

User: text("Use the weather tool")
Assistant: toolUse("weather_tool")
User: text("Use the weather tool")

This results in a validation exception where there is an orphaned tool use persisted in session history.

This PR fixes this by:

1. For agents whose latest message is "toolUse", and the agent is invoked with a message, we first append a "toolResult" to the agent messages to fix the conversation before it continues
2. For existing broken session histories, we add a new "toolResult" after orphaned "toolUse" messages.

One thing to note is that for existing broken sessions, we are not fixing the session in the persisted storage, just adding a temporary "toolResult" to the agent messages to fix it. This is because we would need to perform a backfill on messages in session to fix this issue in persistence. Instead, this stops the issue from continuing.

Related Issues

#1111
#859

Documentation PR

TODO

Type of Change

Bug fix

Testing

How have you tested the change? Verify that the changes do not break functionality or introduce warnings in consuming repositories: agents-docs, agents-tools, agents-cli

• I ran hatch run prepare

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!