ada-agent 0.8.0 → 0.9.0

package/README.md

@@ -258,6 +258,10 @@ JIT-provisions a seat for the verified identity and offboarding is immediate. St
 verification, no new dependency; fail-closed by construction. See
 **[docs/enterprise-stage2-oidc.md](docs/enterprise-stage2-oidc.md)**.
 
+**Deploy** — a `Dockerfile` + `docker-compose.yml` run the backend anywhere (`docker compose up`);
+point clients at it with `ADA_BACKEND_URL` / `ada.backendUrl`. Use Cloudflare Workers AI models
+(`@cf/*`) or an AI Gateway with zero code change. See **[docs/deploy.md](docs/deploy.md)**.
+
 ## Benchmarks
 
 ada can run **SWE-bench Verified** — it generates patches for real GitHub issues (one isolated repo

package/docs/deploy.md

@@ -0,0 +1,84 @@
+# Deploying ada-server
+
+`ada-server` is the routing backend — it holds provider keys and speaks the OpenAI-compatible API
+that every ada client (the `ada` CLI **and** the ada IDE) points at. It's a small Node HTTP server;
+this guide runs it in a container. Clients then set `ADA_BACKEND_URL` (CLI) or `ada.backendUrl` (IDE)
+to its URL.
+
+## Quick start (container)
+
+```bash
+cp .env.example .env          # add at least one provider key (see below)
+docker compose up --build     # → http://localhost:8787
+
+# point a client at it
+ADA_BACKEND_URL=http://localhost:8787/v1 ada
+```
+
+Or without compose:
+
+```bash
+docker build -t ada-server .
+docker run -p 8787:8787 -v ada-data:/data --env-file .env ada-server
+```
+
+The image is **server-only** (~small, `node:22-slim`, no native build) — it drops the `node-pty`
+client tool and the `skills/` bundle it doesn't need.
+
+## Configuration (env)
+
+| Var | Purpose |
+|---|---|
+| provider keys | e.g. `CLOUDFLARE_ACCOUNT_ID`+`CLOUDFLARE_API_TOKEN`, `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, … — set what you use. Every provider + its key env is in [`src/server/config.ts`](../src/server/config.ts). |
+| `ADA_PORT` | listen port (default `8787`). |
+| `ADA_DATA_DIR` | where seats/policy/usage/audit live (default `/data` in the image). **Mount a volume here** — see persistence. |
+| `ADA_ADMIN_KEY` | bootstrap admin key → enables the enterprise control plane ([enterprise.md](enterprise.md)). |
+| `ADA_OIDC_*` | OIDC SSO ([enterprise-stage2-oidc.md](enterprise-stage2-oidc.md)). |
+
+## Persistence — mount `/data`
+
+The stores are flat JSON/JSONL under `ADA_DATA_DIR`. In a container that directory is **ephemeral**
+unless you mount a volume — without one, seats, usage, and the audit log are lost on restart. The
+compose file and the `docker run -v ada-data:/data` above handle this. On a PaaS, attach a persistent
+disk/volume mounted at `/data`.
+
+> If your platform has no persistent volume (e.g. plain Cloudflare Workers), that's the signal to move
+> to the Workers + D1/KV port below rather than the container.
+
+## Cloudflare
+
+Two independent things, don't conflate them:
+
+**1. Using Cloudflare's models (no code, works today).** Set `CLOUDFLARE_ACCOUNT_ID` +
+`CLOUDFLARE_API_TOKEN` and request `@cf/*` model ids (e.g. `@cf/meta/llama-3.3-70b-instruct`) — the
+router sends them to Workers AI. To route *all* providers through a **Cloudflare AI Gateway** (for
+unified logging, caching, rate-limiting), point `CLOUDFLARE_BASE_URL` at your gateway URL.
+
+**2. Hosting the container.**
+- **Easiest durable path (recommended now):** any container host with a persistent volume — **Fly.io**,
+  **Render**, **Railway**. Deploy the Dockerfile, attach a volume at `/data`, set env, done. Put TLS
+  in front (the platform usually does this for you).
+- **Cloudflare Containers** (beta): runnable via a Worker + container binding, but Cloudflare's model
+  is stateless-leaning — durable seat/usage/audit state wants **R2/D1**, not a container disk. For a
+  Cloudflare-native, stateful deploy, prefer the port below.
+
+### Phase 2 — Workers-native port (planned)
+
+The container is deliberately step one. The edge-native version swaps:
+
+- the Node HTTP server → a Workers `fetch` handler,
+- the file-backed stores (already isolated behind `dataDir()` in `enterprise.ts`) → **D1** (seats /
+  policy / usage / audit) or **KV**,
+- streaming metering (currently a `res.write` tee) → **AI Gateway** request logs,
+- and uses **Workers AI** directly for `@cf/*`.
+
+Tracked as a follow-up; the container unblocks distribution first.
+
+## Hardening
+
+- Terminate **TLS** in front (Caddy/nginx, or the PaaS) — seat keys travel as bearer tokens.
+- Back up the `/data` volume (four small files).
+- Lock it down: set `ADA_ADMIN_KEY` or `ADA_OIDC_*` so the backend isn't dev-open (see
+  [enterprise.md](enterprise.md)).
+- To run non-root, add `USER node` to the Dockerfile and ensure the mounted volume is writable by
+  uid 1000.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ada-agent",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "A from-zero terminal coding agent with a Cursor-style routing backend, ~285 skills, MCP connectors, and ask/plan/auto modes",
   "type": "module",
   "license": "MIT",
@@ -56,10 +56,12 @@
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.106.0",
-    "node-pty": "^1.1.0",
     "openai": "^6.45.0",
     "tsx": "^4.22.4"
   },
+  "optionalDependencies": {
+    "node-pty": "^1.1.0"
+  },
   "devDependencies": {
     "@types/node": "^26.0.1",
     "typescript": "^6.0.3"