docs(code): expand doc comments on security, observability, runtime, and peripheral traits

The four underdocumented core trait files now include trait-level doc blocks
explaining purpose and architecture role, method-level documentation with
parameter/return/error descriptions, and public struct/enum documentation.

This brings parity with the well-documented provider, channel, tool, and
memory traits, giving extension developers clear guidance for implementing
these core extension points.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

src/observability/traits.rs

@@ -1,12 +1,15 @@
 use std::time::Duration;
 
-/// Events the observer can record
+/// Discrete events emitted by the agent runtime for observability.
+///
+/// Each variant represents a lifecycle event that observers can record,
+/// aggregate, or forward to external monitoring systems. Events carry
+/// just enough context for tracing and diagnostics without exposing
+/// sensitive prompt or response content.
 #[derive(Debug, Clone)]
 pub enum ObserverEvent {
-    AgentStart {
-        provider: String,
-        model: String,
-    },
+    /// The agent orchestration loop has started a new session.
+    AgentStart { provider: String, model: String },
     /// A request is about to be sent to an LLM provider.
     ///
     /// This is emitted immediately before a provider call so observers can print
@@ -24,6 +27,9 @@ pub enum ObserverEvent {
         success: bool,
         error_message: Option<String>,
     },
+    /// The agent session has finished.
+    ///
+    /// Carries aggregate usage data (tokens, cost) when the provider reports it.
     AgentEnd {
         provider: String,
         model: String,
@@ -32,9 +38,8 @@ pub enum ObserverEvent {
         cost_usd: Option<f64>,
     },
     /// A tool call is about to be executed.
-    ToolCallStart {
-        tool: String,
-    },
+    ToolCallStart { tool: String },
+    /// A tool call has completed with a success/failure outcome.
     ToolCall {
         tool: String,
         duration: Duration,
@@ -42,41 +47,80 @@ pub enum ObserverEvent {
     },
     /// The agent produced a final answer for the current user message.
     TurnComplete,
+    /// A message was sent or received through a channel.
     ChannelMessage {
+        /// Channel name (e.g., `"telegram"`, `"discord"`).
         channel: String,
+        /// `"inbound"` or `"outbound"`.
         direction: String,
     },
+    /// Periodic heartbeat tick from the runtime keep-alive loop.
     HeartbeatTick,
+    /// An error occurred in a named component.
     Error {
+        /// Subsystem where the error originated (e.g., `"provider"`, `"gateway"`).
         component: String,
+        /// Human-readable error description. Must not contain secrets or tokens.
         message: String,
     },
 }
 
-/// Numeric metrics
+/// Numeric metrics emitted by the agent runtime.
+///
+/// Observers can aggregate these into dashboards, alerts, or structured logs.
+/// Each variant carries a single scalar value with implicit units.
 #[derive(Debug, Clone)]
 pub enum ObserverMetric {
+    /// Time elapsed for a single LLM or tool request.
     RequestLatency(Duration),
+    /// Number of tokens consumed by an LLM call.
     TokensUsed(u64),
+    /// Current number of active concurrent sessions.
     ActiveSessions(u64),
+    /// Current depth of the inbound message queue.
     QueueDepth(u64),
 }
 
-/// Core observability trait — implement for any backend
+/// Core observability trait for recording agent runtime telemetry.
+///
+/// Implement this trait to integrate with any monitoring backend (structured
+/// logging, Prometheus, OpenTelemetry, etc.). The agent runtime holds one or
+/// more `Observer` instances and calls [`record_event`](Observer::record_event)
+/// and [`record_metric`](Observer::record_metric) at key lifecycle points.
+///
+/// Implementations must be `Send + Sync + 'static` because the observer is
+/// shared across async tasks via `Arc`.
 pub trait Observer: Send + Sync + 'static {
-    /// Record a discrete event
+    /// Record a discrete lifecycle event.
+    ///
+    /// Called synchronously on the hot path; implementations should avoid
+    /// blocking I/O. Buffer events internally and flush asynchronously
+    /// when possible.
     fn record_event(&self, event: &ObserverEvent);
 
-    /// Record a numeric metric
+    /// Record a numeric metric sample.
+    ///
+    /// Called synchronously; same non-blocking guidance as
+    /// [`record_event`](Observer::record_event).
     fn record_metric(&self, metric: &ObserverMetric);
 
-    /// Flush any buffered data (no-op for most backends)
+    /// Flush any buffered telemetry data to the backend.
+    ///
+    /// The runtime calls this during graceful shutdown. The default
+    /// implementation is a no-op, which is appropriate for backends
+    /// that write synchronously.
     fn flush(&self) {}
 
-    /// Human-readable name of this observer
+    /// Return the human-readable name of this observer backend.
+    ///
+    /// Used in logs and diagnostics (e.g., `"console"`, `"prometheus"`,
+    /// `"opentelemetry"`).
     fn name(&self) -> &str;
 
-    /// Downcast to `Any` for backend-specific operations
+    /// Downcast to `Any` for backend-specific operations.
+    ///
+    /// Enables callers to access concrete observer types when needed
+    /// (e.g., retrieving a Prometheus registry handle for custom metrics).
     fn as_any(&self) -> &dyn std::any::Any;
 }