chore: release v0.2.0 (#60 )

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
ci: Explicitly enable cargo-dist caching for binary artifacts building
2026-08-25 14:53:34 +00:00 · 2026-02-16 22:28:14 +00:00 · 2026-02-16 21:34:49 +01:00 · 2026-02-16 21:29:03 +01:00 · 2026-02-16 15:58:13 +04:00 · 2026-02-16 03:38:06 +00:00
33 changed files with 3765 additions and 351 deletions
@@ -39,7 +39,6 @@ permissions:
 # If there's a prerelease-style suffix to the version, then the release(s)
 # will be marked as a prerelease.
 on:
-  pull_request:
  push:
    tags:
      - '**[0-9]+.[0-9]+.[0-9]+*'
@@ -1,6 +1,8 @@

 .env
 .env.local
+.env.*
+!.env.example

 target/

@@ -7,6 +7,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

 ## [Unreleased]

+## [0.2.0](https://github.com/nearai/ironclaw/compare/v0.1.3...v0.2.0) - 2026-02-16
+
+### Added
+
+- mark Ollama + OpenAI-compatible as implemented ([#102](https://github.com/nearai/ironclaw/pull/102))
+- multi-provider inference + libSQL onboarding selection ([#92](https://github.com/nearai/ironclaw/pull/92))
+- add multi-provider LLM failover with retry backoff ([#28](https://github.com/nearai/ironclaw/pull/28))
+- add libSQL/Turso embedded database backend ([#47](https://github.com/nearai/ironclaw/pull/47))
+- Move debug log truncation from agent loop to REPL channel ([#65](https://github.com/nearai/ironclaw/pull/65))
+
+### Fixed
+
+- shell destructive-command check bypassed by Value::Object arguments ([#72](https://github.com/nearai/ironclaw/pull/72))
+- propagate real tool_call_id instead of hardcoded placeholder ([#73](https://github.com/nearai/ironclaw/pull/73))
+- Fix wasm tool schemas and runtime ([#42](https://github.com/nearai/ironclaw/pull/42))
+- flatten tool messages for NEAR AI cloud-api compatibility ([#41](https://github.com/nearai/ironclaw/pull/41))
+- security hardening across all layers ([#35](https://github.com/nearai/ironclaw/pull/35))
+
+### Other
+
+- Explicitly enable cargo-dist caching for binary artifacts building
+- Skip building binary artifacts on every PR
+- add module specification rules to CLAUDE.md
+- add setup/onboarding specification (src/setup/README.md)
+- deduplicate tool code and remove dead stubs ([#98](https://github.com/nearai/ironclaw/pull/98))
+- Reformat architecture diagram in README ([#64](https://github.com/nearai/ironclaw/pull/64))
+- Add review discipline guidelines to CLAUDE.md ([#68](https://github.com/nearai/ironclaw/pull/68))
+- Bump MSRV to 1.92, add GCP deployment files ([#40](https://github.com/nearai/ironclaw/pull/40))
+- Add OpenAI-compatible HTTP API (/v1/chat/completions, /v1/models)   ([#31](https://github.com/nearai/ironclaw/pull/31))
+
 ## [0.1.3](https://github.com/nearai/ironclaw/compare/v0.1.2...v0.1.3) - 2026-02-12

 ### Other
@@ -630,6 +630,22 @@ RUST_LOG=ironclaw::agent=debug cargo run
 RUST_LOG=ironclaw=debug,tower_http=debug cargo run
 ```

+## Module Specifications
+
+Some modules have a `README.md` that serves as the authoritative specification
+for that module's behavior. When modifying code in a module that has a spec:
+
+1. **Read the spec first** before making changes
+2. **Code follows spec**: if the spec says X, the code must do X
+3. **Update both sides**: if you change behavior, update the spec to match;
+   if you're implementing a spec change, update the code to match
+4. **Spec is the tiebreaker**: when code and spec disagree, the spec is correct
+   (unless the spec is clearly outdated, in which case fix the spec first)
+
+| Module | Spec File |
+|--------|-----------|
+| `src/setup/` | `src/setup/README.md` |
+
 ## Code Style

 - Use `crate::` imports, not `super::`
@@ -2490,7 +2490,7 @@ dependencies = [

 [[package]]
 name = "ironclaw"
-version = "0.1.3"
+version = "0.2.0"
 dependencies = [
 "aes-gcm",
 "aho-corasick",
@@ -1,6 +1,6 @@
 [package]
 name = "ironclaw"
-version = "0.1.3"
+version = "0.2.0"
 edition = "2024"
 rust-version = "1.92"
 description = "Secure personal AI assistant that protects your data and expands its capabilities on the fly"
@@ -139,7 +139,7 @@ pretty_assertions = "1"
 tempfile = "3"

 [features]
-default = ["postgres"]
+default = ["postgres", "libsql"]
 postgres = [
    "dep:deadpool-postgres",
    "dep:tokio-postgres",
@@ -183,11 +183,13 @@ windows-archive = ".tar.gz"
 # The archive format to use for non-windows builds (defaults .tar.xz)
 unix-archive = ".tar.gz"
 # Which actions to run on pull requests
-pr-run-mode = "upload"
+pr-run-mode = "skip"
 # Path that installers should place binaries in
 install-path = "CARGO_HOME"
 # Whether to install an updater program
 install-updater = true
+# Cache intermediate build artifacts to speed up the release pipelines
+cache-builds = true

 [workspace.metadata.dist.github-custom-runners]
 aarch64-unknown-linux-gnu = "ubuntu-24.04-arm"
@@ -164,7 +164,7 @@ This document tracks feature parity between IronClaw (Rust implementation) and O
 | AWS Bedrock | ✅ | ❌ | P3 | |
 | Google Gemini | ✅ | ❌ | P3 | |
 | OpenRouter | ✅ | ❌ | P3 | |
-| Ollama (local) | ✅ | ❌ | P2 | Local models |
+| Ollama (local) | ✅ | ✅ | - | via `rig::providers::ollama` (full support) |
 | node-llama-cpp | ✅ | ➖ | - | N/A for Rust |
 | llama.cpp (native) | ❌ | 🔮 | P3 | Rust bindings |

@@ -0,0 +1,23 @@
+[package]
+name = "discord-channel"
+version = "0.1.0"
+edition = "2021"
+description = "Discord channel for IronClaw"
+license = "MIT OR Apache-2.0"
+publish = false
+
+[dependencies]
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
+wit-bindgen = "0.41.0"
+
+[lib]
+crate-type = ["cdylib"]
+
+[profile.release]
+strip = true
+opt-level = "s"
+lto = true
+codegen-units = 1
+
+
@@ -0,0 +1,121 @@
+# Discord Channel for IronClaw
+
+WASM channel for Discord integration - handle slash commands and button interactions via webhooks.
+
+## Features
+
+- **Slash Commands** - Process Discord slash commands
+- **Button Interactions** - Handle button clicks
+- **Thread Support** - Respond in threads
+- **DM Support** - Handle direct messages
+
+## Setup
+
+1. Create a Discord Application at <https://discord.com/developers/applications>
+2. Create a Bot and get the token
+3. Set up Interactions URL to point to your IronClaw instance
+4. Copy the Application ID and Public Key
+5. Store in IronClaw secrets:
+
+   ```bash
+   ironclaw secret set discord_bot_token YOUR_BOT_TOKEN
+   ```
+
+   **Note:** The `discord_bot_token` secret is the only value read directly by this
+   Discord channel WASM component. The `discord_app_id` and `discord_public_key`
+   secrets are used by the IronClaw host (for example, to verify Discord
+   interaction signatures and manage slash command registration) and are not
+   accessed from the WASM module itself.
+
+## Discord Configuration
+
+### Register Slash Commands
+
+```bash
+curl -X POST \
+  -H "Authorization: Bot YOUR_BOT_TOKEN" \
+  -H "Content-Type: application/json" \
+  https://discord.com/api/v10/applications/YOUR_APP_ID/commands \
+  -d '{
+    "name": "ask",
+    "description": "Ask the AI agent",
+    "options": [{
+      "name": "question",
+      "description": "Your question",
+      "type": 3,
+      "required": true
+    }]
+  }'
+```
+
+### Set Interactions Endpoint
+
+In your Discord app settings, set:
+
+- Interactions Endpoint URL: `https://your-ironclaw.com/webhook/discord`
+
+## Usage Examples
+
+### Slash Command
+
+User types: `/ask question: What is the weather?`
+
+The agent receives:
+
+```text
+User: @username
+Content: /ask question: What is the weather?
+```
+
+### Button Click
+
+When a user clicks a button in a message, the agent receives:
+
+```text
+User: @username
+Content: [Button clicked] Original message content
+```
+
+## Error Handling
+
+If an internal error occurs (e.g., metadata serialization failure), the tool attempts to send an ephemeral message to the user:
+
+```text
+❌ Internal Error: Failed to process command metadata.
+```
+
+Check the host logs for detailed error information.
+
+## Advanced Usage
+
+### Embeds
+
+To send embeds, include an `embeds` array in the `metadata_json` field of the agent's response. The structure should match the Discord API `embed` object.
+
+## Troubleshooting
+
+### "Invalid Signature"
+
+- Check that `discord_public_key` is set correctly in IronClaw secrets.
+- This validation happens on the host before reaching the WASM.
+
+### "401 Unauthorized"
+
+- Check that `discord_bot_token` is set correctly in IronClaw secrets.
+- Ensure the bot is added to the server.
+
+### "Interaction Failed"
+
+- The interaction might have timed out (Discord requires a response within 3 seconds).
+- The `interactions_endpoint_url` might be unreachable.
+
+## Building
+
+```bash
+cd channels-src/discord
+cargo build --target wasm32-wasi --release
+```
+
+## License
+
+MIT/Apache-2.0
@@ -0,0 +1,39 @@
+{
+  "type": "channel",
+  "name": "discord",
+  "description": "Discord Gateway/Webhook channel for handling slash commands, buttons, and messages",
+  "capabilities": {
+    "http": {
+      "allowlist": [
+        { "host": "discord.com", "path_prefix": "/api/v10" }
+      ],
+      "credentials": {
+        "discord_bot_token": {
+          "secret_name": "discord_bot_token",
+          "location": { "type": "header", "header_name": "Authorization", "prefix": "Bot " },
+          "host_patterns": ["discord.com"]
+        }
+      },
+      "rate_limit": {
+        "requests_per_minute": 60,
+        "requests_per_hour": 3600
+      }
+    },
+    "secrets": {
+      "allowed_names": ["discord_bot_token", "discord_*"]
+    },
+    "channel": {
+      "allowed_paths": ["/webhook/discord"],
+      "allow_polling": false,
+      "callback_timeout_secs": 45,
+      "workspace_prefix": "channels/discord/",
+      "emit_rate_limit": {
+        "messages_per_minute": 100,
+        "messages_per_hour": 5000
+      }
+    }
+  },
+  "config": {
+    "require_signature_verification": true
+  }
+}
@@ -0,0 +1,476 @@
+//! Discord Gateway/Webhook channel for IronClaw.
+//!
+//! This WASM component implements the channel interface for handling Discord
+//! interactions via webhooks and sending messages back to Discord.
+//!
+//! # Features
+//!
+//! - URL verification for Discord interactions
+//! - Slash command handling
+//! - Message event parsing (@mentions, DMs)
+//! - Thread support for conversations
+//! - Response posting via Discord Web API
+//! - Automatic message truncation (> 2000 chars)
+//!
+//! # Security
+//!
+//! - Signature validation is handled by the host (webhook secrets)
+//! - Bot token is injected by host during HTTP requests
+//! - WASM never sees raw credentials
+
+wit_bindgen::generate!({
+    world: "sandboxed-channel",
+    path: "../../wit/channel.wit",
+});
+
+use serde::{Deserialize, Serialize};
+
+use exports::near::agent::channel::{
+    AgentResponse, ChannelConfig, Guest, HttpEndpointConfig, IncomingHttpRequest,
+    OutgoingHttpResponse, StatusUpdate,
+};
+use near::agent::channel_host::{self, EmittedMessage};
+
+/// Discord interaction wrapper.
+#[derive(Debug, Deserialize)]
+struct DiscordInteraction {
+    /// Interaction type (1=Ping, 2=ApplicationCommand, 3=MessageComponent)
+    #[serde(rename = "type")]
+    interaction_type: u8,
+
+    /// Interaction ID
+    id: String,
+
+    /// Application ID
+    application_id: String,
+
+    /// Guild ID (if in server)
+    #[allow(dead_code)] // Part of API payload, currently unused
+    guild_id: Option<String>,
+
+    /// Channel ID
+    channel_id: Option<String>,
+
+    /// Member info (if in server)
+    member: Option<DiscordMember>,
+
+    /// User info (if DM)
+    user: Option<DiscordUser>,
+
+    /// Command data (for slash commands)
+    data: Option<DiscordCommandData>,
+
+    /// Message (for component interactions)
+    message: Option<DiscordMessage>,
+
+    /// Token for responding
+    token: String,
+}
+
+#[derive(Debug, Deserialize, Clone)]
+struct DiscordMember {
+    user: DiscordUser,
+    #[allow(dead_code)] // Part of API payload, currently unused
+    nick: Option<String>,
+}
+
+#[derive(Debug, Deserialize, Clone)]
+struct DiscordUser {
+    id: String,
+    username: String,
+    global_name: Option<String>,
+}
+
+#[derive(Debug, Deserialize, Clone)]
+struct DiscordCommandData {
+    #[allow(dead_code)] // Part of API payload, currently unused
+    id: String,
+    name: String,
+    options: Option<Vec<DiscordCommandOption>>,
+}
+
+#[derive(Debug, Deserialize, Clone)]
+struct DiscordCommandOption {
+    name: String,
+    value: serde_json::Value,
+}
+
+#[derive(Debug, Deserialize, Clone)]
+struct DiscordMessage {
+    #[allow(dead_code)] // Part of API payload, currently unused
+    id: String,
+    content: String,
+    channel_id: String,
+    #[allow(dead_code)] // Part of API payload, currently unused
+    author: DiscordUser,
+}
+
+/// Metadata stored with emitted messages for response routing.
+#[derive(Debug, Serialize, Deserialize)]
+struct DiscordMessageMetadata {
+    /// Discord channel ID
+    channel_id: String,
+
+    /// Interaction ID for followups
+    interaction_id: String,
+
+    /// Interaction token for responding
+    token: String,
+
+    /// Application ID
+    application_id: String,
+
+    /// Thread ID (for forum threads)
+    thread_id: Option<String>,
+}
+
+struct DiscordChannel;
+
+impl Guest for DiscordChannel {
+    fn on_start(_config_json: String) -> Result<ChannelConfig, String> {
+        channel_host::log(channel_host::LogLevel::Info, "Discord channel starting");
+
+        Ok(ChannelConfig {
+            display_name: "Discord".to_string(),
+            http_endpoints: vec![HttpEndpointConfig {
+                path: "/webhook/discord".to_string(),
+                methods: vec!["POST".to_string()],
+                require_secret: true,
+            }],
+            poll: None,
+        })
+    }
+
+    fn on_http_request(req: IncomingHttpRequest) -> OutgoingHttpResponse {
+        let body_str = match std::str::from_utf8(&req.body) {
+            Ok(s) => s,
+            Err(_) => {
+                return json_response(400, serde_json::json!({"error": "Invalid UTF-8 body"}));
+            }
+        };
+
+        let interaction: DiscordInteraction = match serde_json::from_str(body_str) {
+            Ok(i) => i,
+            Err(e) => {
+                channel_host::log(
+                    channel_host::LogLevel::Error,
+                    &format!("Failed to parse Discord interaction: {}", e),
+                );
+                return json_response(400, serde_json::json!({"error": "Invalid interaction"}));
+            }
+        };
+
+        match interaction.interaction_type {
+            // Ping - Discord verification
+            1 => {
+                channel_host::log(channel_host::LogLevel::Info, "Responding to Discord ping");
+                json_response(200, serde_json::json!({"type": 1}))
+            }
+
+            // Application Command (slash command)
+            2 => {
+                handle_slash_command(&interaction);
+                json_response(
+                    200,
+                    serde_json::json!({
+                        "type": 5,
+                        "data": {
+                            "content": "🤔 Thinking..."
+                        }
+                    }),
+                )
+            }
+
+            // Message Component (buttons, selects)
+            3 => {
+                if let Some(ref message) = interaction.message {
+                    handle_message_component(&interaction, message);
+                }
+                json_response(200, serde_json::json!({"type": 6}))
+            }
+
+            _ => {
+                channel_host::log(
+                    channel_host::LogLevel::Warn,
+                    &format!(
+                        "Unknown Discord interaction type: {}",
+                        interaction.interaction_type
+                    ),
+                );
+                json_response(200, serde_json::json!({"type": 6}))
+            }
+        }
+    }
+
+    fn on_poll() {}
+
+    fn on_respond(response: AgentResponse) -> Result<(), String> {
+        let metadata: DiscordMessageMetadata = serde_json::from_str(&response.metadata_json)
+            .map_err(|e| format!("Failed to parse metadata: {}", e))?;
+
+        // Use webhook endpoint for followup
+        let url = format!(
+            "https://discord.com/api/v10/webhooks/{}/{}",
+            metadata.application_id, metadata.token
+        );
+
+        // Truncate content to 2000 characters to comply with Discord limits
+        let content = truncate_message(&response.content);
+
+        let mut payload = serde_json::json!({
+            "content": content,
+        });
+
+        // Check for embeds in metadata
+        if let Ok(meta_json) = serde_json::from_str::<serde_json::Value>(&response.metadata_json) {
+            if let Some(embeds) = meta_json.get("embeds") {
+                payload["embeds"] = embeds.clone();
+            }
+        }
+
+        let payload_bytes =
+            serde_json::to_vec(&payload).map_err(|e| format!("Failed to serialize: {}", e))?;
+
+        let headers = serde_json::json!({
+            "Content-Type": "application/json"
+        });
+
+        let result = channel_host::http_request(
+            "POST",
+            &url,
+            &headers.to_string(),
+            Some(&payload_bytes),
+            None,
+        );
+
+        match result {
+            Ok(http_response) => {
+                if http_response.status >= 200 && http_response.status < 300 {
+                    channel_host::log(channel_host::LogLevel::Debug, "Posted followup to Discord");
+                    Ok(())
+                } else {
+                    let body_str = String::from_utf8_lossy(&http_response.body);
+                    Err(format!(
+                        "Discord API error: {} - {}",
+                        http_response.status, body_str
+                    ))
+                }
+            }
+            Err(e) => Err(format!("HTTP request failed: {}", e)),
+        }
+    }
+
+    fn on_status(_update: StatusUpdate) {}
+
+    fn on_shutdown() {
+        channel_host::log(
+            channel_host::LogLevel::Info,
+            "Discord channel shutting down",
+        );
+    }
+}
+
+fn handle_slash_command(interaction: &DiscordInteraction) {
+    let user = interaction
+        .member
+        .as_ref()
+        .map(|m| &m.user)
+        .or(interaction.user.as_ref());
+    let user_id = user.map(|u| u.id.clone()).unwrap_or_default();
+    let user_name = user
+        .map(|u| {
+            u.global_name
+                .as_ref()
+                .filter(|s| !s.is_empty())
+                .unwrap_or(&u.username)
+                .clone()
+        })
+        .unwrap_or_default();
+
+    let channel_id = interaction.channel_id.clone().unwrap_or_default();
+
+    let command_name = interaction
+        .data
+        .as_ref()
+        .map(|d| d.name.clone())
+        .unwrap_or_default();
+    let options = interaction.data.as_ref().and_then(|d| d.options.clone());
+
+    let content = if let Some(opts) = options {
+        let opt_str = opts
+            .iter()
+            .map(|o| format!("{}: {}", o.name, o.value))
+            .collect::<Vec<_>>()
+            .join(", ");
+        format!("/{} {}", command_name, opt_str)
+    } else {
+        format!("/{}", command_name)
+    };
+
+    let metadata = DiscordMessageMetadata {
+        channel_id: channel_id.clone(),
+        interaction_id: interaction.id.clone(),
+        token: interaction.token.clone(),
+        application_id: interaction.application_id.clone(),
+        thread_id: None,
+    };
+
+    let metadata_json = match serde_json::to_string(&metadata) {
+        Ok(json) => json,
+        Err(e) => {
+            channel_host::log(
+                channel_host::LogLevel::Error,
+                &format!("Failed to serialize metadata: {}", e),
+            );
+            // Attempt to notify user of internal error
+            let url = format!(
+                "https://discord.com/api/v10/webhooks/{}/{}",
+                interaction.application_id, interaction.token
+            );
+            let payload = serde_json::json!({
+                "content": "❌ Internal Error: Failed to process command metadata.",
+                "flags": 64 // Ephemeral
+            });
+            let _ = channel_host::http_request(
+                "POST",
+                &url,
+                &serde_json::json!({"Content-Type": "application/json"}).to_string(),
+                Some(&serde_json::to_vec(&payload).unwrap_or_default()),
+                None,
+            );
+            return;
+        }
+    };
+
+    channel_host::emit_message(&EmittedMessage {
+        user_id,
+        user_name: Some(user_name),
+        content,
+        thread_id: None,
+        metadata_json,
+    });
+}
+
+fn handle_message_component(interaction: &DiscordInteraction, message: &DiscordMessage) {
+    // Check member first (for server contexts), then user (for DMs)
+    let user = interaction
+        .member
+        .as_ref()
+        .map(|m| &m.user)
+        .or(interaction.user.as_ref());
+    let user_id = user.map(|u| u.id.clone()).unwrap_or_default();
+    let user_name = user
+        .map(|u| {
+            u.global_name
+                .as_ref()
+                .filter(|s| !s.is_empty())
+                .unwrap_or(&u.username)
+                .clone()
+        })
+        .unwrap_or_default();
+
+    let channel_id = message.channel_id.clone();
+
+    let metadata = DiscordMessageMetadata {
+        channel_id: channel_id.clone(),
+        interaction_id: interaction.id.clone(),
+        token: interaction.token.clone(),
+        application_id: interaction.application_id.clone(),
+        thread_id: None,
+    };
+
+    let metadata_json = match serde_json::to_string(&metadata) {
+        Ok(json) => json,
+        Err(e) => {
+            channel_host::log(
+                channel_host::LogLevel::Error,
+                &format!("Failed to serialize metadata: {}", e),
+            );
+            return; // Don't emit message if metadata can't be serialized
+        }
+    };
+
+    channel_host::emit_message(&EmittedMessage {
+        user_id,
+        user_name: Some(user_name),
+        content: format!("[Button clicked] {}", message.content),
+        thread_id: None,
+        metadata_json,
+    });
+}
+
+fn json_response(status: u16, value: serde_json::Value) -> OutgoingHttpResponse {
+    let body = serde_json::to_vec(&value).unwrap_or_default();
+    let headers = serde_json::json!({"Content-Type": "application/json"});
+
+    OutgoingHttpResponse {
+        status,
+        headers_json: headers.to_string(),
+        body,
+    }
+}
+
+export!(DiscordChannel);
+
+fn truncate_message(content: &str) -> String {
+    if content.len() <= 2000 {
+        content.to_string()
+    } else {
+        let max_bytes = 1990;
+        let cutoff = content
+            .char_indices()
+            .map(|(i, c)| i + c.len_utf8())
+            .take_while(|&end| end <= max_bytes)
+            .last()
+            .unwrap_or(0);
+        let mut truncated = content[..cutoff].to_string();
+        truncated.push_str("\n... (truncated)");
+        truncated
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_truncate_message() {
+        let short = "Hello world";
+        assert_eq!(truncate_message(short), short);
+
+        let long = "a".repeat(2005);
+        let truncated = truncate_message(&long);
+        assert_eq!(truncated.len(), 2006); // 1990 + 16 chars suffix
+        assert!(truncated.ends_with("\n... (truncated)"));
+
+        // Test with multibyte characters (Euro sign is 3 bytes)
+        // 1000 chars * 3 bytes = 3000 bytes
+        let multi = "€".repeat(1000);
+        let truncated_multi = truncate_message(&multi);
+
+        // 1990 bytes limit. 1990 / 3 = 663 with remainder 1.
+        // Should truncate at 663 chars (1989 bytes).
+        // Suffix is 16 bytes. Total: 1989 + 16 = 2005 bytes.
+        assert!(truncated_multi.len() <= 2006);
+        assert!(truncated_multi.len() >= 2006 - 4); // Allow for max utf8 char width variance
+        assert!(truncated_multi.ends_with("\n... (truncated)"));
+
+        let content_part = &truncated_multi[..truncated_multi.len() - 16];
+        assert!(content_part.chars().all(|c| c == '€'));
+    }
+
+    #[test]
+    fn test_metadata_serialization() {
+        let metadata = DiscordMessageMetadata {
+            channel_id: "123".into(),
+            interaction_id: "456".into(),
+            token: "abc".into(),
+            application_id: "789".into(),
+            thread_id: None,
+        };
+        let json = serde_json::to_string(&metadata).unwrap();
+        let parsed: DiscordMessageMetadata = serde_json::from_str(&json).unwrap();
+        assert_eq!(parsed.channel_id, "123");
+        assert_eq!(parsed.interaction_id, "456");
+    }
+}
@@ -338,7 +338,13 @@ fn emit_message(
        team_id,
    };

-    let metadata_json = serde_json::to_string(&metadata).unwrap_or_else(|_| "{}".to_string());
+    let metadata_json = serde_json::to_string(&metadata).unwrap_or_else(|e| {
+        channel_host::log(
+            channel_host::LogLevel::Error,
+            &format!("Failed to serialize Slack metadata: {}", e),
+        );
+        "{}".to_string()
+    });

    // Strip @ mentions of the bot from the text for cleaner messages
    let cleaned_text = strip_bot_mention(&text);
@@ -366,7 +372,13 @@ fn strip_bot_mention(text: &str) -> String {

 /// Create a JSON HTTP response.
 fn json_response(status: u16, value: serde_json::Value) -> OutgoingHttpResponse {
-    let body = serde_json::to_vec(&value).unwrap_or_default();
+    let body = serde_json::to_vec(&value).unwrap_or_else(|e| {
+        channel_host::log(
+            channel_host::LogLevel::Error,
+            &format!("Failed to serialize JSON response: {}", e),
+        );
+        Vec::new()
+    });
    let headers = serde_json::json!({"Content-Type": "application/json"});

    OutgoingHttpResponse {
@@ -285,11 +285,7 @@ impl Guest for TelegramChannel {
        }

        // Persist dm_policy and allow_from for DM pairing in handle_message
-        let dm_policy = config
-            .dm_policy
-            .as_deref()
-            .unwrap_or("pairing")
-            .to_string();
+        let dm_policy = config.dm_policy.as_deref().unwrap_or("pairing").to_string();
        let _ = channel_host::workspace_write(DM_POLICY_PATH, &dm_policy);

        let allow_from_json = serde_json::to_string(&config.allow_from.unwrap_or_default())
@@ -844,8 +840,8 @@ fn send_pairing_reply(chat_id: i64, code: &str) -> Result<(), String> {
        "parse_mode": "Markdown",
    });

-    let payload_bytes = serde_json::to_vec(&payload)
-        .map_err(|e| format!("Failed to serialize payload: {}", e))?;
+    let payload_bytes =
+        serde_json::to_vec(&payload).map_err(|e| format!("Failed to serialize payload: {}", e))?;

    let headers = serde_json::json!({
        "Content-Type": "application/json"
@@ -915,15 +911,10 @@ fn handle_message(message: TelegramMessage) {
    let is_private = message.chat.chat_type == "private";

    // Owner validation: when owner_id is set, only that user can message
-    let owner_configured = channel_host::workspace_read(OWNER_ID_PATH)
-        .map(|s| !s.is_empty())
-        .unwrap_or(false);
+    let owner_id_str = channel_host::workspace_read(OWNER_ID_PATH).filter(|s| !s.is_empty());

-    if owner_configured {
-        if let Ok(owner_id) = channel_host::workspace_read(OWNER_ID_PATH)
-            .unwrap()
-            .parse::<i64>()
-        {
+    if let Some(ref id_str) = owner_id_str {
+        if let Ok(owner_id) = id_str.parse::<i64>() {
            if from.id != owner_id {
                channel_host::log(
                    channel_host::LogLevel::Debug,
@@ -937,8 +928,8 @@ fn handle_message(message: TelegramMessage) {
        }
    } else if is_private {
        // No owner_id: apply dm_policy for private chats
-        let dm_policy = channel_host::workspace_read(DM_POLICY_PATH)
-            .unwrap_or_else(|| "pairing".to_string());
+        let dm_policy =
+            channel_host::workspace_read(DM_POLICY_PATH).unwrap_or_else(|| "pairing".to_string());

        if dm_policy != "open" {
            // Build effective allow list: config allow_from + pairing store
@@ -1001,8 +992,7 @@ fn handle_message(message: TelegramMessage) {

        if !respond_to_all {
            let has_command = content.starts_with('/');
-            let bot_username = channel_host::workspace_read(BOT_USERNAME_PATH)
-                .unwrap_or_default();
+            let bot_username = channel_host::workspace_read(BOT_USERNAME_PATH).unwrap_or_default();
            let has_bot_mention = if bot_username.is_empty() {
                content.contains('@')
            } else {
@@ -254,10 +254,19 @@ struct WhatsAppChannel;

 impl Guest for WhatsAppChannel {
    fn on_start(config_json: String) -> Result<ChannelConfig, String> {
-        let config: WhatsAppConfig = serde_json::from_str(&config_json).unwrap_or(WhatsAppConfig {
-            api_version: default_api_version(),
-            reply_to_message: default_reply_to_message(),
-        });
+        let config: WhatsAppConfig = match serde_json::from_str(&config_json) {
+            Ok(c) => c,
+            Err(e) => {
+                channel_host::log(
+                    channel_host::LogLevel::Warn,
+                    &format!("Failed to parse WhatsApp config, using defaults: {}", e),
+                );
+                WhatsAppConfig {
+                    api_version: default_api_version(),
+                    reply_to_message: default_reply_to_message(),
+                }
+            }
+        };

        channel_host::log(
            channel_host::LogLevel::Info,
@@ -267,6 +276,9 @@ impl Guest for WhatsAppChannel {
            ),
        );

+        // Persist api_version in workspace so on_respond() can read it
+        let _ = channel_host::workspace_write("channels/whatsapp/api_version", &config.api_version);
+
        // WhatsApp Cloud API is webhook-only, no polling available
        Ok(ChannelConfig {
            display_name: "WhatsApp".to_string(),
@@ -327,11 +339,16 @@ impl Guest for WhatsAppChannel {
        let metadata: WhatsAppMessageMetadata = serde_json::from_str(&response.metadata_json)
            .map_err(|e| format!("Failed to parse metadata: {}", e))?;

+        // Read api_version from workspace (set during on_start), fallback to default
+        let api_version = channel_host::workspace_read("channels/whatsapp/api_version")
+            .filter(|s| !s.is_empty())
+            .unwrap_or_else(|| "v18.0".to_string());
+
        // Build WhatsApp API URL with token placeholder
        // Host will replace {WHATSAPP_ACCESS_TOKEN} with actual token in Authorization header
        let api_url = format!(
-            "https://graph.facebook.com/v18.0/{}/messages",
-            metadata.phone_number_id
+            "https://graph.facebook.com/{}/{}/messages",
+            api_version, metadata.phone_number_id
        );

        // Build sendMessage payload
@@ -81,17 +81,34 @@ fn migrate_bootstrap_json_to_env(env_path: &std::path::Path) {
    }
 }

-/// Write `DATABASE_URL` to `~/.ironclaw/.env`.
+/// Write database bootstrap vars to `~/.ironclaw/.env`.
+///
+/// These settings form the chicken-and-egg layer: they must be available
+/// from the filesystem (env vars) BEFORE any database connection, because
+/// they determine which database to connect to. Everything else is stored
+/// in the database itself.
 ///
 /// Creates the parent directory if it doesn't exist.
-/// The value is double-quoted so that `#` (common in URL-encoded passwords)
+/// Values are double-quoted so that `#` (common in URL-encoded passwords)
 /// and other shell-special characters are preserved by dotenvy.
-pub fn save_database_url(url: &str) -> std::io::Result<()> {
+pub fn save_bootstrap_env(vars: &[(&str, &str)]) -> std::io::Result<()> {
    let path = ironclaw_env_path();
    if let Some(parent) = path.parent() {
        std::fs::create_dir_all(parent)?;
    }
-    std::fs::write(&path, format!("DATABASE_URL=\"{}\"\n", url))
+    let mut content = String::new();
+    for (key, value) in vars {
+        content.push_str(&format!("{}=\"{}\"\n", key, value));
+    }
+    std::fs::write(&path, content)
+}
+
+/// Write `DATABASE_URL` to `~/.ironclaw/.env`.
+///
+/// Convenience wrapper around `save_bootstrap_env` for single-value migration
+/// paths. Prefer `save_bootstrap_env` for new code.
+pub fn save_database_url(url: &str) -> std::io::Result<()> {
+    save_bootstrap_env(&[("DATABASE_URL", url)])
 }

 /// One-time migration of legacy `~/.ironclaw/settings.json` into the database.
@@ -184,7 +201,7 @@ pub async fn migrate_disk_to_db(
            Ok(content) => match serde_json::from_str::<serde_json::Value>(&content) {
                Ok(value) => {
                    store
-                        .set_setting(user_id, "nearai.session", &value)
+                        .set_setting(user_id, "nearai.session_token", &value)
                        .await
                        .map_err(|e| {
                            MigrationError::Database(format!(
@@ -385,4 +402,63 @@ mod tests {
        // Nothing should happen
        assert!(!env_path.exists());
    }
+
+    #[test]
+    fn test_save_bootstrap_env_multiple_vars() {
+        let dir = tempdir().unwrap();
+        let env_path = dir.path().join("nested").join(".env");
+
+        std::fs::create_dir_all(env_path.parent().unwrap()).unwrap();
+
+        let vars = [
+            ("DATABASE_BACKEND", "libsql"),
+            ("LIBSQL_PATH", "/home/user/.ironclaw/ironclaw.db"),
+        ];
+
+        // Write manually to the temp path (save_bootstrap_env uses the global path)
+        let mut content = String::new();
+        for (key, value) in &vars {
+            content.push_str(&format!("{}=\"{}\"\n", key, value));
+        }
+        std::fs::write(&env_path, &content).unwrap();
+
+        // Verify dotenvy can parse all entries
+        let parsed: Vec<(String, String)> = dotenvy::from_path_iter(&env_path)
+            .unwrap()
+            .filter_map(|r| r.ok())
+            .collect();
+        assert_eq!(parsed.len(), 2);
+        assert_eq!(
+            parsed[0],
+            ("DATABASE_BACKEND".to_string(), "libsql".to_string())
+        );
+        assert_eq!(
+            parsed[1],
+            (
+                "LIBSQL_PATH".to_string(),
+                "/home/user/.ironclaw/ironclaw.db".to_string()
+            )
+        );
+    }
+
+    #[test]
+    fn test_save_bootstrap_env_overwrites_previous() {
+        let dir = tempdir().unwrap();
+        let env_path = dir.path().join(".env");
+
+        // Write initial content
+        std::fs::write(&env_path, "DATABASE_URL=\"postgres://old\"\n").unwrap();
+
+        // Overwrite with new vars (simulating save_bootstrap_env behavior)
+        let content = "DATABASE_BACKEND=\"libsql\"\nLIBSQL_PATH=\"/new/path.db\"\n";
+        std::fs::write(&env_path, content).unwrap();
+
+        let parsed: Vec<(String, String)> = dotenvy::from_path_iter(&env_path)
+            .unwrap()
+            .filter_map(|r| r.ok())
+            .collect();
+        // Old DATABASE_URL should be gone
+        assert_eq!(parsed.len(), 2);
+        assert!(parsed.iter().all(|(k, _)| k != "DATABASE_URL"));
+    }
 }
@@ -80,14 +80,13 @@ pub enum OAuthCallbackError {

 /// Bind the OAuth callback listener on the fixed port.
 ///
-/// Tries IPv6 loopback (`[::1]`) first so that `http://localhost:…` redirects
-/// work on systems where `localhost` resolves to `::1`. Falls back to IPv4
-/// (`127.0.0.1`) only if IPv6 fails for a reason other than `AddrInUse`
-/// (e.g., IPv6 not supported on the host). If the port is already occupied
-/// on IPv6, the port is occupied period, so we fail immediately.
+/// Binds to IPv4 `127.0.0.1` first because callback URLs use `127.0.0.1`
+/// explicitly (e.g., NEAR AI redirects to `http://127.0.0.1:9876/auth/callback`).
+/// Falls back to IPv6 `[::1]` only if IPv4 binding fails for a reason other
+/// than `AddrInUse`. If the port is already occupied, fails immediately.
 pub async fn bind_callback_listener() -> Result<TcpListener, OAuthCallbackError> {
-    let ipv6_addr = format!("[::1]:{}", OAUTH_CALLBACK_PORT);
-    match TcpListener::bind(&ipv6_addr).await {
+    let ipv4_addr = format!("127.0.0.1:{}", OAUTH_CALLBACK_PORT);
+    match TcpListener::bind(&ipv4_addr).await {
        Ok(listener) => return Ok(listener),
        Err(e) if e.kind() == std::io::ErrorKind::AddrInUse => {
            return Err(OAuthCallbackError::PortInUse(
@@ -96,10 +95,10 @@ pub async fn bind_callback_listener() -> Result<TcpListener, OAuthCallbackError>
            ));
        }
        Err(_) => {
-            // IPv6 not available on this host, fall back to IPv4
+            // IPv4 not available, fall back to IPv6
        }
    }
-    TcpListener::bind(format!("127.0.0.1:{}", OAUTH_CALLBACK_PORT))
+    TcpListener::bind(format!("[::1]:{}", OAUTH_CALLBACK_PORT))
        .await
        .map_err(|e| {
            if e.kind() == std::io::ErrorKind::AddrInUse {
@@ -22,15 +22,36 @@ pub async fn run_status_command() -> anyhow::Result<()> {
    );

    // Database
-    let db_url_set = std::env::var("DATABASE_URL").is_ok();
    print!("  Database:    ");
-    if db_url_set {
-        match check_database().await {
-            Ok(()) => println!("connected"),
-            Err(e) => println!("error ({})", e),
+    let db_backend = std::env::var("DATABASE_BACKEND")
+        .ok()
+        .unwrap_or_else(|| "postgres".to_string());
+    match db_backend.as_str() {
+        "libsql" | "turso" | "sqlite" => {
+            let path = std::env::var("LIBSQL_PATH")
+                .map(std::path::PathBuf::from)
+                .unwrap_or_else(|_| crate::config::default_libsql_path());
+            if path.exists() {
+                let turso = if std::env::var("LIBSQL_URL").is_ok() {
+                    " + Turso sync"
+                } else {
+                    ""
+                };
+                println!("libSQL ({}{})", path.display(), turso);
+            } else {
+                println!("libSQL (file missing: {})", path.display());
+            }
+        }
+        _ => {
+            if std::env::var("DATABASE_URL").is_ok() {
+                match check_database().await {
+                    Ok(()) => println!("connected (PostgreSQL)"),
+                    Err(e) => println!("error ({})", e),
+                }
+            } else {
+                println!("not configured");
+            }
        }
-    } else {
-        println!("not configured");
    }

    // Session / Auth
@@ -42,16 +63,17 @@ pub async fn run_status_command() -> anyhow::Result<()> {
        println!("not found (run `ironclaw onboard`)");
    }

-    // Secrets (auto-detect: env var or keychain)
+    // Secrets (auto-detect from env only; skip keychain probe to avoid
+    // triggering macOS system password dialogs on a simple status check)
    print!("  Secrets:     ");
-    let has_env_key = std::env::var("SECRETS_MASTER_KEY").is_ok();
-    let has_keychain = crate::secrets::keychain::has_master_key().await;
-    if has_env_key {
+    if std::env::var("SECRETS_MASTER_KEY").is_ok() {
        println!("configured (env)");
-    } else if has_keychain {
-        println!("configured (keychain)");
    } else {
-        println!("not configured");
+        // We don't probe the keychain here because get_generic_password()
+        // triggers macOS unlock+authorization dialogs, which is bad UX for
+        // a read-only status command. If onboarding completed with keychain
+        // storage, the key is there; we just can't cheaply verify it.
+        println!("env not set (keychain may be configured)");
    }

    // Embeddings
@@ -5,7 +5,9 @@
 //! in startup). Everything else comes from env vars, the DB settings
 //! table, or auto-detection.

+use std::collections::HashMap;
 use std::path::PathBuf;
+use std::sync::OnceLock;
 use std::time::Duration;

 use secrecy::{ExposeSecret, SecretString};
@@ -13,6 +15,13 @@ use secrecy::{ExposeSecret, SecretString};
 use crate::error::ConfigError;
 use crate::settings::Settings;

+/// Thread-safe overlay for injected env vars (secrets loaded from DB).
+///
+/// Used by `inject_llm_keys_from_secrets()` to make API keys available to
+/// `optional_env()` without unsafe `set_var` calls. `optional_env()` checks
+/// real env vars first, then falls back to this overlay.
+static INJECTED_VARS: OnceLock<HashMap<String, String>> = OnceLock::new();
+
 /// Main configuration for the agent.
 #[derive(Debug, Clone)]
 pub struct Config {
@@ -402,12 +411,24 @@ pub struct NearAiConfig {

 impl LlmConfig {
    fn resolve(settings: &Settings) -> Result<Self, ConfigError> {
-        // Determine backend (default: NearAi)
+        // Determine backend: env var > settings > default (NearAi)
        let backend: LlmBackend = if let Some(b) = optional_env("LLM_BACKEND")? {
            b.parse().map_err(|e| ConfigError::InvalidValue {
                key: "LLM_BACKEND".to_string(),
                message: e,
            })?
+        } else if let Some(ref b) = settings.llm_backend {
+            match b.parse() {
+                Ok(backend) => backend,
+                Err(e) => {
+                    tracing::warn!(
+                        "Invalid llm_backend '{}' in settings: {}. Using default NearAi.",
+                        b,
+                        e
+                    );
+                    LlmBackend::NearAi
+                }
+            }
        } else {
            LlmBackend::NearAi
        };
@@ -476,6 +497,7 @@ impl LlmConfig {

        let ollama = if backend == LlmBackend::Ollama {
            let base_url = optional_env("OLLAMA_BASE_URL")?
+                .or_else(|| settings.ollama_base_url.clone())
                .unwrap_or_else(|| "http://localhost:11434".to_string());
            let model = optional_env("OLLAMA_MODEL")?.unwrap_or_else(|| "llama3".to_string());
            Some(OllamaConfig { base_url, model })
@@ -484,8 +506,9 @@ impl LlmConfig {
        };

        let openai_compatible = if backend == LlmBackend::OpenAiCompatible {
-            let base_url =
-                optional_env("LLM_BASE_URL")?.ok_or_else(|| ConfigError::MissingRequired {
+            let base_url = optional_env("LLM_BASE_URL")?
+                .or_else(|| settings.openai_compatible_base_url.clone())
+                .ok_or_else(|| ConfigError::MissingRequired {
                    key: "LLM_BASE_URL".to_string(),
                    hint: "Set LLM_BASE_URL when LLM_BACKEND=openai_compatible".to_string(),
                })?;
@@ -855,6 +878,11 @@ impl std::fmt::Debug for SecretsConfig {
    }
 }

+/// Process-wide cache for the keychain master key.
+///
+/// Avoids re-prompting the OS keychain on every `SecretsConfig::resolve()` call
+/// (e.g. `Config::from_env()` then `Config::from_db()`). Thread-safe alternative
+/// to caching in a process env var.
 impl SecretsConfig {
    /// Auto-detect secrets master key from env var, then OS keychain.
    ///
@@ -1338,17 +1366,64 @@ impl ClaudeCodeConfig {
    }
 }

+/// Load API keys from the encrypted secrets store into a thread-safe overlay.
+///
+/// This bridges the gap between secrets stored during onboarding and the
+/// env-var-first resolution in `LlmConfig::resolve()`. Keys in the overlay
+/// are read by `optional_env()` before falling back to `std::env::var()`,
+/// so explicit env vars always win.
+pub async fn inject_llm_keys_from_secrets(
+    secrets: &dyn crate::secrets::SecretsStore,
+    user_id: &str,
+) {
+    let mappings = [
+        ("llm_openai_api_key", "OPENAI_API_KEY"),
+        ("llm_anthropic_api_key", "ANTHROPIC_API_KEY"),
+        ("llm_compatible_api_key", "LLM_API_KEY"),
+    ];
+
+    let mut injected = HashMap::new();
+
+    for (secret_name, env_var) in mappings {
+        match std::env::var(env_var) {
+            Ok(val) if !val.is_empty() => continue,
+            _ => {}
+        }
+        match secrets.get_decrypted(user_id, secret_name).await {
+            Ok(decrypted) => {
+                injected.insert(env_var.to_string(), decrypted.expose().to_string());
+                tracing::debug!("Loaded secret '{}' for env var '{}'", secret_name, env_var);
+            }
+            Err(_) => {
+                // Secret doesn't exist, that's fine
+            }
+        }
+    }
+
+    let _ = INJECTED_VARS.set(injected);
+}
+
 // Helper functions

 fn optional_env(key: &str) -> Result<Option<String>, ConfigError> {
+    // Check real env vars first (always win over injected secrets)
    match std::env::var(key) {
-        Ok(val) if val.is_empty() => Ok(None),
-        Ok(val) => Ok(Some(val)),
-        Err(std::env::VarError::NotPresent) => Ok(None),
-        Err(e) => Err(ConfigError::ParseError(format!(
-            "failed to read {key}: {e}"
-        ))),
+        Ok(val) if val.is_empty() => {}
+        Ok(val) => return Ok(Some(val)),
+        Err(std::env::VarError::NotPresent) => {}
+        Err(e) => {
+            return Err(ConfigError::ParseError(format!(
+                "failed to read {key}: {e}"
+            )));
+        }
    }
+
+    // Fall back to thread-safe overlay (secrets injected from DB)
+    if let Some(val) = INJECTED_VARS.get().and_then(|map| map.get(key)) {
+        return Ok(Some(val.clone()));
+    }
+
+    Ok(None)
 }

 fn parse_optional_env<T>(key: &str, default: T) -> Result<T, ConfigError>
@@ -48,7 +48,6 @@ use ironclaw::secrets::PostgresSecretsStore;
 use ironclaw::secrets::SecretsCrypto;
 #[cfg(any(feature = "postgres", feature = "libsql"))]
 use ironclaw::setup::{SetupConfig, SetupWizard};
-
 #[tokio::main]
 async fn main() -> anyhow::Result<()> {
    let cli = Cli::parse();
@@ -444,6 +443,72 @@ async fn main() -> anyhow::Result<()> {
            tracing::warn!("Failed to cleanup stale sandbox jobs: {}", e);
        }
    }
+
+    // Create secrets store early: needed for injecting LLM API keys from encrypted
+    // storage before creating the LLM provider, and later for MCP auth + WASM channels.
+    //
+    // When both `postgres` and `libsql` features are compiled, the runtime-selected
+    // backend determines which store is created: whichever DB init branch ran will
+    // have set its handle (pg_pool or libsql_db), and the or_else chain picks it up.
+    let secrets_store: Option<Arc<dyn SecretsStore + Send + Sync>> =
+        if let Some(master_key) = config.secrets.master_key() {
+            match SecretsCrypto::new(master_key.clone()) {
+                Ok(crypto) => {
+                    let crypto = Arc::new(crypto);
+                    let store: Option<Arc<dyn SecretsStore + Send + Sync>> = None;
+
+                    #[cfg(feature = "libsql")]
+                    let store = store.or_else(|| {
+                        libsql_db.take().map(|db| {
+                            Arc::new(LibSqlSecretsStore::new(db, Arc::clone(&crypto)))
+                                as Arc<dyn SecretsStore + Send + Sync>
+                        })
+                    });
+
+                    #[cfg(feature = "postgres")]
+                    let store = store.or_else(|| {
+                        pg_pool.as_ref().map(|pool| {
+                            Arc::new(PostgresSecretsStore::new(pool.clone(), Arc::clone(&crypto)))
+                                as Arc<dyn SecretsStore + Send + Sync>
+                        })
+                    });
+
+                    store
+                }
+                Err(e) => {
+                    tracing::warn!("Failed to initialize secrets crypto: {}", e);
+                    #[cfg(feature = "libsql")]
+                    let _ = libsql_db.take();
+                    None
+                }
+            }
+        } else {
+            #[cfg(feature = "libsql")]
+            let _ = libsql_db.take();
+            None
+        };
+
+    // Inject LLM API keys from the encrypted secrets store into a thread-safe
+    // overlay so that optional_env() (used by LlmConfig::resolve()) picks them
+    // up. Then re-resolve LlmConfig with the newly available keys (backend may
+    // have been set during onboarding but the API key is in the secrets store).
+    if let Some(ref secrets) = secrets_store {
+        ironclaw::config::inject_llm_keys_from_secrets(secrets.as_ref(), "default").await;
+
+        // Re-resolve LlmConfig now that secrets overlay has been populated
+        if let Some(ref db_ref) = db {
+            match Config::from_db(db_ref.as_ref(), "default").await {
+                Ok(refreshed) => {
+                    config = refreshed;
+                    tracing::debug!("LlmConfig re-resolved after secret injection");
+                }
+                Err(e) => {
+                    tracing::warn!("Failed to re-resolve config after secret injection: {}", e);
+                }
+            }
+        }
+    }
+
    // Initialize LLM provider (clone session so we can reuse it for embeddings)
    let llm = create_llm_provider(&config.llm, session.clone())?;
    tracing::info!("LLM provider initialized: {}", llm.model_name());
@@ -542,49 +607,6 @@ async fn main() -> anyhow::Result<()> {
        tracing::info!("Builder mode enabled");
    }

-    // Create secrets store if master key is configured (needed for MCP auth and WASM channels).
-    //
-    // When both `postgres` and `libsql` features are compiled, the runtime-selected
-    // backend determines which store is created: whichever DB init branch ran will
-    // have set its handle (pg_pool or libsql_db), and the or_else chain picks it up.
-    let secrets_store: Option<Arc<dyn SecretsStore + Send + Sync>> =
-        if let Some(master_key) = config.secrets.master_key() {
-            match SecretsCrypto::new(master_key.clone()) {
-                Ok(crypto) => {
-                    let crypto = Arc::new(crypto);
-                    let store: Option<Arc<dyn SecretsStore + Send + Sync>> = None;
-
-                    #[cfg(feature = "libsql")]
-                    let store = store.or_else(|| {
-                        libsql_db.take().map(|db| {
-                            Arc::new(LibSqlSecretsStore::new(db, Arc::clone(&crypto)))
-                                as Arc<dyn SecretsStore + Send + Sync>
-                        })
-                    });
-
-                    #[cfg(feature = "postgres")]
-                    let store = store.or_else(|| {
-                        pg_pool.as_ref().map(|pool| {
-                            Arc::new(PostgresSecretsStore::new(pool.clone(), Arc::clone(&crypto)))
-                                as Arc<dyn SecretsStore + Send + Sync>
-                        })
-                    });
-
-                    store
-                }
-                Err(e) => {
-                    tracing::warn!("Failed to initialize secrets crypto: {}", e);
-                    #[cfg(feature = "libsql")]
-                    let _ = libsql_db.take();
-                    None
-                }
-            }
-        } else {
-            #[cfg(feature = "libsql")]
-            let _ = libsql_db.take();
-            None
-        };
-
    let mcp_session_manager = Arc::new(McpSessionManager::new());

    // Create WASM tool runtime (sync, just builds the wasmtime engine)
@@ -40,8 +40,18 @@ pub struct Settings {
    #[serde(default)]
    pub secrets_master_key_source: KeySource,

-    // === Step 3: NEAR AI Auth ===
-    // Session stored separately in session.json
+    // === Step 3: Inference Provider ===
+    /// LLM backend: "nearai", "anthropic", "openai", "ollama", "openai_compatible".
+    #[serde(default)]
+    pub llm_backend: Option<String>,
+
+    /// Ollama base URL (when llm_backend = "ollama").
+    #[serde(default)]
+    pub ollama_base_url: Option<String>,
+
+    /// OpenAI-compatible endpoint base URL (when llm_backend = "openai_compatible").
+    #[serde(default)]
+    pub openai_compatible_base_url: Option<String>,

    // === Step 4: Model Selection ===
    /// Currently selected model.
@@ -504,7 +514,11 @@ impl Settings {
    /// Each key is a dotted path (e.g., "agent.name"), value is a JSONB value.
    /// Missing keys get their default value.
    pub fn from_db_map(map: &std::collections::HashMap<String, serde_json::Value>) -> Self {
-        // Start with defaults, then overlay each DB setting
+        // Start with defaults, then overlay each DB setting.
+        //
+        // The settings table stores both Settings struct fields and app-specific
+        // data (e.g. nearai.session_token). Skip keys that don't correspond to
+        // a known Settings path.
        let mut settings = Self::default();

        for (key, value) in map {
@@ -513,17 +527,23 @@ impl Settings {
                serde_json::Value::String(s) => s.clone(),
                serde_json::Value::Bool(b) => b.to_string(),
                serde_json::Value::Number(n) => n.to_string(),
-                serde_json::Value::Null => "null".to_string(),
+                serde_json::Value::Null => continue, // null means default, skip
                other => other.to_string(),
            };

-            if let Err(e) = settings.set(key, &value_str) {
-                tracing::warn!(
-                    "Failed to apply DB setting '{}' = '{}': {}",
-                    key,
-                    value_str,
-                    e
-                );
+            match settings.set(key, &value_str) {
+                Ok(()) => {}
+                // The settings table stores both Settings fields and app-specific
+                // data (e.g. nearai.session_token). Silently skip unknown paths.
+                Err(e) if e.starts_with("Path not found") => {}
+                Err(e) => {
+                    tracing::warn!(
+                        "Failed to apply DB setting '{}' = '{}': {}",
+                        key,
+                        value_str,
+                        e
+                    );
+                }
            }
        }

@@ -858,4 +878,30 @@ mod tests {
            .unwrap();
        assert_eq!(settings.channels.telegram_owner_id, Some(987654321));
    }
+
+    #[test]
+    fn test_llm_backend_round_trip() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("settings.json");
+
+        let settings = Settings {
+            llm_backend: Some("anthropic".to_string()),
+            ollama_base_url: Some("http://localhost:11434".to_string()),
+            openai_compatible_base_url: Some("http://my-vllm:8000/v1".to_string()),
+            ..Default::default()
+        };
+        let json = serde_json::to_string_pretty(&settings).unwrap();
+        std::fs::write(&path, json).unwrap();
+
+        let loaded = Settings::load_from(&path);
+        assert_eq!(loaded.llm_backend, Some("anthropic".to_string()));
+        assert_eq!(
+            loaded.ollama_base_url,
+            Some("http://localhost:11434".to_string())
+        );
+        assert_eq!(
+            loaded.openai_compatible_base_url,
+            Some("http://my-vllm:8000/v1".to_string())
+        );
+    }
 }
@@ -0,0 +1,539 @@
+# Setup / Onboarding Specification
+
+This document is the authoritative specification for IronClaw's onboarding
+wizard. Any code change to `src/setup/` **must** keep this document in sync.
+If a future contributor or coding agent modifies setup behavior, update this
+file first, then adjust the code to match.
+
+---
+
+## Entry Points
+
+```
+ironclaw onboard [--skip-auth] [--channels-only]
+```
+
+Explicit invocation. Loads `.env` files, runs the wizard, exits.
+
+```
+ironclaw          (first run, no database configured)
+```
+
+Auto-detection via `check_onboard_needed()` in `main.rs`. Triggers when
+none of these are true:
+- `DATABASE_URL` env var is set
+- `LIBSQL_PATH` env var is set
+- `~/.ironclaw/ironclaw.db` exists on disk
+
+The `--no-onboard` CLI flag suppresses auto-detection.
+
+---
+
+## Startup Sequence (main.rs)
+
+```
+1. Parse CLI args
+2. If Command::Onboard  → load .env, run wizard, exit
+3. If Command::Run or no command:
+   a. Load .env files (dotenvy::dotenv() then load_ironclaw_env())
+   b. check_onboard_needed() → run wizard if needed
+   c. Config::from_env()     → build config from env vars
+   d. Create SessionManager  → load session token
+   e. ensure_authenticated() → validate session (NEAR AI only)
+   f. ... rest of agent startup
+```
+
+**Critical ordering:** `.env` files must be loaded (step 3a) before
+`Config::from_env()` (step 3c) because bootstrap vars like
+`DATABASE_BACKEND` live in `~/.ironclaw/.env`.
+
+---
+
+## The 7-Step Wizard
+
+### Overview
+
+```
+Step 1: Database Connection
+Step 2: Security (master key)
+Step 3: Inference Provider          ← skipped if --skip-auth
+Step 4: Model Selection
+Step 5: Embeddings
+Step 6: Channel Configuration
+Step 7: Background Tasks (heartbeat)
+       ↓
+   save_and_summarize()
+```
+
+`--channels-only` mode runs only Step 6, skipping everything else.
+
+---
+
+### Step 1: Database Connection
+
+**Module:** `wizard.rs` → `step_database()`
+
+**Goal:** Select backend, establish connection, run migrations.
+
+**Decision tree:**
+
+```
+Both features compiled?
+├─ Yes → DATABASE_BACKEND env var set?
+│  ├─ Yes → use that backend
+│  └─ No  → interactive selection (PostgreSQL vs libSQL)
+├─ Only postgres feature → step_database_postgres()
+└─ Only libsql feature  → step_database_libsql()
+```
+
+**PostgreSQL path** (`step_database_postgres`):
+1. Check `DATABASE_URL` from env or settings
+2. Test connection (creates `deadpool_postgres::Pool`)
+3. Optionally run refinery migrations
+4. Store pool in `self.db_pool`
+
+**libSQL path** (`step_database_libsql`):
+1. Offer local path (default: `~/.ironclaw/ironclaw.db`)
+2. Optional Turso cloud sync (URL + auth token)
+3. Test connection (creates `LibSqlBackend`)
+4. Always run migrations (idempotent CREATE IF NOT EXISTS)
+5. Store backend in `self.db_backend`
+
+**Invariant:** After Step 1, exactly one of `self.db_pool` or
+`self.db_backend` is `Some`. This is required for settings persistence
+in `save_and_summarize()`.
+
+---
+
+### Step 2: Security (Master Key)
+
+**Module:** `wizard.rs` → `step_security()`
+
+**Goal:** Configure encryption for API tokens and secrets.
+
+**Decision tree:**
+
+```
+SECRETS_MASTER_KEY env var set?
+├─ Yes → use env var, done
+└─ No  → try get_master_key() from OS keychain
+   ├─ Ok(bytes) → cache in self.secrets_crypto, ask "use existing?"
+   │  ├─ Yes → done (keychain)
+   │  └─ No  → clear cache, fall through to options
+   └─ Err   → fall through to options
+              ├─ OS Keychain: generate + store + build SecretsCrypto
+              ├─ Env variable: generate + print export command
+              └─ Skip: disable secrets features
+```
+
+**CRITICAL CAVEAT: macOS Keychain Dialogs**
+
+On macOS, `security_framework::get_generic_password()` can trigger TWO
+system dialogs:
+1. "Enter your password to unlock the keychain" (keychain locked)
+2. "Allow ironclaw to access this keychain item" (per-app authorization)
+
+This is OS-level behavior we cannot prevent. To minimize pain:
+
+- **Use `get_master_key()` not `has_master_key()`** in step 2. Both call
+  the same underlying API, but `get_master_key()` returns the key bytes
+  so we can cache them. `has_master_key()` throws them away, forcing a
+  second keychain access later.
+
+- **Build `SecretsCrypto` eagerly.** When the keychain key is retrieved,
+  immediately construct `SecretsCrypto` and store in `self.secrets_crypto`.
+  Later calls to `init_secrets_context()` check this field first, avoiding
+  redundant keychain probes.
+
+- **Never probe the keychain in read-only commands** (e.g., `ironclaw status`).
+  The status command reports "env not set (keychain may be configured)"
+  rather than triggering system dialogs.
+
+**Invariant:** After Step 2, `self.secrets_crypto` is `Some` if the user
+chose Keychain or generated a new key. It may be `None` if the user chose
+env-var mode or skipped secrets.
+
+---
+
+### Step 3: Inference Provider
+
+**Module:** `wizard.rs` → `step_inference_provider()`
+
+**Goal:** Choose LLM backend and authenticate.
+
+**Providers:**
+
+| Provider | Auth Method | Secret Name | Env Var |
+|----------|-------------|-------------|---------|
+| NEAR AI | Browser OAuth | (session token) | `NEARAI_SESSION_TOKEN` |
+| Anthropic | API key | `anthropic_api_key` | `ANTHROPIC_API_KEY` |
+| OpenAI | API key | `openai_api_key` | `OPENAI_API_KEY` |
+| Ollama | None | - | - |
+| OpenAI-compatible | Optional API key | `llm_compatible_api_key` | `LLM_API_KEY` |
+
+**API-key providers** (`setup_api_key_provider`):
+1. Check env var → if set, ask to reuse, persist to secrets store
+2. Otherwise prompt for key entry via `secret_input()`
+3. Store encrypted in secrets via `init_secrets_context()`
+4. **Cache key in `self.llm_api_key`** for model fetching in Step 4
+
+**NEAR AI** (`setup_nearai`):
+- Calls `session_manager.ensure_authenticated()` which opens browser
+- Session token saved to `~/.ironclaw/session.json`
+
+**`self.llm_api_key` caching:** The wizard caches the API key as
+`Option<SecretString>` so that Step 4 (model fetching) and Step 5
+(embeddings) can use it without re-reading from the secrets store or
+mutating environment variables.
+
+---
+
+### Step 4: Model Selection
+
+**Module:** `wizard.rs` → `step_model_selection()`
+
+**Goal:** Choose which model to use.
+
+**Flow:**
+1. If model already set → offer to keep it
+2. Fetch models from provider API (5-second timeout)
+3. On timeout or error → use static fallback list
+4. Present list + "Custom model ID" escape hatch
+5. Store in `self.settings.selected_model`
+
+**Model fetchers pass the cached API key explicitly:**
+```rust
+let cached = self.llm_api_key.as_ref().map(|k| k.expose_secret().to_string());
+let models = fetch_anthropic_models(cached.as_deref()).await;
+```
+
+This avoids mutating environment variables. The fetcher checks the explicit
+key first, then falls back to the standard env var.
+
+---
+
+### Step 5: Embeddings
+
+**Module:** `wizard.rs` → `step_embeddings()`
+
+**Goal:** Configure semantic search for workspace memory.
+
+**Flow:**
+1. Ask "Enable semantic search?" (default: yes)
+2. Detect available providers:
+   - NEAR AI: if backend is `nearai` OR valid session exists
+   - OpenAI: if `OPENAI_API_KEY` in env OR (backend is `openai` AND cached key)
+3. If both available → let user choose
+4. If only one → use it
+5. If neither → disable embeddings
+
+**Default model:** `text-embedding-3-small` (for both providers)
+
+---
+
+### Step 6: Channel Configuration
+
+**Module:** `wizard.rs` → `step_channels()`, delegating to `channels.rs`
+
+**Goal:** Enable input channels (TUI, HTTP, Telegram, etc.).
+
+**Sub-steps:**
+
+```
+6a. Tunnel setup (if webhook channels needed)
+6b. Discover WASM channels from ~/.ironclaw/channels/
+6c. Multi-select: CLI/TUI, HTTP, discovered channels, bundled channels
+6d. Install missing bundled channels (copy WASM binaries)
+6e. Initialize SecretsContext (for token storage)
+6f. Setup HTTP webhook (if selected)
+6g. Setup each WASM channel (secrets, owner binding)
+```
+
+**Tunnel setup** (`setup_tunnel`):
+- Options: ngrok, Cloudflare Tunnel, localtunnel, custom URL
+- Validates HTTPS requirement
+- Stored in `self.settings.tunnel.public_url`
+
+**WASM channel setup** (`setup_wasm_channel`):
+- Reads `capabilities.json` for `setup.required_secrets`
+- For each secret: check existing, prompt or auto-generate, validate regex
+- Save each secret via `SecretsContext`
+
+**Telegram special case** (`setup_telegram`):
+- Validates bot token via Telegram `getMe` API
+- Owner binding: polls `getUpdates` for 120s to capture sender's user ID
+- Optional webhook secret generation
+
+**SecretsContext creation** (`init_secrets_context`):
+1. Check `self.secrets_crypto` (set in Step 2) → use if available
+2. Else try `SECRETS_MASTER_KEY` env var
+3. Else try `get_master_key()` from keychain (only in `channels_only` mode)
+4. Create backend-appropriate secrets store (respects selected database backend)
+
+---
+
+### Step 7: Heartbeat
+
+**Module:** `wizard.rs` → `step_heartbeat()`
+
+**Goal:** Configure periodic background execution.
+
+**Flow:**
+1. Ask "Enable heartbeat?" (default: no)
+2. If yes: interval in minutes (default: 30), notification channel
+3. Store in `self.settings.heartbeat`
+
+---
+
+## Settings Persistence
+
+### Two-Layer Architecture
+
+Settings are persisted in two places:
+
+**Layer 1: `~/.ironclaw/.env`** (bootstrap vars)
+
+Contains only the settings needed BEFORE database connection. Written by
+`save_bootstrap_env()` in `bootstrap.rs`.
+
+```env
+DATABASE_BACKEND="libsql"
+LIBSQL_PATH="/Users/name/.ironclaw/ironclaw.db"
+```
+
+Or for PostgreSQL:
+```env
+DATABASE_BACKEND="postgres"
+DATABASE_URL="postgres://user:pass@localhost/ironclaw"
+```
+
+**Why separate?** Chicken-and-egg: you need `DATABASE_BACKEND` to know
+which database to connect to, so it can't be stored in the database.
+
+**Layer 2: Database settings table** (everything else)
+
+All other settings are stored as key-value pairs in the `settings` table,
+keyed by `(user_id, key)`. Written by `set_all_settings()`.
+
+Settings are serialized via `Settings::to_db_map()` as dotted paths:
+```
+database_backend = "libsql"
+llm_backend = "nearai"
+selected_model = "anthropic/claude-sonnet-4-5"
+embeddings.enabled = "true"
+embeddings.provider = "nearai"
+channels.http_enabled = "true"
+heartbeat.enabled = "true"
+heartbeat.interval_secs = "300"
+```
+
+### save_and_summarize()
+
+Final step of the wizard:
+
+```
+1. Mark onboard_completed = true
+2. Write ALL settings to database (try postgres pool, then libSQL backend)
+3. Write bootstrap vars to ~/.ironclaw/.env:
+   - DATABASE_BACKEND (always)
+   - DATABASE_URL     (if postgres)
+   - LIBSQL_PATH      (if libsql)
+   - LIBSQL_URL       (if turso sync)
+4. Print configuration summary
+```
+
+**Invariant:** Both Layer 1 and Layer 2 must be written. If the database
+write fails, the wizard returns an error and the `.env` file is not written.
+
+### Legacy Migration
+
+`bootstrap.rs` handles one-time upgrades from older config formats:
+- `bootstrap.json` → extracts `DATABASE_URL`, writes `.env`, renames to `.migrated`
+- `settings.json` → migrated to database via `migrate_disk_to_db()`
+
+---
+
+## Settings Struct
+
+**Module:** `settings.rs`
+
+```rust
+pub struct Settings {
+    // Meta
+    pub onboard_completed: bool,
+
+    // Step 1: Database
+    pub database_backend: Option<String>,    // "postgres" | "libsql"
+    pub database_url: Option<String>,
+    pub libsql_path: Option<String>,
+    pub libsql_url: Option<String>,
+
+    // Step 2: Security
+    pub secrets_master_key_source: KeySource, // Keychain | Env | None
+
+    // Step 3: Inference
+    pub llm_backend: Option<String>,         // "nearai" | "anthropic" | "openai" | "ollama" | "openai_compatible"
+    pub ollama_base_url: Option<String>,
+    pub openai_compatible_base_url: Option<String>,
+
+    // Step 4: Model
+    pub selected_model: Option<String>,
+
+    // Step 5: Embeddings
+    pub embeddings: EmbeddingsSettings,      // enabled, provider, model
+
+    // Step 6: Channels
+    pub tunnel: TunnelSettings,              // provider, public_url
+    pub channels: ChannelSettings,           // http config, telegram owner, etc.
+
+    // Step 7: Heartbeat
+    pub heartbeat: HeartbeatSettings,        // enabled, interval, notify
+
+    // Advanced (not in wizard, set via `ironclaw config set`)
+    pub agent: AgentSettings,
+    pub wasm: WasmSettings,
+    pub sandbox: SandboxSettings,
+    pub safety: SafetySettings,
+    pub builder: BuilderSettings,
+}
+```
+
+**KeySource enum:** `Keychain | Env | None`
+
+---
+
+## Secrets Flow
+
+### SecretsContext
+
+Thin wrapper for setup-time secret operations:
+
+```rust
+pub struct SecretsContext {
+    store: Arc<dyn SecretsStore>,
+    user_id: String,
+}
+```
+
+Created by `init_secrets_context()` which:
+1. Gets `SecretsCrypto` from `self.secrets_crypto` or loads from keychain/env
+2. Creates the appropriate backend store:
+   - If both features compiled: respects `self.settings.database_backend`
+   - Tries selected backend first, falls back to the other
+3. Returns `SecretsContext` wrapping the store
+
+### Secret Storage
+
+Secrets are encrypted with AES-256-GCM using the master key, then stored
+in the database `secrets` table. The wizard writes secrets like:
+
+```
+telegram_bot_token    → encrypted bot token
+telegram_webhook_secret → encrypted webhook HMAC secret
+anthropic_api_key     → encrypted API key
+```
+
+---
+
+## Prompt Utilities
+
+**Module:** `prompts.rs`
+
+| Function | Description |
+|----------|-------------|
+| `select_one(label, options)` | Numbered single-choice menu |
+| `select_many(label, options, defaults)` | Checkbox multi-select (raw terminal mode) |
+| `input(label)` | Single line text input |
+| `optional_input(label, hint)` | Text input that can be empty |
+| `secret_input(label)` | Hidden input (shows `*` per char), returns `SecretString` |
+| `confirm(label, default)` | `[Y/n]` or `[y/N]` prompt |
+| `print_header(text)` | Bold section header with underline |
+| `print_step(n, total, text)` | `[1/7] Step Name` |
+| `print_success(text)` | Green checkmark prefix |
+| `print_error(text)` | Red X prefix |
+| `print_info(text)` | Blue info prefix |
+
+`select_many` uses `crossterm` raw mode for arrow key navigation.
+Must properly restore terminal state on all exit paths.
+
+---
+
+## Platform Caveats
+
+### macOS Keychain
+
+- `get_generic_password()` triggers system dialogs (unlock + authorize)
+- Two dialogs per call is normal, not a bug
+- Cache the result after first access to avoid repeat prompts
+- Never probe keychain in read-only commands (`status`, `--help`)
+- Service name: `"ironclaw"`, account: `"master_key"`
+
+### Linux Secret Service
+
+- Uses GNOME Keyring or KWallet via `secret-service` crate
+- May need `gnome-keyring` daemon running
+- Collection unlock may prompt for password
+
+### URL Passwords
+
+- `#` is common in URL-encoded passwords (`%23` decoded)
+- `.env` values must be double-quoted to preserve `#`
+- Display masked: `postgres://user:****@host/db`
+
+### Telegram API
+
+- Bot token format: `123456:ABC-DEF...`
+- Token goes in URL path: `https://api.telegram.org/bot{TOKEN}/method`
+- Webhook secret header: `X-Telegram-Bot-Api-Secret-Token`
+- Owner binding polls `getUpdates` (must delete webhook first)
+
+---
+
+## Testing
+
+Tests live in `mod tests {}` at the bottom of each file.
+
+**What to test when modifying setup:**
+
+- Settings round-trip: `to_db_map()` then `from_db_map()` preserves values
+- Bootstrap `.env`: dotenvy can parse what `save_bootstrap_env()` writes
+- Model fetchers: static fallback works when API is unreachable
+- Channel discovery: handles missing dir, invalid JSON, deduplication
+- Prompt functions: not tested (interactive I/O), but ensure error paths
+  don't panic
+
+**Run setup tests:**
+```bash
+cargo test --lib -- setup
+cargo test --lib -- bootstrap
+```
+
+---
+
+## Modification Checklist
+
+When changing the onboarding flow:
+
+1. Update this README first with the intended behavior change
+2. If adding a new wizard step:
+   - Add to the step enum in `run()`, adjust `total_steps`
+   - Add corresponding settings fields to `Settings`
+   - Add `to_db_map` / `from_db_map` serialization
+   - If the setting is needed before DB connection, add to `save_bootstrap_env()`
+3. If adding a new provider or channel:
+   - Add to the selection menu in the appropriate step
+   - Add authentication flow (API key or OAuth)
+   - Add model fetcher with static fallback + 5s timeout
+4. If touching keychain:
+   - Cache the result, never call `get_master_key()` twice
+   - Test on macOS (dialog behavior differs from Linux)
+5. If touching secrets:
+   - Ensure `init_secrets_context()` respects the selected database backend
+   - Test with both postgres and libsql features
+6. Run the full shipping checklist:
+   ```bash
+   cargo fmt
+   cargo clippy --all --benches --tests --examples --all-features -- -D warnings
+   cargo test --lib -- setup bootstrap
+   ```
+7. Test a fresh onboarding: `rm -rf ~/.ironclaw && cargo run`
@@ -20,6 +20,22 @@ use crate::setup::prompts::{
    confirm, input, optional_input, print_error, print_info, print_success, secret_input,
 };

+/// Typed errors for channel setup flows.
+#[derive(Debug, thiserror::Error)]
+pub enum ChannelSetupError {
+    #[error("I/O error: {0}")]
+    Io(#[from] std::io::Error),
+
+    #[error("{0}")]
+    Network(String),
+
+    #[error("{0}")]
+    Secrets(String),
+
+    #[error("{0}")]
+    Validation(String),
+}
+
 /// Context for saving secrets during setup.
 pub struct SecretsContext {
    store: Arc<dyn SecretsStore>,
@@ -45,32 +61,39 @@ impl SecretsContext {
    }

    /// Save a secret to the database.
-    pub async fn save_secret(&self, name: &str, value: &SecretString) -> Result<(), String> {
+    pub async fn save_secret(
+        &self,
+        name: &str,
+        value: &SecretString,
+    ) -> Result<(), ChannelSetupError> {
        let params = CreateSecretParams::new(name, value.expose_secret());

        self.store
            .create(&self.user_id, params)
            .await
-            .map_err(|e| format!("Failed to save secret: {}", e))?;
+            .map_err(|e| ChannelSetupError::Secrets(format!("Failed to save secret: {}", e)))?;

        Ok(())
    }

    /// Check if a secret exists.
    pub async fn secret_exists(&self, name: &str) -> bool {
-        self.store
-            .exists(&self.user_id, name)
-            .await
-            .unwrap_or(false)
+        match self.store.exists(&self.user_id, name).await {
+            Ok(exists) => exists,
+            Err(e) => {
+                tracing::warn!(secret = name, error = %e, "Failed to check if secret exists, assuming absent");
+                false
+            }
+        }
    }

    /// Read a secret from the database (decrypted).
-    pub async fn get_secret(&self, name: &str) -> Result<SecretString, String> {
+    pub async fn get_secret(&self, name: &str) -> Result<SecretString, ChannelSetupError> {
        let decrypted = self
            .store
            .get_decrypted(&self.user_id, name)
            .await
-            .map_err(|e| format!("Failed to read secret: {}", e))?;
+            .map_err(|e| ChannelSetupError::Secrets(format!("Failed to read secret: {}", e)))?;
        Ok(SecretString::from(decrypted.expose().to_string()))
    }
 }
@@ -107,7 +130,6 @@ struct TelegramGetUpdatesResponse {

 #[derive(Debug, Deserialize)]
 struct TelegramUpdate {
-    #[allow(dead_code)]
    update_id: i64,
    message: Option<TelegramUpdateMessage>,
 }
@@ -134,7 +156,7 @@ struct TelegramUpdateUser {
 pub async fn setup_telegram(
    secrets: &SecretsContext,
    settings: &Settings,
-) -> Result<TelegramSetupResult, String> {
+) -> Result<TelegramSetupResult, ChannelSetupError> {
    println!("Telegram Setup:");
    println!();
    print_info("To create a Telegram bot:");
@@ -146,7 +168,7 @@ pub async fn setup_telegram(
    // Check if token already exists
    if secrets.secret_exists("telegram_bot_token").await {
        print_info("Existing Telegram token found in database.");
-        if !confirm("Replace existing token?", false).map_err(|e| e.to_string())? {
+        if !confirm("Replace existing token?", false)? {
            // Still offer to configure webhook secret and owner binding
            let webhook_secret = setup_telegram_webhook_secret(secrets, &settings.tunnel).await?;
            let owner_id = bind_telegram_owner_flow(secrets, settings).await?;
@@ -159,47 +181,48 @@ pub async fn setup_telegram(
        }
    }

-    let token = secret_input("Bot token (from @BotFather)").map_err(|e| e.to_string())?;
+    loop {
+        let token = secret_input("Bot token (from @BotFather)")?;

-    // Validate the token
-    print_info("Validating bot token...");
+        // Validate the token
+        print_info("Validating bot token...");

-    match validate_telegram_token(&token).await {
-        Ok(username) => {
-            print_success(&format!(
-                "Bot validated: @{}",
-                username.as_deref().unwrap_or("unknown")
-            ));
+        match validate_telegram_token(&token).await {
+            Ok(username) => {
+                print_success(&format!(
+                    "Bot validated: @{}",
+                    username.as_deref().unwrap_or("unknown")
+                ));

-            // Save to database
-            secrets.save_secret("telegram_bot_token", &token).await?;
-            print_success("Token saved to database");
+                // Save to database
+                secrets.save_secret("telegram_bot_token", &token).await?;
+                print_success("Token saved to database");

-            // Bind bot to owner's Telegram account
-            let owner_id = bind_telegram_owner(&token).await?;
+                // Bind bot to owner's Telegram account
+                let owner_id = bind_telegram_owner(&token).await?;

-            // Offer webhook secret configuration
-            let webhook_secret = setup_telegram_webhook_secret(secrets, &settings.tunnel).await?;
+                // Offer webhook secret configuration
+                let webhook_secret =
+                    setup_telegram_webhook_secret(secrets, &settings.tunnel).await?;

-            Ok(TelegramSetupResult {
-                enabled: true,
-                bot_username: username,
-                webhook_secret,
-                owner_id,
-            })
-        }
-        Err(e) => {
-            print_error(&format!("Token validation failed: {}", e));
+                return Ok(TelegramSetupResult {
+                    enabled: true,
+                    bot_username: username,
+                    webhook_secret,
+                    owner_id,
+                });
+            }
+            Err(e) => {
+                print_error(&format!("Token validation failed: {}", e));

-            if confirm("Try again?", true).map_err(|e| e.to_string())? {
-                Box::pin(setup_telegram(secrets, settings)).await
-            } else {
-                Ok(TelegramSetupResult {
-                    enabled: false,
-                    bot_username: None,
-                    webhook_secret: None,
-                    owner_id: None,
-                })
+                if !confirm("Try again?", true)? {
+                    return Ok(TelegramSetupResult {
+                        enabled: false,
+                        bot_username: None,
+                        webhook_secret: None,
+                        owner_id: None,
+                    });
+                }
            }
        }
    }
@@ -209,14 +232,14 @@ pub async fn setup_telegram(
 ///
 /// Polls `getUpdates` until a message arrives, then captures the sender's user ID.
 /// Returns `None` if the user declines or the flow times out.
-async fn bind_telegram_owner(token: &SecretString) -> Result<Option<i64>, String> {
+async fn bind_telegram_owner(token: &SecretString) -> Result<Option<i64>, ChannelSetupError> {
    println!();
    print_info("Account Binding (recommended):");
    print_info("Binding restricts the bot so only YOU can use it.");
    print_info("Without this, anyone who finds your bot can send it messages.");
    println!();

-    if !confirm("Bind bot to your Telegram account?", true).map_err(|e| e.to_string())? {
+    if !confirm("Bind bot to your Telegram account?", true)? {
        print_info("Skipping account binding. Bot will accept messages from all users.");
        return Ok(None);
    }
@@ -227,14 +250,16 @@ async fn bind_telegram_owner(token: &SecretString) -> Result<Option<i64>, String
    let client = Client::builder()
        .timeout(std::time::Duration::from_secs(35))
        .build()
-        .map_err(|e| format!("Failed to create HTTP client: {}", e))?;
+        .map_err(|e| ChannelSetupError::Network(format!("Failed to create HTTP client: {}", e)))?;

    // Clear any existing webhook so getUpdates works
    let delete_url = format!(
        "https://api.telegram.org/bot{}/deleteWebhook",
        token.expose_secret()
    );
-    let _ = client.post(&delete_url).send().await;
+    if let Err(e) = client.post(&delete_url).send().await {
+        tracing::warn!("Failed to delete webhook (getUpdates may not work): {e}");
+    }

    let updates_url = format!(
        "https://api.telegram.org/bot{}/getUpdates",
@@ -249,19 +274,23 @@ async fn bind_telegram_owner(token: &SecretString) -> Result<Option<i64>, String
            .query(&[("timeout", "30"), ("allowed_updates", "[\"message\"]")])
            .send()
            .await
-            .map_err(|e| format!("getUpdates request failed: {}", e))?;
+            .map_err(|e| ChannelSetupError::Network(format!("getUpdates request failed: {}", e)))?;

        if !response.status().is_success() {
-            return Err(format!("getUpdates returned status {}", response.status()));
+            return Err(ChannelSetupError::Network(format!(
+                "getUpdates returned status {}",
+                response.status()
+            )));
        }

-        let body: TelegramGetUpdatesResponse = response
-            .json()
-            .await
-            .map_err(|e| format!("Failed to parse getUpdates response: {}", e))?;
+        let body: TelegramGetUpdatesResponse = response.json().await.map_err(|e| {
+            ChannelSetupError::Network(format!("Failed to parse getUpdates response: {}", e))
+        })?;

        if !body.ok {
-            return Err("Telegram API returned error for getUpdates".to_string());
+            return Err(ChannelSetupError::Network(
+                "Telegram API returned error for getUpdates".to_string(),
+            ));
        }

        // Find the first message with a sender
@@ -285,11 +314,14 @@ async fn bind_telegram_owner(token: &SecretString) -> Result<Option<i64>, String
                    "https://api.telegram.org/bot{}/getUpdates",
                    token.expose_secret()
                );
-                let _ = client
+                if let Err(e) = client
                    .get(&ack_url)
                    .query(&[("offset", &(update.update_id + 1).to_string())])
                    .send()
-                    .await;
+                    .await
+                {
+                    tracing::warn!("Failed to acknowledge Telegram update: {e}");
+                }

                return Ok(Some(from.id));
            }
@@ -307,10 +339,10 @@ async fn bind_telegram_owner(token: &SecretString) -> Result<Option<i64>, String
 async fn bind_telegram_owner_flow(
    secrets: &SecretsContext,
    settings: &Settings,
-) -> Result<Option<i64>, String> {
+) -> Result<Option<i64>, ChannelSetupError> {
    if settings.channels.telegram_owner_id.is_some() {
        print_info("Bot is already bound to a Telegram account.");
-        if !confirm("Re-bind to a different account?", false).map_err(|e| e.to_string())? {
+        if !confirm("Re-bind to a different account?", false)? {
            return Ok(settings.channels.telegram_owner_id);
        }
    }
@@ -325,10 +357,10 @@ async fn bind_telegram_owner_flow(
 ///
 /// This is shared across all channels that need webhook endpoints.
 /// Returns the tunnel URL if configured.
-pub fn setup_tunnel(settings: &Settings) -> Result<Option<String>, String> {
+pub fn setup_tunnel(settings: &Settings) -> Result<Option<String>, ChannelSetupError> {
    if let Some(ref url) = settings.tunnel.public_url {
        print_info(&format!("Existing tunnel configured: {}", url));
-        if !confirm("Change tunnel configuration?", false).map_err(|e| e.to_string())? {
+        if !confirm("Change tunnel configuration?", false)? {
            return Ok(Some(url.clone()));
        }
    }
@@ -348,17 +380,18 @@ pub fn setup_tunnel(settings: &Settings) -> Result<Option<String>, String> {
    print_info("Security comes from provider-specific secrets (e.g., Telegram webhook secret).");
    println!();

-    if !confirm("Configure a tunnel?", false).map_err(|e| e.to_string())? {
+    if !confirm("Configure a tunnel?", false)? {
        return Ok(None);
    }

-    let tunnel_url =
-        input("Tunnel URL (e.g., https://abc123.ngrok.io)").map_err(|e| e.to_string())?;
+    let tunnel_url = input("Tunnel URL (e.g., https://abc123.ngrok.io)")?;

    // Validate URL format
    if !tunnel_url.starts_with("https://") {
        print_error("URL must start with https:// (webhooks require HTTPS)");
-        return Err("Invalid tunnel URL: must use HTTPS".to_string());
+        return Err(ChannelSetupError::Validation(
+            "Invalid tunnel URL: must use HTTPS".to_string(),
+        ));
    }

    // Remove trailing slash if present
@@ -378,7 +411,7 @@ pub fn setup_tunnel(settings: &Settings) -> Result<Option<String>, String> {
 async fn setup_telegram_webhook_secret(
    secrets: &SecretsContext,
    tunnel: &TunnelSettings,
-) -> Result<Option<String>, String> {
+) -> Result<Option<String>, ChannelSetupError> {
    if tunnel.public_url.is_none() {
        print_info("");
        print_info("No tunnel configured. Telegram will use polling mode (30s+ delay).");
@@ -391,7 +424,7 @@ async fn setup_telegram_webhook_secret(
    print_info("A webhook secret adds an extra layer of security by validating");
    print_info("that requests actually come from Telegram's servers.");

-    if !confirm("Generate a webhook secret?", true).map_err(|e| e.to_string())? {
+    if !confirm("Generate a webhook secret?", true)? {
        return Ok(None);
    }

@@ -410,11 +443,13 @@ async fn setup_telegram_webhook_secret(
 /// Validate a Telegram bot token by calling the getMe API.
 ///
 /// Returns the bot's username if valid.
-pub async fn validate_telegram_token(token: &SecretString) -> Result<Option<String>, String> {
+pub async fn validate_telegram_token(
+    token: &SecretString,
+) -> Result<Option<String>, ChannelSetupError> {
    let client = Client::builder()
        .timeout(std::time::Duration::from_secs(10))
        .build()
-        .map_err(|e| format!("Failed to create HTTP client: {}", e))?;
+        .map_err(|e| ChannelSetupError::Network(format!("Failed to create HTTP client: {}", e)))?;

    let url = format!(
        "https://api.telegram.org/bot{}/getMe",
@@ -425,21 +460,26 @@ pub async fn validate_telegram_token(token: &SecretString) -> Result<Option<Stri
        .get(&url)
        .send()
        .await
-        .map_err(|e| format!("Request failed: {}", e))?;
+        .map_err(|e| ChannelSetupError::Network(format!("Request failed: {}", e)))?;

    if !response.status().is_success() {
-        return Err(format!("API returned status {}", response.status()));
+        return Err(ChannelSetupError::Network(format!(
+            "API returned status {}",
+            response.status()
+        )));
    }

    let body: TelegramGetMeResponse = response
        .json()
        .await
-        .map_err(|e| format!("Failed to parse response: {}", e))?;
+        .map_err(|e| ChannelSetupError::Network(format!("Failed to parse response: {}", e)))?;

    if body.ok {
        Ok(body.result.and_then(|u| u.username))
    } else {
-        Err("Telegram API returned error".to_string())
+        Err(ChannelSetupError::Network(
+            "Telegram API returned error".to_string(),
+        ))
    }
 }

@@ -452,38 +492,34 @@ pub struct HttpSetupResult {
 }

 /// Set up HTTP webhook channel.
-pub async fn setup_http(secrets: &SecretsContext) -> Result<HttpSetupResult, String> {
+pub async fn setup_http(secrets: &SecretsContext) -> Result<HttpSetupResult, ChannelSetupError> {
    println!("HTTP Webhook Setup:");
    println!();
    print_info("The HTTP webhook allows external services to send messages to the agent.");
    println!();

-    let port_str = optional_input("Port", Some("default: 8080")).map_err(|e| e.to_string())?;
+    let port_str = optional_input("Port", Some("default: 8080"))?;
    let port: u16 = port_str
        .as_deref()
        .unwrap_or("8080")
        .parse()
-        .map_err(|e| format!("Invalid port: {}", e))?;
+        .map_err(|e| ChannelSetupError::Validation(format!("Invalid port: {}", e)))?;

    if port < 1024 {
        print_info("Note: Ports below 1024 may require root privileges");
    }

-    let host = optional_input("Host", Some("default: 0.0.0.0"))
-        .map_err(|e| e.to_string())?
-        .unwrap_or_else(|| "0.0.0.0".to_string());
+    let host =
+        optional_input("Host", Some("default: 0.0.0.0"))?.unwrap_or_else(|| "0.0.0.0".to_string());

    // Generate a webhook secret
-    if confirm("Generate a webhook secret for authentication?", true).map_err(|e| e.to_string())? {
+    if confirm("Generate a webhook secret for authentication?", true)? {
        let secret = generate_webhook_secret();
        secrets
-            .save_secret("http_webhook_secret", &SecretString::from(secret.clone()))
+            .save_secret("http_webhook_secret", &SecretString::from(secret))
            .await?;
        print_success("Webhook secret generated and saved to database");
-        print_info(&format!(
-            "Secret: {} (store this for your webhook clients)",
-            secret
-        ));
+        print_info("Retrieve it later with: ironclaw secret get http_webhook_secret");
    }

    print_success(&format!("HTTP webhook will listen on {}:{}", host, port));
@@ -497,11 +533,7 @@ pub async fn setup_http(secrets: &SecretsContext) -> Result<HttpSetupResult, Str

 /// Generate a random webhook secret.
 pub fn generate_webhook_secret() -> String {
-    use rand::RngCore;
-    let mut rng = rand::thread_rng();
-    let mut bytes = [0u8; 32];
-    rng.fill_bytes(&mut bytes);
-    bytes.iter().map(|b| format!("{:02x}", b)).collect()
+    generate_secret_with_length(32)
 }

 /// Result of WASM channel setup.
@@ -519,7 +551,7 @@ pub async fn setup_wasm_channel(
    secrets: &SecretsContext,
    channel_name: &str,
    setup: &crate::channels::wasm::SetupSchema,
-) -> Result<WasmChannelSetupResult, String> {
+) -> Result<WasmChannelSetupResult, ChannelSetupError> {
    println!("{} Setup:", channel_name);
    println!();

@@ -530,7 +562,7 @@ pub async fn setup_wasm_channel(
                "Existing {} found in database.",
                secret_config.name
            ));
-            if !confirm("Replace existing value?", false).map_err(|e| e.to_string())? {
+            if !confirm("Replace existing value?", false)? {
                continue;
            }
        }
@@ -538,8 +570,7 @@ pub async fn setup_wasm_channel(
        // Get the value from user or auto-generate
        let value = if secret_config.optional {
            let input_value =
-                optional_input(&secret_config.prompt, Some("leave empty to auto-generate"))
-                    .map_err(|e| e.to_string())?;
+                optional_input(&secret_config.prompt, Some("leave empty to auto-generate"))?;

            if let Some(v) = input_value {
                if !v.is_empty() {
@@ -566,18 +597,21 @@ pub async fn setup_wasm_channel(
            }
        } else {
            // Required secret
-            let input_value = secret_input(&secret_config.prompt).map_err(|e| e.to_string())?;
+            let input_value = secret_input(&secret_config.prompt)?;

            // Validate if pattern is provided
            if let Some(ref pattern) = secret_config.validation {
-                let re = regex::Regex::new(pattern)
-                    .map_err(|e| format!("Invalid validation pattern: {}", e))?;
+                let re = regex::Regex::new(pattern).map_err(|e| {
+                    ChannelSetupError::Validation(format!("Invalid validation pattern: {}", e))
+                })?;
                if !re.is_match(input_value.expose_secret()) {
                    print_error(&format!(
                        "Value does not match expected format: {}",
                        pattern
                    ));
-                    return Err("Validation failed".to_string());
+                    return Err(ChannelSetupError::Validation(
+                        "Validation failed".to_string(),
+                    ));
                }
            }

@@ -589,14 +623,11 @@ pub async fn setup_wasm_channel(
        print_success(&format!("{} saved to database", secret_config.name));
    }

-    // Optionally validate the configuration
+    // TODO: Substitute secrets into the validation URL and make a
+    // GET request to verify the configured credentials actually work.
    if let Some(ref validation_endpoint) = setup.validation_endpoint {
-        print_info("Validating configuration...");
-        // The validation endpoint may contain placeholders like {telegram_bot_token}
-        // For now, we skip validation since we'd need to substitute secrets
-        // A full implementation would fetch secrets and substitute them
        print_info(&format!(
-            "Validation endpoint configured: {} (validation skipped)",
+            "Validation endpoint configured: {} (validation not yet implemented)",
            validation_endpoint
        ));
    }
@@ -620,11 +651,23 @@ fn generate_secret_with_length(length: usize) -> String {

 #[cfg(test)]
 mod tests {
-    use super::*;
+    use crate::setup::channels::generate_webhook_secret;

    #[test]
    fn test_generate_webhook_secret() {
        let secret = generate_webhook_secret();
        assert_eq!(secret.len(), 64); // 32 bytes = 64 hex chars
    }
+
+    #[test]
+    fn test_generate_secret_with_length() {
+        use super::generate_secret_with_length;
+
+        let s = generate_secret_with_length(16);
+        assert_eq!(s.len(), 32); // 16 bytes = 32 hex chars
+        assert!(s.chars().all(|c| c.is_ascii_hexdigit()));
+
+        let s2 = generate_secret_with_length(1);
+        assert_eq!(s2.len(), 2);
+    }
 }
@@ -3,7 +3,7 @@
 //! Provides a guided setup experience for:
 //! 1. Database connection
 //! 2. Security (secrets master key)
-//! 3. NEAR AI authentication
+//! 3. Inference provider selection
 //! 4. Model selection
 //! 5. Embeddings
 //! 6. Channel configuration (HTTP, Telegram, etc.)
@@ -24,7 +24,8 @@ mod prompts;
 mod wizard;

 pub use channels::{
-    SecretsContext, setup_http, setup_telegram, setup_tunnel, validate_telegram_token,
+    ChannelSetupError, SecretsContext, setup_http, setup_telegram, setup_tunnel,
+    validate_telegram_token,
 };
 pub use prompts::{
    confirm, input, optional_input, print_error, print_header, print_info, print_step,
@@ -21,6 +21,7 @@ use secrecy::SecretString;
 /// Display a numbered menu and get user selection.
 ///
 /// Returns the index (0-based) of the selected option.
+/// Pressing Enter without input selects the first option (index 0).
 ///
 /// # Example
 ///
@@ -84,6 +85,10 @@ pub fn select_one(prompt: &str, options: &[&str]) -> io::Result<usize> {
 /// ])?;
 /// ```
 pub fn select_many(prompt: &str, options: &[(&str, bool)]) -> io::Result<Vec<usize>> {
+    if options.is_empty() {
+        return Ok(vec![]);
+    }
+
    let mut stdout = io::stdout();
    let mut selected: Vec<bool> = options.iter().map(|(_, s)| *s).collect();
    let mut cursor_pos = 0;
@@ -0,0 +1,22 @@
+[package]
+name = "github-tool"
+version = "0.1.0"
+edition = "2021"
+description = "GitHub integration tool for IronClaw (WASM component)"
+license = "MIT OR Apache-2.0"
+publish = false
+
+[dependencies]
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
+wit-bindgen = "0.41.0"
+
+[lib]
+crate-type = ["cdylib"]
+
+[profile.release]
+opt-level = "s"
+lto = true
+strip = true
+codegen-units = 1
+
@@ -0,0 +1,189 @@
+# GitHub Tool for IronClaw
+
+WASM tool for GitHub integration - manage repos, issues, PRs, and workflows.
+
+## Features
+
+- **Repository Info** - Get repo details, list user repos
+- **Issues** - List, create, and get issue details
+- **Pull Requests** - List PRs, get PR details, review files, create reviews
+- **File Content** - Read files from repos
+- **Workflows** - Trigger GitHub Actions, check run status
+
+## Setup
+
+1. Create a GitHub Personal Access Token at <https://github.com/settings/tokens>
+2. Required scopes: `repo`, `workflow`, `read:org`
+3. Store the token:
+
+   ```
+   ironclaw secret set github_token YOUR_TOKEN
+   ```
+
+## Usage Examples
+
+### Get Repository Info
+
+```json
+{
+  "action": "get_repo",
+  "owner": "nearai",
+  "repo": "ironclaw"
+}
+```
+
+### List Open Issues
+
+```json
+{
+  "action": "list_issues",
+  "owner": "nearai",
+  "repo": "ironclaw",
+  "state": "open",
+  "limit": 10
+}
+```
+
+### Create Issue
+
+```json
+{
+  "action": "create_issue",
+  "owner": "nearai",
+  "repo": "ironclaw",
+  "title": "Bug: Something is broken",
+  "body": "Detailed description...",
+  "labels": ["bug", "help wanted"]
+}
+```
+
+### List Pull Requests
+
+```json
+{
+  "action": "list_pull_requests",
+  "owner": "nearai",
+  "repo": "ironclaw",
+  "state": "open",
+  "limit": 5
+}
+```
+
+### Review PR
+
+```json
+{
+  "action": "create_pr_review",
+  "owner": "nearai",
+  "repo": "ironclaw",
+  "pr_number": 42,
+  "body": "LGTM! Great work.",
+  "event": "APPROVE"
+}
+```
+
+### Get File Content
+
+```json
+{
+  "action": "get_file_content",
+  "owner": "nearai",
+  "repo": "ironclaw",
+  "path": "README.md",
+  "ref": "main"
+}
+```
+
+### Trigger Workflow
+
+```json
+{
+  "action": "trigger_workflow",
+  "owner": "nearai",
+  "repo": "ironclaw",
+  "workflow_id": "ci.yml",
+  "ref": "main",
+  "inputs": {
+    "environment": "staging"
+  }
+}
+```
+
+### Check Workflow Runs
+
+```json
+{
+  "action": "get_workflow_runs",
+  "owner": "nearai",
+  "repo": "ironclaw",
+  "limit": 5
+}
+```
+
+### List Workflow Runs (Pagination)
+
+```json
+{
+  "action": "get_workflow_runs",
+  "owner": "nearai",
+  "repo": "ironclaw",
+  "limit": 5,
+  "page": 2
+}
+```
+
+## Error Handling
+
+Errors are returned as strings in the `error` field of the response.
+
+### Rate Limit Exceeded
+
+When the GitHub API rate limit is exceeded (and retries fail), you might see:
+
+```text
+GitHub API error 429: { "message": "API rate limit exceeded for user ID ...", ... }
+```
+
+The tool automatically logs warnings when the rate limit is low (<10 remaining) and retries on 429/5xx errors.
+
+### Invalid Parameters
+
+```text
+Invalid event: 'INVALID'. Must be one of: APPROVE, REQUEST_CHANGES, COMMENT
+```
+
+### Missing Token
+
+```text
+GitHub token not found in secret store. Set it with: ironclaw secret set github_token <token>...
+```
+
+## Troubleshooting
+
+### "GitHub API error 404: Not Found"
+
+- Check that the `owner` and `repo` are correct.
+- Ensure the `github_token` has access to the repository (especially for private repos).
+- Verify the token scopes include `repo` and `read:org`.
+
+### "GitHub API error 401: Bad credentials"
+
+- The token might be invalid or expired.
+- Update the token: `ironclaw secret set github_token NEW_TOKEN`.
+
+### Rate Limiting
+
+- The tool logs a warning when remaining requests drop below 10.
+- Check logs for "GitHub API rate limit low".
+- If you hit the limit, wait for the reset time (usually 1 hour).
+
+## Building
+
+```bash
+cd tools-src/github
+cargo build --target wasm32-wasi --release
+```
+
+## License
+
+MIT/Apache-2.0
@@ -0,0 +1,41 @@
+{
+  "capabilities": {
+    "http": {
+      "allowlist": [
+        {
+          "host": "api.github.com",
+          "path_prefix": "/",
+          "methods": [
+            "GET",
+            "POST"
+          ]
+        }
+      ],
+      "credentials": {
+        "github_token": {
+          "secret_name": "github_token",
+          "location": {
+            "type": "bearer"
+          },
+          "host_patterns": [
+            "api.github.com"
+          ]
+        }
+      },
+      "rate_limit": {
+        "requests_per_minute": 60,
+        "requests_per_hour": 3600
+      }
+    },
+    "secrets": {
+      "allowed_names": [
+        "github_token",
+        "github_*"
+      ]
+    }
+  },
+  "config": {
+    "default_limit": 30,
+    "max_limit": 100
+  }
+}
@@ -0,0 +1,845 @@
+//! GitHub WASM Tool for IronClaw.
+//!
+//! Provides GitHub integration for reading repos, managing issues,
+//! reviewing PRs, and triggering workflows.
+//!
+//! # Authentication
+//!
+//! Store your GitHub Personal Access Token:
+//! `ironclaw secret set github_token <token>`
+//!
+//! Token needs these permissions:
+//! - repo (for private repos)
+//! - workflow (for triggering actions)
+//! - read:org (for org repos)
+
+wit_bindgen::generate!({
+    world: "sandboxed-tool",
+    path: "../../wit/tool.wit",
+});
+
+use serde::Deserialize;
+
+const MAX_TEXT_LENGTH: usize = 65536;
+
+/// Validate input length to prevent oversized payloads.
+fn validate_input_length(s: &str, field_name: &str) -> Result<(), String> {
+    if s.len() > MAX_TEXT_LENGTH {
+        return Err(format!(
+            "Input '{}' exceeds maximum length of {} characters",
+            field_name, MAX_TEXT_LENGTH
+        ));
+    }
+    Ok(())
+}
+
+/// Percent-encode a string for safe use in URL path segments.
+/// Encodes everything except alphanumeric, hyphen, underscore, and dot.
+fn url_encode_path(s: &str) -> String {
+    let mut out = String::with_capacity(s.len() * 2);
+    for b in s.bytes() {
+        match b {
+            b'A'..=b'Z' | b'a'..=b'z' | b'0'..=b'9' | b'-' | b'_' | b'.' => {
+                out.push(b as char);
+            }
+            _ => {
+                out.push('%');
+                out.push(char::from(b"0123456789ABCDEF"[(b >> 4) as usize]));
+                out.push(char::from(b"0123456789ABCDEF"[(b & 0xf) as usize]));
+            }
+        }
+    }
+    out
+}
+
+/// Percent-encode a string for use as a URL query parameter value.
+/// Currently identical to `url_encode_path`.
+fn url_encode_query(s: &str) -> String {
+    url_encode_path(s)
+}
+
+/// Validate that a path segment doesn't contain dangerous characters.
+/// Returns true if the segment is safe to use.
+fn validate_path_segment(s: &str) -> bool {
+    !s.is_empty() && !s.contains('/') && !s.contains("..") && !s.contains('?') && !s.contains('#')
+}
+
+struct GitHubTool;
+
+#[derive(Debug, Deserialize)]
+#[serde(tag = "action")]
+enum GitHubAction {
+    #[serde(rename = "get_repo")]
+    GetRepo { owner: String, repo: String },
+    #[serde(rename = "list_issues")]
+    ListIssues {
+        owner: String,
+        repo: String,
+        state: Option<String>,
+        page: Option<u32>,
+        limit: Option<u32>,
+    },
+    #[serde(rename = "create_issue")]
+    CreateIssue {
+        owner: String,
+        repo: String,
+        title: String,
+        body: Option<String>,
+        labels: Option<Vec<String>>,
+    },
+    #[serde(rename = "get_issue")]
+    GetIssue {
+        owner: String,
+        repo: String,
+        issue_number: u32,
+    },
+    #[serde(rename = "list_pull_requests")]
+    ListPullRequests {
+        owner: String,
+        repo: String,
+        state: Option<String>,
+        page: Option<u32>,
+        limit: Option<u32>,
+    },
+    #[serde(rename = "get_pull_request")]
+    GetPullRequest {
+        owner: String,
+        repo: String,
+        pr_number: u32,
+    },
+    #[serde(rename = "get_pull_request_files")]
+    GetPullRequestFiles {
+        owner: String,
+        repo: String,
+        pr_number: u32,
+    },
+    #[serde(rename = "create_pr_review")]
+    CreatePrReview {
+        owner: String,
+        repo: String,
+        pr_number: u32,
+        body: String,
+        event: String,
+    },
+    #[serde(rename = "list_repos")]
+    ListRepos {
+        username: String,
+        page: Option<u32>,
+        limit: Option<u32>,
+    },
+    #[serde(rename = "get_file_content")]
+    GetFileContent {
+        owner: String,
+        repo: String,
+        path: String,
+        r#ref: Option<String>,
+    },
+    #[serde(rename = "trigger_workflow")]
+    TriggerWorkflow {
+        owner: String,
+        repo: String,
+        workflow_id: String,
+        r#ref: String,
+        inputs: Option<serde_json::Value>,
+    },
+    #[serde(rename = "get_workflow_runs")]
+    GetWorkflowRuns {
+        owner: String,
+        repo: String,
+        workflow_id: Option<String>,
+        page: Option<u32>,
+        limit: Option<u32>,
+    },
+}
+
+impl exports::near::agent::tool::Guest for GitHubTool {
+    fn execute(req: exports::near::agent::tool::Request) -> exports::near::agent::tool::Response {
+        match execute_inner(&req.params) {
+            Ok(result) => exports::near::agent::tool::Response {
+                output: Some(result),
+                error: None,
+            },
+            Err(e) => exports::near::agent::tool::Response {
+                output: None,
+                error: Some(e),
+            },
+        }
+    }
+
+    fn schema() -> String {
+        SCHEMA.to_string()
+    }
+
+    fn description() -> String {
+        "GitHub integration for managing repositories, issues, pull requests, \
+         and workflows. Supports reading repo info, listing/creating issues, \
+         reviewing PRs, and triggering GitHub Actions. \
+         Authentication is handled via the 'github_token' secret injected by the host."
+            .to_string()
+    }
+}
+
+fn execute_inner(params: &str) -> Result<String, String> {
+    let action: GitHubAction =
+        serde_json::from_str(params).map_err(|e| format!("Invalid parameters: {e}"))?;
+
+    // Pre-flight check: ensure token exists in secret store.
+    // We don't use the returned value because the host injects it into the request.
+    let _ = get_github_token()?;
+
+    match action {
+        GitHubAction::GetRepo { owner, repo } => get_repo(&owner, &repo),
+        GitHubAction::ListIssues {
+            owner,
+            repo,
+            state,
+            page,
+            limit,
+        } => list_issues(&owner, &repo, state.as_deref(), page, limit),
+        GitHubAction::CreateIssue {
+            owner,
+            repo,
+            title,
+            body,
+            labels,
+        } => create_issue(&owner, &repo, &title, body.as_deref(), labels),
+        GitHubAction::GetIssue {
+            owner,
+            repo,
+            issue_number,
+        } => get_issue(&owner, &repo, issue_number),
+        GitHubAction::ListPullRequests {
+            owner,
+            repo,
+            state,
+            page,
+            limit,
+        } => list_pull_requests(&owner, &repo, state.as_deref(), page, limit),
+        GitHubAction::GetPullRequest {
+            owner,
+            repo,
+            pr_number,
+        } => get_pull_request(&owner, &repo, pr_number),
+        GitHubAction::GetPullRequestFiles {
+            owner,
+            repo,
+            pr_number,
+        } => get_pull_request_files(&owner, &repo, pr_number),
+        GitHubAction::CreatePrReview {
+            owner,
+            repo,
+            pr_number,
+            body,
+            event,
+        } => create_pr_review(&owner, &repo, pr_number, &body, &event),
+        GitHubAction::ListRepos {
+            username,
+            page,
+            limit,
+        } => list_repos(&username, page, limit),
+        GitHubAction::GetFileContent {
+            owner,
+            repo,
+            path,
+            r#ref,
+        } => get_file_content(&owner, &repo, &path, r#ref.as_deref()),
+        GitHubAction::TriggerWorkflow {
+            owner,
+            repo,
+            workflow_id,
+            r#ref,
+            inputs,
+        } => trigger_workflow(&owner, &repo, &workflow_id, &r#ref, inputs),
+        GitHubAction::GetWorkflowRuns {
+            owner,
+            repo,
+            workflow_id,
+            page,
+            limit,
+        } => get_workflow_runs(&owner, &repo, workflow_id.as_deref(), page, limit),
+    }
+}
+
+fn get_github_token() -> Result<String, String> {
+    if near::agent::host::secret_exists("github_token") {
+        // Return dummy value since we only need to verify existence.
+        // The actual token is injected by the host.
+        return Ok("present".to_string());
+    }
+
+    Err("GitHub token not found in secret store. Set it with: ironclaw secret set github_token <token>. \
+         Token needs 'repo', 'workflow', and 'read:org' scopes.".into())
+}
+
+fn github_request(method: &str, path: &str, body: Option<String>) -> Result<String, String> {
+    let url = format!("https://api.github.com{}", path);
+
+    // Authorization header (Bearer <token>) is injected automatically by the host
+    // via the `http-wrapper` proxy based on the `github_token` secret.
+    let headers = serde_json::json!({
+        "Accept": "application/vnd.github+json",
+        "X-GitHub-Api-Version": "2022-11-28",
+        "User-Agent": "IronClaw-GitHub-Tool"
+    });
+
+    let body_bytes = body.map(|b| b.into_bytes());
+
+    // Simple retry logic for transient errors (max 3 attempts)
+    let max_retries = 3;
+    let mut attempt = 0;
+
+    loop {
+        attempt += 1;
+
+        let response = near::agent::host::http_request(
+            method,
+            &url,
+            &headers.to_string(),
+            body_bytes.as_deref(),
+            None,
+        );
+
+        match response {
+            Ok(resp) => {
+                // Log warning if rate limit is low
+                if let Ok(headers_json) =
+                    serde_json::from_str::<serde_json::Value>(&resp.headers_json)
+                {
+                    // Header keys are often lowercase in http libs, check case-insensitively if needed,
+                    // but usually standard is lowercase/case-insensitive. Let's try lowercase.
+                    if let Some(remaining) = headers_json
+                        .get("x-ratelimit-remaining")
+                        .and_then(|v| v.as_str())
+                    {
+                        if let Ok(count) = remaining.parse::<u32>() {
+                            if count < 10 {
+                                near::agent::host::log(
+                                    near::agent::host::LogLevel::Warn,
+                                    &format!("GitHub API rate limit low: {} remaining", count),
+                                );
+                            }
+                        }
+                    }
+                }
+
+                if resp.status >= 200 && resp.status < 300 {
+                    return String::from_utf8(resp.body)
+                        .map_err(|e| format!("Invalid UTF-8: {}", e));
+                } else if attempt < max_retries && (resp.status == 429 || resp.status >= 500) {
+                    near::agent::host::log(
+                        near::agent::host::LogLevel::Warn,
+                        &format!(
+                            "GitHub API error {} (attempt {}/{}). Retrying...",
+                            resp.status, attempt, max_retries
+                        ),
+                    );
+                    // Minimal backoff simulation since we can't block easily in WASM without consuming generic budget?
+                    // actually std::thread::sleep works in WASMtime if configured, but here we might just spin.
+                    // ideally host exposes sleep. For now just retry immediately or rely on host timeout logic?
+                    // Let's assume immediate retry for now as simple strategy.
+                    continue;
+                } else {
+                    let body_str = String::from_utf8_lossy(&resp.body);
+                    return Err(format!("GitHub API error {}: {}", resp.status, body_str));
+                }
+            }
+            Err(e) => {
+                if attempt < max_retries {
+                    near::agent::host::log(
+                        near::agent::host::LogLevel::Warn,
+                        &format!(
+                            "HTTP request failed: {} (attempt {}/{}). Retrying...",
+                            e, attempt, max_retries
+                        ),
+                    );
+                    continue;
+                }
+                return Err(format!(
+                    "HTTP request failed after {} attempts: {}",
+                    max_retries, e
+                ));
+            }
+        }
+    }
+}
+
+// === API Functions ===
+
+fn get_repo(owner: &str, repo: &str) -> Result<String, String> {
+    if !validate_path_segment(owner) || !validate_path_segment(repo) {
+        return Err("Invalid owner or repo name".into());
+    }
+    let encoded_owner = url_encode_path(owner);
+    let encoded_repo = url_encode_path(repo);
+    github_request(
+        "GET",
+        &format!("/repos/{}/{}", encoded_owner, encoded_repo),
+        None,
+    )
+}
+
+fn list_issues(
+    owner: &str,
+    repo: &str,
+    state: Option<&str>,
+    page: Option<u32>,
+    limit: Option<u32>,
+) -> Result<String, String> {
+    if !validate_path_segment(owner) || !validate_path_segment(repo) {
+        return Err("Invalid owner or repo name".into());
+    }
+    let encoded_owner = url_encode_path(owner);
+    let encoded_repo = url_encode_path(repo);
+    let state = state.unwrap_or("open");
+    let limit = limit.unwrap_or(30).min(100); // Cap at 100
+    let encoded_state = url_encode_query(state);
+
+    let mut path = format!(
+        "/repos/{}/{}/issues?state={}&per_page={}",
+        encoded_owner, encoded_repo, encoded_state, limit
+    );
+    if let Some(p) = page {
+        path.push_str(&format!("&page={}", p));
+    }
+
+    github_request("GET", &path, None)
+}
+
+fn create_issue(
+    owner: &str,
+    repo: &str,
+    title: &str,
+    body: Option<&str>,
+    labels: Option<Vec<String>>,
+) -> Result<String, String> {
+    if !validate_path_segment(owner) || !validate_path_segment(repo) {
+        return Err("Invalid owner or repo name".into());
+    }
+    validate_input_length(title, "title")?;
+    if let Some(b) = body {
+        validate_input_length(b, "body")?;
+    }
+
+    let encoded_owner = url_encode_path(owner);
+    let encoded_repo = url_encode_path(repo);
+    let path = format!("/repos/{}/{}/issues", encoded_owner, encoded_repo);
+    let mut req_body = serde_json::json!({
+        "title": title,
+    });
+    if let Some(body) = body {
+        req_body["body"] = serde_json::json!(body);
+    }
+    if let Some(labels) = labels {
+        req_body["labels"] = serde_json::json!(labels);
+    }
+    github_request("POST", &path, Some(req_body.to_string()))
+}
+
+fn get_issue(owner: &str, repo: &str, issue_number: u32) -> Result<String, String> {
+    if !validate_path_segment(owner) || !validate_path_segment(repo) {
+        return Err("Invalid owner or repo name".into());
+    }
+    let encoded_owner = url_encode_path(owner);
+    let encoded_repo = url_encode_path(repo);
+    github_request(
+        "GET",
+        &format!(
+            "/repos/{}/{}/issues/{}",
+            encoded_owner, encoded_repo, issue_number
+        ),
+        None,
+    )
+}
+
+fn list_pull_requests(
+    owner: &str,
+    repo: &str,
+    state: Option<&str>,
+    page: Option<u32>,
+    limit: Option<u32>,
+) -> Result<String, String> {
+    if !validate_path_segment(owner) || !validate_path_segment(repo) {
+        return Err("Invalid owner or repo name".into());
+    }
+    let encoded_owner = url_encode_path(owner);
+    let encoded_repo = url_encode_path(repo);
+    let state = state.unwrap_or("open");
+    let limit = limit.unwrap_or(30).min(100); // Cap at 100
+    let encoded_state = url_encode_query(state);
+
+    let mut path = format!(
+        "/repos/{}/{}/pulls?state={}&per_page={}",
+        encoded_owner, encoded_repo, encoded_state, limit
+    );
+    if let Some(p) = page {
+        path.push_str(&format!("&page={}", p));
+    }
+
+    github_request("GET", &path, None)
+}
+
+fn get_pull_request(owner: &str, repo: &str, pr_number: u32) -> Result<String, String> {
+    if !validate_path_segment(owner) || !validate_path_segment(repo) {
+        return Err("Invalid owner or repo name".into());
+    }
+    let encoded_owner = url_encode_path(owner);
+    let encoded_repo = url_encode_path(repo);
+    github_request(
+        "GET",
+        &format!(
+            "/repos/{}/{}/pulls/{}",
+            encoded_owner, encoded_repo, pr_number
+        ),
+        None,
+    )
+}
+
+fn get_pull_request_files(owner: &str, repo: &str, pr_number: u32) -> Result<String, String> {
+    if !validate_path_segment(owner) || !validate_path_segment(repo) {
+        return Err("Invalid owner or repo name".into());
+    }
+    let encoded_owner = url_encode_path(owner);
+    let encoded_repo = url_encode_path(repo);
+    github_request(
+        "GET",
+        &format!(
+            "/repos/{}/{}/pulls/{}/files",
+            encoded_owner, encoded_repo, pr_number
+        ),
+        None,
+    )
+}
+
+fn create_pr_review(
+    owner: &str,
+    repo: &str,
+    pr_number: u32,
+    body: &str,
+    event: &str,
+) -> Result<String, String> {
+    if !validate_path_segment(owner) || !validate_path_segment(repo) {
+        return Err("Invalid owner or repo name".into());
+    }
+    validate_input_length(body, "body")?;
+
+    let valid_events = ["APPROVE", "REQUEST_CHANGES", "COMMENT"];
+    if !valid_events.contains(&event) {
+        return Err(format!(
+            "Invalid event: '{}'. Must be one of: {}",
+            event,
+            valid_events.join(", ")
+        ));
+    }
+    let encoded_owner = url_encode_path(owner);
+    let encoded_repo = url_encode_path(repo);
+    let path = format!(
+        "/repos/{}/{}/pulls/{}/reviews",
+        encoded_owner, encoded_repo, pr_number
+    );
+    let req_body = serde_json::json!({
+        "body": body,
+        "event": event,
+    });
+    github_request("POST", &path, Some(req_body.to_string()))
+}
+
+fn list_repos(username: &str, page: Option<u32>, limit: Option<u32>) -> Result<String, String> {
+    if !validate_path_segment(username) {
+        return Err("Invalid username".into());
+    }
+    let encoded_username = url_encode_path(username);
+    let limit = limit.unwrap_or(30).min(100); // Cap at 100
+    let mut path = format!("/users/{}/repos?per_page={}", encoded_username, limit);
+    if let Some(p) = page {
+        path.push_str(&format!("&page={}", p));
+    }
+    github_request("GET", &path, None)
+}
+
+fn get_file_content(
+    owner: &str,
+    repo: &str,
+    path: &str,
+    r#ref: Option<&str>,
+) -> Result<String, String> {
+    if !validate_path_segment(owner) || !validate_path_segment(repo) {
+        return Err("Invalid owner or repo name".into());
+    }
+    // Validate path segments - reject path traversal attempts and empty segments
+    for segment in path.split('/') {
+        if segment == ".." {
+            return Err("Invalid path: path traversal not allowed".into());
+        }
+        if segment.is_empty() {
+            return Err("Invalid path: empty segment not allowed".into());
+        }
+    }
+    // Validate ref if provided
+    if let Some(r#ref) = r#ref {
+        if r#ref.contains("..") || r#ref.contains(':') {
+            return Err("Invalid ref: must be a valid branch, tag, or commit SHA".into());
+        }
+    }
+    let encoded_owner = url_encode_path(owner);
+    let encoded_repo = url_encode_path(repo);
+    // Path can contain slashes, so we encode each segment separately
+    let encoded_path = path
+        .split('/')
+        .map(url_encode_path)
+        .collect::<Vec<_>>()
+        .join("/");
+
+    let url_path = if let Some(r#ref) = r#ref {
+        let encoded_ref = url_encode_query(r#ref);
+        format!(
+            "/repos/{}/{}/contents/{}?ref={}",
+            encoded_owner, encoded_repo, encoded_path, encoded_ref
+        )
+    } else {
+        format!(
+            "/repos/{}/{}/contents/{}",
+            encoded_owner, encoded_repo, encoded_path
+        )
+    };
+    github_request("GET", &url_path, None)
+}
+
+fn trigger_workflow(
+    owner: &str,
+    repo: &str,
+    workflow_id: &str,
+    r#ref: &str,
+    inputs: Option<serde_json::Value>,
+) -> Result<String, String> {
+    if !validate_path_segment(owner) || !validate_path_segment(repo) {
+        return Err("Invalid owner or repo name".into());
+    }
+    // Validate inputs size if present
+    if let Some(valid_inputs) = &inputs {
+        let inputs_str = valid_inputs.to_string();
+        validate_input_length(&inputs_str, "inputs")?;
+    }
+
+    // Validate workflow_id - must be a safe filename
+    if workflow_id.contains('/') || workflow_id.contains("..") || workflow_id.contains(':') {
+        return Err("Invalid workflow_id: must be a filename or numeric ID".into());
+    }
+    // Validate ref - must be a valid git ref
+    if r#ref.contains("..") || r#ref.contains(':') {
+        return Err("Invalid ref: must be a valid branch, tag, or commit SHA".into());
+    }
+    let encoded_owner = url_encode_path(owner);
+    let encoded_repo = url_encode_path(repo);
+    let encoded_workflow_id = url_encode_path(workflow_id);
+    let path = format!(
+        "/repos/{}/{}/actions/workflows/{}/dispatches",
+        encoded_owner, encoded_repo, encoded_workflow_id
+    );
+    let mut req_body = serde_json::json!({
+        "ref": r#ref,
+    });
+    if let Some(inputs) = inputs {
+        req_body["inputs"] = inputs;
+    }
+    github_request("POST", &path, Some(req_body.to_string()))
+}
+
+fn get_workflow_runs(
+    owner: &str,
+    repo: &str,
+    workflow_id: Option<&str>,
+    page: Option<u32>,
+    limit: Option<u32>,
+) -> Result<String, String> {
+    if !validate_path_segment(owner) || !validate_path_segment(repo) {
+        return Err("Invalid owner or repo name".into());
+    }
+    // Validate workflow_id if provided
+    if let Some(wid) = workflow_id {
+        if wid.contains('/') || wid.contains("..") || wid.contains(':') {
+            return Err("Invalid workflow_id: must be a filename or numeric ID".into());
+        }
+    }
+    let encoded_owner = url_encode_path(owner);
+    let encoded_repo = url_encode_path(repo);
+    let limit = limit.unwrap_or(30).min(100); // Cap at 100
+    let mut path = if let Some(workflow_id) = workflow_id {
+        let encoded_workflow_id = url_encode_path(workflow_id);
+        format!(
+            "/repos/{}/{}/actions/workflows/{}/runs?per_page={}",
+            encoded_owner, encoded_repo, encoded_workflow_id, limit
+        )
+    } else {
+        format!(
+            "/repos/{}/{}/actions/runs?per_page={}",
+            encoded_owner, encoded_repo, limit
+        )
+    };
+    if let Some(p) = page {
+        path.push_str(&format!("&page={}", p));
+    }
+    github_request("GET", &path, None)
+}
+
+const SCHEMA: &str = r#"{
+    "type": "object",
+    "required": ["action"],
+    "oneOf": [
+        {
+            "properties": {
+                "action": { "const": "get_repo" },
+                "owner": { "type": "string", "description": "Repository owner (user or org)" },
+                "repo": { "type": "string", "description": "Repository name" }
+            },
+            "required": ["action", "owner", "repo"]
+        },
+        {
+            "properties": {
+                "action": { "const": "list_issues" },
+                "owner": { "type": "string" },
+                "repo": { "type": "string" },
+                "state": { "type": "string", "enum": ["open", "closed", "all"], "default": "open" },
+                "limit": { "type": "integer", "default": 30 }
+            },
+            "required": ["action", "owner", "repo"]
+        },
+        {
+            "properties": {
+                "action": { "const": "create_issue" },
+                "owner": { "type": "string" },
+                "repo": { "type": "string" },
+                "title": { "type": "string" },
+                "body": { "type": "string" },
+                "labels": { "type": "array", "items": { "type": "string" } }
+            },
+            "required": ["action", "owner", "repo", "title"]
+        },
+        {
+            "properties": {
+                "action": { "const": "get_issue" },
+                "owner": { "type": "string" },
+                "repo": { "type": "string" },
+                "issue_number": { "type": "integer" }
+            },
+            "required": ["action", "owner", "repo", "issue_number"]
+        },
+        {
+            "properties": {
+                "action": { "const": "list_pull_requests" },
+                "owner": { "type": "string" },
+                "repo": { "type": "string" },
+                "state": { "type": "string", "enum": ["open", "closed", "all"], "default": "open" },
+                "limit": { "type": "integer", "default": 30 }
+            },
+            "required": ["action", "owner", "repo"]
+        },
+        {
+            "properties": {
+                "action": { "const": "get_pull_request" },
+                "owner": { "type": "string" },
+                "repo": { "type": "string" },
+                "pr_number": { "type": "integer" }
+            },
+            "required": ["action", "owner", "repo", "pr_number"]
+        },
+        {
+            "properties": {
+                "action": { "const": "get_pull_request_files" },
+                "owner": { "type": "string" },
+                "repo": { "type": "string" },
+                "pr_number": { "type": "integer" }
+            },
+            "required": ["action", "owner", "repo", "pr_number"]
+        },
+        {
+            "properties": {
+                "action": { "const": "create_pr_review" },
+                "owner": { "type": "string" },
+                "repo": { "type": "string" },
+                "pr_number": { "type": "integer" },
+                "body": { "type": "string", "description": "Review comment" },
+                "event": { "type": "string", "enum": ["APPROVE", "REQUEST_CHANGES", "COMMENT"] }
+            },
+            "required": ["action", "owner", "repo", "pr_number", "body", "event"]
+        },
+        {
+            "properties": {
+                "action": { "const": "list_repos" },
+                "username": { "type": "string" },
+                "limit": { "type": "integer", "default": 30 }
+            },
+            "required": ["action", "username"]
+        },
+        {
+            "properties": {
+                "action": { "const": "get_file_content" },
+                "owner": { "type": "string" },
+                "repo": { "type": "string" },
+                "path": { "type": "string", "description": "File path in repo" },
+                "ref": { "type": "string", "description": "Branch/commit (default: default branch)" }
+            },
+            "required": ["action", "owner", "repo", "path"]
+        },
+        {
+            "properties": {
+                "action": { "const": "trigger_workflow" },
+                "owner": { "type": "string" },
+                "repo": { "type": "string" },
+                "workflow_id": { "type": "string", "description": "Workflow filename or ID" },
+                "ref": { "type": "string", "description": "Branch to run on" },
+                "inputs": { "type": "object" }
+            },
+            "required": ["action", "owner", "repo", "workflow_id", "ref"]
+        },
+        {
+            "properties": {
+                "action": { "const": "get_workflow_runs" },
+                "owner": { "type": "string" },
+                "repo": { "type": "string" },
+                "workflow_id": { "type": "string" },
+                "limit": { "type": "integer", "default": 30 }
+            },
+            "required": ["action", "owner", "repo"]
+        }
+    ]
+}"#;
+
+export!(GitHubTool);
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_url_encode_path() {
+        assert_eq!(url_encode_path("foo-bar_123.baz"), "foo-bar_123.baz");
+        assert_eq!(url_encode_path("foo bar"), "foo%20bar");
+        assert_eq!(url_encode_path("foo/bar"), "foo%2Fbar");
+    }
+
+    #[test]
+    fn test_validate_path_segment() {
+        assert!(validate_path_segment("foo"));
+        assert!(!validate_path_segment(""));
+        assert!(!validate_path_segment("foo/bar"));
+        assert!(!validate_path_segment(".."));
+        // Empty segments are handled in get_file_content logic, not here
+    }
+
+    #[test]
+    fn test_validate_event_in_create_pr_review() {
+        let valid = ["APPROVE", "REQUEST_CHANGES", "COMMENT"];
+        // Ensure valid inputs are accepted
+        for event in valid {
+            assert!(valid.contains(&event));
+        }
+    }
+
+    #[test]
+    fn test_input_length_validation() {
+        assert!(validate_input_length("short", "test").is_ok());
+
+        let long = "a".repeat(MAX_TEXT_LENGTH + 1);
+        assert!(validate_input_length(&long, "test").is_err());
+    }
+}
@@ -136,7 +136,7 @@ fn parse_message(v: &serde_json::Value) -> Message {
        date: get_header(payload, "Date"),
        body: extract_body(payload),
        snippet: v["snippet"].as_str().unwrap_or("").to_string(),
-        is_unread: label_ids.contains(&"UNREAD".to_string()),
+        is_unread: label_ids.iter().any(|l| l == "UNREAD"),
        label_ids,
    }
 }
@@ -198,7 +198,7 @@ pub fn list_messages(
                    to: get_header(payload, "To"),
                    date: get_header(payload, "Date"),
                    snippet: msg["snippet"].as_str().unwrap_or("").to_string(),
-                    is_unread: label_ids.contains(&"UNREAD".to_string()),
+                    is_unread: label_ids.iter().any(|l| l == "UNREAD"),
                    label_ids,
                });
            }
@@ -6,7 +6,7 @@
 //! # Capabilities Required
 //!
 //! - HTTP: `www.googleapis.com/calendar/v3/*` (GET, POST, PUT, PATCH, DELETE)
-//! - Secrets: `google_calendar_token` (OAuth 2.0 token, injected automatically)
+//! - Secrets: `google_oauth_token` (OAuth 2.0 token, injected automatically)
 //!
 //! # Supported Actions
 //!
@@ -269,8 +269,13 @@ pub fn replace_text(

    let parsed = batch_update_raw(document_id, vec![request])?;

-    let occurrences = parsed["replies"][0]["replaceAllText"]["occurrencesChanged"]
-        .as_i64()
+    let first_reply = parsed["replies"].as_array().and_then(|arr| arr.first());
+    let occurrences = first_reply
+        .map(|r| {
+            r["replaceAllText"]["occurrencesChanged"]
+                .as_i64()
+                .unwrap_or(0)
+        })
        .unwrap_or(0);

    Ok(ReplaceResult {
@@ -330,7 +330,13 @@ pub fn add_sheet(spreadsheet_id: &str, title: &str) -> Result<AddSheetResult, St

    let parsed = batch_update(spreadsheet_id, requests)?;

-    let reply = &parsed["replies"][0]["addSheet"]["properties"];
+    let reply = parsed["replies"]
+        .as_array()
+        .and_then(|arr| arr.first())
+        .map(|r| &r["addSheet"]["properties"]);
+
+    let reply = reply.ok_or_else(|| "No reply from batch update".to_string())?;
+
    Ok(AddSheetResult {
        sheet: SheetInfo {
            sheet_id: reply["sheetId"].as_i64().unwrap_or(0),
Author	SHA1	Message	Date
github-actions[bot]GitHubgithub-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>	6895adbcc9	chore: release v0.2.0 (#60 ) Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>	2026-02-16 22:28:14 +00:00
Vlad Frolov	f1480f471b	ci: Explicitly enable cargo-dist caching for binary artifacts building	2026-02-16 21:34:49 +01:00
Vlad Frolov	9db949746f	ci: Skip building binary artifacts on every PR	2026-02-16 21:29:03 +01:00
Peniel Ben GitHub root Peni Illia Polosukhin firat.sertgoz	61a123a746	Add GitHub tool and Discord channel (#34 ) * Add GitHub tool for IronClaw - manage repos, issues, PRs, and workflows * Add Discord channel for IronClaw - slash commands and button interactions * Security fixes: URL encoding, secret validation, Discord button handler - Add URL encoding for all path segments and query parameters (P1) - Add path segment validation to prevent path traversal - Add secret_exists check for better error messages (P2) - Fix http_request signature to use 5 args (P2) - Fix Discord button handler to check member field (P2) - Fix typo in Discord slash command format (P2) - Add github.capabilities.json and discord.capabilities.json (Blocker) - Add Cargo.toml for Discord channel (Blocker) - Add limit caps (max 100) for all list operations (P3) - Remove debug logging * Apply Copilot review fixes Security & Code Quality: - Use secret_get instead of workspace_read for GitHub token - Remove manual Authorization header (host injects via capabilities) - Add validation for file paths (reject path traversal) - Add validation for workflow_id and git refs - Fix url_encode_query comment - Add release profile optimizations to Cargo.toml files - Fix package names to match conventions (github-tool, discord-channel) - Add metadata fields to Cargo.toml - Fix rate limits to be consistent (60/min, 3600/hr) - Fix Discord user_name to filter empty global_name - Fix Discord metadata serialization error handling - Update Discord README to clarify which secrets are used by host vs WASM - Better formatting for Discord command option values * applied all PR change requests and comments * cleaned up workspace * Adding validation for empty path segments and event enum in GitHub tool * addedvalidation for events and vaidation to reject empty file path in github tools and implemented safe UTF-8 trunacating * added codegen units and updated truncating logic also update capabilities.json as requested by copilot review * added codegen units and updated truncating logic also update capabilities.json as requested by copilot review * fixed message trucating and remove url_encode alias, also appled all requested changes from last PR comment --------- Co-authored-by: root <root@cafx> Co-authored-by: Peni <[email protected]> Co-authored-by: Illia Polosukhin <[email protected]> Co-authored-by: firat.sertgoz <[email protected]>	2026-02-16 15:58:13 +04:00
DevBroco GitHub BroccoliFin	0e981429ee	feat: mark Ollama + OpenAI-compatible as implemented (#102 ) Co-authored-by: BroccoliFin <[email protected]>	2026-02-16 03:38:06 +00:00
Illia PolosukhinandClaude Opus 4.6	1b38a64e15	docs: add module specification rules to CLAUDE.md Any agent working on a module with a README.md spec must read it first, keep code and spec in sync, and treat the spec as the tiebreaker when they disagree. Co-Authored-By: Claude Opus 4.6 <[email protected]>	2026-02-15 00:33:41 -08:00
Illia PolosukhinandClaude Opus 4.6	2e5f8b60d5	docs: add setup/onboarding specification (src/setup/README.md) Authoritative specification for the 7-step onboarding wizard. Documents the full flow, settings persistence (two-layer architecture), platform caveats (macOS keychain dialogs, URL passwords), secrets context, and a modification checklist for future contributors. Co-Authored-By: Claude Opus 4.6 <[email protected]>	2026-02-15 00:29:47 -08:00
Illia Polosukhin GitHub Claude Opus 4.6	f0a0642e7d	feat: multi-provider inference + libSQL onboarding selection (#92 ) * feat: add interactive database backend selection during onboarding Previously the onboarding wizard silently defaulted to PostgreSQL because libsql wasn't in the default feature set. Now both backends ship by default and the wizard presents a selection prompt when both are available. DATABASE_BACKEND env var still bypasses the prompt for headless/CI use. Co-Authored-By: Claude Opus 4.6 <[email protected]> * fix: resolve libSQL onboarding crash, keychain double-prompt, and setup audit findings Three bugs fixed: 1. libSQL onboarding crash ("Missing required setting 'database_url'"): DatabaseConfig::resolve() only checked DATABASE_BACKEND env var, falling back to Postgres default. Now reads settings.database_backend, plus settings.libsql_path and settings.libsql_url as fallbacks. 2. OS keychain prompts twice during startup: Config::from_env() and Config::from_db() both called get_master_key(). Now caches the key in SECRETS_MASTER_KEY env var after first read so from_db() skips keychain. 3. "Path not found: nearai.session" warning: from_db_map() tried to apply app-specific DB keys (nearai.session_token) to the Settings struct. Now skips keys that don't map to known Settings fields. Also fixed bootstrap migration key mismatch (nearai.session -> nearai.session_token). Setup module audit fixes (14 findings): - Replace unreachable!() with proper error in provider match - Extract setup_api_key_provider() to deduplicate setup_anthropic/setup_openai - Add SAFETY comments to all unsafe std::env::set_var blocks - Fix .unwrap() calls with proper error handling - Remove incorrect #[allow(dead_code)] on used TelegramUpdate::update_id - Log warnings instead of silently discarding HTTP errors in Telegram binding - Guard select_many against empty options, fix mask_api_key for non-ASCII - Update stale doc comment in mod.rs, rename misleading variable - Add 7 new tests (model fetcher fallbacks, channel discovery, secret gen) Co-Authored-By: Claude Opus 4.6 <[email protected]> * fix: address PR review feedback (set_var safety, parse warnings, db_map efficiency) 1. Replace unsafe set_var keychain caching with OnceLock<String> in SecretsConfig::resolve(). Eliminates the env var write from main.rs entirely, using a process-wide OnceLock cache instead. 2. Log tracing::warn when database_backend or llm_backend settings fail to parse, instead of silently falling back to defaults. 3. Remove O(KS) get() pre-check in from_db_map(). Instead, let set() run and match on "Path not found" errors to skip unknown keys, avoiding full Settings serialization per key. Co-Authored-By: Claude Opus 4.6 <[email protected]> fix: address critical/high audit findings across WASM sub-crates - Telegram: remove .unwrap() panic on workspace_read (owner_id check) - WhatsApp: use configured api_version instead of hardcoded v18.0 - WhatsApp: log config parse errors before falling back to defaults - Slack: log serialization errors in emit_message and json_response - Google Docs: safe array access for batch update replies - Google Sheets: safe array access for add_sheet replies - Google Calendar: fix doc comment secret name mismatch - Gmail: avoid unnecessary String allocation in UNREAD check Co-Authored-By: Claude Opus 4.6 <[email protected]> * fix: address second-round PR review feedback - Validate custom model ID is non-empty (loop until valid input) - Warn on unknown DATABASE_BACKEND env var before defaulting to Postgres - Force re-selection when llm_backend contains unknown provider value - Use ok_or_else for proper String error type in google-sheets Co-Authored-By: Claude Opus 4.6 <[email protected]> * fix: harden setup module error handling and secret safety - Introduce ChannelSetupError typed enum replacing raw String errors across all channel setup functions (setup_telegram, setup_http, setup_tunnel, setup_wasm_channel, validate_telegram_token) - Add From<ChannelSetupError> for SetupError to simplify call sites - Convert setup_telegram retry from recursion to loop (unbounded stack) - Stop printing HTTP webhook secret plaintext to terminal - Use secret_input() for Turso auth token (was visible input()) - Replace dirs::home_dir().unwrap_or_default() with proper error - Fix UTF-8 panic in model name truncation (byte-index to chars-based) - Log warning in secret_exists() instead of silently swallowing errors - Deduplicate generate_webhook_secret() to delegate to shared helper Co-Authored-By: Claude Opus 4.6 <[email protected]> * fix: replace unreachable!() with error return in setup wizard The provider match in step_inference_provider was guarded by is_known but used unreachable!() as the catch-all. If a new provider is added to the is_known check without a corresponding match arm, this would panic at runtime. Return a typed error instead. Co-Authored-By: Claude Opus 4.6 <[email protected]> * fix: remove unsafe set_var, use thread-safe overlay for injected secrets Address PR #92 review comments: - Replace all 5 unsafe `std::env::set_var()` calls with safe alternatives - Add INJECTED_VARS OnceLock<HashMap> overlay in config.rs, checked by optional_env() before falling back to std::env::var() - Cache wizard API key in SetupWizard.llm_api_key field instead of env - Pass explicit key param to fetch_anthropic_models/fetch_openai_models - Persist env-provided API keys to secrets store during onboarding Co-Authored-By: Claude Opus 4.6 <[email protected]> * fix: address remaining PR review comments (clippy, TODO, secrets backend ordering) - Fix empty line after doc comment (clippy: empty_line_after_doc_comments) - Collapse nested if in optional_env overlay check (clippy: collapsible_if) - Remove dangling TODO(#XX) placeholder issue ref in channels.rs - Fix init_secrets_context to respect selected database_backend when both postgres and libsql features are compiled, preventing wrong-backend secrets storage when DATABASE_URL is set but libsql was chosen Co-Authored-By: Claude Opus 4.6 <[email protected]> * fix: address latest PR review comments (SecretString, empty env, docs, embeddings) - Change wizard llm_api_key from String to SecretString to prevent accidental logging of API keys - Fix inject_llm_keys_from_secrets skipping when env var is set but empty, matching optional_env's treatment of empty as unset - Fix inverted doc comment on INJECTED_VARS (env checked first, overlay is the fallback, not the other way around) - Update stale "env vars" comments in main.rs to reflect overlay pattern - Fix step_embeddings not seeing cached OpenAI key from wizard session Co-Authored-By: Claude Opus 4.6 <[email protected]> * fix: OAuth callback listener binds IPv4 first to match redirect URLs The listener was binding to [::1] (IPv6) first, but NEAR AI and other OAuth flows redirect to http://127.0.0.1:9876/... (IPv4 explicit). On macOS and most systems, [::1] and 127.0.0.1 are separate addresses, so the browser's connection to 127.0.0.1 was refused when the listener was on [::1]. Reversed the bind order: try 127.0.0.1 first, fall back to [::1] if IPv4 is unavailable. Co-Authored-By: Claude Opus 4.6 <[email protected]> * fix: cache keychain key eagerly to avoid redundant macOS password dialogs Replace has_master_key() with get_master_key() in step_security() and immediately build SecretsCrypto from the result. This eliminates redundant keychain accesses later in init_secrets_context(), each of which triggers macOS system dialogs (keychain unlock + app authorization). Co-Authored-By: Claude Opus 4.6 <[email protected]> * fix: persist DATABASE_BACKEND to ~/.ironclaw/.env for libSQL startup The wizard saved database_backend only to the database, but Config::from_env() needs it BEFORE connecting to any database (to decide which backend to use). Without it, the backend defaults to Postgres and then fails with "Missing required setting database_url". Now save all database bootstrap vars (DATABASE_BACKEND, DATABASE_URL, LIBSQL_PATH, LIBSQL_URL) to ~/.ironclaw/.env via save_bootstrap_env(). Co-Authored-By: Claude Opus 4.6 <[email protected]> * fix: status command shows libSQL backend and skips keychain probe The status command only checked DATABASE_URL (postgres), showing "not configured" for libSQL users. Now detects the DATABASE_BACKEND env var and reports libSQL path and Turso sync status. Also remove the keychain probe from status. get_generic_password() triggers macOS unlock+authorization dialogs which is terrible UX for a read-only diagnostic command. Co-Authored-By: Claude Opus 4.6 <[email protected]> * style: fix rustfmt formatting in bootstrap test Co-Authored-By: Claude Opus 4.6 <[email protected]> --------- Co-authored-by: Claude Opus 4.6 <[email protected]>	2026-02-15 08:24:51 +00:00