# OAuth Usage Monitor — Implementation Design

## Objective
Create a lightweight local monitoring system for OpenAI Codex OAuth usage that helps Braden:
- understand weekly and daily remaining usage
- estimate normal operating overhead
- identify available project-spend capacity
- avoid unused weekly capacity expiring
- avoid daily-limit bottlenecks near weekly reset

## Core Concepts

### 1. Baseline Overhead
Estimated normal day-to-day usage required to sustain routine operations:
- ordinary Telegram conversations
- recurring checks
- routine system usage
- lightweight execution

### 2. Runway Reserve
How much weekly usage should be preserved to safely finish the current week.

Formula:
`runway_reserve_pct = baseline_overhead_pct_per_day * days_until_week_reset`

### 3. Project Capacity
How much weekly budget is available beyond expected routine needs.

Formula:
`project_capacity_pct = weekly_remaining_pct - runway_reserve_pct`

### 4. Spendable Capacity
How much of the project capacity is realistically usable before weekly reset given daily-bucket constraints.

Version 1 will compute this conservatively using heuristic state rather than a hard mathematical cap.

## Data Sources

### Source A — Usage Buckets (text parse)
Command:
```bash
openclaw models
```

Parse the line shaped like:
```text
openai-codex usage: 5h 91% left ⏱2h 4m · Week 21% left ⏱23h 11m
```

Extract:
- `daily_remaining_pct`
- `daily_reset_eta_hours`
- `weekly_remaining_pct`
- `weekly_reset_eta_hours`

### Source B — OAuth Status / Expiry (JSON)
Command:
```bash
openclaw models status --json
```

Extract from `auth.oauth.providers[]` or `auth.oauth.profiles[]`:
- `provider`
- `profileId`
- `status`
- `expiresAt`
- `remainingMs`

## File Layout

### Snapshot history
```text
/Users/openclaw/.openclaw/workspace/state/oauth-usage-history.jsonl
```

### Collector script
```text
/Users/openclaw/.openclaw/workspace/scripts/ops/oauth_usage_collect.py
```

### Reporter script
```text
/Users/openclaw/.openclaw/workspace/scripts/ops/oauth_usage_report.py
```

## Snapshot Schema
Each line in `oauth-usage-history.jsonl`:

```json
{
  "timestamp": "2026-03-25T16:00:00Z",
  "provider": "openai-codex",
  "profile": "openai-codex:default",
  "daily_remaining_pct": 91,
  "daily_reset_eta_hours": 2.07,
  "weekly_remaining_pct": 21,
  "weekly_reset_eta_hours": 23.18,
  "oauth_status": "ok",
  "oauth_expiry_eta_hours": 95.0,
  "raw_usage_line": "openai-codex usage: 5h 91% left ⏱2h 4m · Week 21% left ⏱23h 11m"
}
```

## Collection Cadence

### Passive snapshots
Recommended four times daily:
- 06:00
- 12:00
- 18:00
- 23:30

Reasoning:
- enough signal to estimate trend
- low operational overhead
- avoids noisy over-sampling

### User-facing report
Recommended once daily:
- 08:30 local

### End-of-week high-value alert
Recommended every 6 hours only when weekly reset is under 36 hours.

## Derived Metrics

### A. Baseline Overhead
Initial version:
- compute the average positive daily decline in `weekly_remaining_pct`
- use trailing 7 days when available
- if insufficient history, use trailing available days

Pseudo:
```text
baseline_overhead_pct_per_day =
  avg(max(0, weekly_remaining_pct_previous - weekly_remaining_pct_current))
```

Notes:
- v1 does not attempt sophisticated outlier removal
- later versions can exclude known heavy-project days

### B. Days Until Weekly Reset
```text
days_until_week_reset = weekly_reset_eta_hours / 24
```

### C. Runway Reserve
```text
runway_reserve_pct = baseline_overhead_pct_per_day * days_until_week_reset
```

### D. Project Capacity
```text
project_capacity_pct = weekly_remaining_pct - runway_reserve_pct
```

### E. Daily Constraint Heuristic
Version 1 heuristic:
- if `daily_remaining_pct >= 40`, treat current day as not constrained
- if `daily_remaining_pct < 40` and `daily_reset_eta_hours > weekly_reset_eta_hours`, treat as constrained
- if daily reset occurs before weekly reset and daily remaining is low, recommend splitting heavy work across the next daily reset boundary

This keeps v1 simple while still operationally useful.

