feat(loop): expose turn_count, final_content, usage, request_metadata in result

[chubes4]

Summary

Closes #135. Expose four universally-needed observability fields on the conversation loop result, eliminating the need for consumers to pass mutable state by reference through their turn runner closure.

Field	Type	Source
turn_count	int	Existing internal loop counter, surfaced
final_content	string	Derived from last assistant message in $messages
usage	array	Summed from each turn runner's optional usage return field
request_metadata	array	Overwritten by each turn runner's optional request_metadata field

Why

Consumers building agents on top of WP_Agent_Conversation_Loop need more than messages + tool_execution_results. They need to know how many turns ran, what the agent finally said, what it cost (tokens), and what the last provider request looked like. The substrate already had access to all of this — it just didn't formalize it as part of the result contract.

Without these fields, consumers resort to passing mutable state by reference through their turn runner closure. The data-machine consumer (inc/Engine/AI/conversation-loop.php:datamachine_run_conversation) does exactly this with six & parameters threaded through a separate build_turn_runner factory just so the outer function can read accumulators after the loop returns. See #135 for full evidence.

What changes

Loop (class-wp-agent-conversation-loop.php)

• Accumulates $turns_run (existing counter), $total_usage (summed across turns), $request_metadata (latest turn).
• Reads $result['usage'] and $result['request_metadata'] from each turn runner return value (both optional — turn runners that don't report them get empty defaults).
• Adds all four fields to the final result.
• Two new private helpers:
  • accumulate_usage( $running, $turn ) — sums canonical token-count fields and preserves provider-specific keys like cache_creation_input_tokens or reasoning_tokens. Numeric fields are summed; non-numeric fields are taken from the latest turn.
  • extract_final_content( $messages ) — walks the transcript backward for the last non-empty assistant text content. Returns '' when none exists (e.g. tool-call-only tail).

Result (class-wp-agent-conversation-result.php)

Validates the four new fields when present:

• turn_count must be int
• final_content must be string
• usage must be array
• request_metadata must be array

All four are optional in the schema — normalize() won't reject results that don't include them, so callers that construct results without the loop (test fixtures, manual normalization) keep working.

Compatibility

100% additive. Every existing consumer keeps working:

• Consumers reading messages, tool_execution_results, status, budget see no change.
• Turn runners that don't return usage or request_metadata get empty defaults in the result.
• Turn runners that already return request_metadata (the existing conversation-loop-transcript-persister-smoke test does this) continue to round-trip correctly — the loop reads it from the per-turn return shape and surfaces it on the final result, exactly as before.

Test plan

All 30 substrate smoke tests pass on this branch:

PASS conversation-loop-smoke                              (6 assertions)
PASS conversation-loop-tool-execution-smoke               (19)
PASS conversation-loop-completion-policy-smoke            (6)
PASS conversation-loop-events-smoke                       (17)
PASS conversation-loop-budgets-smoke                      (24)
PASS conversation-loop-transcript-persister-smoke         (18 — including request_metadata round-trip)
PASS conversation-runner-contracts-smoke                  (18)
PASS iteration-budget-smoke                               (22)
PASS conversation-compaction-smoke
PASS conversation-transcript-lock-smoke
PASS effective-agent-resolver-smoke
PASS execution-principal-smoke
PASS guidelines-substrate-smoke
PASS identity-smoke
PASS markdown-section-compaction-smoke
PASS memory-metadata-contract-smoke
PASS message-envelope-smoke
PASS no-product-imports-smoke
PASS pending-action-store-contract-smoke
PASS registry-smoke
PASS remote-bridge-smoke
PASS routine-smoke                                        (22)
PASS subagents-smoke                                      (6)
PASS tool-policy-contracts-smoke
PASS tool-runtime-smoke
PASS webhook-safety-smoke
PASS workflow-bindings-smoke                              (13)
PASS workflow-runner-smoke                                (26)
PASS workflow-spec-validator-smoke                        (24)
PASS workspace-scope-smoke

Follow-up

After this merges, the data-machine consumer will refactor to drop its by-reference accumulator dance and read directly from the new result fields. Separate PR forthcoming on Extra-Chill/data-machine.