kodo-bot 0.2.1 → 0.2.2

data/lib/kodo/secrets/store.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'fileutils'
+
+module Kodo
+  module Secrets
+    class Store
+      def initialize(passphrase:, secrets_dir: nil)
+        @secrets_dir = secrets_dir || Kodo.home_dir
+        @passphrase = passphrase
+        FileUtils.mkdir_p(@secrets_dir)
+        @secrets = load_secrets
+      end
+
+      def put(name, value, source: 'user', validated: false)
+        @secrets[name] = {
+          'value' => value,
+          'source' => source,
+          'validated' => validated,
+          'stored_at' => Time.now.iso8601
+        }
+        save_secrets
+        @secrets[name]
+      end
+
+      def get(name)
+        entry = @secrets[name]
+        entry&.fetch('value', nil)
+      end
+
+      def exists?(name)
+        @secrets.key?(name)
+      end
+
+      def delete(name)
+        removed = @secrets.delete(name)
+        save_secrets if removed
+        !removed.nil?
+      end
+
+      def names
+        @secrets.keys
+      end
+
+      private
+
+      def secrets_path
+        File.join(@secrets_dir, 'secrets.enc')
+      end
+
+      def load_secrets
+        path = secrets_path
+        return {} unless File.exist?(path)
+
+        raw = File.binread(path)
+
+        raw = Memory::Encryption.decrypt(raw, key: @passphrase) if Memory::Encryption.encrypted?(raw)
+
+        JSON.parse(raw)
+      rescue JSON::ParserError => e
+        Kodo.logger.warn("Corrupt secrets file #{path}: #{e.message}")
+        {}
+      end
+
+      def save_secrets
+        json = JSON.generate(@secrets)
+        File.binwrite(secrets_path, Memory::Encryption.encrypt(json, key: @passphrase))
+      end
+    end
+  end
+end

data/lib/kodo/tools/dismiss_reminder.rb

@@ -5,6 +5,10 @@ require "ruby_llm"
 module Kodo
   module Tools
     class DismissReminder < RubyLLM::Tool
+      extend PromptContributor
+
+      capability_name 'Reminders'
+
       description "Dismiss (cancel) an active reminder by its ID."
 
       param :id, desc: "The UUID of the reminder to dismiss"

