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/runtime/traits.rs

@@ -1,29 +1,68 @@
 use std::path::{Path, PathBuf};
 
-/// Runtime adapter — abstracts platform differences so the same agent
-/// code runs on native, Docker, Cloudflare Workers, Raspberry Pi, etc.
+/// Runtime adapter that abstracts platform differences for the agent.
+///
+/// Implement this trait to port the agent to a new execution environment.
+/// The adapter declares platform capabilities (shell access, filesystem,
+/// long-running processes) and provides platform-specific implementations
+/// for operations like spawning shell commands. The orchestration loop
+/// queries these capabilities to adapt its behavior—for example, disabling
+/// tool execution on runtimes without shell access.
+///
+/// Implementations must be `Send + Sync` because the adapter is shared
+/// across async tasks on the Tokio runtime.
 pub trait RuntimeAdapter: Send + Sync {
-    /// Human-readable runtime name
+    /// Return the human-readable name of this runtime environment.
+    ///
+    /// Used in logs and diagnostics (e.g., `"native"`, `"docker"`,
+    /// `"cloudflare-workers"`).
     fn name(&self) -> &str;
 
-    /// Whether this runtime supports shell access
+    /// Report whether this runtime supports shell command execution.
+    ///
+    /// When `false`, the agent disables shell-based tools. Serverless and
+    /// edge runtimes typically return `false`.
     fn has_shell_access(&self) -> bool;
 
-    /// Whether this runtime supports filesystem access
+    /// Report whether this runtime supports filesystem read/write.
+    ///
+    /// When `false`, the agent disables file-based tools and falls back to
+    /// in-memory storage.
     fn has_filesystem_access(&self) -> bool;
 
-    /// Base storage path for this runtime
+    /// Return the base directory for persistent storage on this runtime.
+    ///
+    /// Memory backends, logs, and other artifacts are stored under this path.
+    /// Implementations should return a platform-appropriate writable directory.
     fn storage_path(&self) -> PathBuf;
 
-    /// Whether long-running processes (gateway, heartbeat) are supported
+    /// Report whether this runtime supports long-running background processes.
+    ///
+    /// When `true`, the agent may start the gateway server, heartbeat loop,
+    /// and other persistent tasks. Serverless runtimes with short execution
+    /// limits should return `false`.
     fn supports_long_running(&self) -> bool;
 
-    /// Maximum memory budget in bytes (0 = unlimited)
+    /// Return the maximum memory budget in bytes for this runtime.
+    ///
+    /// A value of `0` (the default) indicates no limit. Constrained
+    /// environments (embedded, serverless) should return their actual
+    /// memory ceiling so the agent can adapt buffer sizes and caching.
     fn memory_budget(&self) -> u64 {
         0
     }
 
-    /// Build a shell command process for this runtime.
+    /// Build a shell command process configured for this runtime.
+    ///
+    /// Constructs a [`tokio::process::Command`] that will execute `command`
+    /// with `workspace_dir` as the working directory. Implementations may
+    /// prepend sandbox wrappers, set environment variables, or redirect
+    /// I/O as appropriate for the platform.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the runtime does not support shell access or if
+    /// the command cannot be constructed (e.g., missing shell binary).
     fn build_shell_command(
         &self,
         command: &str,