[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)