ask-app-server 0.1.0

data/lib/ask/app_server/config.rb

@@ -0,0 +1,258 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ask
+  module AppServer
+    # Configuration loader for ask-app-server.
+    #
+    # Reads from a JSON config file, then merges environment variable overrides.
+    # Config file search order (first found wins):
+    #   1. ASK_APP_SERVER_CONFIG env var (explicit path)
+    #   2. ./.ask-app-server.json (project-local)
+    #   3. ~/.ask-app-server/config.json (user-global)
+    #
+    # Environment variable overrides:
+    #   ASK_APP_SERVER_MODEL       — model identifier (e.g., "opencode_go/deepseek-v4-flash")
+    #   ASK_APP_SERVER_PERMISSIONS — permission mode (on_request, never)
+    #   DEBUG                      — debug logging
+    #
+    # Example config file (~/.ask-app-server/config.json):
+    #   {
+    #     "model": "opencode_go/deepseek-v4-flash",
+    #     "tools": ["bash", "read", "write", "edit", "glob", "grep"],
+    #     "permissions": {
+    #       "mode": "on_request",
+    #       "blocked_tools": ["write", "edit", "bash", "destroy"],
+    #       "timeout": 300
+    #     },
+    #     "system_prompt": "You are a helpful AI coding assistant.",
+    #     "session": { "timeout": 600 },
+    #     "custom_models": {
+    #       "deepseek-v4-flash": {
+    #         "provider": "opencode_go",
+    #         "context": 1000000,
+    #         "output": 384000
+    #       }
+    #     }
+    #   }
+    class Config
+      DEFAULTS = {
+        model: "opencode_go/deepseek-v4-flash",
+        tools: %w[bash read write edit glob grep].freeze,
+        permissions: {
+          mode: :on_request,
+          blocked_tools: %w[write edit bash destroy].freeze,
+          timeout: 300
+        }.freeze,
+        system_prompt: nil,
+        session: {
+          timeout: 600
+        }.freeze,
+        custom_models: {}.freeze
+      }.freeze
+
+      CONFIG_FILE_PATHS = [
+        -> { ENV["ASK_APP_SERVER_CONFIG"] },
+        -> { File.expand_path(".ask-app-server.json") },
+        -> { File.expand_path("~/.ask-app-server/config.json") }
+      ].freeze
+
+      attr_reader :source_path
+
+      def initialize(config_path: nil)
+        @source_path = nil
+        @data = load_config(config_path)
+        @registered = false
+      end
+
+      # Resolved model identifier (may include provider prefix).
+      def model
+        ENV.fetch("ASK_APP_SERVER_MODEL", @data[:model])
+      end
+
+      # Parse model into [provider, model_id].
+      # Supports "provider/model" format and bare model names.
+      def parsed_model
+        raw = model
+        if raw.include?("/")
+          parts = raw.split("/", 2)
+          [parts[0], parts[1]]
+        else
+          [nil, raw]
+        end
+      end
+
+      # The model ID (without provider prefix).
+      def model_id
+        parsed_model[1]
+      end
+
+      # The provider slug (nil if not specified).
+      def model_provider
+        parsed_model[0]
+      end
+
+      # List of tool names to load.
+      def tools
+        @data[:tools] || DEFAULTS[:tools]
+      end
+
+      # Permission mode symbol (:on_request, :never).
+      def permission_mode
+        env_mode = ENV["ASK_APP_SERVER_PERMISSIONS"]
+        return env_mode.to_sym if env_mode
+
+        raw = @data.dig(:permissions, :mode)
+        raw ? raw.to_sym : DEFAULTS.dig(:permissions, :mode)
+      end
+
+      # List of tool names that require permission.
+      def blocked_tools
+        @data.dig(:permissions, :blocked_tools)&.map(&:to_s) || DEFAULTS.dig(:permissions, :blocked_tools)
+      end
+
+      # Permission request timeout in seconds.
+      def permission_timeout
+        @data.dig(:permissions, :timeout) || DEFAULTS.dig(:permissions, :timeout)
+      end
+
+      # System prompt for the agent.
+      def system_prompt
+        @data[:system_prompt]
+      end
+
+      # Session timeout in seconds.
+      def session_timeout
+        @data.dig(:session, :timeout) || DEFAULTS.dig(:session, :timeout)
+      end
+
+      # State persistence configuration.
+      # Returns nil if no state config is set (use in-memory defaults).
+      def state_config
+        @data[:state]
+      end
+
+      # Path for SQLite state database (if configured).
+      def state_sqlite_path
+        cfg = state_config
+        return nil unless cfg
+
+        cfg[:sqlite_path] || cfg["sqlite_path"] || cfg[:path] || cfg["path"]
+      end
+
+      # Whether debug logging is enabled.
+      def debug?
+        ENV["DEBUG"] == "1"
+      end
+
+      # Custom model definitions from config.
+      def custom_models
+        @data[:custom_models] || {}
+      end
+
+      # Register custom models into Ask::ModelCatalog so ask-agent can find them.
+      # Safe to call multiple times — models are registered only once.
+      def register_models!
+        return if @registered
+        @registered = true
+
+        custom_models.each do |model_id, cfg|
+          provider = cfg[:provider] || cfg["provider"]
+          context = cfg[:context] || cfg["context"] || 4096
+          output = cfg[:output] || cfg["output"] || 4096
+
+          # Build a ModelInfo-compatible struct and register it
+          model_info = OpenStruct.new(
+            id: model_id.to_s,
+            provider: provider.to_s,
+            chat?: true,
+            context: context,
+            output: output
+          )
+
+          # Use the singleton's register if available
+          if Ask::ModelCatalog.respond_to?(:instance)
+            catalog = Ask::ModelCatalog.instance
+            catalog.register(model_info) if catalog.respond_to?(:register)
+          end
+
+          if debug?
+            warn "[ask-app-server] Registered custom model: #{provider}/#{model_id} (#{context}ctx)"
+          end
+        end
+      end
+
+      # All config as a hash (for display).
+      def to_h
+        prov, mod = parsed_model
+        {
+          model: mod,
+          provider: prov,
+          tools: tools,
+          permissions: {
+            mode: permission_mode,
+            blocked_tools: blocked_tools,
+            timeout: permission_timeout
+          },
+          system_prompt: system_prompt,
+          session: { timeout: session_timeout },
+          custom_models: custom_models.keys,
+          source: source_path || "(defaults)"
+        }
+      end
+
+      private
+
+      def load_config(config_path)
+        path = config_path || find_config_file
+        return deep_copy(DEFAULTS) unless path && File.exist?(path)
+
+        @source_path = File.expand_path(path)
+        raw = JSON.parse(File.read(@source_path))
+
+        merged = deep_merge(deep_copy(DEFAULTS), normalize_keys(raw))
+        merged
+      rescue JSON::ParserError => e
+        warn "[ask-app-server] Warning: Invalid config file #{path}: #{e.message}"
+        deep_copy(DEFAULTS)
+      end
+
+      def find_config_file
+        CONFIG_FILE_PATHS.each do |resolver|
+          path = resolver.call
+          return path if path && File.exist?(path)
+        end
+        nil
+      end
+
+      def deep_merge(a, b)
+        a.merge(b) do |_key, old_val, new_val|
+          if old_val.is_a?(Hash) && new_val.is_a?(Hash)
+            deep_merge(old_val, new_val)
+          elsif old_val.is_a?(Array) && new_val.is_a?(Array)
+            new_val
+          else
+            new_val
+          end
+        end
+      end
+
+      def deep_copy(obj)
+        case obj
+        when Hash then obj.each_with_object({}) { |(k, v), h| h[k] = deep_copy(v) }
+        when Array then obj.map { |v| deep_copy(v) }
+        else obj
+        end
+      end
+
+      def normalize_keys(obj)
+        case obj
+        when Hash then obj.each_with_object({}) { |(k, v), h| h[k.to_sym] = normalize_keys(v) }
+        when Array then obj.map { |v| normalize_keys(v) }
+        else obj
+        end
+      end
+    end
+  end
+end