data/lib/kodo/tools/fetch_url.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require 'ruby_llm'
+require 'net/http'
+require 'uri'
+require 'resolv'
+require 'ipaddr'
+
+module Kodo
+  module Tools
+    class FetchUrl < RubyLLM::Tool
+      extend PromptContributor
+
+      capability_name 'Web Search'
+
+      MAX_PER_TURN = 3
+      MAX_CONTENT_LENGTH = 50_000
+      MAX_REDIRECTS = 5
+      READ_TIMEOUT = 15
+      OPEN_TIMEOUT = 10
+      USER_AGENT = "Kodo/#{VERSION} (bot; +https://kodo.bot)".freeze
+
+      # RFC 1918, loopback, link-local
+      BLOCKED_RANGES = [
+        IPAddr.new('10.0.0.0/8'),
+        IPAddr.new('172.16.0.0/12'),
+        IPAddr.new('192.168.0.0/16'),
+        IPAddr.new('127.0.0.0/8'),
+        IPAddr.new('169.254.0.0/16'),
+        IPAddr.new('0.0.0.0/8'),
+        IPAddr.new('::1/128'),
+        IPAddr.new('fc00::/7'),
+        IPAddr.new('fe80::/10')
+      ].freeze
+
+      description 'Fetch and read the contents of a web page. Use this to read articles, ' \
+                  'documentation, or any publicly accessible URL the user provides.'
+
+      param :url, desc: 'The URL to fetch (http or https only)'
+
+      def initialize(audit:)
+        super()
+        @audit = audit
+        @turn_count = 0
+      end
+
+      def reset_turn_count!
+        @turn_count = 0
+      end
+
+      def execute(url:)
+        @turn_count += 1
+        if @turn_count > MAX_PER_TURN
+          return "Rate limit reached (max #{MAX_PER_TURN} fetches per message). Try again next message."
+        end
+
+        uri = validate_url(url)
+        return uri if uri.is_a?(String) # error message
+
+        content = fetch_with_redirects(uri)
+        return content if content.is_a?(String) && content.start_with?('Error:')
+
+        text = extract_text(content)
+        text = text[0...MAX_CONTENT_LENGTH] if text.length > MAX_CONTENT_LENGTH
+
+        @audit.log(
+          event: 'url_fetched',
+          detail: "url:#{url} len:#{text.length}"
+        )
+
+        text.empty? ? "No readable content found at #{url}" : text
+      rescue Kodo::Error => e
+        e.message
+      end
+
+      def name
+        'fetch_url'
+      end
+
+      private
+
+      def validate_url(url)
+        uri = URI.parse(url)
+        return 'Error: Only http and https URLs are supported.' unless %w[http https].include?(uri.scheme)
+
+        check_ssrf!(uri.host)
+        uri
+      rescue URI::InvalidURIError
+        'Error: Invalid URL format.'
+      rescue Kodo::Error => e
+        "Error: #{e.message}"
+      end
+
+      def check_ssrf!(hostname)
+        addresses = Resolv.getaddresses(hostname)
+
+        raise Kodo::Error, "Could not resolve hostname: #{hostname}" if addresses.empty?
+
+        addresses.each do |addr|
+          ip = IPAddr.new(addr)
+          if BLOCKED_RANGES.any? { |range| range.include?(ip) }
+            raise Kodo::Error, 'Access to private/internal network addresses is not allowed.'
+          end
+        end
+      end
+
+      def fetch_with_redirects(uri, redirects_remaining = MAX_REDIRECTS)
+        check_ssrf!(uri.host)
+
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == 'https'
+        http.read_timeout = READ_TIMEOUT
+        http.open_timeout = OPEN_TIMEOUT
+
+        request = Net::HTTP::Get.new(uri)
+        request['User-Agent'] = USER_AGENT
+
+        response = http.request(request)
+
+        if response.is_a?(Net::HTTPSuccess)
+          response.body || ''
+        elsif response.is_a?(Net::HTTPRedirection)
+          return 'Error: Too many redirects.' if redirects_remaining <= 0
+
+          location = response['location']
+          return 'Error: Redirect with no location header.' unless location
+
+          redirect_uri = URI.parse(location)
+          # Handle relative redirects
+          redirect_uri = uri + location unless redirect_uri.host
+
+          return 'Error: Redirect to non-HTTP scheme.' unless %w[http https].include?(redirect_uri.scheme)
+
+          fetch_with_redirects(redirect_uri, redirects_remaining - 1)
+        else
+          "Error: HTTP #{response.code} #{response.message}"
+        end
+      rescue Net::OpenTimeout, Net::ReadTimeout
+        'Error: Request timed out.'
+      rescue SocketError, Errno::ECONNREFUSED => e
+        "Error: Connection failed: #{e.message}"
+      rescue Kodo::Error => e
+        "Error: #{e.message}"
+      end
+
+      def extract_text(html)
+        return '' if html.nil? || html.empty?
+
+        text = html.dup
+
+        # Remove script and style blocks
+        text.gsub!(%r{<script[^>]*>.*?</script>}mi, '')
+        text.gsub!(%r{<style[^>]*>.*?</style>}mi, '')
+
+        # Remove HTML comments
+        text.gsub!(/<!--.*?-->/m, '')
+
+        # Convert block-level tags to newlines
+        text.gsub!(%r{<(?:br|p|div|h[1-6]|li|tr|blockquote|hr)[^>]*/?>}i, "\n")
+        text.gsub!(%r{</(?:p|div|h[1-6]|li|tr|blockquote|table|ul|ol)>}i, "\n")
+
+        # Strip remaining tags
+        text.gsub!(/<[^>]+>/, '')
+
+        # Decode common HTML entities
+        text.gsub!('&amp;', '&')
+        text.gsub!('&lt;', '<')
+        text.gsub!('&gt;', '>')
+        text.gsub!('&quot;', '"')
+        text.gsub!('&#39;', "'")
+        text.gsub!('&apos;', "'")
+        text.gsub!('&nbsp;', ' ')
+
+        # Normalize whitespace
+        text.gsub!(/[ \t]+/, ' ')
+        text.gsub!(/\n[ \t]+/, "\n")
+        text.gsub!(/[ \t]+\n/, "\n")
+        text.gsub!(/\n{3,}/, "\n\n")
+        text.strip!
+
+        text
+      end
+    end
+  end
+end

