pi-zro-provider 1.0.0

package/.github/FUNDING.yml

@@ -0,0 +1,4 @@
+github: monotykamary
+ko_fi: monotykamary
+buy_me_a_coffee: monotykamary
+polar: monotykamary

package/AGENTS.md

@@ -0,0 +1,58 @@
+# AGENTS.md
+
+## DO NOT EDIT — Auto-generated Files
+
+The following files are **idempotent** and regenerated by `scripts/update-models.js`. Never edit them directly — your changes will be overwritten on the next model sync.
+
+| File | Why it's auto-generated |
+|------|------------------------|
+| `models.json` | Built from the Zro model catalog. `update-models.js` fetches `/api/cli/models`, preserves curated data for known IDs, and writes this file. |
+| `deprecated-models.json` | Graveyard for models the API delisted. update-models.js stamps them with deprecatedAt and pi keeps serving them for a 2-week grace period, then evicts them. Never edit by hand. |
+| `README.md` (model table) | The table under `## Available Models` is replaced in-place by `update-models.js` after merging base models → patch → custom models. |
+
+## Correct Files to Edit
+
+When a model needs overrides, new properties, or corrections, edit the appropriate source file below. These are the **source of truth** that the update script reads but never writes.
+
+| File | Purpose |
+|------|---------|
+| `patch.json` | Per-model overrides keyed by model ID. Add reasoning flags, compat settings, pricing corrections, thinking level maps, etc. Applied on top of `models.json` at runtime and for README generation. |
+| `custom-models.json` | Models that don't exist in the provider API (hidden models, router endpoints, cross-provider aliases). Merged after patch. Format: array of full model objects (same schema as `models.json` entries). |
+| `index.ts` | Provider extension code: model sync, streaming wrapper, footer-status wiring. |
+| `status.ts` | Footer-status presentation: config schema, USD/token formatters, progressive-disclosure tiers, width-aware widget. Pure module — no pi imports; exercised by `tests/status.smoke.ts`. |
+| `scripts/update-models.js` | The sync script itself (edit only if changing how models are fetched/transformed). |
+
+## Data Flow
+
+```
+Zro catalog  ──fetch──►  models.json  ──apply──►  patch.json  ──merge──►  custom-models.json
+                                    │                            │                      │
+                                    └────────────────────────────┴──────────────────────┘
+                                                      │
+                                              README model table
+```
+
+1. `models.json` — base data from the provider API (auto-generated, DO NOT EDIT)
+2. `patch.json` — overrides applied on top (EDIT THIS for corrections/enrichments)
+3. `custom-models.json` — additional models not in the API (EDIT THIS for new models)
+4. README table — rendered from the merged result of all three (auto-generated, DO NOT EDIT)
+
+## Common Tasks
+
+### Add a compat setting or override pricing for an existing model
+→ Edit `patch.json`. Add an entry keyed by the model's `id`.
+
+### Add a model not available in the provider API
+→ Edit `custom-models.json`. Add a full model object to the array.
+
+### Update models from the provider API
+→ Run `node scripts/update-models.js` (requires `ZRO_API_KEY` or a stored `zro login`).
+
+### Regenerate the README model table
+→ Run `node scripts/update-models.js` — it updates both `models.json` and the README table.
+
+## TL;DR
+
+- **Never edit `models.json`** — edit `patch.json` instead.
+- **Never edit the README model table** — run the update script instead.
+- `patch.json` and `custom-models.json` are the source files you should modify.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,232 @@
+<div align="center">
+
+# ✨ pi-zro-provider
+
+**3+ models through [Zro](https://zro.moonmath.ai)**
+
+_GLM-5.2, Kimi K3, and DeepSeek V4 Flash — run through the Zro inference endpoint with [pi](https://github.com/earendil-works/pi-coding-agent)._
+
+[![pi extension](https://img.shields.io/badge/pi-extension-blueviolet)](https://github.com/earendil-works/pi-coding-agent)
+[![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
+
+</div>
+
+---
+
+## Features
+
+- **3+ AI Models** — GLM-5.2 (default), Kimi K3, and DeepSeek V4 Flash, straight from Zro's production catalog
+- **Native reasoning effort** — every model ships its published `piLevel` → level-id map (`glm-5.2`: `off`/`high`/`max`, `kimi-k3`: `low`/`high`/`max`, `deepseek-v4-flash-0731`: `off`/`high`), so `/thinking high` etc. maps exactly to what the Zro proxy expects
+- **OpenAI-compatible API** at `https://zro.moonmath.ai/v1`
+- **Official catalog sync** from Zro's `/api/cli/models` endpoint — same one `zro models` uses
+- **Zro login reuse** — if you've run `zro login`, the extension picks up `~/.config/zro/credentials.json` automatically (no duplicated keys)
+- **Footer status widget** — session spend/tokens and account plan / available spend / usage packs / 30-day activity at a glance
+
+## Available Models
+
+| Model | Type | Context | Max Tokens | Input Cost | Output Cost |
+|-------|------|---------|------------|------------|-------------|
+| DeepSeek V4 Flash | Text | 1.0M | 384K | — | — |
+| GLM-5.2 | Text | 524K | 64K | — | — |
+| Kimi K3 | Text | 1.0M | 1.0M | — | — |
+*Costs are per million tokens. Billing is metered by your Zro plan and usage packs — see [zro.moonmath.ai](https://zro.moonmath.ai) for pricing.*
+
+## Installation
+
+### Option 1: Using `pi install` (Recommended)
+
+Install from npm:
+
+```bash
+pi install npm:pi-zro-provider
+```
+
+Or directly from GitHub:
+
+```bash
+pi install https://github.com/monotykamary/pi-zro-provider
+```
+
+Then make sure you're logged in (or set a key) and run pi:
+```bash
+# Recommended: reuse your zro CLI login
+zro login
+
+# Or set as environment variable
+export ZRO_API_KEY=your-api-key-here
+
+pi
+```
+
+Get your API key from [zro.moonmath.ai](https://zro.moonmath.ai).
+
+### Option 2: Manual Clone
+
+1. Clone this repository:
+   ```bash
+   git clone https://github.com/monotykamary/pi-zro-provider.git
+   cd pi-zro-provider
+   ```
+
+2. Make sure you have a Zro credential (any of the [Authentication](#authentication) options).
+
+3. Run pi with the extension:
+   ```bash
+   pi -e /path/to/pi-zro-provider
+   ```
+
+## Usage
+
+After loading the extension, select a model with:
+
+```
+/model zro glm-5.2
+```
+
+Or start pi directly with a Zro model:
+
+```bash
+pi --provider zro --model glm-5.2
+```
+
+### Reasoning Effort
+
+All Zro models are reasoning models. Control thinking depth with `/thinking` or the CLI:
+
+```bash
+pi --provider zro --model glm-5.2 --thinking xhigh
+```
+
+The available levels are model-specific and come straight from Zro's catalog:
+
+| Model | pi levels | Sent as `reasoning_effort` |
+|-------|-----------|----------------------------|
+| `glm-5.2` | `off`, `high`, `xhigh` | `none`, `high`, `max` |
+| `kimi-k3` | `low`, `high`, `xhigh` | `low`, `high`, `max` |
+| `deepseek-v4-flash-0731` | `off`, `high` | `none`, `high` |
+
+Levels map one-to-one through `thinkingLevelMap`, so `off` sends Zro's `none` token instead of silently dropping the field.
+
+### Footer Status
+
+A Neuralwatt-style status line sits below the editor. It appears after the
+session's first Zro turn completes (never before — no half-empty line on
+fresh sessions or other providers), refreshes its balance when the agent run
+fully settles, and makes no status-related API calls in sessions that never
+use Zro:
+
+```
+⚡ $0.42 · 7 req                   Pro ◆ $12.34 avail · $2.50 pack · 1.2k req/30d
+└─ session spend+requests ─┘     └─ plan · available spend · packs · activity ──┘
+```
+
+The left side tracks what the current session has sent/spent — tokens always,
+plus a cost extension when the response exposes one (no polling). The right
+side shows your plan name, total available spend, usage-pack balance, and
+30-day request/token activity from Zro's `/api/cli/status` endpoint — the
+same account view `zro status` prints — plus a request-rate atom from
+response headers when present. The right side compresses progressively as
+the terminal narrows, and turns to a warning color at/below the
+`lowBalanceUsd` threshold.
+
+### Configuration
+
+Edit `~/.pi/agent/extensions/zro.json` or run `/zro-status`:
+
+| Setting | Values | Default |
+|---------|--------|---------|
+| `session` | `widget` \| `statusbar` \| `off` | `widget` |
+| `account` | `widget` \| `statusbar` \| `off` | `widget` |
+| `hideOnOtherProvider` | `true` \| `false` | `true` |
+| `lowBalanceUsd` | number \| `null` | `10` |
+
+Non-interactive toggles:
+
+```
+/zro-status session widget|statusbar|off
+/zro-status account widget|statusbar|off
+/zro-status hide true|false
+/zro-status lowBalance 25|off
+/zro-status refresh
+/zro-status reset
+```
+
+
+## Authentication
+
+The Zro API key can be configured in multiple ways (resolved in this order):
+
+1. **`auth.json`** (recommended) — Add to `~/.pi/agent/auth.json`:
+   ```json
+   { "zro": { "type": "api_key", "key": "your-api-key" } }
+   ```
+   The `key` field supports literal values, env var names, and shell commands (prefix with `!`). See [pi's auth file docs](https://github.com/badlogic/pi-mono) for details.
+2. **Environment variable** — Set `ZRO_API_KEY`
+3. **`zro login` reuse** — If you've already run `zro login`, the extension reads `~/.config/zro/credentials.json` (`XDG_CONFIG_HOME` aware) automatically. No extra configuration needed.
+4. **Runtime override** — Use the `--api-key` CLI flag
+
+Get your API key from [zro.moonmath.ai](https://zro.moonmath.ai).
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `ZRO_API_KEY` | No | Your Zro API key (env var fallback) |
+| `ZRO_ENDPOINT_ROOT` | No | Override the endpoint root (default `https://zro.moonmath.ai`) |
+| `ZRO_AUTH_URL` | No | Override the authentication/API host (used by `zro login`; the extension resolves catalog/status from it too) |
+
+## Configuration
+
+Add to your pi configuration for automatic loading:
+
+```json
+{
+  "extensions": [
+    "/path/to/pi-zro-provider"
+  ]
+}
+```
+
+### Catalog and Compat Settings
+
+Model metadata matches the transform Zro's own pi adapter applies to its
+`/api/cli/models` catalog:
+
+- canonical ids, display names, context windows, and output caps
+- `thinkingLevelMap` built from each model's published reasoning levels
+  (`piLevel` → provider level id)
+- `compat.supportsReasoningEffort: true` and `maxTokensField: "max_tokens"`
+  (plain `openai-completions`, no custom `thinkingFormat`)
+- `supportsDeveloperRole: false`
+- all text-only inputs
+
+`patch.json` is reserved only for a verified provider regression and is
+currently empty.
+
+### Patch Overrides
+
+`patch.json` is applied on top of `models.json` only for verified endpoint
+corrections. It is currently empty because every live field comes from Zro's
+canonical model catalog.
+
+## Updating Models
+
+Run the update script to fetch the latest models from the Zro catalog:
+
+```bash
+node scripts/update-models.js        # uses zro login credentials
+# or
+ZRO_API_KEY=your-api-key node scripts/update-models.js
+```
+
+This will:
+1. Fetch models from `https://zro.moonmath.ai/api/cli/models`
+2. Regenerate `models.json` as pure metadata from the live catalog
+3. Apply overrides from `patch.json` only when building the README
+4. Remove custom models now available upstream from `custom-models.json`
+5. Reconcile delisted models through the 14-day `deprecated-models.json` grace layer
+6. Update `models.json` and the README model table
+
+## License
+
+MIT

package/custom-models.json

@@ -0,0 +1 @@
+[]

package/deprecated-models.json

@@ -0,0 +1 @@
+{}