data/lib/ask/app_server/event_translator.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Ask
+  module AppServer
+    # Translates ask-agent Events into app-server protocol events.
+    #
+    # ask-agent emits events like TurnStart, TextDelta, ToolExecutionStart, etc.
+    # The app-server protocol uses a different set: turn.started, model.streaming,
+    # tool.updated, turn.completed, turn.failed, message.upserted.
+    #
+    # This class maps between the two models, emitting app-server protocol events
+    # that clients such as the Python Telegram bot and Vercel AI SDK expect.
+    class EventTranslator
+      attr_reader :session_id, :turn_id
+
+      def initialize(session_id)
+        @session_id = session_id
+        @turn_id = nil
+        @seq = 0
+        @events = []
+        @streaming_text = +""
+        @turn_active = false
+        @in_reflection = false
+      end
+
+      # Translate an ask-agent event into zero or more app-server events.
+      # Returns an array of event hashes (may be empty).
+      def translate(agent_event)
+        case agent_event
+        when Ask::Agent::Events::TurnStart
+          translate_turn_start
+        when Ask::Agent::Events::TextDelta
+          translate_text_delta(agent_event)
+        when Ask::Agent::Events::ToolCallDelta
+          # ToolCallDelta is informational; we track calls but don't emit
+          # until execution actually starts.
+          []
+        when Ask::Agent::Events::ToolExecutionStart
+          translate_tool_start(agent_event)
+        when Ask::Agent::Events::ToolExecutionUpdate
+          translate_tool_update(agent_event)
+        when Ask::Agent::Events::ToolExecutionEnd
+          translate_tool_end(agent_event)
+        when Ask::Agent::Events::MessageEnd
+          # Fires after the LLM response is complete (before tool execution).
+          # Not mapped directly; we already streamed the text.
+          []
+        when Ask::Agent::Events::TurnEnd
+          # Fires after tool execution completes for one recursive iteration.
+          # The session may continue with more tool calls.
+          []
+        when Ask::Agent::Events::ReflectionStart
+          # Reflection is an internal detail — skip
+          @in_reflection = true
+          []
+        when Ask::Agent::Events::ReflectionDelta
+          # Treat reflection text as regular model output
+          translate_text_delta(agent_event)
+        when Ask::Agent::Events::ReflectionEnd
+          @in_reflection = false
+          []
+        when Ask::Agent::Events::CompactionStart
+          []
+        when Ask::Agent::Events::CompactionEnd
+          []
+        when Ask::Agent::Events::Error
+          translate_error(agent_event)
+        when Ask::Agent::Events::SessionEnd
+          translate_session_end(agent_event)
+        when Ask::Agent::Events::MaxTurnsExceeded
+          translate_turn_failed("Max turns exceeded (#{agent_event.max_turns})")
+        when Ask::Agent::Events::LoopDetected
+          translate_turn_failed("Loop detected on tool: #{agent_event.tool_name}")
+        else
+          []
+        end
+      end
+
+      # All events emitted since last poll.
+      def pending_events
+        @events
+      end
+
+      # Drain and return all pending events, clearing the buffer.
+      def drain_events
+        evs = @events.dup
+        @events.clear
+        evs
+      end
+
+      # The last sequence number we emitted.
+      def last_seq
+        @seq
+      end
+
+      private
+
+      def next_seq
+        @seq += 1
+        @seq
+      end
+
+      def translate_turn_start
+        @turn_id = SecureRandom.uuid
+        @turn_active = true
+        @streaming_text = +""
+
+        ev = build_event("turn.started", { turnId: @turn_id })
+        [ev]
+      end
+
+      def translate_text_delta(event)
+        content = event.content.to_s
+        return [] if content.empty?
+
+        @streaming_text << content
+
+        ev = build_event("model.streaming", { delta: content })
+        [ev]
+      end
+
+      def translate_tool_start(event)
+        ev = build_event("tool.updated", {
+          toolName: event.name,
+          kind: "started",
+          input: event.arguments
+        })
+        [ev]
+      end
+
+      def translate_tool_update(event)
+        ev = build_event("tool.updated", {
+          toolName: event.name,
+          kind: "updated",
+          output: event.partial_result.to_s
+        })
+        [ev]
+      end
+
+      def translate_tool_end(event)
+        kind = event.is_error ? "failed" : "completed"
+        ev = build_event("tool.updated", {
+          toolName: event.name,
+          kind: kind,
+          output: event.result.to_s,
+          durationMs: event.duration_ms
+        })
+        [ev]
+      end
+
+      def translate_session_end(event)
+        @turn_active = false
+        response_text = event.result.to_s
+
+        ev = build_event("turn.completed", {
+          response: response_text,
+          turnCount: event.turn_count,
+          toolCallsMade: event.tool_calls_made,
+          inputTokens: event.input_tokens,
+          outputTokens: event.output_tokens,
+          cost: event.cost
+        })
+        [ev]
+      end
+
+      def translate_error(event)
+        return [] if @turn_active
+        translate_turn_failed(event.error)
+      end
+
+      def translate_turn_failed(message)
+        @turn_active = false
+        ev = build_event("turn.failed", {
+          error: { message: message.to_s }
+        })
+        [ev]
+      end
+
+      def build_event(type, payload)
+        event = {
+          type: type,
+          seq: next_seq,
+          payload: payload,
+          turnId: @turn_id,
+          sessionId: @session_id
+        }
+        @events << event
+        event
+      end
+    end
+  end
+end

