@danypops/jittor 0.1.0

package/README.md

@@ -0,0 +1,54 @@
+# Jittor
+
+**Just-in-Time Token Optimizing Router** for Pi.
+
+Jittor observes provider budgets and per-turn usage, computes whether the current burn rate is sustainable, and applies a deterministic policy before each model request:
+
+1. continue
+2. throttle
+3. lower thinking
+4. switch model
+5. switch provider
+6. halt
+
+Initial telemetry providers:
+
+- ChatGPT-authenticated Codex subscription usage
+- OpenRouter API key usage, response accounting, and model pricing
+
+Jittor follows the Papyrus daemon architecture: a supervised Bun service owns SQLite and provider polling; the native Pi extension uses an authenticated loopback client and applies model/thinking decisions.
+
+## Architecture
+
+The initial service scaffold is split into domain, ports, and adapters:
+
+- `src/domain/metric.ts` — normalized timestamped metric observations
+- `src/ports/metric-store.ts` — storage boundary used by the application service
+- `src/adapters/sqlite-metric-store.ts` — SQLite time-series adapter
+- `src/service.ts` — authenticated operation registry
+- `src/client.ts` — operation-typed loopback client
+- `src/daemon.ts` — Bun composition root and maintenance loop
+
+SQLite runs in WAL mode with versioned migrations, JSON validation, bounded queries, chronological indexes, pruning, and checkpoints. The database follows `XDG_DATA_HOME`; private authentication state follows `XDG_STATE_HOME`; the daemon handle follows `XDG_RUNTIME_DIR`.
+
+Operations currently include `metrics.record`, `metrics.query`, `metrics.prune`, and `service.checkpoint`.
+
+Provider adapters currently include official OpenRouter key/usage/model telemetry and an explicitly experimental Codex subscription adapter. The Codex adapter follows the pinned open-source CLI `/wham/usage` payload and `x-codex-*` response-header contracts, accepts additional metered limits, and fails closed on malformed windows or impossible percentages. File credentials must be explicitly configured and private (`0600`); Jittor reads only the access token and account ID, never refreshes credentials, and never logs or persists OAuth secrets.
+
+The native Pi extension preflights input and every provider turn, applies model/thinking decisions, records response headers and finalized usage through the daemon, and blocks requests when required telemetry is unsafe. It follows Pi's current authenticated model/provider and synchronizes Pi's available models before every decision, so unavailable catalog routes are never selected. Its responsive Alef-style footer groups repository and AI identity with cumulative usage, a color-coded context-window bar, and current-provider budget telemetry. Codex shows a bounded quota bar for its longest percentage window; OpenRouter remains honest about its unbounded raw spend and does not fabricate a denominator. Unknown and stale telemetry are marked explicitly. Run `/jittor` for detailed burn pressure, freshness, route state, and confirmed emergency-halt/override controls.
+
+Blocking always has a daemon-independent escape hatch. `/jittor off` (or `/jittor-off`) immediately enters persisted monitor-only mode and never blocks provider requests. The informational footer is independently controlled with `/jittor footer on` and `/jittor footer off`, so showing status never enables enforcement. `/jittor on` only enables enforcement after telemetry polling and available-route synchronization succeed. Every fail-closed error includes these recovery commands plus the daemon restart command.
+
+Run `/usage` for a colored Unicode token histogram with X/Y axes, provider/model series, input/output/cache totals, refresh, and `24h`, `7d`, `30d`, or `90d` ranges. Left/Right changes range and `r` refreshes. Usage is persisted by the daemon from finalized Pi assistant messages.
+
+See [`docs/CALIBRATION.md`](docs/CALIBRATION.md) for thresholds and rollback, and [`docs/USAGE_PRIOR_ART.md`](docs/USAGE_PRIOR_ART.md) for the chart design research.
+
+```bash
+bun test
+bun x tsc --noEmit
+bun run service:install
+```
+
+The systemd user unit binds only to `127.0.0.1`, discovers a 256-bit token without logging it, restarts on failure, and exposes authenticated health and operation endpoints.
+
+See [`docs/PROVIDER_RESEARCH.md`](docs/PROVIDER_RESEARCH.md) for verified API boundaries and caveats.

