Add agent explainability instrumentation and unify envelope field naming (#795)

Addresses recommendations from the UX developer's agent experience report.
Adds provenance predicates, DAG structure changes, error resilience, and
a published OWL ontology.

Explainability additions:

- Tool candidates: tg:toolCandidate on Analysis events lists the tools
  visible to the LLM for each iteration (names only, descriptions in config)
- Termination reason: tg:terminationReason on Conclusion/Synthesis events
  (final-answer, plan-complete, subagents-complete)
- Step counter: tg:stepNumber on iteration events
- Pattern decision: new tg:PatternDecision entity in the DAG between
  session and first iteration, carrying tg:pattern and tg:taskType
- Latency: tg:llmDurationMs on Analysis events, tg:toolDurationMs on
  Observation events
- Token counts on events: tg:inToken/tg:outToken/tg:llmModel on
  Grounding, Focus, Synthesis, and Analysis events
- Tool/parse errors: tg:toolError on Observation events with tg:Error
  mixin type. Parse failures return as error observations instead of
  crashing the agent, giving it a chance to retry.

Envelope unification:

- Rename chunk_type to message_type across AgentResponse schema,
  translator, SDK types, socket clients, CLI, and all tests.
  Agent and RAG services now both use message_type on the wire.

Ontology:

- specs/ontology/trustgraph.ttl — OWL vocabulary covering all 26 classes,
  7 object properties, and 36+ datatype properties including new predicates.

DAG structure tests:

- tests/unit/test_provenance/test_dag_structure.py verifies the
  wasDerivedFrom chain for GraphRAG, DocumentRAG, and all three agent
  patterns (react, plan, supervisor) including the pattern-decision link.

trustgraph-base/trustgraph/api/async_socket_client.py

@@ -178,24 +178,23 @@ class AsyncSocketClient:
 
     def _parse_chunk(self, resp: Dict[str, Any]):
         """Parse response chunk into appropriate type. Returns None for non-content messages."""
-        chunk_type = resp.get("chunk_type")
         message_type = resp.get("message_type")
 
         # Handle new GraphRAG message format with message_type
         if message_type == "provenance":
             return None
 
-        if chunk_type == "thought":
+        if message_type == "thought":
             return AgentThought(
                 content=resp.get("content", ""),
                 end_of_message=resp.get("end_of_message", False)
             )
-        elif chunk_type == "observation":
+        elif message_type == "observation":
             return AgentObservation(
                 content=resp.get("content", ""),
                 end_of_message=resp.get("end_of_message", False)
             )
-        elif chunk_type == "answer" or chunk_type == "final-answer":
+        elif message_type == "answer" or message_type == "final-answer":
             return AgentAnswer(
                 content=resp.get("content", ""),
                 end_of_message=resp.get("end_of_message", False),
@@ -204,7 +203,7 @@ class AsyncSocketClient:
                 out_token=resp.get("out_token"),
                 model=resp.get("model"),
             )
-        elif chunk_type == "action":
+        elif message_type == "action":
             return AgentThought(
                 content=resp.get("content", ""),
                 end_of_message=resp.get("end_of_message", False)

trustgraph-base/trustgraph/api/socket_client.py

@@ -360,34 +360,26 @@ class SocketClient:
 
     def _parse_chunk(self, resp: Dict[str, Any], include_provenance: bool = False) -> Optional[StreamingChunk]:
         """Parse response chunk into appropriate type. Returns None for non-content messages."""
-        chunk_type = resp.get("chunk_type")
         message_type = resp.get("message_type")
 
-        # Handle GraphRAG/DocRAG message format with message_type
         if message_type == "explain":
             if include_provenance:
                 return self._build_provenance_event(resp)
             return None
 
-        # Handle Agent message format with chunk_type="explain"
-        if chunk_type == "explain":
-            if include_provenance:
-                return self._build_provenance_event(resp)
-            return None
-
-        if chunk_type == "thought":
+        if message_type == "thought":
             return AgentThought(
                 content=resp.get("content", ""),
                 end_of_message=resp.get("end_of_message", False),
                 message_id=resp.get("message_id", ""),
             )
-        elif chunk_type == "observation":
+        elif message_type == "observation":
             return AgentObservation(
                 content=resp.get("content", ""),
                 end_of_message=resp.get("end_of_message", False),
                 message_id=resp.get("message_id", ""),
             )
-        elif chunk_type == "answer" or chunk_type == "final-answer":
+        elif message_type == "answer" or message_type == "final-answer":
             return AgentAnswer(
                 content=resp.get("content", ""),
                 end_of_message=resp.get("end_of_message", False),
@@ -397,7 +389,7 @@ class SocketClient:
                 out_token=resp.get("out_token"),
                 model=resp.get("model"),
             )
-        elif chunk_type == "action":
+        elif message_type == "action":
             return AgentThought(
                 content=resp.get("content", ""),
                 end_of_message=resp.get("end_of_message", False)

trustgraph-base/trustgraph/api/types.py

@@ -149,10 +149,10 @@ class AgentThought(StreamingChunk):
     Attributes:
         content: Agent's thought text
         end_of_message: True if this completes the current thought
-        chunk_type: Always "thought"
+        message_type: Always "thought"
         message_id: Provenance URI of the entity being built
     """
-    chunk_type: str = "thought"
+    message_type: str = "thought"
     message_id: str = ""
 
 @dataclasses.dataclass
@@ -166,10 +166,10 @@ class AgentObservation(StreamingChunk):
     Attributes:
         content: Observation text describing tool results
         end_of_message: True if this completes the current observation
-        chunk_type: Always "observation"
+        message_type: Always "observation"
         message_id: Provenance URI of the entity being built
     """
-    chunk_type: str = "observation"
+    message_type: str = "observation"
     message_id: str = ""
 
 @dataclasses.dataclass
@@ -184,9 +184,9 @@ class AgentAnswer(StreamingChunk):
         content: Answer text
         end_of_message: True if this completes the current answer segment
         end_of_dialog: True if this completes the entire agent interaction
-        chunk_type: Always "final-answer"
+        message_type: Always "final-answer"
     """
-    chunk_type: str = "final-answer"
+    message_type: str = "final-answer"
     end_of_dialog: bool = False
     message_id: str = ""
     in_token: Optional[int] = None
@@ -208,9 +208,9 @@ class RAGChunk(StreamingChunk):
         in_token: Input token count (populated on the final chunk, 0 otherwise)
         out_token: Output token count (populated on the final chunk, 0 otherwise)
         model: Model identifier (populated on the final chunk, empty otherwise)
-        chunk_type: Always "rag"
+        message_type: Always "rag"
     """
-    chunk_type: str = "rag"
+    message_type: str = "rag"
     end_of_stream: bool = False
     error: Optional[Dict[str, str]] = None
     in_token: Optional[int] = None