Summary

Successive tool-runner messages can leave the official Anthropic stream consumer with an empty final answer. Messages now emits one logical lifecycle and retains the run's tool results and continuation history.

Closes #563.

Goal

Provide a coherent Messages stream and an authoritative result for safe continuation.

What Changed

• Rebase content-block indices across turns and retain visible text. Executed client tools stay in the continuation transcript; unexecuted calls remain visible.
• Add MessagesStream.result, get_final_result(), and close(). Streaming and non-streaming use the same finalization; message_stop.result carries the final dictionary. Execution-time PageIndexAPIError also retains it.
• Record actual tool results and distinguish completion, turn limits, failure, cancellation, and uncertain execution. Sum token/cache counters with explicit missing-count semantics.
• Retain native usage and terminal metadata. Follow the installed runner's continuation behavior; compaction disables append-only continuation.
• Document the contract in the existing API docstrings and test it with the real runner, counted tools, mocked HTTP responses, and the public Anthropic client.

Messages streams yield JSON event dictionaries. Turn-limit results use stop_reason="pause_turn" and retain the provider reason in run.model_stop_reason. Continuation uses messages; incomplete model turns are kept out of that history. Closing stops subsequent local work but cannot certify cancellation of dispatched external work.

Validation: 872 passed, 12 skipped in the full local suite with Anthropic 1.7.0; 11 targeted tests passed each on Anthropic 0.122.0, 1.0.0, and 1.1.0. git diff --check passes. Coverage includes single/multiple turns, native metadata, compaction, provider pauses, content indices, usage/cache completeness, turn-limit continuation without duplicate calls, failure, truncated streams, and close. Tests use no paid model calls.

Key Files

• pageindex/local_chat.py: stream composition and shared finalization at the existing runner hook.
• pageindex/chat_stream.py: the result-bearing iterator.
• pageindex/client.py, pageindex/__init__.py: API contract and public types.
• tests/test_local_chat.py, tests/test_package_surface.py: behavioral and public-interface checks.