kward 0.79.0 → 0.80.1

data/examples/plugins/telegram/telegram_api.rb

@@ -0,0 +1,136 @@
+require "json"
+require "net/http"
+require "uri"
+
+module Kward
+  module Telegram
+    # Small dependency-free client for the Telegram Bot API.
+    class BotApi
+      API_BASE_URL = "https://api.telegram.org".freeze
+      MAX_RESPONSE_BYTES = 5 * 1024 * 1024
+
+      class Error < StandardError
+        attr_reader :method, :error_code, :parameters
+
+        def initialize(method, description, error_code: nil, parameters: nil)
+          @method = method
+          @error_code = error_code
+          @parameters = parameters
+          super("Telegram #{method} failed: #{description.to_s}")
+        end
+      end
+
+      class RateLimitError < Error
+        attr_reader :retry_after
+
+        def initialize(method, description, retry_after:, error_code: nil, parameters: nil)
+          @retry_after = Integer(retry_after)
+          super(method, description, error_code: error_code, parameters: parameters)
+        end
+      end
+
+      def initialize(token:, requester: nil, base_url: API_BASE_URL)
+        @token = token.to_s
+        raise ArgumentError, "Telegram bot token is required" if @token.empty?
+
+        @requester = requester || method(:request)
+        @base_url = base_url.to_s.sub(%r{/\z}, "")
+      end
+
+      def get_me
+        call("getMe")
+      end
+
+      def delete_webhook(drop_pending_updates: false)
+        call("deleteWebhook", "drop_pending_updates" => !!drop_pending_updates)
+      end
+
+      def get_updates(offset: nil, timeout: 25)
+        timeout = Integer(timeout)
+        raise ArgumentError, "Telegram polling timeout must be between 0 and 50 seconds" unless (0..50).cover?(timeout)
+
+        params = {
+          "timeout" => timeout,
+          "allowed_updates" => JSON.generate(%w[message callback_query])
+        }
+        params["offset"] = Integer(offset) unless offset.nil?
+        Array(call("getUpdates", params))
+      end
+
+      def answer_callback_query(callback_query_id:, text: nil, show_alert: false)
+        params = {
+          "callback_query_id" => callback_query_id.to_s,
+          "show_alert" => !!show_alert
+        }
+        params["text"] = text.to_s unless text.nil?
+        call("answerCallbackQuery", params)
+      end
+
+      def send_message(chat_id:, text:, reply_to_message_id: nil, reply_markup: nil)
+        text = text.to_s
+        raise ArgumentError, "Telegram message text is required" if text.empty?
+
+        params = { "chat_id" => Integer(chat_id), "text" => text }
+        unless reply_to_message_id.nil?
+          params["reply_parameters"] = JSON.generate({ "message_id" => Integer(reply_to_message_id) })
+        end
+        params["reply_markup"] = JSON.generate(reply_markup) unless reply_markup.nil?
+        call("sendMessage", params)
+      end
+
+      private
+
+      def call(method, params = {})
+        response = @requester.call(method, params)
+        unless response.is_a?(Hash) && response["ok"]
+          raise_error(method, response || {})
+        end
+
+        response["result"]
+      end
+
+      def raise_error(method, response)
+        description = (response["description"] || "unknown API error").to_s.gsub(@token, "[REDACTED]")
+        parameters = response["parameters"] || {}
+        if response["error_code"].to_i == 429 && parameters["retry_after"]
+          raise RateLimitError.new(
+            method,
+            description,
+            retry_after: parameters.fetch("retry_after"),
+            error_code: response["error_code"],
+            parameters: parameters
+          )
+        end
+
+        raise Error.new(
+          method,
+          description,
+          error_code: response["error_code"],
+          parameters: parameters
+        )
+      end
+
+      def request(method, params)
+        uri = URI.parse("#{@base_url}/bot#{@token}/#{method}")
+        request = Net::HTTP::Post.new(uri)
+        request.set_form_data(params.transform_values(&:to_s))
+
+        response = Net::HTTP.start(
+          uri.host,
+          uri.port,
+          use_ssl: uri.scheme == "https",
+          open_timeout: 5,
+          read_timeout: params.fetch("timeout", 10).to_i + 10
+        ) { |http| http.request(request) }
+        body = response.body.to_s
+        raise Error.new(method, "response was too large") if body.bytesize > MAX_RESPONSE_BYTES
+
+        JSON.parse(body)
+      rescue JSON::ParserError
+        raise Error.new(method, "response was not valid JSON")
+      rescue URI::InvalidURIError
+        raise Error.new(method, "invalid Telegram API URL")
+      end
+    end
+  end
+end

