@gonrocca/zero-pi 0.1.24 → 0.1.26

package/README.md

@@ -14,9 +14,12 @@
 **The zero spec-driven development workflow, packaged for [pi](https://pi.dev).**
 
 [![npm](https://img.shields.io/npm/v/@gonrocca/zero-pi?color=af8aff&label=npm)](https://www.npmjs.com/package/@gonrocca/zero-pi)
+[![repo](https://img.shields.io/badge/repo-github-7497ff?logo=github&logoColor=white)](https://github.com/gonzalonicolasr/zero-pi)
 [![license](https://img.shields.io/npm/l/@gonrocca/zero-pi?color=eebe5c)](./LICENSE)
 [![node](https://img.shields.io/node/v/@gonrocca/zero-pi?color=4fddab&label=node)](https://nodejs.org)
 
+**Repositorio:** [github.com/gonzalonicolasr/zero-pi](https://github.com/gonzalonicolasr/zero-pi)
+
 </div>
 
 ---
@@ -195,12 +198,13 @@ re-derived.
 
 ### Provider guard — `provider-guard.ts`
 
-pi reaches the same Claude models through two providers: `pi-claude-cli` (billed
-against your subscription's plan limits) and `anthropic` (the direct API, billed
-per token from your metered extra-usage pool). The guard watches model switches:
-on a deliberate switch to a metered provider it offers — via a confirmation
-dialog — to redirect you to the equivalent model on `pi-claude-cli`. Say no and
-you stay put, no nagging. Switching to a subscription provider is a no-op.
+The `anthropic` provider runs two ways: a Claude Pro/Max **subscription** login
+(OAuth, via `/login` — `pi-claude-oauth-adapter` smooths this path) or an **API
+key**, which bills per token from your metered extra-usage pool. Same provider
+id, different billing. The guard watches model switches and reads pi's auth mode
+(`modelRegistry.isUsingOAuth`): when a model runs on `anthropic` with an API key
+it emits a single non-blocking warning suggesting `/login`. On OAuth, or on any
+other provider, it stays silent.
 
 ### Startup banner — `startup-banner.ts`
 

package/extensions/provider-guard-extension.ts

@@ -1,166 +1,105 @@
-// zero-pi — metered-provider guard, pi wiring.
+// zero-pi — Anthropic metered-billing guard, pi wiring.
 //
 // A thin pi extension that wires the pure decision logic in `provider-guard.ts`
-// to the `model_select` hook. Whenever pi reports a model switch, this handler
-// classifies it (in the pure module) and executes the resulting `GuardAction`:
-// a silent no-op for subscription providers, a non-blocking `warning` for a
-// metered provider with no equivalent (or a session `restore`), or — for a
-// deliberate switch to a metered provider that has an equivalent — a `confirm`
-// dialog offering to redirect to the subscription provider.
+// to the `model_select` hook. On every model switch it reads the auth mode from
+// `ctx.modelRegistry.isUsingOAuth` and, when the `anthropic` provider runs on an
+// API key (metered extra usage) rather than a Claude Pro/Max subscription OAuth
+// login, emits a single non-blocking `warning`.
 //
-// All decisions live in `provider-guard.ts`; this file only declares the
-// minimal pi-API surface it uses, hooks `model_select`, and performs the I/O
-// (`confirm`/`notify`/`setModel`). Both `register` and the handler are wrapped
-// in a swallowing `try/catch` — exactly like `autotune-extension.ts`, a failure
-// must never break a pi session. The package stays dependency-free: only
-// `provider-guard.ts` is imported (no `node:*` is needed here, no third party).
+// All decisions live in `provider-guard.ts`; this file declares the minimal
+// pi-API surface it uses, hooks `model_select`, and performs the I/O (`notify`).
+// Both `register` and the handler are wrapped in a swallowing `try/catch` — a
+// failure must never break a pi session. Dependency-free: only
+// `provider-guard.ts` is imported (no `node:*`, no third party).
 
-import {
-  classifyModelSwitch,
-  redirectFailedMessage,
-  type ModelLike,
-} from "./provider-guard.ts";
+import { classifyModelSwitch } from "./provider-guard.ts";
 
 // ---------------------------------------------------------------------------
 // Minimal local pi-API interfaces
 // ---------------------------------------------------------------------------
-//
-// `provider-guard-extension.ts` declares only the slice of pi's API it uses,
-// exactly like `autotune-extension.ts` and `zero-models.ts`. The guard never
-// depends on pi's full type surface — just the shapes below.
 
-/** The minimum a `Model` of pi must expose for the guard. Mirrors `ModelLike`
- *  of the pure module — `setModel`/the registry both speak this shape. */
+/** The minimum a `Model` of pi must expose for the guard. */
 interface PiModel {
   provider: string;
   id: string;
 }
 
-/** The model registry slice the guard uses: a `find` that resolves a model by
- *  `(provider, id)` or returns `undefined` when no such model exists. */
+/**
+ * The model-registry slice the guard uses. `isUsingOAuth` reports whether a
+ * model authenticates through a Claude subscription OAuth login rather than an
+ * API key. It is optional — older pi builds may not expose it (see
+ * `resolveOAuth`).
+ */
 interface PiModelRegistry {
-  find(provider: string, modelId: string): PiModel | undefined;
+  isUsingOAuth?(model: PiModel): boolean;
 }
 
-/** The slice of pi's UI surface the guard uses. `confirm` may be sync or async
- *  (pi versions differ); both are handled uniformly with `await`. */
+/** The slice of pi's UI surface the guard uses. */
 interface PiUI {
-  confirm(title: string, message: string): Promise<boolean> | boolean;
   notify(message: string, type?: "info" | "warning" | "error"): void;
 }
 
-/** The context pi passes to a `model_select` handler. `modelRegistry` is
- *  optional — if absent the guard degrades to warn-only (it can no longer
- *  resolve equivalents) rather than breaking. */
+/** The context pi passes to a `model_select` handler. */
 interface PiModelSelectContext {
   ui: PiUI;
   modelRegistry?: PiModelRegistry;
 }
 
-/** The `model_select` event pi emits on a model change. The guard only reads
- *  `model` and `source`; `source` is `set`/`cycle`/`restore` or, defensively,
- *  any other string a future pi version might report. */
+/** The `model_select` event pi emits on a model change. */
 interface PiModelSelectEvent {
   type: "model_select";
   model?: PiModel;
-  source?: "set" | "cycle" | "restore" | string;
 }
 
-/** The slice of pi's extension API the guard uses: `on` to hook events and
- *  `setModel` to apply a redirection. */
+/** The slice of pi's extension API the guard uses. */
 interface PiExtensionAPI {
   on(
     event: string,
-    handler: (event: PiModelSelectEvent, ctx: PiModelSelectContext) => void | Promise<void>,
+    handler: (event: PiModelSelectEvent, ctx: PiModelSelectContext) => void,
   ): void;
-  setModel(model: PiModel): Promise<boolean>;
 }
 
 // ---------------------------------------------------------------------------
 // Handler
 // ---------------------------------------------------------------------------
 
+/**
+ * Resolve whether `model` authenticates through subscription OAuth.
+ *
+ * Calls `modelRegistry.isUsingOAuth` when available. When the method is absent
+ * (older pi) or throws, it returns `true` — an unknown auth mode must never
+ * produce a false metered warning.
+ */
+function resolveOAuth(registry: PiModelRegistry | undefined, model: PiModel): boolean {
+  if (!registry || typeof registry.isUsingOAuth !== "function") return true;
+  try {
+    return registry.isUsingOAuth(model) !== false;
+  } catch {
+    // A registry failure degrades to "assume OAuth" — never a false warning.
+    return true;
+  }
+}
+
 /**
  * The `model_select` guard handler.
  *
- * Runs entirely inside `register`'s swallowing `try/catch`, but is also wrapped
- * again here so no failure of `find`/`confirm`/`notify`/`setModel` can ever
- * propagate out of a pi session. The flow:
+ * Wrapped in a swallowing `try/catch` so no failure can propagate out of a pi
+ * session. The flow:
  *
- *   1. Validate `event`/`event.model` — a malformed event returns cleanly.
- *   2. Build the injected `lookup` over `ctx.modelRegistry.find`, wrapped in a
- *      `try/catch` that returns `undefined`. If `modelRegistry` is absent,
- *      degrade to an always-`undefined` lookup (warn-only).
- *   3. `classifyModelSwitch(model, source, lookup)` → a `GuardAction`.
- *   4. Execute the action: `ignore` → no-op; `warn` → `notify(..., "warning")`;
- *      `offer-redirect` → `confirm`, and on a truthy answer `setModel` +
- *      `notify(..., "info")` (or the failure notice if `setModel` returns
- *      `false`). A falsy `confirm` leaves the user on the metered provider.
+ *   1. Validate `event`/`event.model`/`ctx.ui` — a malformed event bails out.
+ *   2. Resolve the auth mode via `resolveOAuth`.
+ *   3. `classifyModelSwitch(model, isOAuth)` → a `GuardAction`.
+ *   4. `warn` → `notify(..., "warning")`; `ignore` → no-op.
  */
-async function handleModelSelect(
-  event: PiModelSelectEvent,
-  ctx: PiModelSelectContext,
-  pi: PiExtensionAPI,
-): Promise<void> {
+function handleModelSelect(event: PiModelSelectEvent, ctx: PiModelSelectContext): void {
   try {
-    // 1. Malformed event — no event, no model, or no UI to talk to: bail out.
     if (!event || !event.model || !ctx || !ctx.ui || typeof ctx.ui.notify !== "function") {
       return;
     }
-
-    // 2. Build the injected lookup. `classifyModelSwitch` assumes a total
-    //    lookup, so `find` is wrapped in a `try/catch` returning `undefined`.
-    //    If `modelRegistry` is absent the guard cannot resolve equivalents —
-    //    degrade to an always-`undefined` lookup so a metered provider still
-    //    produces a warning rather than breaking.
-    const registry = ctx.modelRegistry;
-    const lookup = (provider: string, id: string): ModelLike | undefined => {
-      if (!registry || typeof registry.find !== "function") return undefined;
-      try {
-        return registry.find(provider, id);
-      } catch {
-        // A registry lookup failure degrades to "no equivalent", never throws.
-        return undefined;
-      }
-    };
-
-    // 3. Classify the switch in the pure module.
-    const action = classifyModelSwitch(event.model, event.source, lookup);
-
-    // 4. Execute the action.
-    if (action.kind === "ignore") {
-      // Non-metered provider or malformed event — nothing to do.
-      return;
-    }
-
+    const isOAuth = resolveOAuth(ctx.modelRegistry, event.model);
+    const action = classifyModelSwitch(event.model, isOAuth);
     if (action.kind === "warn") {
-      // Metered provider with no equivalent, or a session `restore` — a single
-      // non-blocking warning, no modal, no `setModel`.
       ctx.ui.notify(action.message, "warning");
-      return;
-    }
-
-    // action.kind === "offer-redirect" — deliberate switch to a metered
-    // provider that has a subscription equivalent. Offer the redirect; the
-    // `confirm` dialog itself is the user's escape (AC 1.5).
-    const accepted = await ctx.ui.confirm(action.confirmTitle, action.confirmMessage);
-    if (!accepted) {
-      // User declined or cancelled — leave them on the metered provider, no
-      // second warning, no `setModel`.
-      return;
-    }
-
-    const applied = await pi.setModel(action.safeModel);
-    if (applied) {
-      // Redirection took effect — confirm it with an `info` notification.
-      ctx.ui.notify(action.redirectMessage, "info");
-    } else {
-      // `setModel` returned `false`: the switch did not apply. Do not claim
-      // "redirected" — emit the optional failure notice instead.
-      ctx.ui.notify(
-        redirectFailedMessage(action.safeModel.id, action.safeModel.provider),
-        "warning",
-      );
     }
   } catch {
     // Any failure of the guard must never break a pi session.
@@ -175,20 +114,16 @@ async function handleModelSelect(
  * The pi extension entry point.
  *
  * pi calls this once when the extension loads. It wires the guard handler to
- * the `model_select` event. The whole body is wrapped in a swallowing
- * `try/catch`, and the handler is wrapped again, so neither registration nor a
- * later failure can ever break a pi session. Called with no or an invalid
- * `pi` (missing, or no `.on` function), it no-ops cleanly.
+ * the `model_select` event. The body is wrapped in a swallowing `try/catch`,
+ * and the handler is wrapped again, so neither registration nor a later failure
+ * can break a pi session. Called with no or an invalid `pi`, it no-ops cleanly.
  */
 export default function register(pi?: unknown): void {
   try {
     if (!pi || typeof (pi as PiExtensionAPI).on !== "function") {
       return;
     }
-    const api = pi as PiExtensionAPI;
-    api.on("model_select", (event: PiModelSelectEvent, ctx: PiModelSelectContext): Promise<void> => {
-      return handleModelSelect(event, ctx, api);
-    });
+    (pi as PiExtensionAPI).on("model_select", handleModelSelect);
   } catch {
     // Registration itself must never break a pi session.
   }

package/extensions/provider-guard.ts

@@ -1,48 +1,26 @@
-// zero-pi — metered-provider guard, pure-logic module.
+// zero-pi — Anthropic metered-billing guard, pure-logic module.
 //
-// pi can reach the same Claude models through two providers: `pi-claude-cli`
-// (routes via the locally installed Claude CLI, billed against the user's
-// subscription PLAN — no per-token charge) and `anthropic` (the direct
-// Anthropic API provider, which consumes a metered "extra usage" pool and
-// bills per token). `/model` lists the same models under both, so it is easy
-// to slide into metered billing unnoticed.
+// pi reaches Claude models through the `anthropic` provider with one of two
+// auth modes:
 //
-// This module holds every *decision* of the guard — classifying a model switch
-// into the action the wiring must run — in plain, dependency-free TypeScript so
-// it is testable with plain objects via `node --test`. The pi wiring (the
-// `model_select` handler that performs `confirm`/`notify`/`setModel`) lives in
-// `provider-guard-extension.ts`.
+//   • OAuth — a Claude Pro/Max subscription login (`/login`). The
+//     `pi-claude-oauth-adapter` package smooths this path. This is the mode
+//     to prefer: it authenticates against the Claude subscription.
+//   • API key — `ANTHROPIC_API_KEY`. This bills per token from the metered
+//     "extra usage" pool.
 //
-// This file has no pi imports, no filesystem access, and no side-effecting
-// top-level code; it is pure data plus an injected lookup function.
-
-/**
- * Mapping metered-provider → equivalent subscription-provider.
- *
- * A provider that appears as a *key* here is "metered" — switching to it
- * triggers the guard. The mapped *value* is the subscription provider the
- * guard offers to redirect to. v1 has exactly one pair; adding another
- * metered↔subscription pair is a single extra line.
- *
- * Invariant the no-redirect-loop guarantee depends on: a redirection target
- * (a *value*) must never itself be a *key*. `pi-claude-cli` is a value, not a
- * key, so the `setModel`-triggered second `model_select` event classifies as
- * `ignore` and the chain terminates.
- */
-export const METERED_TO_SUBSCRIPTION: Readonly<Record<string, string>> = {
-  anthropic: "pi-claude-cli",
-};
-
-/**
- * Origin of a model change, as pi reports it on `ModelSelectEvent.source`.
- * `set`/`cycle` are deliberate user actions; `restore` is a non-deliberate
- * session restore that must never raise a modal.
- */
-export type GuardSource = "set" | "cycle" | "restore";
+// Same provider id (`anthropic`), different billing. pi reports the auth mode
+// via `modelRegistry.isUsingOAuth(model)`, so the guard keys off that — not off
+// the provider name. (The earlier guard redirected `anthropic` → `pi-claude-cli`;
+// that provider is no longer used, so the redirect is gone.)
+//
+// This module holds the guard's decision in plain, dependency-free TypeScript
+// so it is testable with plain objects via `node --test`. The pi wiring (the
+// `model_select` handler that reads `isUsingOAuth` and calls `notify`) lives in
+// `provider-guard-extension.ts`. No pi imports, no filesystem, no side effects.
 
-/** The deliberate sources that may raise a redirect modal. Any other source
- *  (including `restore` and unknown strings) is treated as non-deliberate. */
-const DELIBERATE_SOURCES: readonly string[] = ["set", "cycle"];
+/** The pi provider whose billing depends on the auth mode. */
+export const METERED_PROVIDER = "anthropic";
 
 /** The minimum a `Model` of pi must expose for the guard to classify it. */
 export interface ModelLike {
@@ -51,67 +29,24 @@ export interface ModelLike {
 }
 
 /**
- * Injected registry-lookup function. The wiring builds this over
- * `ctx.modelRegistry.find`; the pure module never knows `modelRegistry` or any
- * pi type. Returns `undefined` when no equivalent model exists. The wiring is
- * responsible for wrapping `find` so this lookup is total — `classifyModelSwitch`
- * assumes a `lookup` that never throws.
- */
-export type RegistryLookup = (provider: string, id: string) => ModelLike | undefined;
-
-/**
- * The action the wiring must execute, as a discriminated union keyed on `kind`.
+ * The action the wiring must execute, a discriminated union keyed on `kind`.
  *
- * - `ignore` — no-op: non-metered provider, or a malformed event.
- * - `warn` — emit only `ctx.ui.notify(message, "warning")`; no modal, no
- *   `setModel`. Used for `restore`, for a metered provider with no equivalent,
- *   and for any non-deliberate source.
- * - `offer-redirect` — show `ctx.ui.confirm(confirmTitle, confirmMessage)`; on
- *   a truthy answer `setModel(safeModel)` and, if applied, notify with
- *   `redirectMessage`.
+ * - `ignore` — no-op: not the `anthropic` provider, `anthropic` on OAuth
+ *   (subscription), or a malformed event.
+ * - `warn` — emit `ctx.ui.notify(message, "warning")`: `anthropic` on an API
+ *   key, which bills metered extra usage.
  */
 export type GuardAction =
   | { kind: "ignore" }
-  | { kind: "warn"; message: string }
-  | {
-      kind: "offer-redirect";
-      safeModel: ModelLike;
-      confirmTitle: string;
-      confirmMessage: string;
-      redirectMessage: string;
-    };
+  | { kind: "warn"; message: string };
 
 // ---------------------------------------------------------------------------
-// User-facing Spanish strings
+// User-facing Spanish string
 // ---------------------------------------------------------------------------
-//
-// Exported as constants/functions so the test can assert them verbatim. `id`
-// is the model id (e.g. `claude-opus-4-7`); `metered`/`subscription` are the
-// provider names from `METERED_TO_SUBSCRIPTION`.
-
-/** Title of the redirect `confirm` dialog. */
-export const CONFIRM_TITLE = "zero · proveedor con cobro por token";
-
-/** Body of the redirect `confirm` dialog — explains the metered billing and
- *  asks whether to switch to the subscription equivalent. */
-export function confirmMessage(id: string, metered: string, subscription: string): string {
-  return `Estás cambiando a «${id}» vía el proveedor «${metered}», que factura por token y consume tu pool medido de extra usage. ¿Querés cambiar al equivalente «${id}» en «${subscription}», que usa los límites de tu suscripción?`;
-}
-
-/** `info` notification emitted after `setModel` succeeds. */
-export function redirectMessage(id: string, subscription: string): string {
-  return `zero: redirigido a «${id}» en ${subscription} — usando los límites de tu suscripción.`;
-}
 
-/** `warning` notification — no equivalent available, or `restore`. */
-export function warnMessage(id: string, metered: string): string {
-  return `zero: «${id}» está activo vía el proveedor «${metered}», que factura por token y consume tu pool medido de extra usage.`;
-}
-
-/** `warning` notification — `setModel` returned `false` (redirection did not
- *  apply). Optional; emitted by the wiring as a defensive courtesy. */
-export function redirectFailedMessage(id: string, subscription: string): string {
-  return `zero: no se pudo cambiar a «${id}» en ${subscription} — seguís en el proveedor medido.`;
+/** `warning` notification — the model runs on the metered `anthropic` API key. */
+export function warnMessage(id: string): string {
+  return `zero: «${id}» usa el provider «anthropic» con API key — factura por token (extra usage). Logueá con Claude Pro/Max vía /login para usar tu suscripción.`;
 }
 
 // ---------------------------------------------------------------------------
@@ -126,58 +61,38 @@ function isNonEmptyString(value: unknown): value is string {
 /**
  * Classify a model switch into the `GuardAction` the wiring must execute.
  *
- * Pure and total — never throws (assuming `lookup` is total, which is the
- * wiring's contract). The branches, in order:
+ * Pure and total — never throws. The branches, in order:
+ *
+ *   1. `model` falsy, or `provider`/`id` not non-empty strings → `ignore`
+ *      (malformed event).
+ *   2. `model.provider` is not `anthropic` → `ignore` (other providers carry
+ *      no OAuth-vs-API-key billing split this guard reasons about).
+ *   3. The provider is `anthropic`:
+ *        - `isOAuth` truthy → `ignore` (subscription auth — the intended path).
+ *        - `isOAuth` falsy → `warn` (API key — metered extra usage).
  *
- *   1. `model` falsy, or `model.provider`/`model.id` not non-empty strings →
- *      `ignore` (malformed event, AC 6.3).
- *   2. `model.provider` is not a key of `METERED_TO_SUBSCRIPTION` → `ignore`
- *      (non-metered provider, AC 4.1/4.2 — this also classifies `pi-claude-cli`,
- *      which is the structural no-redirect-loop guarantee, Story 5).
- *   3. The provider is metered. Resolve the subscription provider and call
- *      `lookup(subProvider, model.id)`:
- *        - `source === "restore"` → always `warn`, never a modal, regardless of
- *          whether an equivalent exists (AC 3.x).
- *        - `source` deliberate (`set`/`cycle`):
- *            - `lookup` found a model → `offer-redirect` (AC 1).
- *            - `lookup` returned `undefined` → `warn` (AC 2).
- *        - any other (unknown) `source` → treated as non-deliberate → `warn`
- *          (defensive: no modal unless the switch is known to be deliberate).
+ * `isOAuth` is supplied by the wiring from `modelRegistry.isUsingOAuth`. When
+ * the wiring cannot determine the auth mode it passes `true`, so an unknown
+ * state never produces a false warning.
  */
 export function classifyModelSwitch(
   model: ModelLike | null | undefined,
-  source: GuardSource | string | null | undefined,
-  lookup: RegistryLookup,
+  isOAuth: boolean,
 ): GuardAction {
   // 1. Malformed event — no model, or missing/empty provider/id.
   if (!model || !isNonEmptyString(model.provider) || !isNonEmptyString(model.id)) {
     return { kind: "ignore" };
   }
 
-  // 2. Non-metered provider — silent no-op (covers `pi-claude-cli`).
-  const subscriptionProvider = METERED_TO_SUBSCRIPTION[model.provider];
-  if (subscriptionProvider === undefined) {
+  // 2. Any provider other than `anthropic` — out of scope, silent no-op.
+  if (model.provider !== METERED_PROVIDER) {
     return { kind: "ignore" };
   }
 
-  // 3. Metered provider. A deliberate switch with an equivalent gets a modal;
-  //    everything else (restore, no equivalent, unknown source) gets a warn.
-  const meteredProvider = model.provider;
-  const id = model.id;
-  const isDeliberate = typeof source === "string" && DELIBERATE_SOURCES.includes(source);
-
-  if (isDeliberate) {
-    const safeModel = lookup(subscriptionProvider, id);
-    if (safeModel) {
-      return {
-        kind: "offer-redirect",
-        safeModel,
-        confirmTitle: CONFIRM_TITLE,
-        confirmMessage: confirmMessage(id, meteredProvider, subscriptionProvider),
-        redirectMessage: redirectMessage(id, subscriptionProvider),
-      };
-    }
+  // 3. `anthropic`: OAuth is the subscription path (fine); an API key is the
+  //    metered path (warn).
+  if (isOAuth) {
+    return { kind: "ignore" };
   }
-
-  return { kind: "warn", message: warnMessage(id, meteredProvider) };
+  return { kind: "warn", message: warnMessage(model.id) };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gonrocca/zero-pi",
-  "version": "0.1.24",
+  "version": "0.1.26",
   "description": "zero-pi — an installable layer for pi (pi.dev): the zero spec-driven development workflow, skill auto-learning, and an animated ZERO startup banner. Adds capability to pi without modifying pi.",
   "type": "module",
   "keywords": [