ask-app-server 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 77f123a7ad41bee740dc6678faa847ee174fc688ac09cab76b43c3ea2037da71
+  data.tar.gz: 1afcf87beb1af260dfc6042305e10d00d06b546c2acb464fe89e757732fccc31
+SHA512:
+  metadata.gz: c7179daf83e380074cc04d7584dbaf4043d2c7cfff3df6e49c23a6fdc68bf34fc2b421b49866056a162702eb66d6054ecd437d63365f34dfad5a1cbb0968ce78
+  data.tar.gz: ad552bb79034f61d6b06a519cb041f711db6eb0f34c67b8e069cfc5c973782dcb47ab21d226f5726f78ee58992b3dbdc65322fbe59e0585cb73346ccda227eb8

data/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## [0.1.0] - 2026-07-23
+
+### Added
+
+- Initial release of `ask-app-server` — JSON-RPC/stdio app-server for ask-rb agents.
+- **Protocol handler** — implements the ZCode/Codex app-server JSON-RPC protocol over stdio.
+- **Agent adapter** — wraps `Ask::Agent::Session` behind the app-server protocol.
+- **Event translator** — converts ask-agent event types to app-server protocol event types.
+- **Session manager** — create, list, resume, subscribe, and poll sessions.
+- **CLI binary** — `ask-app-server` command (stdio mode).
+- **Mid-execution injection** — abort running turns and send new messages.
+- **Subscription streaming** — push `session/event` notifications to subscribed clients.
+- **Event polling** — retrieve events by sequence number via `session/events`.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kaka Ruto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,108 @@
+# ask-app-server
+
+[![Gem Version](https://badge.fury.io/rb/ask-app-server.svg)](https://badge.fury.io/rb/ask-app-server)
+
+**JSON-RPC/stdio app-server for ask-rb agents.** Exposes `Ask::Agent::Session` behind the standard app-server protocol, the same protocol spoken by ZCode and Codex app-servers.
+
+## What is this?
+
+`ask-app-server` turns an ask-rb agent into a **programmable service** that speaks JSON-RPC over stdio. Any client that can speak the app-server protocol can drive your agent:
+
+- **Telegram bots**: the `zcode-telegram-bot` connects to ask-app-server instead of ZCode
+- **AI SDK providers**: the Vercel AI SDK provider works with ask-app-server unchanged
+- **IDE extensions**: VS Code, Cursor, and JetBrains extensions connect over stdio/socket
+- **Headless automation**: CI/CD pipelines, batch processing, scriptable agent tasks
+
+## Installation
+
+```bash
+gem install ask-app-server
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem "ask-app-server"
+```
+
+## Quick Start
+
+```bash
+# Start the server (reads JSON-RPC from stdin, writes to stdout)
+ask-app-server
+```
+
+From another process, send JSON-RPC requests:
+
+```json
+{"id":1, "method":"session/create", "params":{"workspace":{"workspacePath":"."}}}
+{"id":2, "method":"session/send",  "params":{"sessionId":"...", "content":"List files in this directory"}}
+```
+
+## Protocol
+
+### Methods
+
+| Method | Description |
+|---|---|
+| `initialize` | Handshake, returns server capabilities |
+| `session/create` | Create a new agent session |
+| `session/list` | List active sessions |
+| `session/resume` | Resume an existing session |
+| `session/subscribe` | Subscribe to streaming events |
+| `session/send` | Send a message to a session |
+| `session/events` | Poll for events after a sequence number |
+| `session/abort` | Abort the current turn |
+| `workspace/readState` | Read model and workspace settings |
+
+### Events (server → client notifications)
+
+| Event | When |
+|---|---|
+| `turn.started` | A new turn begins processing |
+| `model.streaming` | Text delta from the model |
+| `tool.updated` | Tool execution started/updated/completed/failed |
+| `turn.completed` | Turn finished successfully |
+| `turn.failed` | Turn ended with an error |
+
+Event payloads are delivered as `session/event` notifications on subscribed sessions. The server also sends `interaction/requestPermission` when a blocked tool needs approval and `interaction/requestUserInput` when it needs input from the user.
+
+## Clients
+
+This server is a drop-in replacement for `zcode app-server`. The following clients work without changes:
+
+- [ask-coding-providers](https://github.com/ask-rb/ask-coding-providers): ZCode adapter (set `ZCODE_CLI_PATH` to the `ask-app-server` binary)
+- [zcode-telegram-bot](https://github.com/ask-rb/zcode-telegram-bot): Python Telegram bot
+- [ai-sdk-provider-codex-app-server](https://github.com/pablof7z/ai-sdk-provider-codex-app-server): Vercel AI SDK provider
+
+## Configuration
+
+Flags: `--version`, `--help`, `--config PATH`.
+
+The config file is searched in order: `ASK_APP_SERVER_CONFIG` env var, then `./.ask-app-server.json`, then `~/.ask-app-server/config.json`.
+
+Environment variables:
+
+| Variable | Default | Description |
+|---|---|---|
+| `ASK_APP_SERVER_CONFIG` | auto-detected | Path to the config file |
+| `ASK_APP_SERVER_MODEL` | `opencode_go/deepseek-v4-flash` | Model identifier (overrides config file) |
+| `ASK_APP_SERVER_PERMISSIONS` | `on_request` | Permission mode (`on_request`, `never`) |
+| `DEBUG` | unset | Set to `1` for debug logging |
+
+## Development
+
+```bash
+git clone https://github.com/ask-rb/ask-app-server.git
+cd ask-app-server
+bundle install
+bundle exec rake test
+```
+
+## Full documentation
+
+The full ask-rb documentation lives at https://ask-rb.github.io/ask-docs. The [Gem reference](https://ask-rb.github.io/ask-docs/reference/gems) (Agent Infrastructure section) covers ask-app-server. API reference: https://ask-rb.github.io/ask-docs/reference/api.
+
+## License
+
+MIT

data/bin/ask-app-server

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/ask-app-server"
+
+Ask::AppServer::CLI.run!

data/lib/ask/app_server/agent_adapter.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+module Ask
+  module AppServer
+    # Wraps an Ask::Agent::Session and translates its events into the
+    # app-server protocol event format via EventTranslator.
+    #
+    # Each wrapper is associated with one session and maintains an
+    # EventTranslator that app-server clients poll or subscribe to.
+    class AgentAdapter
+      # The underlying ask-agent session.
+      attr_reader :session
+
+      # The event translator that accumulates protocol events.
+      attr_reader :translator
+
+      # The session ID (same as ask-agent session id).
+      attr_reader :session_id
+
+      # Whether a turn is currently in progress.
+      attr_reader :running
+
+      # When the session was created.
+      attr_reader :created_at
+
+      def initialize(model:, tools: nil, system_prompt: nil, agent_dir: nil, **session_opts)
+        @model = model
+        @system_prompt = system_prompt
+        @tools = resolve_tools(tools)
+        @session_opts = session_opts
+        @agent_dir = agent_dir
+        @session = nil
+        @translator = nil
+        @session_id = nil
+        @running = false
+        @running_mutex = Mutex.new
+        @run_thread = nil
+        @abort_requested = false
+        @created_at = Time.now
+        @logger = Logger.new($stdout, level: ENV["DEBUG"] ? Logger::DEBUG : Logger::WARN)
+      end
+
+      # Start a new ask-agent session.
+      # Returns the session ID.
+      def start_session
+        opts = @session_opts.dup
+
+        # Extract hooks from session opts and pass them to Session
+        hooks = opts.delete(:hooks) || {}
+
+        @session = Ask::Agent::Session.new(
+          model: @model,
+          tools: @tools,
+          system_prompt: @system_prompt,
+          agent_dir: @agent_dir,
+          hooks: hooks,
+          **opts
+        )
+        @session_id = @session.id
+        @translator = EventTranslator.new(@session_id)
+        @session.on_event { |event| handle_agent_event(event) }
+        @session_id
+      end
+
+      # Resume an existing session (re-attach event handler).
+      def resume(session)
+        @session = session
+        @session_id = session.id
+        @translator = EventTranslator.new(@session_id)
+        @session.on_event { |event| handle_agent_event(event) }
+        @session_id
+      end
+
+      # Send a message and start processing. Runs in a background thread.
+      # The caller should poll or subscribe to receive events.
+      def send_message(content)
+        raise "Session not started" unless @session
+        raise "Session already busy" if @running
+
+        @running_mutex.synchronize do
+          @abort_requested = false
+          @running = true
+        end
+
+        @run_thread = Thread.new do
+          begin
+            @session.run(content)
+          rescue => e
+            # Agent may have been aborted — that's fine
+            @logger.debug("Agent run error: #{e.message}") if ENV["DEBUG"]
+          ensure
+            @running_mutex.synchronize { @running = false }
+          end
+        end
+
+        true
+      end
+
+      # Request abort of the current turn.
+      def abort_turn!
+        @abort_requested = true
+        @session&.abort if @session
+      end
+
+      # Wait for the current turn to complete (with timeout).
+      # Returns true if completed, false if timed out.
+      def wait_for_turn(timeout: 600)
+        thread = @run_thread
+        return true unless thread
+
+        thread.join(timeout)
+        !thread.alive?
+      end
+
+      # Whether this session is idle (no turn running).
+      def idle?
+        !@running
+      end
+
+      # Inject a message into a running session (mid-execution).
+      # Aborts the current turn; the message will be processed when
+      # the next turn starts.
+      # Note: ask-agent doesn't natively support mid-execution injection.
+      # We abort and queue the message for the next run.
+      def inject_message(content)
+        if @running
+          abort_turn!
+          # The caller should wait for idle, then call send_message again
+          false
+        else
+          send_message(content)
+          true
+        end
+      end
+
+      # The accumulated streaming text from the current/ last turn.
+      def streaming_text
+        @translator&.instance_variable_get(:@streaming_text).to_s
+      end
+
+      # All events since last drain.
+      def pending_events
+        @translator&.pending_events || []
+      end
+
+      # Drain and return pending events.
+      def drain_events
+        @translator&.drain_events || []
+      end
+
+      # Last sequence number.
+      def last_seq
+        @translator&.last_seq || 0
+      end
+
+      # Events after a given sequence number.
+      def events_after(after_seq)
+        pending_events.select { |e| e[:seq] > after_seq }
+      end
+
+      private
+
+      def handle_agent_event(event)
+        translated = @translator.translate(event)
+        # Translated events are already stored in the translator's buffer.
+        # Nothing else to do here — clients poll or subscribe to get them.
+      end
+
+      def resolve_tools(tool_list)
+        return default_tools if tool_list.nil?
+
+        tool_list.map do |t|
+          case t
+          when Class then t.new
+          when String then resolve_tool_by_name(t)
+          else t
+          end
+        end
+      end
+
+      def resolve_tool_by_name(name)
+        case name.downcase
+        when "bash" then Ask::Tools::Bash.new
+        when "read" then Ask::Tools::Read.new
+        when "write" then Ask::Tools::Write.new
+        when "edit" then Ask::Tools::Edit.new
+        when "glob" then Ask::Tools::Glob.new
+        when "grep" then Ask::Tools::Grep.new
+        when "code" then Ask::Tools::Code.new
+        else raise ArgumentError, "Unknown tool: #{name}"
+        end
+      end
+
+      def default_tools
+        [
+          Ask::Tools::Bash.new,
+          Ask::Tools::Read.new,
+          Ask::Tools::Write.new,
+          Ask::Tools::Edit.new,
+          Ask::Tools::Glob.new,
+          Ask::Tools::Grep.new
+        ]
+      end
+    end
+  end
+end

data/lib/ask/app_server/cli.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Ask
+  module AppServer
+    # CLI for the ask-app-server command.
+    #
+    # Usage:
+    #   ask-app-server                   # Start in stdio mode (default)
+    #   ask-app-server --version         # Show version
+    #   ask-app-server --help            # Show help
+    #   ask-app-server --config PATH     # Use specific config file
+    #
+    # Environment variables:
+    #   ASK_APP_SERVER_CONFIG   - Path to config file (default: auto-detect)
+    #   ASK_APP_SERVER_MODEL    - Model to use (overrides config file)
+    #   ASK_APP_SERVER_PERMISSIONS - Permission mode (overrides config file)
+    #   DEBUG                   - Enable debug logging (1/0)
+    class CLI
+      def self.run!(args = ARGV)
+        new.run(args)
+      end
+
+      def run(args)
+        case args.first
+        when "--version", "-v"
+          puts "ask-app-server v#{Ask::AppServer::VERSION}"
+          return
+        when "--help", "-h"
+          show_help
+          return
+        end
+
+        # Parse --config from args
+        config_path = nil
+        remaining_args = []
+        args.each_with_index do |arg, i|
+          if arg == "--config" && i + 1 < args.length
+            config_path = args[i + 1]
+          elsif !arg.start_with?("--config")
+            remaining_args << arg
+          end
+        end
+
+        # Load configuration
+        config = Config.new(config_path: config_path)
+
+        # Register custom models from config into the model catalog
+        config.register_models!
+
+        $stdout.sync = true
+        $stderr.sync = true
+
+        if config.debug?
+          $stderr.puts "[ask-app-server] Starting v#{Ask::AppServer::VERSION}"
+          $stderr.puts "[ask-app-server] Config: #{JSON.pretty_generate(config.to_h)}"
+        end
+
+        # Build the session manager with config values
+        store = build_state_store(config)
+        session_manager = SessionManager.new(
+          store: store,
+          permission_mode: config.permission_mode,
+          blocked_tools: config.blocked_tools,
+          permission_timeout: config.permission_timeout
+        )
+
+        # Start the server
+        server = Server.new(session_manager: session_manager)
+
+        # Wire the server as the protocol sender for permission requests.
+        # Every time a new session is created with a PermissionHandler,
+        # the server registers its outgoing request callback.
+        session_manager.on_new_permission_handler do |handler|
+          server.register_permission_handler(handler)
+        end
+
+        begin
+          server.start
+        rescue Interrupt
+          $stderr.puts "\n[ask-app-server] Shutting down..." if config.debug?
+          server.stop
+        end
+      end
+
+      private
+
+      def build_state_store(config)
+        # Default path: ~/.ask-app-server/state.db
+        sqlite_path = config.state_sqlite_path || File.expand_path("~/.ask-app-server/state.db")
+
+        begin
+          require "sqlite3"
+          require "ask/state/providers/sqlite"
+        rescue LoadError
+          $stderr.puts "[ask-app-server] sqlite3 gem not available, using in-memory state store." if config.debug?
+          return nil
+        end
+
+        dir = File.dirname(File.expand_path(sqlite_path))
+        FileUtils.mkdir_p(dir) unless File.directory?(dir)
+
+        state = Ask::State::Providers::SQLite.new(path: sqlite_path)
+        $stderr.puts "[ask-app-server] State store: #{sqlite_path}" if config.debug?
+        Ask::AppServer::SessionStore.new(state: state)
+      rescue => e
+        $stderr.puts "[ask-app-server] Warning: Could not initialize SQLite state: #{e.message}"
+        $stderr.puts "[ask-app-server] Falling back to in-memory state store."
+        nil
+      end
+
+      def show_help
+        puts <<~HELP
+          ask-app-server v#{Ask::AppServer::VERSION}
+
+          JSON-RPC/stdio app-server for ask-rb agents.
+          Drop-in compatible with the ZCode/Codex app-server protocol.
+
+          USAGE:
+            ask-app-server                  Start in stdio mode
+
+          OPTIONS:
+            --version, -v                  Show version
+            --help, -h                     Show this help message
+            --config PATH                  Config file path (default: auto-detect)
+
+          CONFIG FILE (JSON):
+            Search order:
+              1. ASK_APP_SERVER_CONFIG env
+              2. ./.ask-app-server.json
+              3. ~/.ask-app-server/config.json
+
+            Example ~/.ask-app-server/config.json:
+              {
+                "model": "claude-sonnet-4",
+                "tools": ["bash", "read", "write", "edit", "glob", "grep"],
+                "permissions": {
+                  "mode": "on_request",
+                  "blocked_tools": ["write", "edit", "bash", "destroy"],
+                  "timeout": 300
+                },
+                "system_prompt": "You are a coding assistant...",
+                "session": { "timeout": 600 }
+              }
+
+          ENVIRONMENT:
+            ASK_APP_SERVER_CONFIG        Config file path
+            ASK_APP_SERVER_MODEL         Model identifier (overrides config)
+            ASK_APP_SERVER_PERMISSIONS   Permission mode (overrides config)
+            DEBUG                        Set to 1 for debug logging
+
+          PROTOCOL:
+            Speaks the standard app-server JSON-RPC protocol over stdio.
+            Compatible clients:
+              - ask-coding-providers ZCode adapter
+              - ai-sdk-provider-codex-app-server (Vercel AI SDK)
+              - zcode-telegram-bot (Python Telegram bot)
+
+          EXAMPLE:
+            # Start with defaults
+            ask-app-server
+
+            # Start with a specific config
+            ask-app-server --config /path/to/config.json
+
+            # Send a ping from another shell:
+            echo '{"id":1,"method":"ping"}' | ask-app-server
+        HELP
+      end
+    end
+  end
+end