Expose LLM token usage across all service layers (#782)

Expose LLM token usage (in_token, out_token, model) across all
service layers

Propagate token counts from LLM services through the prompt,
text-completion, graph-RAG, document-RAG, and agent orchestrator
pipelines to the API gateway and Python SDK. All fields are Optional
— None means "not available", distinguishing from a real zero count.

Key changes:

- Schema: Add in_token/out_token/model to TextCompletionResponse,
  PromptResponse, GraphRagResponse, DocumentRagResponse,
  AgentResponse

- TextCompletionClient: New TextCompletionResult return type. Split
  into text_completion() (non-streaming) and
  text_completion_stream() (streaming with per-chunk handler
  callback)

- PromptClient: New PromptResult with response_type
  (text/json/jsonl), typed fields (text/object/objects), and token
  usage. All callers updated.

- RAG services: Accumulate token usage across all prompt calls
  (extract-concepts, edge-scoring, edge-reasoning,
  synthesis). Non-streaming path sends single combined response
  instead of chunk + end_of_session.

- Agent orchestrator: UsageTracker accumulates tokens across
  meta-router, pattern prompt calls, and react reasoning. Attached
  to end_of_dialog.

- Translators: Encode token fields when not None (is not None, not truthy)

- Python SDK: RAG and text-completion methods return
  TextCompletionResult (non-streaming) or RAGChunk/AgentAnswer with
  token fields (streaming)

- CLI: --show-usage flag on tg-invoke-llm, tg-invoke-prompt,
  tg-invoke-graph-rag, tg-invoke-document-rag, tg-invoke-agent

tests/unit/test_retrieval/test_graph_rag.py

@@ -7,6 +7,7 @@ import unittest.mock
 from unittest.mock import MagicMock, AsyncMock
 
 from trustgraph.retrieval.graph_rag.graph_rag import GraphRag, Query
+from trustgraph.base import PromptResult
 
 
 class TestGraphRag:
@@ -172,7 +173,7 @@ class TestQuery:
         mock_prompt_client = AsyncMock()
         mock_rag.prompt_client = mock_prompt_client
 
-        mock_prompt_client.prompt.return_value = "machine learning\nneural networks\n"
+        mock_prompt_client.prompt.return_value = PromptResult(response_type="text", text="machine learning\nneural networks\n")
 
         query = Query(
             rag=mock_rag,
@@ -196,7 +197,7 @@ class TestQuery:
         mock_prompt_client = AsyncMock()
         mock_rag.prompt_client = mock_prompt_client
 
-        mock_prompt_client.prompt.return_value = ""
+        mock_prompt_client.prompt.return_value = PromptResult(response_type="text", text="")
 
         query = Query(
             rag=mock_rag,
@@ -220,7 +221,7 @@ class TestQuery:
         mock_rag.graph_embeddings_client = mock_graph_embeddings_client
 
         # extract_concepts returns empty -> falls back to [query]
-        mock_prompt_client.prompt.return_value = ""
+        mock_prompt_client.prompt.return_value = PromptResult(response_type="text", text="")
 
         # embed returns one vector set for the single concept
         test_vectors = [[0.1, 0.2, 0.3]]
@@ -565,14 +566,14 @@ class TestQuery:
         # Mock prompt responses for the multi-step process
         async def mock_prompt(prompt_name, variables=None, streaming=False, chunk_callback=None):
             if prompt_name == "extract-concepts":
-                return ""  # Falls back to raw query
+                return PromptResult(response_type="text", text="")
             elif prompt_name == "kg-edge-scoring":
-                return json.dumps({"id": test_edge_id, "score": 0.9})
+                return PromptResult(response_type="jsonl", objects=[{"id": test_edge_id, "score": 0.9}])
             elif prompt_name == "kg-edge-reasoning":
-                return json.dumps({"id": test_edge_id, "reasoning": "relevant"})
+                return PromptResult(response_type="jsonl", objects=[{"id": test_edge_id, "reasoning": "relevant"}])
             elif prompt_name == "kg-synthesis":
-                return expected_response
-            return ""
+                return PromptResult(response_type="text", text=expected_response)
+            return PromptResult(response_type="text", text="")
 
         mock_prompt_client.prompt = mock_prompt
 
@@ -607,7 +608,8 @@ class TestQuery:
                 explain_callback=collect_provenance
             )
 
-            assert response == expected_response
+            response_text, usage = response
+            assert response_text == expected_response
 
             # 5 events: question, grounding, exploration, focus, synthesis
             assert len(provenance_events) == 5