From 1d51243a7a332863c39e5c3ff55ade7b4abfdec9 Mon Sep 17 00:00:00 2001
From: Emanuele <106186915+OneStepAt4time@users.noreply.github.com>
Date: Wed, 13 May 2026 07:59:10 +0200
Subject: [PATCH] docs: cost tracking API, ag init onboarding, runner
abstraction
Documents 3 new features from merged PRs:
- #3267: Cost tracking API (GET /v1/sessions/:id/cost, /v1/cost/summary,
/v1/cost/by-model) in api-reference.md + api-quick-ref.md
- #3270: ag init conversational onboarding (--model, --name flags)
in getting-started.md + README
- #3268: Runner abstraction layer in architecture.md module table
---
README.md | 2 +-
docs/api-quick-ref.md | 8 +++
docs/api-reference.md | 135 ++++++++++++++++++++++++++++++++++++++++
docs/architecture.md | 1 +
docs/getting-started.md | 2 +
5 files changed, 147 insertions(+), 1 deletion(-)
diff --git a/README.md b/README.md
index 94e7a70ae..af0885dff 100644
--- a/README.md
+++ b/README.md
@@ -55,7 +55,7 @@ ag run "Build a login page with email/password fields." --cwd /path/to/project
Step-by-step setup
```bash
-ag init # Bootstrap config (use --force to overwrite)
+ag init # Bootstrap config (use --force to overwrite, --model for non-interactive)
ag # Start server
ag create "Your prompt" --cwd /path/to/project # Create session
ag doctor # Verify setup
diff --git a/docs/api-quick-ref.md b/docs/api-quick-ref.md
index def44bd1f..d9bc61cb2 100644
--- a/docs/api-quick-ref.md
+++ b/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 |
diff --git a/docs/api-reference.md b/docs/api-reference.md
index 937417eb3..943ce4f4e 100644
--- a/docs/api-reference.md
+++ b/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
diff --git a/docs/architecture.md b/docs/architecture.md
index 50acda219..32327c90d 100644
--- a/docs/architecture.md
+++ b/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 |
diff --git a/docs/getting-started.md b/docs/getting-started.md
index bfce8e8ae..4b2f5f74c 100644
--- a/docs/getting-started.md
+++ b/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 ` to set the default model and `--name ` to set a display name for the session.
```bash
ag