open-agents-ai 0.184.33 → 0.184.35

package/README.md

@@ -244,92 +244,291 @@ Shows per-process RAM and CPU usage before killing. Detects: cloudflared tunnels
 Open Agents runs a persistent REST API — like Ollama's `/api/` surface but with agentic task execution, OpenAI compatibility, and full TUI command access.
 
 ```bash
-oa serve                          # Start on default port 11435
-oa serve --port 9999              # Custom port
-OA_API_KEY=secret oa serve        # Enable Bearer token auth
+oa serve                                              # Start on default port 11435
+oa serve --port 9999                                   # Custom port
+OA_API_KEY=mysecret oa serve                           # Single admin key
+OA_API_KEYS="key1:admin:alice,key2:run:ci,key3:read:grafana" oa serve  # Scoped multi-key
 ```
 
-**Health & Observability:**
+#### Working Directory
+
+Pass `X-Working-Directory` header to run commands in your current terminal directory:
+
+```bash
+# Auto-inject current dir — agent operates on YOUR project, not the server's cwd
+curl -X POST http://localhost:11435/v1/run \
+  -H "X-Working-Directory: $(pwd)" \
+  -H "Content-Type: application/json" \
+  -d '{"task":"fix all lint errors"}'
+```
+
+Or set it in the JSON body: `"working_directory": "/path/to/project"`
+
+#### Health & Observability
 
 ```bash
-curl http://localhost:11435/health          # → {"status":"ok","uptime_s":123}
-curl http://localhost:11435/health/ready     # → {"status":"ready","ollama":"reachable"} or 503
-curl http://localhost:11435/version          # → {"version":"0.184.31","node":"v24.14.0","platform":"linux"}
-curl http://localhost:11435/metrics          # → Prometheus text format (request counts, tokens, errors)
+# Liveness
+curl http://localhost:11435/health
+```
+```json
+{"status":"ok","uptime_s":142,"version":"0.184.33"}
 ```
 
-**OpenAI-Compatible Inference** (drop-in for any OpenAI client library):
+```bash
+# Readiness (probes Ollama backend)
+curl http://localhost:11435/health/ready
+```
+```json
+{"status":"ready","ollama":"reachable"}
+```
 
 ```bash
-# List models (52 models in OpenAI format)
+# Version info
+curl http://localhost:11435/version
+```
+```json
+{"version":"0.184.33","node":"v24.14.0","platform":"linux"}
+```
+
+```bash
+# Prometheus metrics (scrape with Grafana/Prometheus)
+curl http://localhost:11435/metrics
+```
+```
+# HELP oa_requests_total Total HTTP requests
+# TYPE oa_requests_total counter
+oa_requests_total{method="POST",path="/v1/chat/completions",status="200"} 47
+oa_tokens_in_total 12450
+oa_tokens_out_total 8230
+oa_errors_total 0
+```
+
+#### OpenAI-Compatible Inference
+
+Drop-in replacement for any OpenAI client library. Change `api.openai.com` → `localhost:11435`.
+
+```bash
+# List models
 curl http://localhost:11435/v1/models
+```
+```json
+{"object":"list","data":[{"id":"qwen3.5:9b","object":"model","created":0,"owned_by":"local"},{"id":"qwen3.5:4b","object":"model",...}]}
+```
 
-# Chat completions (non-streaming)
+```bash
+# Chat completion (non-streaming)
 curl -X POST http://localhost:11435/v1/chat/completions \
   -H "Content-Type: application/json" \
-  -d '{"model":"qwen3.5:9b","messages":[{"role":"user","content":"Hello"}]}'
-# → {"id":"chatcmpl-...","choices":[{"message":{"role":"assistant","content":"Hi there!"}}],"usage":{"prompt_tokens":25,"completion_tokens":5}}
+  -d '{
+    "model": "qwen3.5:9b",
+    "messages": [{"role": "user", "content": "What is 2+2?"}]
+  }'
+```
+```json
+{
+  "id": "chatcmpl-a1b2c3d4e5f6",
+  "object": "chat.completion",
+  "model": "qwen3.5:9b",
+  "choices": [{
+    "index": 0,
+    "message": {"role": "assistant", "content": "4"},
+    "finish_reason": "stop"
+  }],
+  "usage": {"prompt_tokens": 25, "completion_tokens": 2, "total_tokens": 27}
+}
+```
 
