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

The conversation loop's result contract previously surfaced only
`messages`, `tool_execution_results`, `events`, and the optional
`status`/`budget` pair. Consumers building real agents on top of the
substrate need four additional pieces of information:

* `turn_count` — how many turns actually executed
* `final_content` — text of the last assistant message
* `usage` — accumulated token counts across all turns
* `request_metadata` — most recent turn's provider request descriptor

The substrate already had access to all four — `turn_count` lives in
the loop counter, `final_content` is computable from `messages`, and
turn runners were already returning `usage` and `request_metadata` per
turn (the latter was even tested for passthrough). They just weren't
formalized as part of the result contract.

Without these fields, consumers like data-machine resort to passing
mutable state by reference through their turn runner closure so the
outer caller can read accumulators after the loop returns:

    $turn_runner = build_turn_runner(
        ...
        &$last_request_metadata,
        &$total_usage,
        &$turns_run,
        &$final_content,
    );
    WP_Agent_Conversation_Loop::run( $messages, $turn_runner, $options );
    // Now read the by-reference accumulators back into the result.

This is gross and a sign the substrate is missing universal-consumer
observability. Other future consumers will hit the same gap.

## What changes

* The loop accumulates `turn_count` (existing internal counter, just
  surfaced now), `final_content` (extracted from messages at result
  time), `total_usage` (summed from each turn runner's optional
  `usage` field), and `request_metadata` (overwritten by each turn
  runner's optional `request_metadata` field).
* `WP_Agent_Conversation_Result::normalize()` validates the four new
  fields when present (int, string, array, array respectively).
* Two new private helpers: `accumulate_usage()` sums numeric token
  counts while preserving provider-specific extras like
  `cache_creation_input_tokens` or `reasoning_tokens`;
  `extract_final_content()` walks messages backward for the last
  non-empty assistant text content.

## Compatibility

All four fields are **additive** to the result shape — existing
consumers reading `messages`/`tool_execution_results`/`status`/`budget`
continue to work unchanged.

The turn-runner contract gains two optional return fields (`usage`,
`request_metadata`); turn runners that don't return them get the empty
default. Turn runners that already return `request_metadata` (the
existing `conversation-loop-transcript-persister-smoke` test does this)
continue to round-trip correctly.

## Verification

All 30 substrate smoke tests pass:

* conversation-loop-smoke (6 assertions)
* conversation-loop-tool-execution-smoke (19)
* conversation-loop-completion-policy-smoke (6)
* conversation-loop-events-smoke (17)
* conversation-loop-budgets-smoke (24)
* conversation-loop-transcript-persister-smoke (18 — including the
  pre-existing request_metadata round-trip test)
* conversation-runner-contracts-smoke (18)
* iteration-budget-smoke (22)
* plus the broader substrate suites (compaction, identity, guidelines,
  workflows, routines, subagents, etc.)

Closes #135

Author: chubes4

src/Runtime/class-wp-agent-conversation-loop.php

@@ -89,7 +89,19 @@ public static function run( array $messages, callable $turn_runner, array $optio
 		$tool_results          = array();
 		$conversation_complete = false;
 		$exceeded_budget       = null;
-		$last_request_metadata = array();
+
+		// Universal observability accumulators. Turn runners may report
+		// `usage` (token counts) and `request_metadata` (last provider request
+		// descriptor) in their per-turn return value; the loop accumulates
+		// these and exposes them in the final result so consumers don't have
+		// to track them out-of-band via mutable state.
+		$turns_run        = 0;
+		$total_usage      = array(
+			'prompt_tokens'     => 0,
+			'completion_tokens' => 0,
+			'total_tokens'      => 0,
+		);
+		$request_metadata = array();
 
 		if ( null !== $transcript_lock && '' !== $lock_session_id ) {
 			$lock_token = $transcript_lock->acquire_session_lock( $lock_session_id, $lock_ttl );
@@ -109,6 +121,7 @@ public static function run( array $messages, callable $turn_runner, array $optio
 
 		try {
 			for ( $turn = 1; $turn <= $max_turns; ++$turn ) {
+				$turns_run            = $turn;
 				$turn_context         = $context;
 				$turn_context['turn'] = $turn;
 
@@ -157,6 +170,18 @@ public static function run( array $messages, callable $turn_runner, array $optio
 					throw $error;
 				}
 
+				// Accumulate optional observability fields from the turn runner.
+				// `usage` is a per-turn token-count array that gets summed into
+				// `$total_usage`. `request_metadata` is the most recent provider
+				// request descriptor and overwrites on each turn — consumers
+				// typically only care about the last one.
+				if ( isset( $result['usage'] ) && is_array( $result['usage'] ) ) {
+					$total_usage = self::accumulate_usage( $total_usage, $result['usage'] );
+				}
+				if ( isset( $result['request_metadata'] ) && is_array( $result['request_metadata'] ) ) {
+					$request_metadata = $result['request_metadata'];
+				}
+
 				// When mediation is enabled, the turn runner returns tool_calls
 				// and the loop handles execution. Otherwise, the caller-managed path applies.
 				if ( $mediation_enabled && isset( $result['tool_calls'] ) && is_array( $result['tool_calls'] ) ) {
@@ -237,12 +262,12 @@ public static function run( array $messages, callable $turn_runner, array $optio
 				'messages'               => $messages,
 				'tool_execution_results' => $tool_results,
 				'events'                 => $events,
+				'turn_count'             => $turns_run,
+				'final_content'          => self::extract_final_content( $messages ),
+				'usage'                  => $total_usage,
+				'request_metadata'       => $request_metadata,
 			);
 
-			if ( ! empty( $last_request_metadata ) ) {
-				$final_result_data['request_metadata'] = $last_request_metadata;
-			}
-
 			if ( null !== $exceeded_budget ) {
 				$final_result_data['status'] = 'budget_exceeded';
 				$final_result_data['budget'] = $exceeded_budget;
@@ -253,7 +278,7 @@ public static function run( array $messages, callable $turn_runner, array $optio
 			self::persist_transcript( $transcript_persister, $messages, $options, $final_result );
 
 			self::emit_event( $on_event, 'completed', array(
-				'turn'          => $turn,
+				'turn'          => $turns_run,
 				'message_count' => count( $messages ),
 				'tool_results'  => count( $tool_results ),
 			) );
@@ -752,6 +777,61 @@ private static function maybe_compact( array $messages, array $options ): array
 		);
 	}
 
+	/**
+	 * Accumulate per-turn usage into the running total.
+	 *
+	 * Sums the canonical `prompt_tokens`/`completion_tokens`/`total_tokens`
+	 * fields and preserves any provider-specific keys from the latest turn
+	 * (e.g. `cache_creation_input_tokens`, `reasoning_tokens`) so consumers
+	 * can read provider extensions without the loop having to know about
+	 * each one. Numeric fields are summed; non-numeric fields are taken
+	 * from the latest turn.
+	 *
+	 * @param array<string, mixed> $running Current accumulated usage.
+	 * @param array<string, mixed> $turn    Per-turn usage.
+	 * @return array<string, mixed> Accumulated usage.
+	 */
+	private static function accumulate_usage( array $running, array $turn ): array {
+		foreach ( $turn as $key => $value ) {
+			if ( is_int( $value ) || is_float( $value ) ) {
+				$running[ $key ] = (float) ( $running[ $key ] ?? 0 ) + (float) $value;
+				if ( is_int( $value ) && (float) (int) $running[ $key ] === (float) $running[ $key ] ) {
+					$running[ $key ] = (int) $running[ $key ];
+				}
+				continue;
+			}
+			$running[ $key ] = $value;
+		}
+		return $running;
+	}
+
+	/**
+	 * Extract the text of the last assistant message from a transcript.
+	 *
+	 * Returns an empty string when no assistant message exists or the
+	 * latest assistant message has no text content (e.g. tool-call-only
+	 * turns at the tail).
+	 *
+	 * @param array $messages Normalized transcript messages.
+	 * @return string Final assistant text content.
+	 */
+	private static function extract_final_content( array $messages ): string {
+		for ( $i = count( $messages ) - 1; $i >= 0; --$i ) {
+			$message = $messages[ $i ];
+			if ( ! is_array( $message ) ) {
+				continue;
+			}
+			if ( ( $message['role'] ?? '' ) !== 'assistant' ) {
+				continue;
+			}
+			$content = $message['content'] ?? '';
+			if ( is_string( $content ) && '' !== $content ) {
+				return $content;
+			}
+		}
+		return '';
+	}
+
 	/**
 	 * Normalize the max turn option.
 	 *

src/Runtime/class-wp-agent-conversation-result.php

@@ -97,6 +97,23 @@ public static function normalize( array $result ): array {
 			throw self::invalid( 'budget', 'must be a string when present' );
 		}
 
+		// Validate optional observability fields surfaced by the loop.
+		if ( array_key_exists( 'turn_count', $result ) && ! is_int( $result['turn_count'] ) ) {
+			throw self::invalid( 'turn_count', 'must be an integer when present' );
+		}
+
+		if ( array_key_exists( 'final_content', $result ) && ! is_string( $result['final_content'] ) ) {
+			throw self::invalid( 'final_content', 'must be a string when present' );
+		}
+
+		if ( array_key_exists( 'usage', $result ) && ! is_array( $result['usage'] ) ) {
+			throw self::invalid( 'usage', 'must be an array when present' );
+		}
+
+		if ( array_key_exists( 'request_metadata', $result ) && ! is_array( $result['request_metadata'] ) ) {
+			throw self::invalid( 'request_metadata', 'must be an array when present' );
+		}
+
 		return $result;
 	}