pi-requesty-discover 2.0.0 → 2.1.0

package/CONTRIBUTING.adoc

@@ -32,4 +32,5 @@ Notes:
 * Keep implementation in `src/`; root `index.ts` is just the package entrypoint.
 * Edit `README.adoc` if necessary.
 * See `AGENTS.md` for detailed repository conventions.
+* See `docs/DECISIONS.adoc` for deliberate design decisions.
 * I am pretty good at identifying AI slop 😁.

package/README.adoc

@@ -18,6 +18,7 @@ This is a fork of https://github.com/requestyai/pi-requesty[pi-requesty] with ad
 * Health-check available models and write a log about them
 * Brief information about what was found, including added/removed models, health summary
 * Confirm before writing `models.json`, with a dry-run mode that only previews
+* A footer status line showing your monthly Requesty spend against your monthly limit
 
 == When and why use it
 
@@ -27,6 +28,7 @@ Use this extension if
 - you are limited to certain models by a company policy (for instance, for data residency/protection reasons)
 - you don't want to handcraft your own curated list of models constantly
 - you want to health-check models and preview the diff before writing
+- you want to keep in touch with your usage without having to constantly visit the Requesty dashboard
 
 == Installation
 
@@ -142,3 +144,23 @@ After a successful write, run `/reload`.
 ----
 
 Same discovery and health checks, but never prompts to write and leaves `models.json` unchanged.
+
+== Usage status
+
+The extension shows your current Requesty monthly spend as a persistent line in Pi's footer, e.g.:
+
+[source,text]
+----
+Requesty Usage (<API Key Name>): $63.55/$150.00 (42%)
+----
+
+When your API key has no monthly limit (`monthly_limit` is `0`), the limit is treated as unlimited:
+
+[source,text]
+----
+Requesty Usage (<API Key Name>): $63.55 (unlimited)
+----
+
+When you select a model from a provider other than `REQUESTY_PROVIDER_ID`, the status is cleared — there is no Requesty usage to show for it. If `REQUESTY_API_KEY` is not configured, the status is left untouched.
+
+NOTE: The footer update is best-effort and never blocks a turn. If it fails (network error, stale context after `/reload`), it fails silently without spamming notifications.

package/README.md

