docs: describe the runtime public API surface

This adds crate-level and type-level Rustdoc to the runtime crate's core exported types so downstream crates and contributors can understand the session, prompt, permission, OAuth, usage, and tool I/O primitives without spelunking every implementation file.

Constraint: The docs pass needed to stay focused on public runtime types without changing behavior
Rejected: Add blanket docs to every public item in one sweep | larger churn than needed for a targeted docs pass
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: When exporting new runtime primitives from lib.rs, add a short Rustdoc summary in the defining module at the same time
Tested: cargo build --workspace; cargo test --workspace
Not-tested: rustdoc HTML rendering beyond  doc-test coverage

Author: Yeachan-Heo

rust/crates/runtime/src/bash.rs

@@ -14,6 +14,7 @@ use crate::sandbox::{
 };
 use crate::ConfigLoader;
 
+/// Input schema for the built-in bash execution tool.
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
 pub struct BashCommandInput {
     pub command: String,
@@ -33,6 +34,7 @@ pub struct BashCommandInput {
     pub allowed_mounts: Option<Vec<String>>,
 }
 
+/// Output returned from a bash tool invocation.
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
 pub struct BashCommandOutput {
     pub stdout: String,
@@ -64,6 +66,7 @@ pub struct BashCommandOutput {
     pub sandbox_status: Option<SandboxStatus>,
 }
 
+/// Executes a shell command with the requested sandbox settings.
 pub fn execute_bash(input: BashCommandInput) -> io::Result<BashCommandOutput> {
     let cwd = env::current_dir()?;
     let sandbox_status = sandbox_status_for_input(&input, &cwd);

rust/crates/runtime/src/compact.rs

@@ -5,6 +5,7 @@ const COMPACT_CONTINUATION_PREAMBLE: &str =
 const COMPACT_RECENT_MESSAGES_NOTE: &str = "Recent messages are preserved verbatim.";
 const COMPACT_DIRECT_RESUME_INSTRUCTION: &str = "Continue the conversation from where it left off without asking the user any further questions. Resume directly — do not acknowledge the summary, do not recap what was happening, and do not preface with continuation text.";
 
+/// Thresholds controlling when and how a session is compacted.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct CompactionConfig {
     pub preserve_recent_messages: usize,
@@ -20,6 +21,7 @@ impl Default for CompactionConfig {
     }
 }
 
+/// Result of compacting a session into a summary plus preserved tail messages.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct CompactionResult {
     pub summary: String,
@@ -28,11 +30,13 @@ pub struct CompactionResult {
     pub removed_message_count: usize,
 }
 
+/// Roughly estimates the token footprint of the current session transcript.
 #[must_use]
 pub fn estimate_session_tokens(session: &Session) -> usize {
     session.messages.iter().map(estimate_message_tokens).sum()
 }
 
+/// Returns `true` when the session exceeds the configured compaction budget.
 #[must_use]
 pub fn should_compact(session: &Session, config: CompactionConfig) -> bool {
     let start = compacted_summary_prefix_len(session);
@@ -46,6 +50,7 @@ pub fn should_compact(session: &Session, config: CompactionConfig) -> bool {
             >= config.max_estimated_tokens
 }
 
+/// Normalizes a compaction summary into user-facing continuation text.
 #[must_use]
 pub fn format_compact_summary(summary: &str) -> String {
     let without_analysis = strip_tag_block(summary, "analysis");
@@ -61,6 +66,7 @@ pub fn format_compact_summary(summary: &str) -> String {
     collapse_blank_lines(&formatted).trim().to_string()
 }
 
+/// Builds the synthetic system message used after session compaction.
 #[must_use]
 pub fn get_compact_continuation_message(
     summary: &str,
@@ -85,6 +91,7 @@ pub fn get_compact_continuation_message(
     base
 }
 
+/// Compacts a session by summarizing older messages and preserving the recent tail.
 #[must_use]
 pub fn compact_session(session: &Session, config: CompactionConfig) -> CompactionResult {
     if !should_compact(session, config) {

rust/crates/runtime/src/config.rs

@@ -6,35 +6,41 @@ use std::path::{Path, PathBuf};
 use crate::json::JsonValue;
 use crate::sandbox::{FilesystemIsolationMode, SandboxConfig};
 
+/// Schema name advertised by generated settings files.
 pub const CLAW_SETTINGS_SCHEMA_NAME: &str = "SettingsSchema";
 
+/// Origin of a loaded settings file in the configuration precedence chain.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
 pub enum ConfigSource {
     User,
     Project,
     Local,
 }
 
+/// Effective permission mode after decoding config values.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum ResolvedPermissionMode {
     ReadOnly,
     WorkspaceWrite,
     DangerFullAccess,
 }
 
+/// A discovered config file and the scope it contributes to.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ConfigEntry {
     pub source: ConfigSource,
     pub path: PathBuf,
 }
 
+/// Fully merged runtime configuration plus parsed feature-specific views.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct RuntimeConfig {
     merged: BTreeMap<String, JsonValue>,
     loaded_entries: Vec<ConfigEntry>,
     feature_config: RuntimeFeatureConfig,
 }
 
+/// Parsed plugin-related settings extracted from runtime config.
 #[derive(Debug, Clone, PartialEq, Eq, Default)]
 pub struct RuntimePluginConfig {
     enabled_plugins: BTreeMap<String, bool>,
@@ -44,6 +50,7 @@ pub struct RuntimePluginConfig {
     bundled_root: Option<String>,
 }
 
+/// Structured feature configuration consumed by runtime subsystems.
 #[derive(Debug, Clone, PartialEq, Eq, Default)]
 pub struct RuntimeFeatureConfig {
     hooks: RuntimeHookConfig,
@@ -56,31 +63,36 @@ pub struct RuntimeFeatureConfig {
     sandbox: SandboxConfig,
 }
 
+/// Hook command lists grouped by lifecycle stage.
 #[derive(Debug, Clone, PartialEq, Eq, Default)]
 pub struct RuntimeHookConfig {
     pre_tool_use: Vec<String>,
     post_tool_use: Vec<String>,
     post_tool_use_failure: Vec<String>,
 }
 
+/// Raw permission rule lists grouped by allow, deny, and ask behavior.
 #[derive(Debug, Clone, PartialEq, Eq, Default)]
 pub struct RuntimePermissionRuleConfig {
     allow: Vec<String>,
     deny: Vec<String>,
     ask: Vec<String>,
 }
 
+/// Collection of configured MCP servers after scope-aware merging.
 #[derive(Debug, Clone, PartialEq, Eq, Default)]
 pub struct McpConfigCollection {
     servers: BTreeMap<String, ScopedMcpServerConfig>,
 }
 
+/// MCP server config paired with the scope that defined it.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ScopedMcpServerConfig {
     pub scope: ConfigSource,
     pub config: McpServerConfig,
 }
 
+/// Transport families supported by configured MCP servers.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum McpTransport {
     Stdio,
@@ -91,6 +103,7 @@ pub enum McpTransport {
     ManagedProxy,
 }
 
+/// Scope-normalized MCP server configuration variants.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum McpServerConfig {
     Stdio(McpStdioServerConfig),
@@ -101,6 +114,7 @@ pub enum McpServerConfig {
     ManagedProxy(McpManagedProxyServerConfig),
 }
 
+/// Configuration for an MCP server launched as a local stdio process.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct McpStdioServerConfig {
     pub command: String,
@@ -109,6 +123,7 @@ pub struct McpStdioServerConfig {
     pub tool_call_timeout_ms: Option<u64>,
 }
 
+/// Configuration for an MCP server reached over HTTP or SSE.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct McpRemoteServerConfig {
     pub url: String,
@@ -117,24 +132,28 @@ pub struct McpRemoteServerConfig {
     pub oauth: Option<McpOAuthConfig>,
 }
 
+/// Configuration for an MCP server reached over WebSocket.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct McpWebSocketServerConfig {
     pub url: String,
     pub headers: BTreeMap<String, String>,
     pub headers_helper: Option<String>,
 }
 
+/// Configuration for an MCP server addressed through an SDK name.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct McpSdkServerConfig {
     pub name: String,
 }
 
+/// Configuration for an MCP managed-proxy endpoint.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct McpManagedProxyServerConfig {
     pub url: String,
     pub id: String,
 }
 
+/// OAuth overrides associated with a remote MCP server.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct McpOAuthConfig {
     pub client_id: Option<String>,
@@ -143,6 +162,7 @@ pub struct McpOAuthConfig {
     pub xaa: Option<bool>,
 }
 
+/// OAuth client configuration used by the main Claw runtime.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct OAuthConfig {
     pub client_id: String,
@@ -153,6 +173,7 @@ pub struct OAuthConfig {
     pub scopes: Vec<String>,
 }
 
+/// Errors raised while reading or parsing runtime configuration files.
 #[derive(Debug)]
 pub enum ConfigError {
     Io(std::io::Error),
@@ -176,6 +197,7 @@ impl From<std::io::Error> for ConfigError {
     }
 }
 
+/// Discovers config files and merges them into a [`RuntimeConfig`].
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ConfigLoader {
     cwd: PathBuf,
@@ -441,6 +463,7 @@ impl RuntimePluginConfig {
 }
 
 #[must_use]
+/// Returns the default per-user config directory used by the runtime.
 pub fn default_config_home() -> PathBuf {
     std::env::var_os("CLAW_CONFIG_HOME")
         .map(PathBuf::from)
@@ -1338,7 +1361,10 @@ mod tests {
             .load()
             .expect("config should load");
 
-        let remote_server = loaded.mcp().get("remote").expect("remote server should exist");
+        let remote_server = loaded
+            .mcp()
+            .get("remote")
+            .expect("remote server should exist");
         assert_eq!(remote_server.transport(), McpTransport::Http);
         match &remote_server.config {
             McpServerConfig::Http(config) => {

rust/crates/runtime/src/conversation.rs

@@ -18,12 +18,14 @@ use crate::usage::{TokenUsage, UsageTracker};
 const DEFAULT_AUTO_COMPACTION_INPUT_TOKENS_THRESHOLD: u32 = 100_000;
 const AUTO_COMPACTION_THRESHOLD_ENV_VAR: &str = "CLAUDE_CODE_AUTO_COMPACT_INPUT_TOKENS";
 
+/// Fully assembled request payload sent to the upstream model client.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ApiRequest {
     pub system_prompt: Vec<String>,
     pub messages: Vec<ConversationMessage>,
 }
 
+/// Streamed events emitted while processing a single assistant turn.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum AssistantEvent {
     TextDelta(String),
@@ -37,6 +39,7 @@ pub enum AssistantEvent {
     MessageStop,
 }
 
+/// Prompt-cache telemetry captured from the provider response stream.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct PromptCacheEvent {
     pub unexpected: bool,
@@ -46,14 +49,17 @@ pub struct PromptCacheEvent {
     pub token_drop: u32,
 }
 
+/// Minimal streaming API contract required by [`ConversationRuntime`].
 pub trait ApiClient {
     fn stream(&mut self, request: ApiRequest) -> Result<Vec<AssistantEvent>, RuntimeError>;
 }
 
+/// Trait implemented by tool dispatchers that execute model-requested tools.
 pub trait ToolExecutor {
     fn execute(&mut self, tool_name: &str, input: &str) -> Result<String, ToolError>;
 }
 
+/// Error returned when a tool invocation fails locally.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ToolError {
     message: String,
@@ -76,6 +82,7 @@ impl Display for ToolError {
 
 impl std::error::Error for ToolError {}
 
+/// Error returned when a conversation turn cannot be completed.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct RuntimeError {
     message: String,
@@ -98,6 +105,7 @@ impl Display for RuntimeError {
 
 impl std::error::Error for RuntimeError {}
 
+/// Summary of one completed runtime turn, including tool results and usage.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct TurnSummary {
     pub assistant_messages: Vec<ConversationMessage>,
@@ -108,11 +116,13 @@ pub struct TurnSummary {
     pub auto_compaction: Option<AutoCompactionEvent>,
 }
 
+/// Details about automatic session compaction applied during a turn.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct AutoCompactionEvent {
     pub removed_message_count: usize,
 }
 
+/// Coordinates the model loop, tool execution, hooks, and session updates.
 pub struct ConversationRuntime<C, T> {
     session: Session,
     api_client: C,
@@ -637,6 +647,7 @@ where
     }
 }
 
+/// Reads the automatic compaction threshold from the environment.
 #[must_use]
 pub fn auto_compaction_threshold_from_env() -> u32 {
     parse_auto_compaction_threshold(
@@ -739,6 +750,7 @@ fn merge_hook_feedback(messages: &[String], output: String, is_error: bool) -> S
 
 type ToolHandler = Box<dyn FnMut(&str) -> Result<String, ToolError>>;
 
+/// Simple in-memory tool executor for tests and lightweight integrations.
 #[derive(Default)]
 pub struct StaticToolExecutor {
     handlers: BTreeMap<String, ToolHandler>,