pi-meta-oauth 0.7.0 → 0.7.1

package/README.md

@@ -18,8 +18,10 @@ Meta Model API OAuth for [pi](https://pi.dev).
 ## Install
 
 ```bash
-# OAuth-only branch
-pi install git:github.com/BlockedPath/pi-meta-oauth@meta-oauth-only
+pi install npm:pi-meta-oauth
+
+# Or track main
+pi install git:github.com/BlockedPath/pi-meta-oauth
 
 # Or from a local checkout
 pi install /absolute/path/to/pi-meta-oauth
@@ -94,6 +96,17 @@ count. Pi writes the cache during interactive or RPC startup, and again after
 not itself trigger a network catalog refresh. The cached catalog is also used
 when Pi starts without network access.
 
+On Pi 0.86.1 and later, Pi's built-in pi.dev catalog overlay for `meta` shares
+this store entry and refreshes before the extension. The extension persists its
+catalog with `lastModified: 0` and `source: "pi-meta-oauth"`, so the overlay
+skips pi.dev for 4 hours after a successful Meta refresh. On restore, entries
+written by the overlay are ignored in favor of the bundled models, and the base
+URL is always `https://api.meta.ai/v1`. If a Meta refresh fails after the
+overlay wrote its entry, the extension republishes its last good catalog. If
+pi.dev fails while the cached Meta entry is missing, older than 4 hours, or
+written by an earlier release, Pi aborts that refresh before the Meta catalog is
+fetched.
+
 The bundled fallback uses Meta's nominal `1,048,576`-token context window. A
 cached Muse Code 0.1.0/R708.1 catalog observed on 2026-08-06 reported a lower
 effective limit of `1,007,997` for `muse-spark-1.2` and
@@ -107,14 +120,58 @@ catalog.
 ```bash
 pi --list-models meta
 pi -p --provider meta --model muse-spark-1.3 "Reply exactly: META_OK"
-bun run typecheck
-bun test
+bun install --frozen-lockfile
+bun run check
 ```
 
-`bun test` is hermetic unless a Meta credential is already available. The live cache-hit probe makes real billable API calls when a credential resolves: two identical `/v1/responses` calls (asserting `cached_tokens` on the second), plus one 2s retry if that second call misses cache. The live fingerprint probe makes two tiny Contributor-`max` calls: one without the fingerprint (status logged only) and one with it (asserting HTTP 200). It sends the header directly and does not depend on `META_MUSE_USER_AGENT`. The credential is resolved, in order, from `PI_META_LIVE_API_KEY`, `META_API_KEY`, `MODEL_API_KEY`, or the minted key from `~/.pi/agent/auth.json` after `/login meta` (skipped if expired). OAuth is enough — you do not need a separate key. Skipped when no valid credential exists (CI):
+`bun run check` runs Biome, TypeScript, and the hermetic test suite. Use
+`bun run test` for tests alone, or pass a file or test filter after the command.
+The launcher clears Meta credentials in the child process, disables dotenv
+loading, and gives it an empty temporary home. Your environment and stored
+credentials are preserved. CI uses the same command and committed lockfile.
+
+Live probes require the explicit `bun run test:live` command. Direct `bun test`
+also bypasses isolation and can run these probes when credentials are available.
+The cache probe makes two billable Responses requests plus one retry on a cache
+miss. The fingerprint probe makes two tiny Contributor-`max` requests; it sends
+the header directly, independently of `META_MUSE_USER_AGENT`. The catalog probe
+runs when `PI_META_LIVE_API_KEY` is set. Cache and fingerprint probes resolve
+credentials from `PI_META_LIVE_API_KEY`, `META_API_KEY`, `MODEL_API_KEY`, or an
+unexpired minted key in `~/.pi/agent/auth.json`, in that order. Probes skip when
+no usable credential exists.
 
 ```bash
-bun test tests/meta-cache.test.ts
+bun run test:live tests/meta-cache.test.ts
 # or, if you are not logged in:
-PI_META_LIVE_API_KEY='LLM|...' bun test tests/meta-cache.test.ts
+PI_META_LIVE_API_KEY='LLM|...' bun run test:live tests/meta-cache.test.ts
 ```
+
+## Development
+
+`extensions/meta.ts` is the only registered Pi extension. It registers the
+provider; implementation modules live in `src/meta/` and ship with
+the package:
+
+- `oauth.ts`: device authorization, cancellable polling, key minting, and refresh.
+- `models.ts`: fresh fallback definitions and validation of remote/cached models.
+- `model-store.ts`: catalog refresh and Pi 0.83/0.84+ persistence compatibility.
+- `muse-policy.ts` and `request-policy.ts`: opt-in effort gating and request hints.
+- `provider.ts`, `environment.ts`, `http.ts`, `constants.ts`, and `types.ts`:
+  provider assembly and request-local streaming, key aliases, shared transport,
+  and common definitions.
+
+The provider's stream adapter applies cache hints and the opt-in fingerprint
+using the in-flight request's model and endpoint, not the session's current
+selection. Switching models during request preparation cannot apply Meta
+settings to another provider's request. Explicit headers and cache-retention
+values remain authoritative, including payloads replaced by caller callbacks.
+
+Network JSON and persisted catalogs are validated before becoming Pi model
+definitions. Each provider configuration owns its model metadata; mutations
+cannot alter later configurations or cached entries. Login honors Pi's abort
+signal across authorization, polling, and minting. Catalog persistence remains
+best-effort and uses the host's generation check when available.
+
+Use `bun run format` to apply formatting and safe lint fixes, and
+`bun run lint` or `bun run typecheck` for individual checks. The extension's
+existing named exports remain available from `extensions/meta.ts`.