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-botconnects 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
gem install ask-app-server
Or add to your Gemfile:
gem "ask-app-server"
Quick Start
# Start the server (reads JSON-RPC from stdin, writes to stdout)
ask-app-server
From another process, send JSON-RPC requests:
{"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: ZCode adapter (set
ZCODE_CLI_PATHto theask-app-serverbinary) - zcode-telegram-bot: Python Telegram bot
- 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
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 (Agent Infrastructure section) covers ask-app-server. API reference: https://ask-rb.github.io/ask-docs/reference/api.
License
MIT