data/examples/plugins/telegram/telegram_transport.rb

@@ -0,0 +1,304 @@
+require "thread"
+require_relative "telegram_api"
+
+module Kward
+  module Telegram
+    # Long-polling Telegram adapter backed by normal Kward sessions.
+    class Transport
+      TELEGRAM_MESSAGE_LIMIT = 4096
+      DEFAULT_POLL_TIMEOUT = 25
+      MAX_RETRY_DELAY = 30
+
+      def initialize(host:, config:, api: nil, sleeper: nil)
+        @host = host
+        @config = config || {}
+        @token = host.secret("bot_token", env: "TELEGRAM_BOT_TOKEN")
+        @workspace = required_config("workspace")
+        @allowed_user_ids = required_ids("allowed_user_ids")
+        @allowed_chat_ids = required_ids("allowed_chat_ids")
+        @poll_timeout = Integer(@config.fetch("poll_timeout_seconds", DEFAULT_POLL_TIMEOUT))
+        raise ArgumentError, "poll_timeout_seconds must be between 0 and 50" unless (0..50).cover?(@poll_timeout)
+
+        @api = api || BotApi.new(token: @token)
+        @sleeper = sleeper || method(:sleep)
+        @state_mutex = Mutex.new
+        @stop = false
+        @thread = nil
+        @last_error = nil
+      end
+
+      def start
+        @api.delete_webhook
+        @api.get_me
+        @host.interactions.subscribe { |request| handle_interaction(request) }
+        @state_mutex.synchronize do
+          @stop = false
+          @last_error = nil
+          @thread = Thread.new { poll_loop }
+        end
+        nil
+      end
+
+      def stop
+        thread = @state_mutex.synchronize do
+          @stop = true
+          @thread
+        end
+        return nil unless thread
+
+        thread.join(@poll_timeout + 10)
+        thread.kill if thread.alive?
+        @state_mutex.synchronize { @thread = nil }
+        nil
+      end
+
+      def health
+        @state_mutex.synchronize do
+          {
+            state: @thread&.alive? ? "running" : "stopped",
+            error: @last_error
+          }
+        end
+      end
+
+      private
+
+      def poll_loop
+        offset = Integer(@host.storage.get("telegram:offset") || 0)
+        until stopping?
+          begin
+            updates = @api.get_updates(offset: offset, timeout: @poll_timeout)
+            updates.each do |update|
+              update_id = Integer(update.fetch("update_id"))
+              handle_update(update)
+              offset = [offset, update_id + 1].max
+              @host.storage.put("telegram:offset", offset)
+            end
+          rescue BotApi::RateLimitError => error
+            record_error(error)
+            wait_for([error.retry_after, MAX_RETRY_DELAY].min)
+          rescue StandardError => error
+            record_error(error)
+            wait_for(2)
+          end
+        end
+      end
+
+      def handle_update(update)
+        if update["callback_query"]
+          handle_callback(update.fetch("callback_query"))
+        elsif update["message"]
+          handle_message(update.fetch("message"), update.fetch("update_id"))
+        end
+      rescue StandardError => error
+        record_error(error)
+      end
+
+      def handle_message(message, update_id)
+        text = message["text"].to_s
+        return if text.empty?
+
+        user_id = Integer(message.fetch("from").fetch("id"))
+        chat_id = Integer(message.fetch("chat").fetch("id"))
+        return unless allowed?(user_id, chat_id)
+        return unless @host.storage.claim("telegram:update:#{update_id}")
+
+        conversation = Kward::Transport.conversation_key(
+          transport_id: @host.transport_id,
+          external_id: "chat:#{chat_id}"
+        )
+        actor = Kward::Transport.actor(
+          id: "telegram:user:#{user_id}",
+          display_name: message.dig("from", "username") || user_id.to_s,
+          metadata: { provider: "telegram", user_id: user_id, chat_id: chat_id }
+        )
+        @host.authorize!(:telegram_message, actor: actor, conversation: conversation)
+
+        session = @host.sessions.resolve(
+          conversation: conversation,
+          actor: actor,
+          workspace_root: @workspace,
+          name: "Telegram chat #{chat_id}"
+        )
+        remember_session(session, conversation, chat_id, actor)
+
+        turn = session.start_turn(text)
+        @host.storage.put("telegram:turn:#{turn.id}", {
+          "chat_id" => chat_id,
+          "session_id" => session.id,
+          "reply_to_message_id" => message["message_id"]
+        })
+        turn.subscribe { |event| handle_turn_event(event) }
+      end
+
+      def handle_turn_event(event)
+        return unless %w[answer assistantMessage assistant_message].include?(event.type.to_s)
+
+        turn = @host.storage.get("telegram:turn:#{event.turn_id}")
+        return unless turn
+        return if @host.storage.get("telegram:delivered:#{event.turn_id}")
+
+        content = event.payload[:content] || event.payload["content"]
+        if content.to_s.empty? && %w[assistantMessage assistant_message].include?(event.type.to_s)
+          message = event.payload[:message] || event.payload["message"]
+          content = message[:content] || message["content"] if message.is_a?(Hash)
+        end
+        return if content.to_s.empty?
+
+        split_message(content.to_s).each do |part|
+          @api.send_message(
+            chat_id: turn.fetch("chat_id"),
+            text: part,
+            reply_to_message_id: turn["reply_to_message_id"]
+          )
+        end
+        @host.storage.put("telegram:delivered:#{event.turn_id}", true)
+      rescue StandardError => error
+        record_error(error)
+      end
+
+      def handle_interaction(request)
+        session = @host.storage.get("telegram:session:#{request.session_id}")
+        return unless session
+
+        record = {
+          "chat_id" => session.fetch("chat_id"),
+          "session_id" => request.session_id,
+          "external_id" => session.fetch("external_id"),
+          "actor_id" => session.fetch("actor_id"),
+          "actor_name" => session["actor_name"],
+          "kind" => request.kind.to_s
+        }
+        buttons = case request.kind.to_s
+                  when "tool_approval"
+                    record["answers"] = { "approve" => true, "deny" => false }
+                    [[
+                      { "text" => "Approve", "callback_data" => callback_data(request.id, "approve") },
+                      { "text" => "Deny", "callback_data" => callback_data(request.id, "deny") }
+                    ]]
+                  when "question"
+                    question, options = question_options(request)
+                    return if options.empty?
+
+                    record["question"] = question
+                    record["answers"] = options.each_with_index.to_h { |option, index| [index.to_s, option] }
+                    [options.each_with_index.map do |option, index|
+                      { "text" => option, "callback_data" => callback_data(request.id, index.to_s) }
+                    end]
+                  else
+                    return
+                  end
+
+        @host.storage.put("telegram:interaction:#{request.id}", record)
+        @api.send_message(
+          chat_id: record.fetch("chat_id"),
+          text: request.prompt,
+          reply_markup: { "inline_keyboard" => buttons }
+        )
+      rescue StandardError => error
+        record_error(error)
+      end
+
+      def handle_callback(callback)
+        data = callback["data"].to_s
+        match = /\Akward:([^:]+):([^:]+)\z/.match(data)
+        return unless match
+
+        request_id, choice = match.captures
+        chat_id = Integer(callback.fetch("message").fetch("chat").fetch("id"))
+        user_id = Integer(callback.fetch("from").fetch("id"))
+        return unless allowed?(user_id, chat_id)
+
+        record = @host.storage.get("telegram:interaction:#{request_id}")
+        return unless record && record.fetch("chat_id") == chat_id
+        return unless record.fetch("actor_id") == "telegram:user:#{user_id}"
+        return if @host.storage.get("telegram:answered:#{request_id}")
+
+        conversation = Kward::Transport.conversation_key(
+          transport_id: @host.transport_id,
+          external_id: record.fetch("external_id")
+        )
+        actor = Kward::Transport.actor(
+          id: record.fetch("actor_id"),
+          display_name: record["actor_name"],
+          metadata: { provider: "telegram", user_id: user_id, chat_id: chat_id }
+        )
+        session = @host.sessions.resolve(
+          conversation: conversation,
+          actor: actor,
+          workspace_root: @workspace
+        )
+        answer = record.fetch("answers").fetch(choice)
+        answer = [{ question: record.fetch("question"), answer: answer }] if record.fetch("kind") == "question"
+        session.answer_interaction(request_id: request_id, answer: answer)
+        @host.storage.put("telegram:answered:#{request_id}", true)
+        @api.answer_callback_query(callback_query_id: callback.fetch("id"))
+      rescue StandardError => error
+        record_error(error)
+      end
+
+      def remember_session(session, conversation, chat_id, actor)
+        @host.storage.put("telegram:session:#{session.id}", {
+          "chat_id" => chat_id,
+          "external_id" => conversation.external_id,
+          "actor_id" => actor.id,
+          "actor_name" => actor.display_name
+        })
+      end
+
+      def question_options(request)
+        question = request.choices.first || {}
+        options = Array(question[:options] || question["options"]).map do |option|
+          (option[:label] || option["label"]).to_s
+        end.reject(&:empty?)
+        [question[:question] || question["question"] || request.prompt, options]
+      end
+
+      def callback_data(request_id, choice)
+        "kward:#{request_id}:#{choice}"
+      end
+
+      def split_message(text)
+        text.each_char.each_slice(TELEGRAM_MESSAGE_LIMIT).map(&:join)
+      end
+
+      def allowed?(user_id, chat_id)
+        @allowed_user_ids.include?(user_id) && @allowed_chat_ids.include?(chat_id)
+      end
+
+      def stopping?
+        @state_mutex.synchronize { @stop }
+      end
+
+      def wait_for(seconds)
+        @sleeper.call(seconds) unless stopping?
+      end
+
+      def record_error(error)
+        message = error.message.to_s.gsub(@token.to_s, "[REDACTED]")
+        summary = "#{error.class}: #{message}"
+        @state_mutex.synchronize { @last_error = summary }
+        @host.logger.error("Telegram transport error: #{summary}")
+      rescue StandardError
+        nil
+      end
+
+      def required_config(key)
+        value = @config[key] || @config[key.to_sym]
+        raise ArgumentError, "Telegram transport requires #{key}" if value.to_s.empty?
+
+        value.to_s
+      end
+
+      def required_ids(key)
+        values = @config[key] || @config[key.to_sym]
+        values = Array(values).map { |value| Integer(value) }
+        raise ArgumentError, "Telegram transport requires non-empty #{key}" if values.empty?
+
+        values.uniq.freeze
+      rescue ArgumentError, TypeError
+        raise ArgumentError, "Telegram transport #{key} must contain numeric IDs"
+      end
+    end
+  end
+end