-# Chat completions (SSE streaming)
+```bash
+# Chat completion (SSE streaming)
 curl -N -X POST http://localhost:11435/v1/chat/completions \
   -H "Content-Type: application/json" \
   -d '{"model":"qwen3.5:9b","messages":[{"role":"user","content":"Hello"}],"stream":true}'
-# → data: {"choices":[{"delta":{"content":"Hi"}}]}\n\ndata: {"choices":[{"delta":{"content":" there"}}]}\n\n...data: [DONE]
+```
+```
+data: {"id":"chatcmpl-...","choices":[{"delta":{"role":"assistant","content":"Hi"}}]}
+data: {"id":"chatcmpl-...","choices":[{"delta":{"content":" there!"}}]}
+data: {"id":"chatcmpl-...","choices":[{"delta":{},"finish_reason":"stop"}]}
+data: [DONE]
 ```
 
-**Agentic Task Execution** (the unique OA capability):
+#### Agentic Task Execution
+
+The unique OA capability — submit a coding task and get an autonomous agent loop.
 
 ```bash
-# Submit an agentic task
+# Run task in your current directory
 curl -X POST http://localhost:11435/v1/run \
   -H "Content-Type: application/json" \
-  -d '{"prompt":"fix the null check in auth.ts","model":"qwen3.5:9b","stream":true}'
+  -H "X-Working-Directory: $(pwd)" \
+  -d '{
+    "task": "fix all TypeScript errors in src/",
+    "model": "qwen3.5:9b",
+    "max_turns": 25,
+    "stream": true
+  }'
+```
+```
+data: {"type":"run_started","run_id":"job-a1b2c3","pid":12345}
+data: {"type":"stdout","data":"{\"turn\":1,\"tool\":\"file_read\",...}"}
+data: {"type":"stdout","data":"{\"turn\":2,\"tool\":\"file_edit\",...}"}
+data: {"type":"exit","code":0}
+data: [DONE]
+```
 
-# List runs
+```bash
+# Run in isolated sandbox (temp workspace, safe for untrusted tasks)
+curl -X POST http://localhost:11435/v1/run \
+  -H "Content-Type: application/json" \
+  -d '{"task":"write a hello world app","isolate":true}'
+```
+
+```bash
+# List all runs
 curl http://localhost:11435/v1/runs
+```
+```json
+{"runs":[{"id":"job-a1b2c3","task":"fix TypeScript errors","status":"completed","startedAt":"..."}]}
+```
 
-# Abort a run
-curl -X DELETE http://localhost:11435/v1/runs/run-abc123
+```bash
+# Get specific run status
+curl http://localhost:11435/v1/runs/job-a1b2c3
 ```
 
-**Configuration:**
+```bash
+# Abort a running task
+curl -X DELETE http://localhost:11435/v1/runs/job-a1b2c3
+```
+```json
+{"status":"aborted","run_id":"job-a1b2c3"}
+```
+
+#### Configuration
+
+```bash
+# Get all config
+curl http://localhost:11435/v1/config
+```
+```json
+{"config":{"backendUrl":"http://127.0.0.1:11434","model":"qwen3.5:122b","backendType":"ollama",...}}
+```
 
 ```bash
-curl http://localhost:11435/v1/config              # Get all settings
-curl http://localhost:11435/v1/config/model         # → {"model":"qwen3.5:122b"}
+# Get current model
+curl http://localhost:11435/v1/config/model
+```
+```json
+{"model":"qwen3.5:122b"}
+```
+
+```bash
+# Switch model
 curl -X PUT http://localhost:11435/v1/config/model \
-  -H "Content-Type: application/json" -d '{"model":"qwen3.5:27b"}'
-curl http://localhost:11435/v1/config/endpoint      # → {"url":"...","backendType":"..."}
+  -H "Content-Type: application/json" \
+  -d '{"model":"qwen3.5:27b"}'
+```
+```json
+{"model":"qwen3.5:27b","status":"updated"}
+```
+
+```bash
+# Get endpoint
+curl http://localhost:11435/v1/config/endpoint
+```
+```json
+{"url":"http://127.0.0.1:11434","backendType":"ollama","auth":"none"}
+```
+
+```bash
+# Switch endpoint (e.g., to Chutes AI)
+curl -X PUT http://localhost:11435/v1/config/endpoint \
+  -H "Content-Type: application/json" \
+  -d '{"url":"https://llm.chutes.ai","auth":"Bearer cpk_..."}'
+```
+
+```bash
+# Update settings (admin scope required)
+curl -X PATCH http://localhost:11435/v1/config \
+  -H "Content-Type: application/json" \
+  -d '{"verbose":true}'
+```
+```json
+{"config":{...},"updated":["verbose"]}
+```
+
+#### Slash Commands via REST
+
+Every `/command` from the TUI is available as a REST endpoint.
+
+```bash
+# List all available commands
+curl http://localhost:11435/v1/commands
+```
+```json
+{"commands":[{"command":"/help","description":"Show help"},{"command":"/stats","description":"Session metrics"},...]}
+```
+
+```bash
+# Execute /stats
+curl -X POST http://localhost:11435/v1/commands/stats
+```
+
+```bash
+# Execute /nexus status
+curl -X POST http://localhost:11435/v1/commands/nexus \
+  -H "Content-Type: application/json" \
+  -d '{"args":"status"}'
+```
+
+```bash
+# Execute /destroy processes --global
+curl -X POST http://localhost:11435/v1/commands/destroy \
+  -H "Content-Type: application/json" \
+  -d '{"args":"processes --global"}'
+```
+
+#### Auth Scopes
+
+```bash
+# Multi-key setup: read (monitoring), run (CI), admin (ops)
+OA_API_KEYS="grafana-key:read:grafana,ci-key:run:github-actions,ops-key:admin:ops-team" oa serve
 ```
 
