Feature/stab fixes sessions flows

[wolfy-j]

This pull request introduces several improvements and bug fixes to the Claude and OpenAI mappers, as well as updates to the Stream module documentation. The most significant changes include stricter tool ID sanitization and handling for Claude integration, improved merging logic for developer messages, a more robust approach to empty function call arguments in the OpenAI mapper, and a comprehensive rewrite of the Stream module's documentation to clarify its API and behavior.

Claude Mapper Improvements:

• Added a sanitize_tool_id function to enforce Claude's tool ID format and applied it wherever tool IDs are set or read, preventing invalid tool IDs from causing errors. [1] [2] [3] [4] [5]
• Improved merging logic for developer messages: now, if the previous message is a tool result or if there are no previous messages, a new user message is created instead of merging, ensuring correct message sequencing.

OpenAI Mapper Fixes:

• Fixed an issue where empty function call arguments would serialize as {} by replacing them with { invoke = true }, ensuring downstream compatibility.
• Adjusted prompt token calculation to subtract cached tokens, providing more accurate token usage reporting.

Documentation Updates:

• Completely rewrote the Stream module documentation to clarify its API, including chunk-based and token-based reading, scanner lifecycle, async behavior, error handling, and best practices. This makes the module's usage and expected behaviors much clearer for developers. [1] [2]

Minor/Other:

• Added retrieval of the from PID in the message processing spec for completeness.
• Removed extraneous newlines and minor formatting tweaks in the OpenAI mapper for code cleanliness. [1] [2] [3] [4] [5]