data/lib/kward/agent.rb

@@ -28,11 +28,12 @@ module Kward
   # lowest layer that owns the behavior, and use `Agent` only for cross-step turn
   # coordination.
   class Agent
-    def initialize(client:, tool_registry: ToolRegistry.new, conversation: Conversation.new, telemetry_logger: TelemetryLogger.new, hook_manager: nil, hook_context: nil)
+    def initialize(client:, tool_registry: ToolRegistry.new, conversation: Conversation.new, telemetry_logger: nil, warning_sink: nil, hook_manager: nil, hook_context: nil)
       @client = client
       @tool_registry = tool_registry
       @conversation = conversation
-      @telemetry_logger = telemetry_logger
+      @warning_sink = warning_sink
+      @telemetry_logger = telemetry_logger || TelemetryLogger.new(warning_sink: warning_sink)
       @hook_manager = hook_manager
       @hook_context = hook_context
     end
@@ -191,9 +192,9 @@ module Kward
 
     def auto_compact_if_needed
       context_window = @client.current_context_window if @client.respond_to?(:current_context_window)
-      Compactor.new(conversation: @conversation, client: @client).auto_compact_if_needed(context_window: context_window)
+      Compactor.new(conversation: @conversation, client: @client, warning_sink: @warning_sink).auto_compact_if_needed(context_window: context_window)
     rescue StandardError => e