package/docs/CALIBRATION.md

@@ -0,0 +1,102 @@
+# Jittor routing calibration and rollback
+
+Verified locally on 2026-07-19 without logging provider credentials or raw usage values.
+
+## Live dogfood result
+
+The supervised daemon successfully:
+
+- loaded explicitly configured private Codex file credentials;
+- polled the experimental ChatGPT Codex usage contract;
+- polled the official OpenRouter key endpoint;
+- persisted normalized observations through the daemon-owned SQLite store;
+- reported both sources fresh and the router ready;
+- calculated a deterministic policy decision for the active Pi route;
+- exposed status through authenticated operations and the Pi footer/panel.
+
+The live Codex response exposed one default window and one additional metered limit. The OpenRouter key exposed spend telemetry but no configured per-key limit, so OpenRouter contributes raw USD status and response cost accounting but does not yet create a resettable pressure window. Jittor does not invent an OpenRouter budget.
+
+## Pressure model
+
+For each resettable window:
+
+```text
+observed burn     = delta(used fraction) / delta(time)
+                 or average used fraction / elapsed window time
+sustainable burn = remaining fraction / time until reset
+pressure          = observed burn / sustainable burn
+```
+
+The highest-pressure fresh required window binds the decision. Provider percentage and observed Pi token velocity remain separate metrics.
+
+## Initial thresholds
+
+| Pressure | Decision |
+|---:|---|
+| `<= 1.00` | continue |
+| `> 1.00` | throttle, up to 30 seconds |
+| `> 1.25` | lower thinking |
+| `> 1.50` | switch to a cheaper model on the same provider |
+| `> 2.00` | switch provider |
+| `> 3.00` | halt |
+
+A consumed fraction of 99% is an unconditional hard stop. Missing, failed, older-than-120-second, impossible, or low-confidence required telemetry also halts before a provider request.
+
+Recovery uses 10% hysteresis and a five-minute cooldown. Escalation is immediate; recovery waits, preventing route oscillation around a threshold.
+
+## Dynamic route ladder
+
+Jittor contains no model-ID allowlist. Before every decision, the Pi extension rebuilds the route ladder from `ModelRegistry.getAvailable()` and the active Pi model:
+
+1. the current model and thinking level;
+2. supported lower thinking levels on that model;
+3. authenticated text models from the same current provider, ordered by advertised input-plus-output cost.
+
+Routes from unrelated providers are intentionally excluded. Provider switching therefore halts unless a future explicit cross-provider policy is configured; Jittor does not silently start spending through another configured API. The current route and dynamic ladder are sent to the daemon before policy evaluation. A route that disappears is removed and the policy is evaluated once more instead of aborting with a stale catalog model.
+
+## User controls
+
+- Footer status: Codex longest-window percentage, raw OpenRouter spend, and current decision.
+- `/jittor`: provider windows, observed/sustainable burn, pressure, current route, next downgrade, freshness, and controls.
+- Pause/resume and route overrides require confirmation.
+- Overrides expire after one hour unless cleared earlier.
+
+Pause is a safety halt, not a bypass. It intentionally blocks subsequent provider requests.
+
+## Scenario coverage
+
+`test/calibration.test.ts` verifies:
+
+- sustainable continuation;
+- throttling;
+- thinking downgrade;
+- same-provider model handoff;
+- provider handoff;
+- stale-telemetry fail-closed behavior;
+- pressure and utilization hard halts;
+- cooldown/hysteresis route retention.
+
+Extension tests verify pre-request blocking, model/thinking actuation, response-header ingestion, finalized usage recording, and footer formatting.
+
+## Rollback
+
+To remove enforcement without creating a fail-closed outage:
+
+1. Remove or disable the local Jittor Pi package, then reload Pi:
+   ```bash
+   pi remove /home/dpopsuev/Projects/jittor
+   ```
+2. Stop and disable the daemon only after the extension is unloaded:
+   ```bash
+   systemctl --user disable --now jittor.service
+   ```
+
+Stopping the daemon while the extension remains loaded intentionally blocks provider requests. To restore:
+
+```bash
+cd /home/dpopsuev/Projects/jittor
+bun src/cli.ts service install
+pi install /home/dpopsuev/Projects/jittor
+```
+
+Then reload Pi and run `/jittor` to confirm both readiness and provider freshness.

