Preserve provider output with append-only CodeAct text correction 🤖🤖🤖

[furgalep]

Problem

CodeAct requires each model turn to call execute_python() or return_result(). When a model instead returns plain text, both text-only recovery routes remove the provider-authored LLMOutput and replace it with synthetic events.

For Responses reasoning models, the removed event can contain the exact assistant text plus opaque/encrypted reasoning output items needed for stateless multi-turn continuation. Removing it loses reasoning continuity. Attaching those items to the synthetic tool call would retain bytes but would incorrectly attribute the model reasoning to a function call the model never produced.

Affected continuations:

• text_only_stop_behavior=return_result when synthetic return validation fails and the model is asked to retry
• text_only_stop_behavior=synthetic_comment, which always continues to another model turn

A successful synthetic return_result does not require another provider call, but its trace should still preserve what the provider actually returned.

Desired design

Make CodeAct correction append-only:

1. Preserve the original provider-authored output event and exact replayable output batch.
2. Record provider/client/model-family provenance with opaque continuation state.
3. Add correction and synthetic execution events after the provider event instead of deleting or rewriting it.
4. Keep framework-synthetic events distinguishable from provider-authored events.
5. On the next request, replay the exact provider reasoning + assistant output, followed by a normal model-visible correction.
6. Do not replay retained state to an incompatible provider or model family.

Acceptance criteria

• Neither text-only recovery route removes the provider-authored output.
• A validation-failure retry replays the original Responses items in their original order before correction.
• Synthetic-comment continuation preserves the same ordering.
• Synthetic events are not represented as provider-authored output.
• Persistence/session resume preserves the continuation state and provenance.
• Tests cover Actor → event storage → CodeAct recovery → formatter → second Responses request.
• Existing Completion-client text-only behavior remains unchanged.

Related: #261

🤖🤖🤖

[furgalep]

#264 addressed on fix/gpt56-responses-reasoning (f1d2a54)

Implemented append-only text-only recovery in the base CodeAct strategy (so the experimental single-tool strategy inherits it), using the design Paul asked for: A/ keep the provider LLMOutput in place (an artificial assistant "prefill"-style turn is what already existed for prefill, so this mirrors that), then B/ a set of pluggable correction options.

What changed

• CodeActConfig.text_only_correction — opt-in Literal["comment", "return", "custom"] | None, plus text_only_correction_fn: Callable[[str], str] | None for the custom message.
• Append-only: when opted in, neither recovery route deletes the provider-authored LLMOutput. For Responses reasoning models it carries reasoning_items, so stateless replay keeps reasoning continuity, in the correct order (reasoning → assistant → function_call → function_call_output, verified through the formatter).
  • Route A (return) passes an empty event_id to _process_tool_calls so the preserved event isn't removed.
  • Route B (comment) skips the remove() and appends the synthetic comment after the provider turn, flagged metadata.synthetic so it's never mistaken for provider output.
  • custom appends the callable's message as a model-visible Error.
• Legacy unchanged: with text_only_correction unset, the old delete-then-replace behavior holds, so existing configs and Completion-client behavior are untouched.

Acceptance-criteria mapping

• Provider output preserved on both routes ✅
• Reasoning items replay in original order before correction ✅ (formatter-verified)
• Synthetic events flagged, not provider-authored ✅
• Completion-client text-only behavior unchanged ✅ (legacy default + reasoning_items is None there)

Remaining from the issue's "desired design" that I did not do here (happy to follow up): an explicit provider/model-family provenance tag with a replay gate for cross-family safety, and a full Actor→storage→recovery→formatter→second-Responses-request integration test (the current tests cover storage + recovery + formatter ordering, but not a live second request).

Verification

• New append-only tests: 10 passed in test_codeact_text_only_reply.py.
• Regression: 1041 passed across tests/strategies, tests/config, formatter, test_llm_complete_event, and test_responses_reasoning_state.
• ruff check + ruff format --check: clean.

[furgalep]

#264 follow-ups (1) and (2) done — 7ee4940

Both items I flagged are now on fix/gpt56-responses-reasoning.

(1) Provider/model-family provenance tag + replay gate

Opaque OpenAI reasoning state is now never replayed to a different family:

• unifiedllm.model_family(model) → "openai" | "anthropic" | "other".
• reasoning_provenance stored alongside reasoning_items on LLMOutput, ToolCallEvent, and RenderedMessage, tagged at capture in the actor and CodeAct.
• Replay gate: the Responses/OpenAI formatters only emit reasoning_items when the current model family (a render-scoped contextvar the actor sets) matches the stored provenance; ResponsesClient._transform_messages drops opaque state on non-OpenAI models. Unknown values stay permissive, so existing behavior is unchanged.

(2) Full integration test

Added TestAppendOnlyReasoningReplayIntegration covering Actor → event storage → CodeAct recovery → formatter → second Responses request: append-only recovery preserves the provider reasoning turn (with provenance openai), replays the reasoning items in order before a reconstructed assistant message for a same-family request, and drops them on a family switch. Plus provenance-gate unit tests (same-family replays, different-family drops, unknown permissive).

Also confirmed while here

• Prefill does not break Responses. Prefill emits function_call/function_call_output (CodeAct) or an assistant message (pure-Python) with no reasoning_items; the Responses API only requires reasoning items (when present) to precede their call, so an unprefixed call/message is valid.
• Coverage on CodeAct + ExCodeAct. The recovery routes live only in base CodeActStrategy; CodeActExperimental inherits them, verified at runtime (append_only=True for both).

Verification

• 1398 passed across tests/strategies, tests/config, tests/context_blocks/test_formatters.py, test_llm_complete_event, and tests/unifiedllm.
• ruff check + ruff format --check: clean.

This completes the "desired design" bullets in #264 (append-only preservation, ordered replay, synthetic events distinguishable, provenance/model-family gate, integration test, Completion behavior unchanged).

[furgalep]

Now tracked in stacked PR #268

Per review preference, the #264 work (append-only text-only recovery + model-family provenance gate) is now its own PR #268, stacked on top of #261 (fix/gpt56-responses-reasoning). It'll retarget to dev/tui once #261 merges. Both branches verified green (#261: 93 passed, #268: 56 passed on the focused suites; 1398 in the full run).