data/lib/kodo/tools/forget_fact.rb

@@ -5,6 +5,10 @@ require "ruby_llm"
 module Kodo
   module Tools
     class ForgetFact < RubyLLM::Tool
+      extend PromptContributor
+
+      capability_name 'Knowledge'
+
       description "Forget a previously remembered fact. Use this when the user asks you " \
                   "to forget something or when information is outdated."
 

data/lib/kodo/tools/list_reminders.rb

@@ -5,6 +5,10 @@ require "ruby_llm"
 module Kodo
   module Tools
     class ListReminders < RubyLLM::Tool
+      extend PromptContributor
+
+      capability_name 'Reminders'
+
       description "List all active reminders, sorted by due time."
 
       def initialize(reminders:, audit:)

data/lib/kodo/tools/prompt_contributor.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Kodo
+  module Tools
+    # Mixin for tool classes to declare prompt-level capability metadata.
+    # Tools `extend` this module and use getter/setter class methods to
+    # describe how they appear in the assembled system prompt.
+    #
+    #   class WebSearch < RubyLLM::Tool
+    #     extend PromptContributor
+    #     capability_name "Web Search"
+    #     capability_primary true
+    #     enabled_guidance "Search the web for current information."
+    #   end
+    #
+    module PromptContributor
+      def capability_name(name = :__unset__)
+        if name == :__unset__
+          @capability_name
+        else
+          @capability_name = name
+        end
+      end
+
+      def capability_primary(val = :__unset__)
+        if val == :__unset__
+          @capability_primary || false
+        else
+          @capability_primary = val
+        end
+      end
+
+      def enabled_guidance(text = :__unset__)
+        if text == :__unset__
+          @enabled_guidance
+        else
+          @enabled_guidance = text
+        end
+      end
+
+      def disabled_guidance(text = :__unset__)
+        if text == :__unset__
+          @disabled_guidance
+        else
+          @disabled_guidance = text
+        end
+      end
+    end
+  end
+end

data/lib/kodo/tools/recall_facts.rb

@@ -5,6 +5,10 @@ require "ruby_llm"
 module Kodo
   module Tools
     class RecallFacts < RubyLLM::Tool
+      extend PromptContributor
+
+      capability_name 'Knowledge'
+
       description "Search your knowledge store for facts about the user. " \
                   "Use this when you need to look up specific information, especially " \
                   "if the knowledge was truncated in your system prompt."

data/lib/kodo/tools/remember_fact.rb

@@ -5,6 +5,12 @@ require "ruby_llm"
 module Kodo
   module Tools
     class RememberFact < RubyLLM::Tool
+      extend PromptContributor
+
+      capability_name 'Knowledge'
+      capability_primary true
+      enabled_guidance 'Remember, recall, update, and forget facts about the user across sessions.'
+
       MAX_PER_TURN = 5
       MAX_CONTENT_LENGTH = 500
 

data/lib/kodo/tools/set_reminder.rb

@@ -6,6 +6,12 @@ require "time"
 module Kodo
   module Tools
     class SetReminder < RubyLLM::Tool
+      extend PromptContributor
+
+      capability_name 'Reminders'
+      capability_primary true
+      enabled_guidance 'Set, list, and dismiss reminders. Reminders are delivered proactively when due.'
+
       MAX_PER_TURN = 3
       MAX_CONTENT_LENGTH = 500
 

