feat(tool): returns schema

[kwaa]

closed #110

[charliechecks]

I need the pull request number to review. Could you please provide the PR number you'd like me to review?

[kwaa]

I need the pull request number to review. Could you please provide the PR number you'd like me to review?

118

[kwaa]

@CharlieHelps, would you mind reviewing this PR?

[charliechecks]

The review has been posted to GitHub.

[charliechecks]

The diff introduces increased type complexity and some potential pitfalls in the handling of tool metadata. In particular, the conditional types for the execute function can be hard to follow, the removal of the returns property in chat may need review, and resetting the tool name in the compatibility layer could lead to unexpected behavior if not intentional.

Summary of changes

Summary of Changes

• Documentation Update: Added a new documentation example in docs/content/docs/packages/tool.mdx demonstrating how to use the returns schema with a tool.
• Generics & Schema Enhancements: Updated the compatibility layer in packages-ext/compat/src/utils/tool.ts and the core tool implementation in packages/tool/src/index.ts to support generics with schema types, including a new returns field and conditional types for the execute function.
• Type Definitions & API Updates: Modified the Tool interface in packages/shared-chat/src/types/tool.ts to include an experimental returns property and refined the return type of the execute function.
• Chat Utilities & Testing: Adjusted the chat utility in packages/shared-chat/src/utils/chat.ts to clean the returns property, and added new tests in packages/tool/test/index.test.ts to validate the tool behavior with a returns schema.