Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@ daemonize = "0.5.0"
nix = { version = "0.31.3", features = ["signal", "process", "term"] }

[target.'cfg(windows)'.dependencies]
windows-sys = { version = "0.61.2", features = ["Win32_Foundation", "Win32_System_Threading"] }
windows-sys = { version = "0.61.2", features = ["Win32_Foundation", "Win32_Security", "Win32_Security_Authorization", "Win32_Storage_FileSystem", "Win32_System_Threading"] }

[dev-dependencies]
tempfile = "3.27.0"
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -123,7 +123,7 @@ cleared when the daemon stops.
| `eggpass login` | Sign in to a provider. |
| `eggpass logout` | Revoke and remove a provider credential. |
| `eggpass status` | Show provider login and server state. |
| `eggpass usage` | Read subscription usage where available. |
| `eggpass usage` | Show remaining subscription usage where available. |
| `eggpass run` | Start the server. Use `--foreground` to keep it in the terminal. |
| `eggpass stop` / `restart` | Stop or restart the server. |
| `eggpass port` / `host` | Show or change the listen address. Changes restart the server. |
Expand Down
10 changes: 9 additions & 1 deletion docs/commands.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,10 +66,18 @@ eggpass usage --provider xai # query one provider
eggpass usage --json # machine-readable report
```

Queries provider usage directly, without needing the daemon. This is a fresh request, not a cached or polled reading. The report describes usage as reported by each provider. On the default xAI `api` upstream, the reported consumer-subscription quota is separate from inference requests, which are billed to the xAI API tier. The report's caption reflects the configured upstream. If quota is unavailable, the report may include the latest inference HTTP status kept by the daemon in memory. That endpoint reports only per-provider client-facing HTTP status codes, not prompts or response bodies.
Queries provider usage directly, without needing the daemon. By default it queries only providers enabled in configuration. `--provider` can select one enabled provider; selecting a disabled provider, or running the command when none are enabled, returns an actionable configuration error. Human-readable output shows the percentage and bar for the allowance left, plus each available reset time and countdown; JSON preserves the provider-reported fields. On the default xAI `api` upstream, the reported consumer-subscription quota is separate from inference requests, which are billed to the xAI API tier. The report's caption reflects the configured upstream. If quota is unavailable, the report may include the latest inference HTTP status kept by the daemon in memory. That endpoint reports only per-provider client-facing HTTP status codes, not prompts or response bodies.

**Exit codes:** `0` if at least one provider is signed in and not every selected provider failed operationally, `1` if every selected provider failed operationally, `2` if none is signed in.

### Authenticated daemon endpoint: GET /v1/usage

The daemon also serves `GET /v1/usage` for clients that need a usage report over HTTP. Send the configured or issued Eggpass client key in `Authorization: Bearer <key>` or `X-Api-Key: <key>`. The response body uses the same `{"providers":[...]}` JSON structure as `eggpass usage --json`; it includes only enabled providers. If every provider is disabled, the endpoint returns a completed empty list. OpenAI/ChatGPT usage is queried only when that provider is enabled; the optional Codex app-server result may describe a different account from Eggpass's inference credential.

A complete report is retained only in daemon memory for 600 seconds from completion. Cache hits do not contact providers. A cold or expired request starts one shared refresh and its initiating client waits at most 30 seconds; if still running, that client receives `504` and the refresh continues. Other requests while it is active receive `202` with `Retry-After`. Timed-out providers alone are retried, for at most three retries after the initial attempt, spaced 5, 15, and 30 seconds apart. xAI usage HTTP requests have bounded 15-second request/body timeouts (and a 5-second connect cap); OAuth refresh requests have a 60-second total deadline, and the optional local Codex session has an 8-second deadline.

On success, responses include `Cache-Control: private, no-store`, `X-Eggpass-Usage-Age` (integer seconds), and `X-Eggpass-Usage-Updated-At` (RFC 3339 UTC). `last_inference` is attached from the daemon's current in-memory state on each response. After all timeout retries fail, the last successful report is returned with `X-Eggpass-Usage-Stale: true` during a 600-second cooldown; if no successful report exists, the endpoint returns `503` with `Retry-After`. A process restart clears the snapshot and cooldown. There is no polling, disk persistence, or force-refresh operation.

## `run`, `stop`, and `restart`

```sh
Expand Down
2 changes: 1 addition & 1 deletion docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@ The advanced `[oauth.xai]` settings are `client_id`, `issuer`, `scopes`, and `re

A client key is required to start the server, including when it listens only on loopback. Use `eggpass key add` to create a numbered, revocable key, or set `api_key` for one static key. The static key is readable in the config. Issued keys are shown once and stored as salted hashes. Clients may send either as `Authorization: Bearer <key>` or `X-Api-Key: <key>`.

The server listens on loopback by default. Binding to a non-loopback address exposes the proxy and the provider accounts it can use to the network. A key is required for that bind. The `GET /health` and `GET /v1/last-inference` probes are unauthenticated: health returns a JSON object with `status`, `service`, and a version string; last-inference returns only per-provider client-facing HTTP status codes. All other API requests require a valid key.
The server listens on loopback by default. Binding to a non-loopback address exposes the proxy and the provider accounts it can use to the network. A key is required for that bind. The `GET /health` and `GET /v1/last-inference` probes are unauthenticated: health returns a JSON object with `status`, `service`, and a version string; last-inference returns only per-provider client-facing HTTP status codes. `GET /v1/usage` is not an unauthenticated probe: it requires a valid Eggpass client key like every other data endpoint. It returns quota data for enabled providers, so do not expose it without protecting the server.

Eggpass runs locally, but inference requests are sent to the provider selected by routing. Prompts and request content are transmitted to xAI or ChatGPT for inference; they do not stay on this machine. `eggpass usage` also contacts providers directly to query usage, and `eggpass status` may contact them to count available models.

Expand Down
8 changes: 3 additions & 5 deletions docs/how-it-works.md
Original file line number Diff line number Diff line change
Expand Up @@ -73,11 +73,9 @@ Streaming responses are forwarded as chunks arrive. The proxy does not buffer
the full answer before sending it to the client. Provider errors keep their
status codes and error details where supported.

The `eggpass usage` command fetches current usage where a provider exposes it.
For ChatGPT, the OAuth flow has no quota endpoint, so the command reports usage
as unavailable rather than estimating it. The daemon keeps only the most recent
client-facing inference status for each provider in memory. It is not written
to a file and disappears when the daemon stops.
The `eggpass usage` command fetches current usage where a provider exposes it, and both it and the daemon endpoint query only providers enabled in configuration. For ChatGPT, the OAuth flow has no quota endpoint, so usage is unavailable rather than estimated; when OpenAI is enabled, the optional local Codex app-server may provide a report from a separate account.

The authenticated `GET /v1/usage` endpoint returns the CLI-compatible JSON report. It caches one complete snapshot in memory for 10 minutes, starts at most one demand-triggered refresh, and never polls or writes usage data to disk. Its initiating request waits up to 30 seconds; if that deadline expires it gets `504` while the finite refresh continues. Concurrent requests get `202` with `Retry-After`. A refresh retries only timed-out providers, up to three times at 5/15/30-second intervals. Each xAI billing/settings request is capped at 15 seconds; OAuth refresh has a 60-second total deadline and Codex has an 8-second session deadline. Success adds age and update-time headers; after retry exhaustion, a previous successful snapshot is marked stale during a 10-minute cooldown, or `503` is returned if no good snapshot exists. A daemon restart clears the cache. The latest inference status is read afresh for every report response.

## Updates

Expand Down
29 changes: 18 additions & 11 deletions docs/plans/cli-spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -658,7 +658,7 @@ be read or written, or the arguments were wrong.

## `eggpass usage`

Report how much of the subscription allowance is used.
Report how much of the subscription allowance remains.

```
eggpass usage # every provider you are signed in to
Expand Down Expand Up @@ -690,9 +690,9 @@ between blocks, no colour:

