[API][Tool] Align Java and Python Tool outcome contracts

[joeyutong]

Linked issue: #956

Purpose of change

Java can distinguish whether a Tool invocation returned from whether the returned ToolResponse represents a successful Tool operation. Python previously exposed only raw return values, so every normal return was recorded as a successful Tool operation.

This change aligns the Java and Python Tool outcome contracts:

• adds Python ToolResponse.success(...) and ToolResponse.error(...) while preserving raw Python returns as successful results;
• normalizes sequential and parallel Python Tool calls through the same result-recording path;
• preserves explicit Tool outcomes across both Java-to-Python and Python-to-Java bridges without inspecting arbitrary user payloads;
• records missing Skill resources and MCP protocol error results as failed Tool operations while retaining their existing model-facing messages;
• keeps Outcome<T> focused on whether the durable invocation returned or raised.

ToolResponseEvent, Execution Events, and downstream metrics can therefore consume the same normalized Tool outcome in both languages. The existing ToolResponseEvent.responses wire representation is unchanged.

Tests

• mvn -pl api,plan,runtime,integrations/mcp -am -DskipITs test
• pytest for the affected Python Tool API, Tool call, MCP, Skill, and Java bridge suites (66 passed)
• Ruff format and lint checks for all changed Python files

API

Adds the public Python flink_agents.api.tools.ToolResponse type. Existing Python Tools that return raw values remain source- and behavior-compatible.

Documentation

• doc-needed
• doc-not-needed
• doc-included

Was this patch authored or co-authored using generative AI tooling?

• Yes
• No

Generated-by: Codex 0.151.0-alpha.7.2 (GPT-5.6 Sol)

[wenjin272]

Thanks for working on aligning the Java and Python tool outcome contracts!

[wenjin272]

Could we also normalize explicit outcomes in PythonMCPTool.call()? That Java wrapper still wraps every normal Python return in ToolResponse.success(...). Returning ToolResponse.error(...) here therefore causes Java agents using Python MCP tools to record failures as successes. This reproduces with real Pemja for both transport exceptions and MCP protocol errors. Please cover this path with a cross-language regression test.

[joeyutong]

Fixed. PythonMCPTool now uses the same bridge encoder/decoder as FunctionTool, so an explicit Python ToolResponse.error(...) remains a failed Java ToolResponse. I also added a unit regression and extended MCPCrossLanguageTest with a real FastMCP protocol error over Pemja.

[wenjin272]

Could we move the protocol-error check outside async with self._get_session()? With a real ClientSession, raising here gets wrapped in an AnyIO ExceptionGroup. MCPTool.call() then retains only the outer message, “unhandled errors in a TaskGroup”, losing the original MCP error content and recovery hints. A regression test retaining the real session lifecycle would catch this; the current fake session does not.

[joeyutong]

Fixed by moving MCP content/error interpretation outside the session context. The regression now uses a real ClientSession lifecycle and verifies that the original protocol error content is retained instead of only the outer ExceptionGroup message.