@llblab/pi-kit 0.24.0 → 0.25.0

package/AGENTS.md

@@ -20,7 +20,7 @@
 
 - Start work from `BACKLOG.md` and inspect the included package manifests before changing pins or resource paths.
 - Keep `dependencies`, `bundledDependencies`, Pi resource paths, README inventory, tests, and lockfile synchronized.
-- Bundle every included Pi package so npm installation is self-contained under this package's module root.
+- Bundle every included Pi package so npm installation is self-contained under this package's module root. Keep repository-local `legacy-peer-deps=true` so host-provided Pi peers are not resolved into the kit's lockfile; Pi supplies them at runtime.
 - Expose only resources declared by each included package. Prefer published distribution entrypoints over source entrypoints when both exist.
 - Do not copy extension source, Skills, or documentation into this repository.
 - Preserve package independence: a kit release may advance any subset of included extensions without forcing lockstep extension releases.

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to `@llblab/pi-kit` are documented here.
 
+## 0.25.0 - 2026-10-02
+
+- `State Flow Modes`: Advances the exact State Flow pin from `0.21.0` to `0.23.0`. Adds sparse-state handling and session-owned modes; new sessions now default to Off while retained choices and explicit global policy survive. Telegram adds mode radios and scope explanations, with opt-in barrier diagnostics. No State Flow memory is erased by switching modes.
+- `Claude Subscription Usage`: Adds the independently released `@llblab/pi-claude-usage@0.1.1` as an eighth bundled member and seventh extension entrypoint. It shows Claude Pro/Max quota windows using Pi Anthropic OAuth, with shared cross-instance refresh and optional Telegram status. Existing Codex Usage stays at `0.10.0`.
+- `Host Peer Isolation`: Repository-local npm peer settings keep Pi-provided packages out of the kit lockfile and validation audit; Pi continues to supply them at runtime. The six unchanged member pins, existing resource order, Skill ownership and Pi minimum remain unchanged; the new Claude entrypoint is inserted explicitly.
+
+## 0.24.1 - 2026-09-26
+
+- `Follower Thread Hotfix`: Advances the exact Telegram pin to `0.51.5`. Telegram `/new` in a follower Thread now replaces that follower's session while the leader durably authorizes the Thread binding handoff; automatic follower restore reports why it could not reconnect. Package membership, load order, and other pins remain unchanged.
+
 ## 0.24.0 - 2026-09-25
 
 - `Minimal State Flow Reconciliation`: Advances the exact State Flow pin to `0.21.0`. Frozen context heads retain cache-stable prefixes while predictable accepted writes omit redundant semantic tails. Shared drift, changed hints and unknown fallback still reconcile; lazy bodies and provenance remain hidden. Artifact prediction cannot reject an already accepted patch. Canonical storage, other package pins, resources and load order are unchanged.

package/README.md