-**Slash Commands via REST:**
+| Scope | Can do | Cannot do |
+|-------|--------|-----------|
+| `read` | GET /v1/models, /v1/config, /v1/runs, /v1/commands | POST /v1/run, PATCH /v1/config |
+| `run` | Everything in `read` + POST /v1/run, POST /v1/commands | PATCH /v1/config, PUT endpoints |
+| `admin` | Everything | — |
 
 ```bash
-curl http://localhost:11435/v1/commands              # List all 100+ commands
-curl -X POST http://localhost:11435/v1/commands/stats  # Execute /stats
-curl -X POST http://localhost:11435/v1/commands/nexus  # Execute /nexus status
-```
-
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| GET | `/health` | Liveness check |
-| GET | `/health/ready` | Readiness (probes Ollama) |
-| GET | `/health/startup` | Startup complete |
-| GET | `/version` | OA + Node version |
-| GET | `/metrics` | Prometheus metrics |
-| GET | `/v1/models` | List models (OpenAI format) |
-| POST | `/v1/chat/completions` | Chat inference (OpenAI compatible, streaming + non-streaming) |
-| POST | `/v1/embeddings` | Generate embeddings |
-| POST | `/v1/run` | Submit agentic task |
-| GET | `/v1/runs` | List runs |
-| GET | `/v1/runs/:id` | Run status |
-| DELETE | `/v1/runs/:id` | Abort run |
-| GET | `/v1/config` | All settings |
-| PATCH | `/v1/config` | Update settings |
-| GET/PUT | `/v1/config/model` | Current/switch model |
-| GET/PUT | `/v1/config/endpoint` | Current/switch endpoint |
-| GET | `/v1/commands` | List slash commands |
-| POST | `/v1/commands/:cmd` | Execute command |
+# With auth
+curl -H "Authorization: Bearer ops-key" http://localhost:11435/v1/models
+```
+
+#### Endpoint Reference
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| GET | `/health` | none | Liveness probe |
+| GET | `/health/ready` | none | Readiness (probes Ollama) |
+| GET | `/health/startup` | none | Startup complete |
+| GET | `/version` | none | Version + platform |
+| GET | `/metrics` | none | Prometheus counters |
+| GET | `/v1/models` | read | List models (OpenAI format) |
+| POST | `/v1/chat/completions` | run | Chat inference (stream + sync) |
+| POST | `/v1/embeddings` | run | Generate embeddings |
+| POST | `/v1/run` | run | Submit agentic task |
+| GET | `/v1/runs` | read | List all runs |
+| GET | `/v1/runs/:id` | read | Run status |
+| DELETE | `/v1/runs/:id` | run | Abort run |
+| GET | `/v1/config` | read | All settings |
+| PATCH | `/v1/config` | admin | Update settings |
+| GET | `/v1/config/model` | read | Current model |
+| PUT | `/v1/config/model` | admin | Switch model |
+| GET | `/v1/config/endpoint` | read | Current endpoint |
+| PUT | `/v1/config/endpoint` | admin | Switch endpoint |
+| GET | `/v1/commands` | read | List commands |
+| POST | `/v1/commands/:cmd` | run | Execute command |
 
 ### Enterprise Licensing