package/docs/PROVIDER_RESEARCH.md

@@ -0,0 +1,237 @@
+# Jittor provider telemetry research
+
+Verified 2026-07-18. Contracts marked **official** are documented provider APIs. Contracts marked **experimental** are implemented by an official open-source client but are not published as stable public APIs.
+
+## Decision summary
+
+| Source | Hot-path telemetry | Budget semantics | Stability |
+|---|---|---|---|
+| Codex subscription | `/backend-api/wham/usage`, Codex response headers, local Pi turn usage | Provider reports used percentage and reset time; absolute token allowance is not exposed | Experimental |
+| OpenAI API key | Standard rate-limit headers and response usage | Exact token rate limits and API billing | Official, separate from subscription |
+| OpenRouter | `/api/v1/key`, response `usage`, `/generation`, `/models` | Exact per-request tokens/cost; key limit when configured; otherwise Jittor budget required | Official |
+| OpenRouter Analytics | `/api/v1/analytics/query` with management key | Historical aggregate spend/tokens | Official beta; not hot path |
+
+## Codex subscription
+
+### Officially documented behavior
+
+OpenAI documents that:
+
+- ChatGPT-authenticated Codex uses plan allowance rather than standard API billing.
+- Usage depends on model, context, reasoning, tools, retrieval, and caching; prompt length alone is not a reliable estimate.
+- Local messages and cloud chats can share a five-hour window and additional weekly limits may apply.
+- Users can inspect remaining allowance in the Codex usage dashboard and with `/status` in Codex CLI.
+- Switching to a smaller model is the recommended mitigation near limits.
+- `~/.codex/auth.json` may contain plaintext OAuth credentials and must be treated as a password.
+- The workspace Analytics API is for aggregated Business/Enterprise reporting and is not a personal real-time subscription-quota API.
+
+There is no documented personal-plan API contract equivalent to the usage dashboard.
+
+### Experimental contract used by official Codex CLI
+
+The open-source `openai/codex` client calls:
+
+```text
+GET https://chatgpt.com/backend-api/wham/usage
+Authorization: Bearer <ChatGPT OAuth access token>
+ChatGPT-Account-Id: <account id>
+```
+
+For the alternate Codex API path style, its source constructs `/api/codex/usage`. The ChatGPT path above was live-probed successfully without logging credentials.
+
+Observed response fields include:
+
+- `plan_type`
+- `rate_limit.primary_window` and `secondary_window`
+- `used_percent`
+- `limit_window_seconds`
+- `reset_at`
+- `credits.{has_credits, unlimited, balance}`
+- `additional_rate_limits[]` with `metered_feature`, `limit_name`, and independent windows
+- spend-control and rate-limit-reached metadata
+
+The official CLI also parses rolling response headers:
+
+```text
+x-codex-primary-used-percent
+x-codex-primary-window-minutes
+x-codex-primary-reset-at
+x-codex-secondary-used-percent
+x-codex-secondary-window-minutes
+x-codex-secondary-reset-at
+x-codex-credits-has-credits
+x-codex-credits-unlimited
+x-codex-credits-balance
+x-codex-<limit>-primary-used-percent
+x-codex-<limit>-limit-name
+```
+
+It warns at 75%, 90%, and 95%, and offers a smaller-model switch around 90%. Jittor may use different configurable thresholds but should preserve hysteresis.
+
+### What Codex does not expose
+
+The subscription usage response does **not** expose an absolute token budget. Therefore Jittor must not label provider percentage as tokens. It will maintain two metrics:
+
+1. **Provider budget pressure:** percentage consumed versus time remaining.
+2. **Observed token velocity:** Pi assistant usage tokens per elapsed time, grouped by model and thinking level.
+
+Over time Jittor can estimate tokens-per-budget-percent with an EWMA, but that estimate must retain confidence and sampling metadata because provider metering includes reasoning, tools, caching, and potentially non-Pi Codex usage.
+
+### Credential and reliability rules
+
+- Never persist or log OAuth/access/refresh tokens.
+- File-based Codex auth is supported only when explicitly configured; keyring-backed auth needs a separate credential broker.
+- Do not implement OAuth token refresh independently in v1. Codex owns credential refresh.
+- Treat 401, missing fields, unknown schema, stale snapshots, and impossible reset times as telemetry failure.
+- Poll no faster than once per minute unless response headers provide an update.
+- The adapter is version-pinned and explicitly `experimental`; schema drift fails closed according to policy.
+
+## OpenAI API-key mode is a separate source
+
+Standard OpenAI API requests expose official token/request limit headers such as:
+
+- `x-ratelimit-limit-tokens`
+- `x-ratelimit-remaining-tokens`
+- `x-ratelimit-reset-tokens`
+- request and project-token equivalents
+
+These are API organization/project limits, not ChatGPT subscription allowance. Jittor must never merge them into one budget window.
+
+## OpenRouter
+
+### Key and credit telemetry
+
+Official endpoint:
+
+```text
+GET https://openrouter.ai/api/v1/key
+Authorization: Bearer <OpenRouter key>
+```
+
+Useful fields:
+
+- `limit`, `limit_reset`, `limit_remaining`
+- `usage`, `usage_daily`, `usage_weekly`, `usage_monthly`
+- BYOK usage variants
+- `rate_limit`
+- key capability flags including management/provisioning status
+
+A live probe succeeded. The current key has no configured per-key limit, so `limit_remaining` is `null`; Jittor therefore needs user-defined daily/weekly/monthly budgets unless a key cap is configured.
+
+Credit exhaustion produces HTTP 402. Rate limits produce 429 and may be OpenRouter-level or upstream-provider-level. Honor `Retry-After`; streaming errors may arrive as SSE error events after HTTP 200.
+
+### Per-request accounting
+
+Every OpenRouter response includes native-token accounting:
+
+- prompt tokens
+- completion tokens
+- reasoning tokens
+- cached read/write tokens when supported
+- total `cost`
+- upstream inference cost details
+
+Streaming responses place usage in the last SSE event. A generation ID can later be queried through the `/generation` endpoint for audit/reconciliation.
+
+This is Jittor's authoritative OpenRouter hot-path cost signal.
+
+### Model catalog
+
+Official endpoint:
+
+```text
+GET https://openrouter.ai/api/v1/models
+```
+
+A live probe returned 344 models. Model records include canonical ID, context length, pricing, conditional pricing overrides, supported parameters, reasoning support, top-provider details, expiration, and per-request limits.
+
+Routing rules:
+
+- Prefer canonical model IDs for deterministic budgets; `~...latest` aliases can change.
+- Refresh catalog with TTL and retain the last known-good snapshot.
+- Account for pricing overrides, cache pricing, reasoning, and request/tool surcharges.
+- Filter candidates by required capabilities before sorting by cost.
+- Provider-native fallbacks are useful for availability, but Jittor should record the actual served model/provider and cost.
+
+### Analytics API
+
+OpenRouter's beta Analytics API accepts management keys and can aggregate `total_usage`, token metrics, cache hit rate, reasoning tokens, model, API key, and generation dimensions. It is useful for calibration and audits, not pre-request routing. The API is beta: discover metadata dynamically, parse count metrics as number or string, and honor truncation metadata.
+
+## Normalized Jittor model
+
+```ts
+interface BudgetWindow {
+  source: "codex-subscription" | "openai-api" | "openrouter" | "jittor";
+  scope: string;
+  usedFraction: number | null;
+  usedAmount: number | null;
+  limitAmount: number | null;
+  unit: "provider-percent" | "usd" | "tokens" | "requests";
+  windowSeconds: number | null;
+  resetsAt: number | null;
+  observedAt: number;
+  freshness: "fresh" | "stale" | "failed";
+  confidence: number;
+}
+```
+
+For a resettable window:
+
+```text
+observed burn     = delta(used) / delta(time)
+sustainable burn = remaining / max(reset_at - now, minimum_horizon)
+pressure          = observed burn / sustainable burn
+```
+
+Token velocity and cost velocity are tracked separately per provider/model/thinking route. Decisions must include their input snapshot IDs and a human-readable explanation.
+
+## Pi enforcement points
+
+Verified Pi APIs support:
+
+- `input`: preflight and return `{action: "handled"}` for a hard stop before the agent starts.
+- `turn_start`: re-evaluate before each model/tool loop turn.
+- `pi.setModel(model)`: switch provider/model after resolving it through `ctx.modelRegistry`.
+- `pi.setThinkingLevel(level)`: lower reasoning effort, clamped to model support.
+- `after_provider_response`: observe status and provider headers before streaming.
+- `message_end`: record finalized assistant token/cost usage.
+- `ctx.abort()`: stop an active agent operation if a mid-run hard threshold is crossed.
+
+The Pi extension is an actuator and event collector. Policy, provider polling, history, and decisions live in the supervised Jittor daemon.
+
+## Initial policy ladder
+
+The policy engine is deterministic and configured by route tiers:
+
+1. `continue`
+2. `throttle(delayMs)`
+3. `lower-thinking(level)`
+4. `switch-model(provider, model, thinking)`
+5. `switch-provider(provider, model, thinking)`
+6. `halt(reason)`
+
+Required safeguards: hysteresis, cooldown, maximum delay, minimum telemetry freshness, explicit capability checks, route availability/auth checks, and no automatic retry of non-idempotent requests.
+
+## Sources
+
+### OpenAI / Codex
+
+- https://learn.chatgpt.com/docs/pricing#what-are-the-usage-limits-for-my-plan
+- https://developers.openai.com/codex/auth
+- https://developers.openai.com/codex/enterprise/analytics-api
+- https://developers.openai.com/api/docs/guides/rate-limits
+- https://github.com/openai/codex/blob/312caf176a8fd3a5897a3d1fd3ed0a283bd1b5ac/codex-rs/backend-client/src/client/rate_limit_resets.rs
+- https://github.com/openai/codex/blob/312caf176a8fd3a5897a3d1fd3ed0a283bd1b5ac/codex-rs/codex-api/src/rate_limits.rs
+- https://github.com/openai/codex/blob/312caf176a8fd3a5897a3d1fd3ed0a283bd1b5ac/codex-rs/tui/src/chatwidget/rate_limits.rs
+
+### OpenRouter
+
+- https://openrouter.ai/docs/api/reference/limits
+- https://openrouter.ai/docs/cookbook/administration/usage-accounting
+- https://openrouter.ai/docs/cookbook/administration/analytics-cost-control
+- https://openrouter.ai/docs/guides/overview/models
+
+### Pi
+
+- Pi extension lifecycle and model APIs: local `docs/extensions.md`
+- Pi model/provider configuration: local `docs/models.md`

