Phase 1 · Batch 1: Read-only Usage Core — runtime usage service, schemas, API endpoint #30

New Issue

Closed

opened 2026-05-20 19:48:53 -05:00 by null · 1 comment

null commented

2026-05-20 19:48:53 -05:00

Owner

Outcome

Mission Control can compute model usage, cost, and time remaining from OpenClaw runtime data.

Scope

Add backend/app/services/openclaw/runtime_usage.py
Add backend/app/schemas/runtime_usage.py (response models)
Add API route: GET /api/v1/gateways/{gateway_id}/runtime-usage
Wire router in backend/app/main.py if new router file created
Add tests under backend/tests/test_runtime_usage*.py

Implementation Details

Provider/model normalization and cost calculation using typed Python helpers
Config-backed pricing with defaults + override file/env setting
Account/source normalization (multiple Claude, OpenAI, Ollama accounts kept separate)
Parse session JSONL defensively: skip malformed lines, ignore messages without usage, preserve unknown models as zero-cost with token counts
5-hour and 7-day windows, per-model totals, current burn rate, reset time, top sessions
account_key derived from gateway config, environment/profile name, or explicit MC mapping
Never expose raw API keys or secrets in usage payloads
Mark unpriced local models as unpriced=false, cost_usd=0; mark unknown paid models as unpriced=true

Data Contract

See docs/runtime-usage-dashboard-plan.md → Proposed Data Contract section for the response schema.

Open Questions (must resolve before implementation)

Gateway-scoped endpoint vs organization-wide aggregation?
Where should pricing overrides live: backend settings, DB table, or checked-in JSON config?
Should non-admin users see costs, or are costs admin-only?
Time remaining tracks: output tokens only, total tokens, calls, cost, or provider-specific limit profile?
Historical persistence in MC, or on-demand JSONL parsing sufficient for v1?

Reference

openclaw-dashboard server.js: DEFAULT_MODEL_PRICING, loadModelPricing, normalizeProvider, normalizeModel, estimateMsgCost, isSessionFile, extractSessionId, getSessionCost, getCostData, getUsageWindows
data/model_pricing_usd_per_million.json

Depends On

None — this is the first slice.

Labels

phase-1, backend, priority-high

## Outcome Mission Control can compute model usage, cost, and time remaining from OpenClaw runtime data. ## Scope - Add `backend/app/services/openclaw/runtime_usage.py` - Add `backend/app/schemas/runtime_usage.py` (response models) - Add API route: `GET /api/v1/gateways/{gateway_id}/runtime-usage` - Wire router in `backend/app/main.py` if new router file created - Add tests under `backend/tests/test_runtime_usage*.py` ## Implementation Details - Provider/model normalization and cost calculation using typed Python helpers - Config-backed pricing with defaults + override file/env setting - Account/source normalization (multiple Claude, OpenAI, Ollama accounts kept separate) - Parse session JSONL defensively: skip malformed lines, ignore messages without usage, preserve unknown models as zero-cost with token counts - 5-hour and 7-day windows, per-model totals, current burn rate, reset time, top sessions - `account_key` derived from gateway config, environment/profile name, or explicit MC mapping - Never expose raw API keys or secrets in usage payloads - Mark unpriced local models as `unpriced=false, cost_usd=0`; mark unknown paid models as `unpriced=true` ## Data Contract See `docs/runtime-usage-dashboard-plan.md` → Proposed Data Contract section for the response schema. ## Open Questions (must resolve before implementation) 1. Gateway-scoped endpoint vs organization-wide aggregation? 2. Where should pricing overrides live: backend settings, DB table, or checked-in JSON config? 3. Should non-admin users see costs, or are costs admin-only? 4. Time remaining tracks: output tokens only, total tokens, calls, cost, or provider-specific limit profile? 5. Historical persistence in MC, or on-demand JSONL parsing sufficient for v1? ## Reference - `openclaw-dashboard` `server.js`: DEFAULT_MODEL_PRICING, loadModelPricing, normalizeProvider, normalizeModel, estimateMsgCost, isSessionFile, extractSessionId, getSessionCost, getCostData, getUsageWindows - `data/model_pricing_usd_per_million.json` ## Depends On None — this is the first slice. ## Labels phase-1, backend, priority-high

null referenced this issue

2026-05-20 19:48:57 -05:00

Phase 1 · Batch 2: Dashboard Cards and Session Enrichment #31

null referenced this issue

2026-05-20 19:49:02 -05:00

Phase 2 · Batch 3: Provider Usage Scrapers as Optional Local Adapters #32

null referenced this issue

2026-05-20 19:49:07 -05:00

Phase 2 · Batch 4: Live Feed and Activity Correlation #33

null referenced this issue

2026-05-20 19:49:12 -05:00

Phase 3 · Batch 5: Memory, Cron, and Health Panels #34

null referenced this issue

2026-05-20 19:49:16 -05:00

Phase 4 · Batch 6: Admin Controls — Gateway Restart, Config Edit, Logs, Docker #35

null commented

2026-05-20 20:14:18 -05:00

Author

Owner

✅ Verification complete. Issue #30 accurately reflects the Batch 1 scope from docs/runtime-usage-dashboard-plan.md. All files listed, data contract matches, open questions captured, dependencies correct. No discrepancies found.

null closed this issue

2026-05-20 20:14:21 -05:00

null referenced this issue from a commit

2026-05-20 20:15:15 -05:00

feat(runtime-usage): add read-only usage core service, schemas, and API endpoint (batch 1, #30)

null referenced this issue

2026-05-20 20:44:43 -05:00

Phase 1 · Batch 2: Dashboard Cards and Session Enrichment #31

null referenced this issue

2026-05-20 20:54:42 -05:00

Phase 2 · Batch 3: Provider Usage Scrapers as Optional Local Adapters #32

null referenced this issue