docs: cost tracking API, ag init onboarding, runner abstraction

README.md

@@ -55,7 +55,7 @@ ag run "Build a login page with email/password fields." --cwd /path/to/project
 <summary>Step-by-step setup</summary>
 
 ```bash
-ag init                    # Bootstrap config (use --force to overwrite)
+ag init                    # Bootstrap config (use --force to overwrite, --model <model> for non-interactive)
 ag                         # Start server
 ag create "Your prompt" --cwd /path/to/project  # Create session
 ag doctor                  # Verify setup

docs/api-quick-ref.md

@@ -24,6 +24,7 @@ A compact summary of all Aegis API endpoints. For detailed documentation, exampl
 |--------|------|------|---------|
 | `GET` | `/v1/sessions/{id}` | Bearer | Get session details |
 | `GET` | `/v1/sessions/{id}/health` | Bearer | Single session health check |
+| `GET` | `/v1/sessions/{id}/cost` | Bearer | Per-session cost summary with burn rate |
 
 ## Session Actions
 
@@ -176,6 +177,13 @@ A compact summary of all Aegis API endpoints. For detailed documentation, exampl
 | `GET` | `/v1/webhooks/dead-letter` | Bearer | Webhook dead letter queue |
 | `GET` | `/v1/channels/health` | Bearer | Channel health reporting |
 
+## Cost Tracking
+
+| Method | Path | Auth | Summary |
+|--------|------|------|---------|
+| `GET` | `/v1/cost/summary` | Bearer | Aggregate cost summary with burn rate |
+| `GET` | `/v1/cost/by-model` | Bearer | Cost grouped by model |
+
 ## Metrics
 
 | Method | Path | Auth | Summary |

docs/api-reference.md

@@ -2626,6 +2626,141 @@ curl http://localhost:9100/v1/analytics/rate-limits \
 }
 ```
 
+### Get Session Cost
+
+```
+GET /v1/sessions/:id/cost
+```
+
+Returns per-session cost summary with burn rate, cache-hit rate, and token breakdown.
+
+| Role | Required |
+|------|----------|
+| admin, operator, viewer (owner) | Yes |
+
+```bash
+curl http://localhost:9100/v1/sessions/sess_abc123/cost \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+**Response:**
+
+```json
+{
+  "sessionId": "sess_abc123",
+  "totalInputTokens": 150000,
+  "totalOutputTokens": 50000,
+  "totalCacheCreationTokens": 20000,
+  "totalCacheReadTokens": 80000,
+  "cacheHitRate": 0.8,
+  "estimatedCostUsd": 3.42,
+  "model": "claude-sonnet-4-20250514",
+  "burnRateUsdPerHour": 12.5,
+  "durationMinutes": 16,
+  "recordCount": 24
+}
+```
+
+---
+
+### Get Cost Summary
+
+```
+GET /v1/cost/summary
+```
+
+Returns aggregate cost summary with burn rate across all sessions.
+
+| Role | Required |
+|------|----------|
+| admin, operator, viewer | Yes |
+
+**Query Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `from` | string | no | ISO timestamp lower bound (inclusive) |
+| `to` | string | no | ISO timestamp upper bound (inclusive) |
+
+```bash
+curl "http://localhost:9100/v1/cost/summary?from=2026-05-01T00:00:00Z&to=2026-05-13T00:00:00Z" \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+**Response:**
+
+```json
+{
+  "from": "2026-05-01T00:00:00.000Z",
+  "to": "2026-05-13T00:00:00.000Z",
+  "totalInputTokens": 2400000,
+  "totalOutputTokens": 800000,
+  "totalCacheCreationTokens": 100000,
+  "totalCacheReadTokens": 500000,
+  "cacheHitRate": 0.8333,
+  "estimatedCostUsd": 52.40,
+  "burnRateUsdPerHour": 4.37,
+  "sessions": 42
+}
+```
+
+---
+
+### Get Cost by Model
+
+```
+GET /v1/cost/by-model
+```
+
+Returns cost grouped by model with per-model token breakdown and cache-hit rate.
+
+| Role | Required |
+|------|----------|
+| admin, operator, viewer | Yes |
+
+**Query Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `from` | string | no | ISO timestamp lower bound (inclusive) |
+| `to` | string | no | ISO timestamp upper bound (inclusive) |
+
+```bash
+curl "http://localhost:9100/v1/cost/by-model" \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+**Response:**
+
+```json
+{
+  "from": null,
+  "to": null,
+  "models": [
+    {
+      "model": "claude-sonnet-4-20250514",
+      "inputTokens": 2000000,
+      "outputTokens": 700000,
+      "cacheCreationTokens": 80000,
+      "cacheReadTokens": 400000,
+      "estimatedCostUsd": 45.20,
+      "cacheHitRate": 0.8333
+    },
+    {
+      "model": "claude-opus-4-20250514",
+      "inputTokens": 400000,
+      "outputTokens": 100000,
+      "cacheCreationTokens": 20000,
+      "cacheReadTokens": 100000,
+      "estimatedCostUsd": 7.20,
+      "cacheHitRate": 0.8333
+    }
+  ],
+  "totalModels": 2,
+  "totalCostUsd": 52.40
+}
+```
+
 ---
 
 ## 8. Monitoring

docs/architecture.md

@@ -256,6 +256,7 @@ See: PRs #1779 (search/filter), #1782 (keyboard shortcuts), #1791 (CSV export),
 |---|---|
 | `session.ts` | Core session lifecycle: create, send messages, kill, state tracking |
 | `session-cleanup.ts` | Reaps idle sessions and frees resources |
+| `runners/` | Pluggable agent runner abstraction — defines the `AgentRunner` interface for start/send/read/kill lifecycle. Registry maps runner IDs to implementations |
 | `services/acp/backend.ts` | ACP backend: child process lifecycle management via JSON-RPC over stdio |
 | `services/acp/child-process.ts` | Claude Code child process spawning and management |
 | `services/acp/terminal-bridge.ts` | Terminal output streaming from ACP child processes |

docs/getting-started.md

@@ -50,6 +50,8 @@ ag init
 ```
 
 > **Warning:** Running `ag init` a second time overwrites `.aegis/config.yaml` and generates a new auth token. Restart the server to apply changes. Use `ag init --force` to skip the confirmation prompt.
+>
+> `ag init` now supports conversational onboarding with `--model` and `--name` flags for non-interactive setup. Use `--model <provider/model>` to set the default model and `--name <name>` to set a display name for the session.
 
 ```bash
 ag