package/docs/USAGE_PRIOR_ART.md

@@ -0,0 +1,64 @@
+# Token-usage TUI prior art
+
+Research performed before implementing Jittor's `/usage` frontend.
+
+## Local agent implementations
+
+### Claude Code
+
+`~/Repositories/claude/src/components/Stats.tsx` contains the strongest terminal chart precedent:
+
+- `generateTokenChart()` renders daily model-token series with an eight-row `asciichart` plot.
+- Width adapts to the terminal and is capped near 52 columns.
+- The top three models receive distinct theme colors.
+- The X axis places three or four date labels at even positions.
+- The Y axis abbreviates values as `k` and `M`.
+
+`~/Repositories/claude/src/utils/heatmap.ts` adds a GitHub-style activity view using percentile-derived `░▒▓█` intensity. `src/components/design-system/ProgressBar.tsx` uses eighth-cell Unicode blocks (`▏▎▍▌▋▊▉█`) for fractional precision.
+
+Useful decisions: adaptive width, short axes, bounded series count, theme colors, Unicode partial cells. The Jittor requirement is a histogram rather than Claude's line chart, so only the layout and scaling ideas are reused.
+
+### OpenCode
+
+`~/Repositories/opencode/packages/stats/core/src/domain/home.ts` keeps usage projection in the domain layer. It defines explicit ranges (`1D`, `1W`, `2W`, `1M`, `2M`, `3M`, `YTD`, `ALL`), computes date windows, creates deterministic buckets, and formats range-appropriate labels.
+
+Useful decision: range/window/bucket projection is separate from rendering and data access.
+
+### Codex
+
+`~/Repositories/codex` exposes turn-level `last` and `total` token usage plus account rate-limit snapshots. Its TUI focuses on compact totals and quota state; no reusable historical token histogram was found.
+
+Useful decision: finalized turn usage is the durable accounting point. Jittor already records Pi assistant usage on `message_end`.
+
+### Cline
+
+Cline tracks accumulated input/output/cache/cost values and presents context/cost in its status area. Its local CLI sources did not contain a historical terminal histogram comparable to the requested chart.
+
+Useful decision: preserve input, output, cache-read, and cache-write categories rather than collapsing accounting at ingestion.
+
+## Pi extensions
+
+Registry and package-source review covered:
+
+- `@pi-vault/pi-usage@0.6.0`: polished framed/tabbed dashboard, Today/This Week/Last Week/All Time tables, live provider quotas, width-safe theme adapters. It has no historical vertical token histogram.
+- `@sreetej510/pi-usage@0.1.20`: `/usage` provider quota reports, cache, retries, statusline, and 20-cell `█░` quota bars.
+- `@narumitw/pi-codex-usage@0.20.0`: Codex 5-hour/weekly quota bars and compact statusline.
+- `@alexanderfortin/pi-token-usage@0.3.0`: session-file aggregation and table/export overlay, but no chart.
+
+Useful decisions: native `registerCommand`, `ctx.ui.custom`, width-bounded rendering, theme-derived colors, keyboard refresh/range navigation, and daemon/cache-backed data rather than synchronous file scans in render.
+
+## OpenRouter visual reference
+
+OpenRouter's authenticated web dashboard is not distributed as reusable terminal source. Its relevant visual grammar is a compact time-bucket histogram with colored model/provider series, readable axes, totals, and a legend. Jittor reproduces that grammar with Unicode blocks rather than copying web implementation details.
+
+## Jittor design
+
+Jittor combines the best applicable patterns:
+
+1. Pure domain projection in `src/domain/usage.ts`.
+2. Explicit `24h`, `7d`, `30d`, and `90d` windows.
+3. Provider/model-preserving series and input/output/cache totals.
+4. Vertically scaled, colored, stacked Unicode bars with fractional top blocks.
+5. Width-safe X/Y axes and provider/model legend.
+6. Native `/usage` panel with Left/Right range switching and refresh.
+7. Data access only through authenticated daemon `metrics.query`; the extension never opens SQLite or reads provider credentials.