-      warn "Auto-compaction failed: #{e.message}"
+      emit_warning "Auto-compaction failed: #{e.message}"
       nil
     end
 
@@ -201,14 +202,18 @@ module Kward
       settings = Compaction::Settings.from_config
       return nil unless settings.enabled
 
-      Compactor.new(conversation: @conversation, client: @client, settings: settings).compact(
+      Compactor.new(conversation: @conversation, client: @client, settings: settings, warning_sink: @warning_sink).compact(
         custom_instructions: "The previous model request exceeded the context window. Preserve the current task state and critical details needed to retry."
       )
     rescue Compaction::NothingToCompact, Compaction::AlreadyCompacted, StandardError => compaction_error
-      warn "Context overflow recovery failed: #{compaction_error.message}; original error: #{error.message}"
+      emit_warning "Context overflow recovery failed: #{compaction_error.message}; original error: #{error.message}"
       nil
     end
 
+    def emit_warning(message)
+      @warning_sink ? @warning_sink.call(message) : warn(message)
+    end
+
     def chat(on_reasoning_delta: nil, on_retry: nil, cancellation: nil, steering: nil, options: {}, tool_registry: nil)
       reasoning_delta = lambda do |delta|
         cancellation&.raise_if_cancelled!

data/lib/kward/ansi.rb

@@ -22,6 +22,7 @@ module Kward
       cyan: 36,
       gray: 90,
       grey: 90,
+      white: 97,
       primary_green: "38;2;138;160;106",
       bright_accent_green: "38;2;155;255;0",
       augen: "38;2;155;255;0",

data/lib/kward/auth/api_key_store.rb

@@ -0,0 +1,99 @@
+require "json"
+require_relative "../config_files"
+require_relative "../private_file"
+require_relative "../model/provider_catalog"
+
+# Namespace for Kward credential storage.
+module Kward
+  # Stores API keys outside the non-secret Kward configuration file.
+  class APIKeyStore
+    def initialize(path: APIKeyStore.default_path, config_path: ConfigFiles.config_path, env: ENV)
+      @path = File.expand_path(path)
+      @config_path = File.expand_path(config_path)
+      @env = env
+    end
+
+    attr_reader :path
+
+    def self.default_path
+      File.join(ConfigFiles.config_dir, "api_keys.json")
+    end
+
+    def fetch(provider_id)
+      provider = ProviderCatalog.fetch(provider_id)
+      environment_key(provider) || stored_key(provider.id)
+    end
+
+    def configured?(provider_id)
+      !fetch(provider_id).to_s.empty?
+    end
+
+    def store(provider_id, api_key)
+      provider = ProviderCatalog.fetch(provider_id)
+      raise ArgumentError, "#{provider.name} does not accept an API key" unless provider.api_key?
+
+      api_key = api_key.to_s.strip
+      raise ArgumentError, "API key must be a non-empty string" if api_key.empty?
+
+      keys = stored_keys
+      keys[provider.id] = api_key
+      write_keys(keys)
+      path
+    end
+
+    def delete(provider_id)
+      provider = ProviderCatalog.fetch(provider_id)
+      keys = stored_keys
+      return false unless keys.delete(provider.id)
+
+      write_keys(keys)
+      true
+    end
+
+    def stored?(provider_id)
+      !stored_key(provider_id).to_s.empty?
+    end
+
+    def stored_value(provider_id)
+      ProviderCatalog.fetch(provider_id)
+      stored_key(provider_id)
+    end
+
+    def migrate_openrouter_config_key!
+      return false if stored?("openrouter")
+
+      config = ConfigFiles.read_config(@config_path)
+      key = config["openrouter_api_key"].to_s.strip
+      return false if key.empty?
+
+      store("openrouter", key)
+      ConfigFiles.delete_config_key("openrouter_api_key", @config_path)
+      true
+    end
+
+    private
+
+    def environment_key(provider)
+      provider.api_key_env.map { |name| @env[name].to_s.strip }.find { |key| !key.empty? }
+    end
+
+    def stored_key(provider_id)
+      stored_keys[provider_id.to_s]
+    end
+
+    def stored_keys
+      return {} unless File.exist?(path)
+
+      data = JSON.parse(File.read(path))
+      raise "Invalid Kward API key file: #{path}" unless data.is_a?(Hash)
+
+      data.transform_keys(&:to_s).transform_values(&:to_s)
+    rescue JSON::ParserError => e
+      raise "Invalid Kward API key file: #{path}: #{e.message}"
+    end
+
+    def write_keys(keys)
+      PrivateFile.write_json(path, keys)
+    end
+  end
+end