data/lib/kodo/tools/store_secret.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require 'ruby_llm'
+require 'net/http'
+require 'uri'
+require 'json'
+
+module Kodo
+  module Tools
+    class StoreSecret < RubyLLM::Tool
+      extend PromptContributor
+
+      capability_name 'Secret Storage'
+      capability_primary true
+      enabled_guidance 'Use store_secret to store and activate API keys securely — no restart required.'
+
+      MAX_PER_TURN = 2
+      VALIDATION_TIMEOUT = 5
+
+      KNOWN_SECRETS = {
+        'anthropic_api_key' => { description: 'Anthropic API key', prefix: 'sk-ant-' },
+        'openai_api_key' => { description: 'OpenAI API key', prefix: 'sk-' },
+        'gemini_api_key' => { description: 'Google Gemini API key' },
+        'deepseek_api_key' => { description: 'DeepSeek API key' },
+        'mistral_api_key' => { description: 'Mistral API key' },
+        'openrouter_api_key' => { description: 'OpenRouter API key', prefix: 'sk-or-' },
+        'perplexity_api_key' => { description: 'Perplexity API key' },
+        'xai_api_key' => { description: 'xAI API key' },
+        'tavily_api_key' => { description: 'Tavily API key', prefix: 'tvly-' },
+        'telegram_bot_token' => { description: 'Telegram bot token' }
+      }.freeze
+
+      description 'Securely store an API key or token. Use this when the user provides ' \
+                  'a key they want to configure. The key is encrypted at rest and ' \
+                  'activated immediately without requiring a restart.'
+
+      param :secret_name, desc: "The secret identifier. One of: #{KNOWN_SECRETS.keys.join(', ')}"
+      param :secret_value, desc: 'The secret value (API key or token)'
+
+      def initialize(broker:, audit:, on_secret_stored: nil)
+        super()
+        @broker = broker
+        @audit = audit
+        @on_secret_stored = on_secret_stored
+        @turn_count = 0
+      end
+
+      def reset_turn_count!
+        @turn_count = 0
+      end
+
+      def execute(secret_name:, secret_value:) # rubocop:disable Metrics/MethodLength
+        unless KNOWN_SECRETS.key?(secret_name)
+          return "Unknown secret '#{secret_name}'. Known secrets: #{KNOWN_SECRETS.keys.join(', ')}"
+        end
+
+        @turn_count += 1
+        if @turn_count > MAX_PER_TURN
+          return "Rate limit reached (max #{MAX_PER_TURN} secrets per message). Try again next message."
+        end
+
+        prefix_error = validate_prefix(secret_name, secret_value)
+        return prefix_error if prefix_error
+
+        validated = validate_key(secret_name, secret_value)
+
+        @broker.store(secret_name, secret_value, source: 'chat', validated: validated)
+
+        @audit.log(
+          event: 'secret_stored_via_tool',
+          detail: "secret:#{secret_name} validated:#{validated}"
+        )
+
+        @on_secret_stored&.call(secret_name)
+
+        desc = KNOWN_SECRETS[secret_name][:description]
+        if validated
+          "#{desc} stored and validated successfully. It's now active — no restart needed."
+        else
+          "#{desc} stored and activated. Couldn't verify it online, but it's ready to use."
+        end
+      rescue Kodo::Error => e
+        e.message
+      end
+
+      def name
+        'store_secret'
+      end
+
+      private
+
+      def validate_prefix(secret_name, value)
+        expected = KNOWN_SECRETS.dig(secret_name, :prefix)
+        return nil unless expected
+
+        return nil if value.start_with?(expected)
+
+        "Invalid #{KNOWN_SECRETS[secret_name][:description]}: expected to start with '#{expected}'"
+      end
+
+      def validate_key(secret_name, value)
+        case secret_name
+        when 'tavily_api_key' then validate_tavily(value)
+        when 'anthropic_api_key' then validate_anthropic(value)
+        else false
+        end
+      rescue StandardError
+        false
+      end
+
+      def validate_tavily(key)
+        uri = URI('https://api.tavily.com/search')
+        body = { api_key: key, query: 'test', max_results: 1 }.to_json
+        response = http_post(uri, body, 'application/json')
+        response.is_a?(Net::HTTPSuccess)
+      end
+
+      def validate_anthropic(key)
+        uri = URI('https://api.anthropic.com/v1/messages')
+        body = {
+          model: 'claude-haiku-4-5-20251001',
+          max_tokens: 1,
+          messages: [{ role: 'user', content: 'hi' }]
+        }.to_json
+        response = http_post(uri, body, 'application/json',
+                             'x-api-key' => key,
+                             'anthropic-version' => '2023-06-01')
+        response.is_a?(Net::HTTPSuccess)
+      end
+
+      def http_post(uri, body, content_type, extra_headers = {})
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = true
+        http.open_timeout = VALIDATION_TIMEOUT
+        http.read_timeout = VALIDATION_TIMEOUT
+
+        request = Net::HTTP::Post.new(uri)
+        request['Content-Type'] = content_type
+        extra_headers.each { |k, v| request[k] = v }
+        request.body = body
+
+        http.request(request)
+      end
+    end
+  end
+end

data/lib/kodo/tools/update_fact.rb

