feat: allow async functions as tools

[ajbozarth]

Misc PR

Type of PR

• Bug Fix
• New Feature
• Documentation
• Other

Description

• Link to Issue: Fixes part of Move MCP tool integration from contribs into core mellea #1032

Add async support to MelleaTool.from_callable (and by extension the @tool
decorator) so any developer can register an async function as a tool.

• from_callable detects inspect.iscoroutinefunction(func) and wraps the
  coroutine through mellea's shared event loop (_run_async_in_thread), so
  sync callers of .run() receive the resolved value rather than an
  un-awaited coroutine.
• The @tool decorator gets the same support for free (it delegates to
  from_callable).
• Added overloads on both from_callable and @tool so
  Callable[P, Awaitable[R]] narrows to MelleaTool[P, R], keeping
  static return types correct whether the wrapped function is sync or async.

Split out from a broader plan that also adds MCP tool support.

Testing

• Tests added to the respective file if code was changed
• New code has 100% coverage if code as added
• Ensure existing tests and github automation passes (a maintainer will kick off the github automation when the rest of the PR is populated)

Added:

• test/backends/test_mellea_tool.py — async wrap, schema parity with sync, exception propagation.
• test/backends/test_tool_decorator.py — @tool on async (edge case class).
• test/typing/check_tools.py — mypy assert_type verification that the async overload narrows through .run().

Attribution

• AI coding assistants used (Claude Code)

[ajbozarth]

@jakelorocco When moving the MCP tool support over I tried moving it's asynchronous handling into MelleaTool, but realized that it didn't make sense to have MCPToolSpec leverage from_callable instead of just creating MelleaTool directly. But as the feature was still worth doing I have opened this.

I also opened #1043 as a follow up issue to replace this implementation with actual async tool calling