```
x.ai · SuperGrok
Weekly ████░░░░░░░░░░░░░░░░ 20% used
Resets Nov 20, 03:07 (UTC)
Api ██░░░░░░░░░░░░░░░░░░ 10% used
Weekly ████████████████░░░░ 80% left
Resets Nov 20, 03:07 (UTC) · in 2d 15hr
Api ██████████████████░░ 90% left
Prepaid $0.00
This is your Grok subscription. `eggpass` requests are billed separately against the xAI API tier.

Expand All @@ -710,18 +710,25 @@ ChatGPT

- **The label column is twelve characters wide**, so every value starts in the
same place.
- **The bar is twenty cells**, `█` filled and `░` empty. A non-zero
percentage always shows at least one cell, and the bar is omitted entirely
when the percentage is unavailable.
- **The number is the amount *used*.** It reads `20% used`, never `20% left`.
- **The bar is twenty cells**, `█` filled and `░` empty. It represents the
allowance left; a non-zero remainder always shows at least one cell, and the
bar is omitted entirely when the percentage is unavailable.
- **The number is the amount remaining.** It reads `80% left`. The JSON report
still preserves the provider's `used_percent` field unchanged.
- **Missing is not zero.** The Grok billing endpoint is proto3 JSON and omits
zero-valued scalars, so an absent percentage means the provider did not
say. It reads `unavailable`, never `0% used`.
say. It reads `unavailable`, never `0% left`.
- **A supplied duration labels its window**, such as `5-hour` or `7-day`, in
place of a generic `Primary` or `Secondary` label. Multiple Codex buckets keep
their bucket names when needed to distinguish otherwise identical windows.
A window is not invented when the provider does not report it, and there is
no separate Duration row.
- **An explicit state replaces the percentage.** When the provider says the
account is not eligible, that is the answer and no number is shown.
- **The reset time is local**, with its offset, because `Nov 18, 09:00` alone
is ambiguous. The year appears only when it differs from the current year.
A reset more than an hour in the past is marked `(stale)`.
is ambiguous. Future resets also show a compact countdown (for example,
`in 3hr 21m` or `in 3d 15hr`); the year appears only when it differs from
the current year. A reset more than an hour in the past is marked `(stale)`.
- **The caption is not optional.** On the default `api` upstream, `eggpass`'s
inference is metered against the xAI API tier and does **not** draw from
the consumer subscription the billing endpoint reports. The caption says
Expand Down
Loading
Loading