@@ -10,6 +10,7 @@ This is a fork of [pi-requesty](https://github.com/requestyai/pi-requesty) with
 * Health-check available models and write a log about them
 * Brief information about what was found, including added/removed models, health summary
 * Confirm before writing `models.json`, with a dry-run mode that only previews
+* A footer status line showing your monthly Requesty spend against your monthly limit
 
 ## When and why use it
 
@@ -19,6 +20,7 @@ Use this extension if
 * you are limited to certain models by a company policy (for instance, for data residency/protection reasons)
 * you don’t want to handcraft your own curated list of models constantly
 * you want to health-check models and preview the diff before writing
+* you want to keep in touch with your usage without having to constantly visit the Requesty dashboard
 
 ## Installation
 
@@ -108,3 +110,22 @@ After a successful write, run `/reload`.
 ```
 
 Same discovery and health checks, but never prompts to write and leaves `models.json` unchanged.
+
+## Usage status
+
+The extension shows your current Requesty monthly spend as a persistent line in Pi’s footer, e.g.:
+
+```text
+Requesty Usage (<API Key Name>): $63.55/$150.00 (42%)
+```
+
+When your API key has no monthly limit (`monthly_limit` is `0`), the limit is treated as unlimited:
+
+```text
+Requesty Usage (<API Key Name>): $63.55 (unlimited)
+```
+
+When you select a model from a provider other than `REQUESTY_PROVIDER_ID`, the status is cleared — there is no Requesty usage to show for it. If `REQUESTY_API_KEY` is not configured, the status is left untouched.
+
+**📌 NOTE**\
+The footer update is best-effort and never blocks a turn. If it fails (network error, stale context after `/reload`), it fails silently without spamming notifications.

package/docs/DECISIONS.adoc

@@ -0,0 +1,36 @@
+= Decision records
+
+Short notes for non-obvious decisions: context, decision, why not the obvious alternative.
+
+== Usage status stays on `setStatus` (shared, truncated footer line)
+
+Pi's `FooterComponent` joins all extensions' `setStatus` entries on one line and
+ellipsis-truncates the joined line to terminal width. No per-key layout, no wrap.
+
+`ctx.ui.setFooter(factory)` is replacement-only — it swaps the whole footer (pwd,
+tokens, context %, model, statuses), and the factory gets `footerData` but not
+token/model state. No "extra footer" API exists.
+
+Decision: keep `setStatus`. Revisit when the line overflows visibly with other
+extensions' statuses, or if the usage string grows past a typical width.
+
+== Not a provider — a models.json-writing extension
+
+Context: Requesty already works as a Pi provider via `models.json`. The temptation
+is to make this extension *be* the provider: read the model list from the Requesty
+API, hold it in memory, surface usage stats, let Pi manage the API key.
+
+Why not:
+
+- Health-checking is the core value and has no home in a provider. A provider serves
+  models; it doesn't vet them. The health check plus the diff/confirm/write flow is a
+  discovery-and-selection step, not serving.
+- A provider keeps its model list in-memory and refreshes occasionally. Here the
+  list is a persistent on-disk snapshot (`models.json`) — constant until you re-run
+  `/requesty-discover`. That matches the intent: an explicit, reviewed, user-confirmed write,
+  after which Pi's normal provider machinery serves the models.
+
+The provider-like parts (API model fetch, usage footer, wanting Pi-managed auth) are
+real, but the health check and the snapshot model break the provider fit.
+
+Decision: stay a `/requesty-discover` command that writes `models.json`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-requesty-discover",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Discover available Requesty models for the Pi Coding Agent",
   "repository": {
     "type": "git",

package/src/env.ts

@@ -5,6 +5,8 @@ import { getAgentDir } from '@earendil-works/pi-coding-agent'
 
 const HealthCheckModeSchema = z.enum(['off', 'basic', 'full']).default('full')
 
+export const DEFAULT_PROVIDER_ID = 'requesty-export'
+
 export type Env = {
   models_json_path: string
   health_check_log_path: string
@@ -28,7 +30,7 @@ export function getEnv(): Env {
   return {
     models_json_path: path.join(agentPath, 'models.json'),
     health_check_log_path: path.join(agentPath, 'requesty-health-check.log'),
-    provider_id: envVars.REQUESTY_PROVIDER_ID ?? 'requesty-export',
+    provider_id: envVars.REQUESTY_PROVIDER_ID ?? DEFAULT_PROVIDER_ID,
     requesty_api_key: apiKey,
     health_check_mode: result.data,
   }

package/src/index.ts

@@ -1,4 +1,9 @@
-import { ExtensionAPI, ExtensionCommandContext, ProviderModelConfig } from '@earendil-works/pi-coding-agent'
+import {
+  ExtensionAPI,
+  ExtensionCommandContext,
+  ExtensionContext,
+  ProviderModelConfig,
+} from '@earendil-works/pi-coding-agent'
 import { type Env, getEnv } from './env'
 import {
   diffModels,
@@ -7,12 +12,13 @@ import {
   type ModelsDiff,
   updateModelsJson,
 } from './models-json'
-import { discoverModels } from './requesty-api'
+import { type ApiKeyInfo, discoverModels, fetchApiUsage } from './requesty-api'
 import { checkModels, formatHealthSummary, writeHealthCheckLog } from './health-check'
 import { RequestyStatusLoader } from './ui/requesty-status-loader.ts'
 
 const COMMAND_NAME = 'requesty-discover'
 const DRY_RUN_ARG = '--dry-run'
+export const USAGE_STATUS_KEY = 'requesty-usage'
 
 interface AutocompleteItem {
   value: string
@@ -55,6 +61,9 @@ type EvaluationResult =
     }
   | { ok: false; error: unknown }
 
+// A per-instance token suppresses stale writes when turns overlap
+let latestToken: object = {}
+
 // noinspection JSUnusedGlobalSymbols
 export default function (pi: ExtensionAPI) {
   pi.registerCommand(COMMAND_NAME, {
@@ -64,6 +73,18 @@ export default function (pi: ExtensionAPI) {
       await runDiscoveryWorkflow(ctx, args)
     },
   })
+
+  pi.on('turn_end', (_event, ctx) => {
+    void updateUsageStatus(ctx)
+  })
+
+  pi.on('session_start', (_event, ctx) => {
+    void updateUsageStatus(ctx)
+  })
+
+  pi.on('model_select', (_event, ctx) => {
+    void updateUsageStatus(ctx)
+  })
 }
 
 export async function runDiscoveryWorkflow(ctx: ExtensionCommandContext, args: string) {
@@ -272,3 +293,48 @@ function createLoaderStatusReporter(loader: RequestyStatusLoader): StatusReporte
     },
   }
 }
+
+export async function updateUsageStatus(ctx: ExtensionContext): Promise<void> {
+  if (!ctx.hasUI) return // no footer to write to (print/json mode): skip the wasted fetch
+  const token: object = {}
+  latestToken = token
+  const providerId = getRequestyProviderId()
+  if (providerId === undefined) return // not configured for Requesty: nothing to do
+  const shouldClear = ctx.model?.provider !== providerId
+  try {
+    if (shouldClear) {
+      ctx.ui.setStatus(USAGE_STATUS_KEY, undefined)
+      return
+    }
+    const info = await fetchUsageStatus()
+    if (latestToken !== token) return
+    ctx.ui.setStatus(USAGE_STATUS_KEY, formatUsageStatus(info))
+  } catch {
+    // best-effort footer update: swallow fetch errors and stale-ctx throws (e.g. after /reload)
+  }
+}
+
+/** Returns the configured Requesty provider id, or undefined when Requesty is not configured. */
+function getRequestyProviderId(): string | undefined {
+  try {
+    return getEnv().provider_id
+  } catch {
+    return undefined
+  }
+}
+
+export function formatUsageStatus(info: ApiKeyInfo): string {
+  const spend = `$${info.monthlySpend.toFixed(2)}`
+  if (info.monthlyLimit <= 0) {
+    return `Requesty Usage (${info.name}): ${spend} (unlimited)`
+  }
+  const limit = `$${info.monthlyLimit.toFixed(2)}`
+  const percent = Math.floor((info.monthlySpend / info.monthlyLimit) * 100)
+  return `Requesty Usage (${info.name}): ${spend}/${limit} (${percent}%)`
+}
+
+async function fetchUsageStatus(): Promise<ApiKeyInfo> {
+  const env = getEnv()
+  const { provider } = getRequestyConfig(env)
+  return await fetchApiUsage(provider)
+}

package/src/requesty-api.ts

@@ -3,6 +3,7 @@ import { z } from 'zod'
 
 const DEFAULT_CONTEXT_WINDOW = 128000
 const DEFAULT_MAX_TOKENS = 4096
+const REQUESTY_MANAGE_URL = 'https://api-v2.requesty.ai/v1/manage'
 
 const RequestyModelSchema = z
   .object({
@@ -66,3 +67,31 @@ function pricePerMillionTokens(value: number | null | undefined): number {
   const raw = (value ?? 0) * 1_000_000
   return Number(raw.toFixed(3))
 }
+
+const ApiKeyInfoSchema = z
+  .object({
+    name: z.string().min(1),
+    monthly_spend: z.coerce.number(),
+    monthly_limit: z.coerce.number(),
+  })
+  .transform(value => ({
+    name: value.name,
+    monthlySpend: value.monthly_spend,
+    monthlyLimit: value.monthly_limit,
+  }))
+
+export type ApiKeyInfo = z.infer<typeof ApiKeyInfoSchema>
+
+export async function fetchApiUsage(provider: Provider): Promise<ApiKeyInfo> {
+  const url = `${REQUESTY_MANAGE_URL}/apikey/self`
+  const response = await fetch(url, {
+    headers: { Authorization: `Bearer ${provider.apiKey}` },
+  })
+
+  if (!response.ok) {
+    throw new Error(`HTTP ${response.status} ${response.statusText}`)
+  }
+
+  const rawData = await response.json()
+  return ApiKeyInfoSchema.parse(rawData)
+}