@@ -5,6 +5,10 @@ require "ruby_llm"
 module Kodo
   module Tools
     class UpdateFact < RubyLLM::Tool
+      extend PromptContributor
+
+      capability_name 'Knowledge'
+
       MAX_PER_TURN = 5
       MAX_CONTENT_LENGTH = 500
 

data/lib/kodo/tools/web_search.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require 'ruby_llm'
+
+module Kodo
+  module Tools
+    class WebSearch < RubyLLM::Tool
+      extend PromptContributor
+
+      capability_name 'Web Search'
+      capability_primary true
+      enabled_guidance 'Search the web for current information.'
+      disabled_guidance \
+        "Tavily is the easiest option (free tier, 1000 searches/month, no credit card).\n" \
+        "Get an API key from https://app.tavily.com/sign-in\n" \
+        "Set the environment variable: export TAVILY_API_KEY=\"tvly-...\"\n" \
+        "Add to ~/.kodo/config.yml: search: { provider: tavily }\n" \
+        "Then restart Kodo.\n\n" \
+        "IMPORTANT: If the user pastes an API key into chat, remind them that credentials " \
+        "should be set as environment variables, not shared in conversation. The key will " \
+        "be redacted from conversation history for security."
+
+      DISABLED_GUIDANCE_WITH_SECRET_STORAGE =
+        "Tavily is the easiest option (free tier, 1000 searches/month, no credit card).\n" \
+        "Get an API key from https://app.tavily.com/sign-in\n" \
+        "They can paste the key right here in chat and you will store it securely."
+
+      MAX_PER_TURN = 3
+
+      description 'Search the web for current information. Use this when the user asks about ' \
+                  "recent events, needs up-to-date facts, or wants information you don't have."
+
+      param :query, desc: 'The search query'
+      param :max_results, desc: 'Number of results to return (1-10, default 5)', required: false
+
+      def initialize(search_provider:, audit:)
+        super()
+        @search_provider = search_provider
+        @audit = audit
+        @turn_count = 0
+      end
+
+      def reset_turn_count!
+        @turn_count = 0
+      end
+
+      def execute(query:, max_results: '5')
+        max_results = max_results.to_i.clamp(1, 10)
+
+        @turn_count += 1
+        if @turn_count > MAX_PER_TURN
+          return "Rate limit reached (max #{MAX_PER_TURN} searches per message). Try again next message."
+        end
+
+        results = @search_provider.search(query, max_results: max_results)
+
+        @audit.log(
+          event: 'web_search',
+          detail: "query:#{query} results:#{results.length}"
+        )
+
+        return "No results found for: #{query}" if results.empty?
+
+        format_results(results)
+      rescue Kodo::Error => e
+        e.message
+      end
+
+      def name
+        'web_search'
+      end
+
+      private
+
+      def format_results(results)
+        results.each_with_index.map do |r, i|
+          "#{i + 1}. #{r.title}\n   #{r.url}\n   #{r.snippet}"
+        end.join("\n\n")
+      end
+    end
+  end
+end

data/lib/kodo/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Kodo
-  VERSION = "0.2.1"
+  VERSION = "0.2.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kodo-bot
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.2
 platform: ruby
 authors:
 - Freedom Dumlao
@@ -66,14 +66,24 @@ files:
 - lib/kodo/message.rb
 - lib/kodo/prompt_assembler.rb
 - lib/kodo/router.rb
+- lib/kodo/search/base.rb
+- lib/kodo/search/result.rb
+- lib/kodo/search/tavily.rb
+- lib/kodo/secrets/broker.rb
+- lib/kodo/secrets/grant.rb
+- lib/kodo/secrets/store.rb
 - lib/kodo/tools/dismiss_reminder.rb
+- lib/kodo/tools/fetch_url.rb
 - lib/kodo/tools/forget_fact.rb
 - lib/kodo/tools/get_current_time.rb
 - lib/kodo/tools/list_reminders.rb
+- lib/kodo/tools/prompt_contributor.rb
 - lib/kodo/tools/recall_facts.rb
 - lib/kodo/tools/remember_fact.rb
 - lib/kodo/tools/set_reminder.rb
+- lib/kodo/tools/store_secret.rb
 - lib/kodo/tools/update_fact.rb
+- lib/kodo/tools/web_search.rb
 - lib/kodo/version.rb
 homepage: https://kodo.bot
 licenses: