claude-agent-server 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '09c3725ebdfb2ef25ab33f08e3d76e60b9805ec5b466aa2191e92816a948cbe5'
+  data.tar.gz: f39f47d131e6654de322d62221692cf6ec433f4f65fa69b253529a6fbe7402cd
+SHA512:
+  metadata.gz: 2a768a352fa1ec65643997d1cc1ad06dd9446726b9c85e920678ad49eb156c2e3abef5ab0ebefe566610a607fe6704e72d34941af5fe094cc89009d3a711e9d3
+  data.tar.gz: 86103d694771510121f761f65f80eee7ea56dae9a18dcee0a62f8d3de905df1de7ef40741e4fbf026b461762e049a8842d3897c4ad63702ce0e6752ac5432d01

data/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+## [0.1.0] - 2026-03-05
+
+### Added
+- Initial release
+- REST API for one-shot queries (`POST /query`, `POST /query/stream`)
+- Interactive session management (`POST /sessions`, `DELETE /sessions/:id`)
+- Session messaging (`POST /sessions/:id/messages`)
+- SSE streaming for session messages (`GET /sessions/:id/messages/stream`)
+- Session interrupt (`POST /sessions/:id/interrupt`)
+- Model switching (`POST /sessions/:id/model`)
+- MCP status (`GET /sessions/:id/mcp-status`)
+- Session history (`GET /sessions/:id/history`)
+- CLI session browsing (`GET /cli-sessions`, `GET /cli-sessions/:id/messages`)
+- Health check (`GET /health`) and server info (`GET /info`)
+- Bearer token authentication with timing-safe comparison
+- CORS support with origin validation
+- Request ID propagation
+- Error handling middleware (SDK errors mapped to HTTP status codes)
+- CLI executable (`claude-agent-server`) with Falcon
+- Docker support
+- Session TTL with automatic reaper
+- Configurable session limits

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Community Contributors
+
+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,213 @@
+# claude-agent-server
+
+HTTP server wrapping the [Claude Agent Ruby SDK](https://github.com/ya-luotao/claude-agent-sdk-ruby) as a REST + SSE API. Expose Claude Code as a network service with session management, streaming, and authentication.
+
+## Requirements
+
+- Ruby 3.2+
+- Claude Code CLI 2.0.0+ (`npm install -g @anthropic-ai/claude-code`)
+- `ANTHROPIC_API_KEY` environment variable
+
+## Installation
+
+```bash
+gem install claude-agent-server
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem 'claude-agent-server'
+```
+
+## Quick Start
+
+```bash
+# Start the server
+claude-agent-server --port 9292
+
+# One-shot query
+curl -X POST http://localhost:9292/query \
+  -H 'Content-Type: application/json' \
+  -d '{"prompt":"Say hello"}'
+
+# Streaming query (SSE)
+curl -N -X POST http://localhost:9292/query/stream \
+  -H 'Content-Type: application/json' \
+  -d '{"prompt":"Say hello"}'
+
+# Interactive session
+curl -X POST http://localhost:9292/sessions \
+  -H 'Content-Type: application/json' \
+  -d '{"prompt":"Hello"}'
+
+# Send message to session
+curl -X POST http://localhost:9292/sessions/<id>/messages \
+  -H 'Content-Type: application/json' \
+  -d '{"prompt":"What is 2+2?"}'
+
+# Stream session messages (SSE)
+curl -N http://localhost:9292/sessions/<id>/messages/stream
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CLAUDE_SERVER_HOST` | `0.0.0.0` | Bind address |
+| `CLAUDE_SERVER_PORT` | `9292` | Listen port |
+| `CLAUDE_SERVER_AUTH_TOKEN` | (none) | Bearer token for authentication |
+| `CLAUDE_SERVER_CORS_ORIGINS` | `*` | Comma-separated allowed origins |
+| `CLAUDE_SERVER_SESSION_TTL` | `3600` | Session idle timeout (seconds) |
+| `CLAUDE_SERVER_MAX_SESSIONS` | `100` | Maximum concurrent sessions |
+| `CLAUDE_SERVER_LOG_LEVEL` | `info` | Log level |
+
+### CLI Options
+
+```
+Usage: claude-agent-server [options]
+    -p, --port PORT          Port to listen on (default: 9292)
+    -b, --bind HOST          Host to bind to (default: 0.0.0.0)
+    -t, --token TOKEN        Authentication token
+        --session-ttl SECONDS Session TTL in seconds (default: 3600)
+        --max-sessions N     Maximum concurrent sessions (default: 100)
+        --cors-origins ORIGINS Comma-separated CORS origins
+    -v, --version            Show version
+    -h, --help               Show help
+```
+
+### Ruby Configuration
+
+```ruby
+require 'claude_agent_server'
+
+ClaudeAgentServer.configure do |config|
+  config.auth_token = 'my-secret-token'
+  config.max_sessions = 50
+  config.default_sdk_options = { model: 'claude-sonnet-4-20250514' }
+end
+
+run ClaudeAgentServer.app
+```
+
+## API Reference
+
+### Health
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| GET | `/health` | No | Health check |
+| GET | `/info` | Yes | Server version, SDK version, active sessions |
+
+### One-Shot Query
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| POST | `/query` | Yes | Execute query, return JSON array of messages |
+| POST | `/query/stream` | Yes | Execute query, return SSE stream |
+
+**Request body:**
+```json
+{
+  "prompt": "Your prompt here",
+  "options": {
+    "model": "claude-sonnet-4-20250514",
+    "maxTurns": 5,
+    "allowedTools": ["Read", "Bash"]
+  }
+}
+```
+
+### Interactive Sessions
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| GET | `/sessions` | Yes | List active sessions |
+| POST | `/sessions` | Yes | Create session (optionally with initial prompt) |
+| GET | `/sessions/:id` | Yes | Get session info |
+| DELETE | `/sessions/:id` | Yes | Disconnect and cleanup |
+| POST | `/sessions/:id/messages` | Yes | Send message to session |
+| GET | `/sessions/:id/messages/stream` | Yes | SSE stream of session messages |
+| POST | `/sessions/:id/interrupt` | Yes | Interrupt current turn |
+| POST | `/sessions/:id/model` | Yes | Switch model mid-session |
+| GET | `/sessions/:id/mcp-status` | Yes | Get MCP server status |
+| GET | `/sessions/:id/history` | Yes | Get session transcript |
+
+### CLI Session Browsing
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| GET | `/cli-sessions` | Yes | List past CLI sessions (read-only) |
+| GET | `/cli-sessions/:id/messages` | Yes | Get session transcript |
+
+## SSE Event Format
+
+```
+event: assistant
+data: {"type":"assistant","content":[{"type":"text","text":"Hello!"}],"model":"claude-sonnet-4-20250514"}
+
+event: result
+data: {"type":"result","subtype":"result","durationMs":1200,"isError":false}
+
+event: done
+data: {"status":"complete"}
+```
+
+## Authentication
+
+When `CLAUDE_SERVER_AUTH_TOKEN` is set, all routes except `/health` require a Bearer token:
+
+```bash
+curl -H 'Authorization: Bearer your-token' http://localhost:9292/info
+```
+
+Uses timing-safe comparison to prevent timing attacks.
+
+## Error Responses
+
+All errors return JSON:
+
+```json
+{
+  "error": {
+    "code": "session_not_found",
+    "message": "Session 'abc-123' not found"
+  }
+}
+```
+
+| HTTP Status | Code | Description |
+|-------------|------|-------------|
+| 400 | `bad_request` | Invalid input |
+| 401 | `unauthorized` | Missing or invalid auth token |
+| 404 | `session_not_found` | Session does not exist |
+| 429 | `session_limit_reached` | Max sessions exceeded |
+| 502 | `cli_connection_error` | Claude CLI failed |
+| 503 | `cli_not_found` | Claude CLI not installed |
+| 500 | `internal_error` | Unexpected error |
+
+## Docker
+
+```bash
+docker build -t claude-agent-server .
+docker run -p 9292:9292 \
+  -e ANTHROPIC_API_KEY=your-key \
+  -e CLAUDE_SERVER_AUTH_TOKEN=your-token \
+  claude-agent-server
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec                  # Run unit tests
+bundle exec rubocop                # Run linter
+bundle exec rake                   # Run both
+RUN_INTEGRATION=1 bundle exec rspec  # Include integration tests
+```
+
+## License
+
+MIT

data/config.ru

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative 'lib/claude_agent_server'
+
+# Configure from environment variables (already defaults in Config)
+ClaudeAgentServer.configure do |config|
+  # Override defaults here if needed
+end
+
+run ClaudeAgentServer.app