From db776e0bccc81f48a24e67017be6f83d19a200d8 Mon Sep 17 00:00:00 2001 From: pekth <5535435+pekth@users.noreply.github.com> Date: Sat, 17 Oct 2026 11:16:11 -0400 Subject: [PATCH] docs: update public beta to build 61 --- CHANGELOG.md | 72 ++++++ README.md | 39 +-- docs/API_USAGE_BETA.md | 275 +++++++++++----------- docs/BETA.md | 55 +++-- docs/DEMO.md | 94 ++++---- docs/KB.md | 11 +- docs/SCREENSHOTS.md | 15 +- docs/VERSIONS.md | 12 +- docs/images/beta-notch-claude.png | Bin 98738 -> 98738 bytes docs/images/beta-notch-codex.png | Bin 145252 -> 145025 bytes docs/images/beta-settings-api.png | Bin 0 -> 171687 bytes docs/images/beta-settings-appearance.png | Bin 104887 -> 80423 bytes docs/images/beta-settings-connections.png | Bin 190353 -> 183284 bytes docs/images/beta-social-preview.png | Bin 166003 -> 237314 bytes docs/images/beta-usage-claude.png | Bin 129446 -> 127097 bytes docs/images/beta-usage-codex.png | Bin 179831 -> 176449 bytes 16 files changed, 337 insertions(+), 236 deletions(-) create mode 100644 docs/images/beta-settings-api.png diff --git a/CHANGELOG.md b/CHANGELOG.md index 782ee6b..d3c225f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -38,6 +38,78 @@ follows [Semantic Versioning](https://semver.org/). link directly to the current Apple silicon app ZIP, and keep build commands in the contributor guide instead of the README. +## [0.3.0-beta.3] - 2026-10-17 + +### Release + +- Publish signed and notarized Electron build 61 for Apple silicon. Keep the + stable Swift download and updater unchanged. Refresh beta documentation and + screenshots, including the separate API connections page. +- Reuse the verified build from source c2d092c. Source/package checks passed; + native timing, broad provider compatibility and complete billing acceptance + remain disclosed beta limits. + +### Added + +- Show Grok Bot Desktop quota burn in percentage points per hour from recent + same-account readings. Collect for at least a minute, discard old/reset + observations and show an estimated run-out only when measured. +- Add separate OpenAI API and Anthropic API billing cards backed by projected + owner-only snapshots. A bundled one-run helper uses existing environment-only + organization Admin keys. Keep API billing distinct from subscription quota + and estimates; show report periods, capture age and stale state. Live billing + acceptance remains pending. +- Add an explicit Antigravity Desktop connection in Electron setup and Settings. + Read account allowance from one running, signed-in desktop language server + without requiring `agy`. Keep CLI selection explicit and local activity + separate. Synthetic fixtures cover identity changes, unavailable quota, + transport limits and cancellation. Native and live-provider acceptance remain + pending beyond the owner-confirmed live connection. + +### Changed + +- Move API setup to its own Settings sidebar page. OpenAI and Anthropic API + setup now accepts a one-time Admin key and fetches billing directly, with no + Terminal steps. Existing legacy Admin keys can be reused through a read-only + Keychain action; newly pasted keys are not saved. Account connections and + onboarding stay separate. + +- Connect new Grok Bot accounts through **Grok Bot Desktop (Beta)** after + explicit consent. Read only the active account-bound encrypted access token and team + through a fixed Keychain item; use a bounded read-only allowance request with + MeterUsage's own headers. Reject identity/team/store changes and cancelled + results. Keep saved Cursor connections compatible and CLI selection explicit. + No token refresh, app writes or separate xAI sign-in is added. Native store, + Keychain and endpoint compatibility remain incomplete beta acceptance. +- Shorten heatmap hover/focus totals to values such as `42.4B tokens` and + `1.6K sessions` across local and account history. Keep exact grouped counts + in tooltips and accessibility labels. Summary counts compact from 1,000. + +### Fixed + +- Preload the tray usage window hidden after completed onboarding, before + connection recovery or provider collection. The first click reuses the loaded + renderer instead of starting its initial load. +- Read Grok Bot's account-bound encrypted legacy v10 access values and correct + its fixed Keychain account to Grok Bot Key. Preserve scope, expiry, identity, + cancellation and store checks; reject plaintext and unsupported encryption. +- Give 30-day provider activity the same 26-column, seven-row heatmap layout. + Keep older unavailable dates distinct from measured zero-token days. +- Add **Use local OpenCode** setup for key-free Go session history and restore + executable Bun-install discovery for the read-only SQL fallback. +- Name saved legacy Grok connections as Cursor sources while new connections + use Grok Bot Desktop. + +- Group Antigravity Desktop limits under compact model headings and shorten + remaining-allowance labels to match the CLI presentation. Preserve every + reported bucket, its used percentage and reset. Keep account allowance + separate from CLI activity, and describe unavailable saved connections + without claiming a live connection. +- Exclude Apple's system `CursorUIViewService` from the Cursor editor process + guard. Continue rejecting active Cursor processes and unsafe database state. +- Show the running app bundle's version in Settings instead of the legacy + hardcoded version. Source previews omit the version when none is supplied. + ## [0.3.0-beta.1] - 2026-10-16 ### Added diff --git a/README.md b/README.md index 8f4cd67..db60f98 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ Swift app remains the stable download and rollback option during migration. | Edition | Current status | Setup and behavior | | --- | --- | --- | -| Electron 0.3.0-beta.1, build 54 | Public beta for Apple silicon, macOS 13+; signed and notarized | [Download beta](https://github.com/pekth/meterusage/releases/tag/v0.3.0-beta.1) · [Beta guide](docs/BETA.md) | +| Electron 0.3.0-beta.3, build 61 | Public beta for Apple silicon, macOS 13+; signed and notarized | [Download beta](https://github.com/pekth/meterusage/releases/tag/v0.3.0-beta.3) · [Beta guide](docs/BETA.md) | | Legacy Swift 0.2.41 | Frozen for new features; published stable download and migration rollback | [Swift guide](docs/swift/README.md) | Electron is the active app for new features. Swift remains the stable download @@ -29,16 +29,19 @@ and the [version strategy](docs/VERSIONS.md). Electron beta hover card and compact side-notch usage rail

-Synthetic demo captures of build 54's renderer. Claude Desktop provides allowance, +Synthetic demo captures of build 61's renderer. Claude Desktop provides allowance, not a chat-history heatmap. See the [full screenshot gallery and capture details](docs/SCREENSHOTS.md) for Codex, Claude, side notch and Settings. The beta includes Codex browser sign-in/account history, optional Claude Desktop allowance, existing CLI sources, compact provider tabs and hover cards, provider reordering and readable token totals. Account coverage depends on the source. -Grok remains Beta and CLI-only; Antigravity desktop login is follow-up work. -Build 54's Settings footer incorrectly says `0.2.41`; the packaged version is -`0.3.0-beta.1`. See [known beta limits](docs/BETA.md#known-limits). +The beta also includes Antigravity Desktop allowance, Grok Bot Desktop (Beta), +key-free OpenCode Go local setup and separate [API billing](docs/API_USAGE_BETA.md) +under Settings → API connections. Reuse a legacy saved Admin key or enter a +one-time key. Pasted keys are not saved. OpenRouter retains its existing balance +and activity integration. Desktop compatibility and billing coverage vary; +see [known beta limits](docs/BETA.md#known-limits). ## Stable Swift installation @@ -68,13 +71,15 @@ All nine provider adapters remain in the retained Swift and candidate source: Codex, Claude Code, Antigravity, OpenRouter, Grok, OpenCode Go, Cursor, Copilot CLI and Gemini CLI. Their inputs and available measurements differ. The [Swift provider matrix](docs/swift/README.md#provider-matrix) describes existing -CLI/local collection. The [Electron source choices](https://github.com/pekth/meterusage/blob/v0.3.0-beta.1/docs/electron/README.md#source-choices) +CLI/local collection. The [Electron source choices](https://github.com/pekth/meterusage/blob/v0.3.0-beta.3/docs/electron/README.md#source-choices) also describe optional Codex browser sign-in and Claude Desktop allowance. Local activity covers this Mac. Provider-reported account data has its own -coverage limits. Missing tokens remain unknown; costs are estimates and provider -dashboards remain the billing source of record. Read the [privacy contract](docs/PRIVACY.md) -before changing a data source or sharing screenshots. +coverage limits. Missing tokens remain unknown. Local token costs are estimates; optional API +billing cards label provider-reported amounts separately. Provider dashboards +remain the billing source of record. Read the [beta privacy contract](https://github.com/pekth/meterusage/blob/v0.3.0-beta.3/docs/PRIVACY.md) +for Electron or the [Swift privacy contract](docs/PRIVACY.md) before changing a +data source or sharing screenshots. ## Can both editions coexist? @@ -82,20 +87,20 @@ The beta tag contains the Electron source and retained Swift tree. The default branch retains stable Swift source during migration; the intended end state is one Electron app. Normal-profile side-by-side installation is unsafe: the app name, bundle ID and default preferences/data locations are shared. -Use only the documented [isolated candidate QA profiles](https://github.com/pekth/meterusage/blob/v0.3.0-beta.1/docs/electron/README.md#isolated-qa) +Use only the documented [isolated candidate QA profiles](https://github.com/pekth/meterusage/blob/v0.3.0-beta.3/docs/electron/README.md#isolated-qa) for testing. A separate app identity and data root require a later decision; -there is no automatic cutover. See [ADR 0010](https://github.com/pekth/meterusage/blob/v0.3.0-beta.1/docs/adr/0010-macos-typescript-electron.md). +there is no automatic cutover. See [ADR 0010](https://github.com/pekth/meterusage/blob/v0.3.0-beta.3/docs/adr/0010-macos-typescript-electron.md). ## Documentation - [Beta download, verification and limits](docs/BETA.md) - [Current beta screenshots](docs/SCREENSHOTS.md) - [Swift guide](docs/swift/README.md) -- [Electron guide and known gaps](https://github.com/pekth/meterusage/blob/v0.3.0-beta.1/docs/electron/README.md) +- [Electron guide and known gaps](https://github.com/pekth/meterusage/blob/v0.3.0-beta.3/docs/electron/README.md) - [Versions and staged Swift retirement](docs/VERSIONS.md) - [Contributing](CONTRIBUTING.md) - [Project knowledge](docs/KB.md) and [decision index](docs/adr/README.md) -- [Desktop connections](https://github.com/pekth/meterusage/blob/v0.3.0-beta.1/docs/DESKTOP-CONNECTIONS.md), [demo mode](docs/DEMO.md) +- [Desktop connections](https://github.com/pekth/meterusage/blob/v0.3.0-beta.3/docs/DESKTOP-CONNECTIONS.md), [demo mode](docs/DEMO.md) and [side notch](docs/SIDE-NOTCH.md) - [Concept mockups](docs/mockups/README.md) and [changelog](CHANGELOG.md) @@ -108,11 +113,11 @@ the Swift guide; product screenshots now show the Electron beta. See [downloads](#download). -See the [Electron candidate guide](https://github.com/pekth/meterusage/blob/v0.3.0-beta.1/docs/electron/README.md). +See the [Electron candidate guide](https://github.com/pekth/meterusage/blob/v0.3.0-beta.3/docs/electron/README.md). See [Swift additional local accounts](docs/swift/README.md#second-accounts) and -[Electron advanced local accounts](https://github.com/pekth/meterusage/blob/v0.3.0-beta.1/docs/electron/README.md#advanced-local-accounts). +[Electron advanced local accounts](https://github.com/pekth/meterusage/blob/v0.3.0-beta.3/docs/electron/README.md#advanced-local-accounts). See [Swift requirements](docs/swift/README.md#requirements). @@ -122,7 +127,7 @@ See [contributor setup](CONTRIBUTING.md). See the [Swift Agent Budget CLI](docs/swift/README.md#agent-budget-cli) and -[Electron commands](https://github.com/pekth/meterusage/blob/v0.3.0-beta.1/docs/electron/README.md#build-and-test). +[Electron commands](https://github.com/pekth/meterusage/blob/v0.3.0-beta.3/docs/electron/README.md#build-and-test). @@ -145,7 +150,7 @@ See [installation details](docs/swift/README.md#download-and-installation). See [beta diagnostics and bug reports](docs/BETA.md#known-limits) and the -[reporting guide](docs/REPORTING.md). +[beta reporting guide](https://github.com/pekth/meterusage/blob/v0.3.0-beta.3/docs/REPORTING.md). See [downloads](#download). diff --git a/docs/API_USAGE_BETA.md b/docs/API_USAGE_BETA.md index d1d9246..d5409e2 100644 --- a/docs/API_USAGE_BETA.md +++ b/docs/API_USAGE_BETA.md @@ -1,141 +1,142 @@ -# API usage tracking beta - -> **Status: Research proposal; not implemented.** meterusage does not currently fetch OpenAI API or Anthropic API organization usage or cost data. - -This proposal adds provider-reported API spend to meterusage without mixing it with Codex or Claude subscription usage. It is a documentation-only research record. `README.md` and `docs/PRIVACY.md` stay unchanged until an implementation is approved and verified. - -## Supported provider findings - -### OpenAI API - -OpenAI documents organization-level usage endpoints and an organization costs endpoint. The costs response supports time buckets and grouping fields. Access requires an organization Admin API key, which has broader authority than a project API key. - -Official sources: - -- [Usage API reference](https://platform.openai.com/docs/api-reference/usage) -- [Costs endpoint reference](https://platform.openai.com/docs/api-reference/usage/costs) -- [Administration overview](https://platform.openai.com/docs/api-reference/administration) - -### Anthropic API - -Anthropic documents organization usage and cost reports through the Admin API. The reports support time buckets and grouping by fields such as workspace and model. Access requires an organization Admin API key. Anthropic states that Priority Tier costs are not included in the cost report. - -Official sources: - -- [Usage and cost API](https://platform.claude.com/docs/en/manage-claude/usage-cost-api) - -### Other providers - -Other providers remain research candidates. They should enter this beta only when they expose a documented aggregate usage or billing API with a clear authentication contract. Per-request token fields and local price calculations are not substitutes for a provider-reported billing total. - -## Proposed beta boundary - -The first beta would support only OpenAI API and Anthropic API organization spend. It would be disabled by default and would not change the menu-bar label. - -The beta would report: - -- current UTC-month spend from the provider's cost report -- daily spend for the last seven days -- request and token totals when the provider reports them -- the last successful snapshot time -- loading, stale, unavailable, and authentication-error states - -Provider cost reports would remain distinct from meterusage's locally estimated token costs. The interface must label provider-reported amounts as billing data and local calculations as estimates. - -## Proposed snapshot-helper flow - -```mermaid -flowchart LR - A[User starts local helper] --> B[Helper reads admin key from its process environment] - B --> C[Official provider usage and cost API] - C --> D[Drop project, workspace, key, and account identifiers] - D --> E[Write owner-readable normalized snapshot] - E --> F[meterusage reads snapshot] - F --> G[OpenAI API or Anthropic API spend card] +# API billing snapshots + +Electron 0.3.0-beta.3, build 61 includes separate OpenAI API and Anthropic API +billing cards. OpenRouter keeps its existing account +balance, key limits and aggregate activity integration. + +## What the cards report + +OpenAI API and Anthropic API show provider-reported USD cost buckets for the +current UTC month through the request time. They are separate from Codex +and Claude subscriptions and from locally estimated token costs. Empty reports +remain unavailable; a provider-reported zero is displayed as zero. These cards +do not invent token counts, budgets or quota percentages. + +The card shows the report period and exact snapshot time. A snapshot becomes +stale after 24 hours or a UTC-month change. A prior month's snapshot retains +its own period. Refresh rereads the file; it does not fetch billing or make an +old snapshot fresh. Anthropic's cost report excludes Priority Tier costs. Neither +provider's report replaces its dashboard or invoice. + +## Set up in Settings + +1. Open **Settings → API connections**. +2. If you saved an Admin key in the previous MeterUsage, click **Use saved key** for that provider. Approve macOS Keychain access if asked. This fetches billing without entering the key again. +3. Otherwise, create an organization Admin key in **OpenAI Platform → Organization settings → Admin keys**, or **Anthropic Console → Settings → Admin keys**. +4. Paste the key into the matching provider's masked field and click **Fetch billing**. + +MeterUsage clears the field on submit and updates the billing snapshot after a +successful request. Pasted keys are not saved. Use **Use saved key** again to +refresh with an existing Keychain key; otherwise, enter a one-time key. Leaving the API page clears unsubmitted input. A normal project key or +ChatGPT or Claude subscription sign-in cannot read organization billing. + +The key passes through the trusted Settings bridge to a one-time main-process +request to that provider. A pasted key never enters preferences, Keychain, diagnostic +reports or billing snapshots. There is no background billing fetch. Demo and +isolated profiles cannot fetch billing. Keep keys out of chat and documentation. + +Authentication failure means the key is invalid or lacks organization access. +Data unavailable means no supported report could be fetched. Check the provider +billing dashboard; a failed fetch preserves the previous snapshot. Refresh +rereads snapshots without contacting the billing API. + +Saved-key access reads only the previous app's fixed `com.meterusage.api-keys` +Keychain service and `openAI` or `anthropic` account. The key stays in the main +process and native helper; it is never returned to the UI or copied elsewhere. +The original entry is not changed or deleted. Missing and denied entries show +a fixed error, with no environment or other-account fallback. Keychain is read +only after the explicit action, never at startup or during polling. + +## Advanced: use the helper + +The bundled environment-only helper remains available. Open Terminal on your +Mac, paste the matching command below, then paste the Admin key at the hidden +prompt and press Return. The commands use macOS zsh. The entered key is not a +command, so it does not enter shell history. The subshell supplies only the +selected environment variable to the helper and exits afterward. The parent +shell and MeterUsage do not save the entered key. Never put a key in command +text, a profile, a repository or chat. + +OpenAI API: + +```zsh +( + IFS= read -rs 'OPENAI_ADMIN_KEY?Paste OpenAI Admin key (hidden): ' || exit 1 + print + export OPENAI_ADMIN_KEY + ELECTRON_RUN_AS_NODE=1 /Applications/MeterUsage.app/Contents/MacOS/meterusage \ + /Applications/MeterUsage.app/Contents/Resources/api-usage-helper.cjs openai +) ``` -The recommended beta uses a separate, short-lived local helper. The helper reads an existing Admin API key from its process environment, calls the official API, removes identifiers, and writes a normalized snapshot with owner-only file permissions. meterusage reads the snapshot and does not receive or persist the key. - -The snapshot should contain only the fields needed for display and freshness checks: - -- provider identity -- bucket start and end timestamps -- currency and amount -- aggregate request, input-token, output-token, and cache-token counts when available -- snapshot creation time -- schema version - -The helper must not write a key, authorization header, raw provider response, organization identifier, project identifier, workspace identifier, user identifier, or API-key identifier to disk or logs. +Anthropic API: -This proposal does not define a command for supplying credentials. Any later setup documentation must preserve the current rule against asking users to paste keys into meterusage. - -## Separate product identities - -API billing must use identities that are separate from the existing Codex and Claude providers. Suggested display names are `OpenAI API` and `Anthropic API`. - -This separation prevents an API cost snapshot from replacing or being presented as: - -- Codex subscription quota -- Claude subscription activity or optional quota windows -- OpenRouter usage and account balance -- locally estimated model costs - -The storage key, settings toggle, refresh status, diagnostics entry, and card must use the API-specific identity throughout the data path. - -## Security and privacy constraints - -Organization Admin API keys can expose organization-wide usage and cost data. The beta must treat them as high-authority credentials. - -- meterusage must not provide a key-entry field. -- meterusage must not read, display, log, cache, or persist an Admin API key. -- The helper must keep the key in memory only for one fetch run. -- The helper must use documented HTTPS endpoints and reject non-success responses without writing their raw bodies to logs. -- Snapshots must exclude account, organization, project, workspace, user, and key identifiers. -- Snapshots must use owner-only file permissions and an atomic replacement write. -- Diagnostics must report provider, freshness, and error category without including request or response bodies. -- Fixtures and tests must use synthetic values. -- A future implementation requires security and privacy review before release. - -The existing OpenRouter path proves that meterusage can show authenticated aggregate usage while retaining only display-safe fields. It does not remove the need for a separate review because OpenAI and Anthropic require organization-level admin credentials for these reports. - -## UX concept - -Each API provider would have an optional card in the popover and a separate Settings toggle. The card would lead with current-month spend, followed by a seven-day daily trend and secondary usage totals. It would always show the snapshot timestamp. - -State labels should be explicit: - -- `Not configured` when no snapshot exists -- `Updated