## Status Model

### Red — Conserve
Condition:
```text
weekly_remaining_pct < runway_reserve_pct
```
Action:
- routine work only
- avoid discretionary heavy tasks

### Yellow — On Pace
Condition:
```text
abs(weekly_remaining_pct - runway_reserve_pct) <= buffer_pct
```
Action:
- normal operations only
- no large optional project blocks

### Green — Above Pace
Condition:
```text
weekly_remaining_pct > runway_reserve_pct + buffer_pct
```
Action:
- safe to spend on planned larger work

### Use-It-Or-Lose-It
Condition:
- `weekly_reset_eta_hours <= 36`
- `project_capacity_pct > threshold_pct`
- daily state does not block meaningful usage

Action:
- intentionally queue heavier work before reset

## Buffer Policy
Recommended:
```text
buffer_pct = max(5, baseline_overhead_pct_per_day * 0.5)
```

This reduces alert flapping.

## Recommendation Engine

### Suggested thresholds
- `project_capacity_pct < 0` → conserve
- `0 to <5` → routine only
- `5 to <15` → one medium project block is safe
- `15+` → actively schedule meaningful heavier work

### Daily-limit overlays
- if daily remaining is low but next daily reset occurs before weekly reset:
  - recommend scheduling work after reset or splitting across windows
- if daily remaining is high:
  - recommend immediate execution when project capacity exists

## Reporter Output

### Compact Telegram daily alert
```text
OAuth usage check

Week: 21% left, resets in 23.2h
Today: 91% left, resets in 2.1h
Overhead: ~9%/day
Reserve needed: 8.7%
Project capacity: 12.3%

Status: Use-it-or-lose-it
Recommendation: Safe to schedule one heavier project block before weekly reset.
```

### End-of-week alert
```text
OAuth capacity alert

Weekly reset is in 23h and estimated project capacity is ~12%.
Recommendation: pull forward one meaningful heavy task so capacity does not expire unused.
```

## Script Responsibilities

### oauth_usage_collect.py
Responsibilities:
- run `openclaw models`
- run `openclaw models status --json`
- parse usage line
- parse JSON auth block
- append a single JSONL snapshot
- fail loudly on parse drift

### oauth_usage_report.py
Responsibilities:
- load snapshot history
- compute baseline overhead
- compute runway reserve and project capacity
- assess daily-constraint heuristic
- generate:
  - compact human-readable summary
  - optional JSON payload for later automation

## Parsing Strategy

### Usage line regex target
The collector should match a single line containing `openai-codex usage:`.

Expected fields:
```text
openai-codex usage: <x> <daily_remaining>% left ⏱<daily_eta> · Week <weekly_remaining>% left ⏱<weekly_eta>
```

Implementation notes:
- do not depend on the first time-like token before daily remaining
- anchor on:
  - provider prefix
  - first percent before `left`
  - `Week`
  - second percent before `left`
- convert `2h 4m` style durations into fractional hours

### Parse-failure behavior
If parsing fails:
- write a non-zero exit status
- emit the raw matching line to stderr
- do not append a malformed snapshot

## Cron Design

### Phase 1 cron plan
1. Collector snapshots 4x/day
2. Daily report 1x/day
3. Optional end-of-week report every 6h when within 36h of weekly reset

### Delivery
Recommended delivery path:
- daily report announces to current Telegram DM via cron systemEvent or existing alert lane
- long-form analysis remains in workspace artifacts / Notion

## Verification Plan

### Collector verification
- run collector manually
- confirm new JSONL line exists
- confirm fields match live CLI output

### Reporter verification
- run reporter manually
- verify computed values against hand calculation for at least 3 snapshots

### End-to-end verification
- simulate one low-capacity and one high-capacity case using fixture snapshots
- verify recommendation state classification

## Known Risks / Constraints
1. `openclaw models` usage data is currently text-only and therefore parser-fragile.
2. Early baseline estimates will be noisy until enough snapshots accumulate.
3. Daily-limit logic in v1 is heuristic, not a perfect spendability model.

## Phase Plan

### Phase 1
- collector
- history file
- reporter
- daily alert
- simple weekly reserve/project capacity logic

### Phase 2
- outlier filtering
- stronger spendable-capacity model
- anomaly detection
- dashboard / Notion integration if useful

## Recommendation
Implement Phase 1 first. It gives immediate operational value with limited complexity and can be validated quickly against real usage patterns.