[integrations][plan] Handle finish_reason in OpenAI-family connections

[weiqingy]

Linked issue: #936

Purpose of change

finish_reason was never read in either language, so a truncated completion came back as ordinary partial content. Under structured output that content went straight to a JSON parser, so the caller got an error naming the parser instead of the truncation. Worse, when the truncated content happened to still be valid JSON, nothing raised at all and the caller silently received wrong data.

Cases 1 and 3 of #936 shipped in #952 and #989. This is the last one.

The change has three parts:

1. Both languages record the provider's reason as finish_reason in message metadata. Unknown values are stored verbatim, and an absent reason writes no key.
2. The shared structured-output path checks it before parsing. length and content_filter fail with the cause named. stop, tool_calls, unknown values and an absent key parse as before. Non-structured calls are untouched, so a truncated answer is still returned and the caller decides.
3. Python's outbound converter had to be fixed first. It merged all of extra_args into outbound messages, and since the chat action replays the assistant response on the next tool-call turn, model_name, promptTokens, completionTokens and structured_output were reaching the provider as message fields. Each role now sends only the fields OpenAI defines, matching Java.

Four things worth knowing when reading the diff:

• Java reads through _finishReason().asKnown() rather than finishReason(). The plain accessor throws OpenAIInvalidDataException when the member is absent or null, and VLLMChatModelConnection extends OpenAICompletionsConnection, so OpenAI-compatible servers that omit it would start failing calls that work today.
• The check runs before the parser execution is reported, not inside the parse. The reporting wrapper labels any parse exception model_output_parse_error, so gating inside it would report a truncation as a parse failure, which is the same misleading diagnosis this change removes. The trade is that a truncation no longer produces a PARSER failure report. The action-level failure is still reported.
• Java's structured-output result now carries inbound metadata forward instead of starting from an empty map. It previously dropped finish_reason exactly when an output schema was in play, while Python kept it.
• Two visible behavior changes. A Python caller can no longer forward arbitrary extra_args to the provider, which Java never allowed and nothing in the repo relies on. And truncated content that still parses now raises instead of returning wrong data, so callers using RETRY will see those responses retried.

Out of scope: the Responses API reports status and incomplete_details.reason, a different vocabulary. Providers that record no reason are unaffected and pick the behavior up if they later write the same key.

Tests

./tools/build.sh and ./tools/ut.sh are green: 33/33 modules, Java 1592 run with 0 failures, Python 938 passed. Each of the five commits also builds and passes on its own.

Coverage was driven by mutation testing, and every mutant in scope is killed in both languages: swapping in the throwing accessor, moving either capture inside the token-usage guard, moving the gate inside the reporting wrapper, dropping either terminal reason, and reinstating the blanket merge.

Two test properties are load-bearing and easy to lose in a later refactor. The throwing tests use valid JSON, because truncated JSON raises on its own and a malformed fixture would pass with no gate at all. And one test asserts that a rejected response produces no parser execution report, which is the only thing stopping the gate from drifting back inside the wrapper.

Both languages were also driven through identical inputs to confirm they agree, including that neither sends the metadata keys to a provider.

API

No public API change. finish_reason is a metadata key rather than a field, and no new exception type or problem category is introduced. Failures reuse ValueError in Python and IllegalStateException in Java, both already used for this class of failure in their packages. Since json.JSONDecodeError subclasses ValueError, Python callers catching today's symptom keep working and simply get a clearer message.

Documentation

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

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

• Yes
• No

Generated-by: Claude Code 2.1.234 (Claude Opus 5)