chore: prevent orphan tool messages when enable_snapshot_clean is on

[fengju0213]

Description

Summary

This PR fixes a state-leak issue in ChatAgent that can produce invalid message history (orphan tool messages) across agent reuse scenarios.

Root Cause

• ChatAgent keeps snapshot-clean metadata in _tool_output_history.
• reset() previously did not clear this cache.
• When an agent instance is reused (e.g., worker pool), stale entries from a previous task can still be processed.
• _clean_snapshot_in_memory() could rewrite a cleaned FUNCTION/tool record even if the original referenced records no longer existed in current memory.
• This may inject orphan tool messages (without preceding assistant.tool_calls), which can trigger strict backend validation errors (e.g., Azure/LiteLLM 400).

Fix Approach

1. Clear snapshot-clean cache on reset:
   • ChatAgent.reset() now clears _tool_output_history.
2. Add safe-guard before rewriting cleaned tool output:
   • In _clean_snapshot_in_memory(), only rewrite when referenced record UUIDs still exist in storage.
   • If no referenced records are found, skip rewrite and mark the entry as cached.

Why this is safe

• Normal snapshot-clean flow is unchanged when records exist.
• Only stale/cross-task cache entries are blocked from writing new tool records.
• This prevents invalid cross-conversation contamination without affecting valid tool-call chains.

Tests

Added unit tests in test/agents/test_chat_agent.py:

• test_chat_agent_reset_clears_tool_output_history
• test_clean_snapshot_in_memory_skips_missing_records

Checklist

Go over all the following points, and put an x in all the boxes that apply.

• I have read the CONTRIBUTION guide (required)
• I have linked this PR to an issue using the Development section on the right sidebar or by adding Fixes #issue-number in the PR description (required)
• I have checked if any dependencies need to be added or updated in pyproject.toml and uv lock
• I have updated the tests accordingly (required for a bug fix or a new feature)
• I have updated the documentation if needed:
• I have added examples if this is a new feature

If you are unsure about any of these, don't hesitate to ask. We are here to help!

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch fix_eigent_1223

---

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 and usage tips.}

[Wendong-Fan]

thanks @fengju0213 for the fix, this bug is introduced by #3409 which introduce one design issue as commented in #3409 (review), there's one enhance pr #3413 would solve this issue from the root which was not merged, i think we should move this pr forward instead of doing temperary fix here, i will close this pr for now

cc @nitpicker55555