@@ -13,18 +13,19 @@ Package links lead to the owning repositories for usage, documentation, issues,
 | Package | Version | Purpose |
 | --- | ---: | --- |
 | [`@llblab/pi-actors`](https://github.com/llblab/pi-actors) | `0.53.2` | Inspectable local Runs, reusable Recipes, persistent tools, and delegation Skills |
+| [`@llblab/pi-claude-usage`](https://github.com/llblab/pi-claude-usage) | `0.1.1` | Claude Pro/Max subscription quota status using Pi's Anthropic OAuth login |
 | [`@llblab/pi-clean-room`](https://github.com/llblab/pi-clean-room) | `0.2.0` | Isolated nested Pi TUI with named npm extensions and compatible model selection |
 | [`@llblab/pi-codex-usage`](https://github.com/llblab/pi-codex-usage) | `0.10.0` | Compact Codex/Spark subscription-limit and Business credit-usage status |
 | [`@llblab/pi-grow-loop`](https://github.com/llblab/pi-grow-loop) | `0.8.2` | Visible continuation scheduling and bounded worker Skills through compiled, manifest-owned resources |
-| [`@llblab/pi-state-flow`](https://github.com/llblab/pi-state-flow) | `0.21.0` | Incremental scoped context/memory compiler with cache-stable heads, sparse acceptance reconciliation, lazy isolation, private fork memory, and optional Git backup |
-| [`@llblab/pi-telegram`](https://github.com/llblab/pi-telegram) | `0.51.4` | Telegram companion with resolver-owned filterable Skills, compiled distribution, self-healing follower registration, in-flight model switching, files, voice, and controls |
+| [`@llblab/pi-state-flow`](https://github.com/llblab/pi-state-flow) | `0.23.0` | Scoped context/memory compiler; new sessions default to Off with opt-in Passive/Active and Telegram mode controls |
+| [`@llblab/pi-telegram`](https://github.com/llblab/pi-telegram) | `0.51.5` | Telegram companion with follower Thread `/new`, restore diagnostics, filterable Skills, files, voice, and controls |
 | [`@llblab/skills`](https://github.com/llblab/skills) | `1.15.0` | Portable workflows for engineering, review, design, context maintenance, and other focused tasks |
 
 Versions are exact by design. An upstream release does not change an installed kit until this repository explicitly advances the dependency and publishes a new kit version. Runtime defects and package-specific feature requests belong in the linked repository; package selection and kit installation issues belong here.
 
 ## Install
 
-Requires **Pi 0.87.0+** and **Node.js 22.19.0+**. State Flow requires its canonical checkpoint/tail storage format and does not convert unsupported stores in place. Preserve existing stores and consult the [owning package's storage guidance](https://github.com/llblab/pi-state-flow/blob/v0.19.0/docs/usage.md#moving-a-store-and-the-017-format-boundary) before changing installations.
+Requires **Pi 0.87.0+** and **Node.js 22.19.0+**. State Flow requires its canonical checkpoint/tail storage format and does not convert unsupported stores in place. Preserve existing stores and consult the [owning package's storage guidance](https://github.com/llblab/pi-state-flow/blob/v0.23.0/docs/usage.md#moving-a-store-and-the-017-format-boundary) before changing installations.
 
 From npm:
 
@@ -38,7 +39,7 @@ From GitHub:
 pi install git:github.com/llblab/pi-kit
 ```
 
-Pi loads the six extension entrypoints and the Skill resources explicitly declared by the kit. The kit adds no runtime behavior and does not copy the packages' source or instructions into a new owner. State Flow remains opt-in; bundling it does not enable its state handoff mode.
+Pi loads the seven extension entrypoints and the Skill resources explicitly declared by the kit. The kit adds no runtime behavior and does not copy the packages' source or instructions into a new owner. State Flow remains opt-in; bundling it does not enable its state handoff mode.
 
 Prefer the kit instead of separately loading the same packages. If you already use individual installations or local Skill copies, use `pi config` to disable duplicate resources. Installing the kit does not remove or rewrite those installations.
 
@@ -49,7 +50,7 @@ npm install
 npm run validate
 ```
 
-To advance an included package, update its exact version in `dependencies`, run `npm install`, synchronize bundled dependencies, declared resource paths, tests, the table above, and the changelog, then validate the packed artifact. Expose only resources declared by the published owning package; do not use version ranges or unpublished local paths.
+The repository-local `.npmrc` keeps Pi-provided peer packages out of the kit's lockfile; Pi supplies those peers at runtime. To advance an included package, update its exact version in `dependencies`, run `npm install`, synchronize bundled dependencies, declared resource paths, tests, the table above, and the changelog, then validate the packed artifact. Expose only resources declared by the published owning package; do not use version ranges or unpublished local paths.
 
 ## Security
 

package/node_modules/@llblab/pi-claude-usage/AGENTS.md

@@ -0,0 +1,20 @@
+# Agent Notes
+
+- `Statusline-first scope`: Keep this extension zero-configuration and focused on compact status surfaces.
+  - Trigger: Considering commands, menus, persisted settings, or notification output.
+  - Action: Prefer deleting the surface unless it is required for the optimistic TUI status widget or the optional `pi-telegram` `/start` status-line mirror.
+- `Optimistic refresh`: Preserve the last good statusline bar during refresh and transient failures.
+  - Trigger: Updating quota polling or error handling.
+  - Action: Do not collapse the bar while a request is in flight; only show `n/a` or `error` after repeated failures or no usable quota.
+- `Adaptive compact status`: Match the status representation to the server-provided quota windows.
+  - Trigger: Changing statusline formatting.
+  - Action: When both windows exist, keep the classic dual bar with 20 top steps for the 5-hour window and 20 bottom steps for the weekly window. When only one weekly window exists, show its rounded remaining percentage directly instead of using a bar.
+- `Weekly reset countdown`: Append the weekly reset countdown whenever the available weekly window exposes a reset time.
+  - Trigger: Changing reset-time normalization or statusline refresh cadence.
+  - Action: Map `five_hour` to the primary window and `seven_day` to the secondary (weekly) window; treat a sole window as weekly. Keep `d` labels rounded upward in 144-minute day-tenth steps above 24h, show 24h..1h labels in upward-rounded 6-minute hour-tenth steps, keep `m`/`s` labels floored, and hold `0s` until a successful quota refresh reports the next window.
+- `Pi auth only`: Usage is read from `https://api.anthropic.com/api/oauth/usage` with the Pi `anthropic` provider OAuth token (`sk-ant-oat…`) and the `anthropic-beta: oauth-2025-04-20` header.
+  - Trigger: Touching auth or adding usage sources.
+  - Action: Do not add fallbacks, CLI probes, or API-key paths; API keys have no subscription quota, so report `n/a`. `utilization` is a used percent.
+- `Rate-limit discipline`: Quota polling must be shared across instances; HTTP 429 triggers shared backoff.
+  - Trigger: Changing refresh cadence, retries, locking, or adding fetch paths.
+  - Action: Keep the single shared-state protocol in the `Shared Refresh` section of `index.ts` (leader refreshes every minute, takeover after 90 seconds by claiming leadership before fetching, a non-waiting OS-backed SQLite mutex around claiming and fenced publication, atomic writes, shared failure backoff). Always re-read the file for request authorization (`owner` + `claimId` + lease) and publication; do not use an in-memory ownership fallback. Lock failures and failed claim writes must deny requests. `mutex.sqlite` stores no quota or leadership data: never unlink/replace it while instances run or evict a paused holder; close or process death releases the mutex. Keep network calls outside critical sections. Instances otherwise only read the file; never add per-instance polling or probing requests.

package/node_modules/@llblab/pi-claude-usage/BACKLOG.md

@@ -0,0 +1,3 @@
+# Backlog
+
+No open implementation items.

package/node_modules/@llblab/pi-claude-usage/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.1.1: Trusted CI Publication
+
+- Releases use the configured npm Trusted Publisher for GitHub Actions, with provenance and workflow-owned GitHub Release creation. Public-package verification now allows approximately 30 minutes for npm processing, with a 35-minute step limit, while retaining exact commit and package-inventory checks.
+- Quota polling, OAuth authentication, shared-state coordination, and statusline behavior are unchanged from 0.1.0.
+
+## 0.1.0: Claude Subscription Usage
+
+- Initial standalone release, adapted from [pi-codex-usage](https://github.com/llblab/pi-codex-usage), for Claude Pro/Max subscriptions. Reads the 5-hour and 7-day quota windows using Pi's Anthropic OAuth login; API-key-only auth reports `n/a`.
+- Shows remaining quota in a compact dual bar, with reset countdowns, animated loading, exhausted-quota highlighting, and optimistic display during refreshes or transient failures. A single available window uses a remaining percentage. Optionally mirrors the same value in the `pi-telegram` status menu.
+- Coordinates all local Pi instances through one shared `usage.json`: the leader refreshes every minute, followers normally read every 30 seconds, and takeover becomes eligible after 90 seconds. Shared failure backoff, including HTTP 429, prevents independent polling.
+- Uses an OS-backed SQLite mutex, atomic JSON writes, and on-disk claim generation/lease checks to deny requests when coordination fails and discard superseded results. Requires Node ≥22.19.0 and a local filesystem. **Upgrade from development versions:** close all old Pi sessions before starting this version; never delete or replace `mutex.sqlite` while sessions run.

package/node_modules/@llblab/pi-claude-usage/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 narumiruna
+Copyright (c) 2026 llblab
+
+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/node_modules/@llblab/pi-claude-usage/README.md

@@ -0,0 +1,110 @@
+# pi-claude-usage
+
+> Minimal zero-configuration Pi extension for showing Anthropic Claude subscription usage limits in the statusline
+
+![Claude Usage](./banner.jpg)
+
+This repository is an adaptation of [`pi-codex-usage`](https://github.com/llblab/pi-codex-usage) for Anthropic Claude Pro/Max subscriptions. It keeps the statusline design, but reads quota from the Anthropic OAuth usage endpoint using Pi's own Anthropic login.
+
+## Start Here
+
+- [Agent Notes](./AGENTS.md)
+- [Backlog](./BACKLOG.md)
+- [Changelog](./CHANGELOG.md)
+
+## Features
+
+- Shows two counter-moving half-height markers in the statusline bar while quota is loading, then keeps the bar fresh (the countdown ticks locally)
+- Keeps the last usable bar visible during ordinary refreshes instead of replacing known quota with a loading state
+- Dual bar: the top half shows the 5-hour session window and the bottom half shows the 7-day window, 20 steps (5% each) per window
+- If only one window is returned, shows its remaining percentage and reset countdown instead of a bar
+- Shown only while the active model uses the Pi `anthropic` provider
+- When `pi-telegram` is available, the same compact value appears as `claude: <value>` in the `/start` menu status text
+- Missing OAuth auth, API-key-only auth, or missing quota windows are shown as `n/a`, not as an error
+- Network/provider failures keep the last good bar, then show `error` after repeated failures
+- Any number of Pi instances share one request stream, see [Shared Refresh](#shared-refresh)
+- No commands or configuration are required
+
+## Install
+
+From npm:
+
+```bash
+pi install npm:@llblab/pi-claude-usage
+```
+
+From git:
+
+```bash
+pi install git:github.com/llblab/pi-claude-usage
+```
+
+## Statusline
+
+```text
+claude ██████▀▀▀▀ 6d
+```
+
+The ten-character bar encodes two twenty-step limits at once: the top quadrants show the remaining 5-hour limit and the bottom quadrants show the remaining weekly limit. If either window is exhausted, the bar keeps its shape but switches to the error background color.
+
+When the weekly reset time is available, it follows the bar. More than a day remains is shown in 144-minute day-tenth steps such as `7d`, `6.9d`, `1.1d`, rounded upward. At 24 hours and below it switches to upward-rounded hour-tenths such as `24h`, `23.7h`, `1.1h`, `1h`. Under an hour it shows floored minutes, then seconds. After the reset passes, `0s` is held until the next successful refresh.
+
+When the 5-hour window is exhausted and exposes its reset time, the statusline adds it before the weekly reset:
+
+```text
+claude ▄▄▄▄▄⠀⠀⠀⠀⠀ 5h/7d
+```
+
+If only one window is returned, the exact remaining percentage is shown:
+
+```text
+claude 67% 7d
+```
+
+Unavailable (no Anthropic subscription auth):
+
+```text
+claude n/a
+```
+
+Runtime failure, such as a network or provider error (including rate limiting of the usage endpoint):
+
+```text
+claude error
+```
+
+## Shared Refresh
+
+The coordination code lives in the `Shared Refresh` section of [`index.ts`](./index.ts); the extension ships as a single TypeScript source file.
+
+To avoid independent polling, instances coordinate through `~/.pi/agent/tmp/pi-claude-usage/usage.json` (percentages and timestamps only, no tokens):
+
+- The instance that last updated the file is the leader and refreshes it every minute
+- Every other instance only reads the file (re-checking every ≤30s) and redraws when it changes
+- Leadership is never cached in memory: before each usage request, the instance re-reads the file and checks its `owner`, unique `claimId`, and 90s lease. Publication rechecks that claim under the lock; a superseded success or failure is discarded. Failed locks or unwritten claims never authorize a request
+- If the file is 90 seconds old (leader is closed, busy, or asleep), the first follower that obtains the mutex takes over: it re-reads the JSON, writes itself as the leader with a fresh timestamp, releases the mutex, then fetches from the server and publishes under the mutex after rechecking its claim. Its next refresh is one minute later; JSON writes remain atomic renames
+- Claiming and publication use a non-waiting transaction in `mutex.sqlite`, through Node's built-in `node:sqlite` (Node ≥22.19.0, the existing package minimum). It stores no quota or leadership records and needs no extra package or service. The OS releases the lock when the connection closes or the process dies; there is no timeout-based lock stealing
+- Failures are written to the file with an exponential backoff (1 to 5 minutes; 5 to 30 minutes for HTTP 429) that applies to all instances
+- The last report stays visible for up to an hour; after that `error` is shown
+
+Coordination assumes a local filesystem and cooperating instances on the same machine. Never delete or replace `mutex.sqlite` while instances are running. Network requests do not hold the mutex; a process paused inside a short critical section keeps it until it resumes or exits, so other writers retry later without blocking the TUI. This preserves exclusion instead of stealing a live lock.
+
+**Upgrade:** Close all old instances before starting updated ones. The legacy `lock` files are ignored; old and new locking protocols must not run together. Cached `usage.json` data needs no migration.
+
+## Telegram Status Menu
+
+If `@llblab/pi-telegram` is loaded with the public status-line provider API, this extension registers an optional `/start` menu status row while the active model uses the Anthropic provider:
+
+```text
+claude: ██████▀▀▀▀ 6d
+```
+
+If `pi-telegram` is absent or older, or the active model is not Anthropic, no Telegram row is added.
+
+## Auth
+
+The extension uses the OAuth token of Pi's `anthropic` provider (`/login` → Anthropic Claude Pro/Max) and calls `GET https://api.anthropic.com/api/oauth/usage` with the `anthropic-beta: oauth-2025-04-20` header. Pi refreshes the token as needed. Anthropic API keys are not subscription auth and do not expose these quotas.
+
+## License
+
+MIT. See [`LICENSE`](./LICENSE).