data/lib/ask/app_server/permission_handler.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Ask
+  module AppServer
+    # Protocol-aware permission handler that integrates with ask-agent's
+    # before_tool_call hook system.
+    #
+    # When a blocked tool is called, this handler:
+    #   1. Sends an `interaction/requestPermission` protocol message to the client
+    #   2. Blocks the tool thread until the client responds (or timeout)
+    #   3. Returns { action: :proceed } if approved, { action: :block } if denied
+    #
+    # Usage:
+    #   handler = PermissionHandler.new(mode: :on_request)
+    #   handler.on_request { |req_id, tool_name, args| send_protocol_message(...) }
+    #
+    #   # Wire into ask-agent session
+    #   session = Ask::Agent::Session.new(hooks: { before_tool: [handler] })
+    #
+    #   # When the client responds:
+    #   handler.handle_response(request_id, "approve")
+    class PermissionHandler
+      # Default tools that require permission.
+      DEFAULT_BLOCKED_TOOLS = %i[write edit bash destroy].freeze
+
+      # Default timeout in seconds.
+      DEFAULT_TIMEOUT = 300
+
+      attr_reader :mode
+
+      # @param mode [Symbol] :on_request (ask for dangerous tools) or :never (allow all)
+      # @param blocked_tools [Array<Symbol>] list of tool names that require permission
+      # @param timeout [Integer] seconds to wait for client response
+      def initialize(mode: :on_request, blocked_tools: nil, timeout: DEFAULT_TIMEOUT)
+        @mode = mode
+        @blocked_tools = (blocked_tools || DEFAULT_BLOCKED_TOOLS).map(&:to_sym)
+        @timeout = timeout
+        @pending = {}
+        @sender = nil
+        @mutex = Mutex.new
+        @logger = Logger.new($stdout, level: ENV["DEBUG"] ? Logger::DEBUG : Logger::WARN)
+      end
+
+      # Register a callback for sending the protocol message.
+      # The callback receives (request_id, tool_name, tool_arguments).
+      def on_request(&block)
+        @sender = block
+      end
+
+      # Hook interface for Ask::Agent::Session's before_tool_call chain.
+      # Returns { action: :proceed } or { action: :block, reason: "..." }.
+      def before_tool_call(tool_call, _context = {})
+        return { action: :proceed } unless @blocked_tools.include?(tool_call.name.to_sym)
+        return { action: :proceed } if @mode == :never
+
+        request_approval(tool_call)
+      end
+
+      # Called by the server when the client responds to a permission request.
+      #
+      # @param request_id [String] the ID that was sent in the permission request
+      # @param decision [String] "approve" or "deny"
+      # @param reason [String, nil] optional reason from the client
+      def handle_response(request_id, decision, reason: nil)
+        @mutex.synchronize do
+          entry = @pending[request_id]
+          return false unless entry
+
+          entry[:responded] = true
+          entry[:approved] = (decision.to_s == "approve")
+          entry[:reason] = reason
+          entry[:condition].signal
+          true
+        end
+      end
+
+      # Cancel all pending permission requests (e.g., on session shutdown).
+      def cancel_all!
+        @mutex.synchronize do
+          @pending.each_value do |entry|
+            entry[:responded] = true
+            entry[:approved] = false
+            entry[:reason] = "Permission request cancelled"
+            entry[:condition].signal
+          end
+          @pending.clear
+        end
+      end
+
+      # Number of pending permission requests.
+      def pending_count
+        @mutex.synchronize { @pending.size }
+      end
+
+      # Are there any pending permission requests?
+      def pending?
+        pending_count > 0
+      end
+
+      private
+
+      def request_approval(tool_call)
+        request_id = SecureRandom.uuid
+        condition = ConditionVariable.new
+
+        @mutex.synchronize do
+          @pending[request_id] = {
+            tool_call: tool_call,
+            condition: condition,
+            responded: false,
+            approved: false,
+            reason: nil,
+            created_at: Time.now
+          }
+        end
+
+        @logger.debug("Requesting permission for #{tool_call.name} (#{request_id})")
+
+        # Send the permission request via the registered callback
+        @sender&.call(request_id, tool_call.name.to_s, tool_call.arguments)
+
+        # Block the tool thread until the client responds
+        response_reason = nil
+        was_approved = false
+
+        @mutex.synchronize do
+          deadline = Time.now + @timeout
+
+          loop do
+            entry = @pending[request_id]
+            break unless entry      # cancelled or already processed
+            break if entry[:responded]  # response received
+
+            remaining = deadline - Time.now
+            if remaining <= 0
+              @pending.delete(request_id)
+              @logger.debug("Permission request #{request_id} timed out")
+              return { action: :block, reason: "Permission request timed out after #{@timeout}s" }
+            end
+
+            condition.wait(@mutex, remaining)
+          end
+
+          entry = @pending.delete(request_id)
+          if entry
+            was_approved = entry[:approved]
+            response_reason = entry[:reason]
+          end
+        end
+
+        if was_approved
+          @logger.debug("Permission granted for #{request_id}")
+          { action: :proceed }
+        else
+          @logger.debug("Permission denied for #{request_id}: #{response_reason}")
+          { action: :block, reason: response_reason || "Permission denied" }
+        end
+      rescue => e
+        @pending.delete(request_id) rescue nil
+        @logger.debug("Permission error: #{e.message}")
+        { action: :block, reason: "Permission error: #{e.message}" }
+      end
+    end
+  end
+end