pi-requesty-discover 2.0.0 → 2.1.1

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,52 @@
+= 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.
+
+== Hand-rolled `Try<T>` instead of an effects library
+
+Context: env loading and discovery evaluation both need a caught-error result value
+(`{ ok: true, value } | { ok: false, error }`). Libraries like Effect ship an
+industrial `Either`/`Effect.try` for exactly this.
+
+Why not: Effect is a runtime, a generator DSL, and a worldview — not a utility.
+Two call sites in a Pi extension don't justify the dependency weight or the
+learning curve for contributors. The hand-rolled version is ~10 lines
+(`Try<T>`, `runCatching`, `runCatchingAsync`, named after Kotlin's `Result`),
+lives in `src/index.ts`, and documents intent just as well.
+
+Decision: keep the hand-rolled `Try<T>`. No `monads.ts` module either — rule of
+three. Revisit if the extension ever needs typed errors, retries, or resource
+scoping; that's the day Effect earns its place.
+
+== 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.1",
   "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
@@ -45,28 +51,42 @@ type DiscoveryEvaluation = {
   healthCheckSummary: string
   logNote: string
   data: ModelsJsonData
-  env: Env
 }
 
-type EvaluationResult =
-  | {
-      ok: true
-      value: DiscoveryEvaluation
-    }
-  | { ok: false; error: unknown }
+export type Try<T> = { ok: true; value: T } | { ok: false; error: unknown }
+
+// token suppresses stale writes when turns overlap
+let latestToken: object = {}
 
 // noinspection JSUnusedGlobalSymbols
 export default function (pi: ExtensionAPI) {
+  const env = runCatching(() => getEnv())
+
   pi.registerCommand(COMMAND_NAME, {
     description: 'Dynamically discover Requesty models, run health checks, and update the local models.json.',
     getArgumentCompletions,
     handler: async (args, ctx) => {
-      await runDiscoveryWorkflow(ctx, args)
+      await runDiscoveryWorkflow(ctx, env, args)
     },
   })
+
+  pi.on('turn_end', (_event, ctx) => {
+    void updateUsageStatus(ctx, env)
+  })
+
+  pi.on('session_start', (_event, ctx) => {
+    complainOnBrokenEnv(ctx, env)
+    void updateUsageStatus(ctx, env)
+  })
+
+  pi.on('model_select', (_event, ctx) => {
+    void updateUsageStatus(ctx, env)
+  })
 }
 
-export async function runDiscoveryWorkflow(ctx: ExtensionCommandContext, args: string) {
+export async function runDiscoveryWorkflow(ctx: ExtensionCommandContext, env: Try<Env>, args: string) {
+  complainOnBrokenEnv(ctx, env)
+  if (!env.ok) return
   // Interactive TUI command; no print/json/rpc path.
   if (ctx.mode !== 'tui') {
     return
@@ -77,14 +97,11 @@ export async function runDiscoveryWorkflow(ctx: ExtensionCommandContext, args: s
 
   // Phase A: progress UI only. Loader must close before confirm (Phase B).
   // Errors are wrapped because ctx.ui.custom resolves via done() and does not reject.
-  const evaluationResult: EvaluationResult = await runWithStatusUi(ctx, 'Discovering models...', async status => {
-    try {
-      const evaluation = await evaluateDiscovery(args, status)
-      return { ok: true, value: evaluation }
-    } catch (error) {
-      return { ok: false, error }
-    }
-  })
+  const evaluationResult: Try<DiscoveryEvaluation> = await runWithStatusUi(
+    ctx,
+    'Discovering models...',
+    async status => await runCatchingAsync(() => evaluateDiscovery(args, env.value, status)),
+  )
 
   if (!evaluationResult.ok) {
     notifier.notify(formatDiscoveryFailure(evaluationResult.error), 'error')
@@ -92,7 +109,12 @@ export async function runDiscoveryWorkflow(ctx: ExtensionCommandContext, args: s
   }
 
   // Phases B + C: decide, optional write, final notify — outside the loader.
-  await finalizeDiscovery(evaluationResult.value, confirmer, notifier)
+  await finalizeDiscovery(evaluationResult.value, confirmer, notifier, env.value)
+}
+
+function formatDiscoveryFailure(error: unknown): string {
+  const detail = formatError(error)
+  return `Discovery failed: ${detail}`
 }
 
 async function runWithStatusUi<T>(
@@ -111,16 +133,10 @@ async function runWithStatusUi<T>(
   })
 }
 
-function formatDiscoveryFailure(error: unknown): string {
-  const detail = error instanceof Error ? error.message : String(error)
-  return `Discovery failed: ${detail}`
-}
-
-async function evaluateDiscovery(args: string, status: StatusReporter): Promise<DiscoveryEvaluation> {
+async function evaluateDiscovery(args: string, env: Env, status: StatusReporter): Promise<DiscoveryEvaluation> {
   status.set('Discovering Requesty models...')
   const dryRun = args.split(' ').includes(DRY_RUN_ARG)
 
-  const env = getEnv()
   const { data, provider, existingModelIds } = getRequestyConfig(env)
   const models = await discoverModels(provider)
   const modelsMap = new Map(models.map(m => [m.id, m]))
@@ -162,7 +178,6 @@ async function evaluateDiscovery(args: string, status: StatusReporter): Promise<
     healthCheckSummary,
     logNote,
     data,
-    env,
   }
 }
 
@@ -170,6 +185,7 @@ async function finalizeDiscovery(
   evaluation: DiscoveryEvaluation,
   confirmer: Confirmer,
   notifier: Notifier,
+  env: Env,
 ): Promise<void> {
   const level = notificationLevel(evaluation)
   const summary = buildDiscoverySummary(evaluation)
@@ -197,7 +213,7 @@ Left models.json unchanged.`,
   const { title, message } = buildConfirmPrompt(evaluation)
   const shouldUpdate = await confirmer.confirm(title, message)
   if (shouldUpdate) {
-    updateModelsJson(evaluation.data, evaluation.passing, evaluation.env)
+    updateModelsJson(evaluation.data, evaluation.passing, env)
     notifier.notify('Updated models.json. Run /reload to use the changes.', 'info')
     return
   }
@@ -248,7 +264,7 @@ function getArgumentCompletions(prefix: string): AutocompleteItem[] {
   return options.filter(o => o.value.toLowerCase().startsWith(prefix.toLowerCase()))
 }
 
-function createUiNotifier(ctx: ExtensionCommandContext): Notifier {
+function createUiNotifier(ctx: ExtensionContext): Notifier {
   return {
     notify(message: string, level?: NotificationLevel) {
       const prefixedMessage = `${COMMAND_NAME}: ${message}`
@@ -257,7 +273,7 @@ function createUiNotifier(ctx: ExtensionCommandContext): Notifier {
   }
 }
 
-function createUiConfirmer(ctx: ExtensionCommandContext): Confirmer {
+function createUiConfirmer(ctx: ExtensionContext): Confirmer {
   return {
     confirm(title, message) {
       return ctx.ui.confirm(title, message)
@@ -272,3 +288,79 @@ function createLoaderStatusReporter(loader: RequestyStatusLoader): StatusReporte
     },
   }
 }
+
+async function updateUsageStatus(ctx: ExtensionContext, env: Try<Env>): Promise<void> {
+  if (!env.ok) return
+  if (!ctx.hasUI) return // no footer to write to (print/json mode): skip the wasted fetch
+  const token: object = {}
+  latestToken = token
+  const shouldClear = ctx.model?.provider !== env.value.provider_id
+  try {
+    if (shouldClear) {
+      ctx.ui.setStatus(USAGE_STATUS_KEY, undefined)
+      return
+    }
+    const info = await fetchUsageStatus(env.value)
+    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)
+  }
+}
+
+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}%)`
+}
+
+let lastFetched: { value: ApiKeyInfo; time: Date } | undefined
+
+async function fetchUsageStatus(env: Env): Promise<ApiKeyInfo> {
+  const now = new Date()
+  if (lastFetched?.time && now.getTime() - lastFetched.time.getTime() < 2000) {
+    return lastFetched.value
+  }
+  const { provider } = getRequestyConfig(env)
+  const value = await fetchApiUsage(provider)
+  lastFetched = { value, time: new Date() }
+  return value
+}
+
+function formatError(error: unknown) {
+  return error instanceof Error ? error.message : String(error)
+}
+
+/**
+ * For testing purposes, reset the cache after each run
+ */
+export function resetUsageStatusCache(): void {
+  lastFetched = undefined
+}
+
+function runCatching<T>(fn: () => T): Try<T> {
+  try {
+    return { ok: true, value: fn() }
+  } catch (error) {
+    return { ok: false, error }
+  }
+}
+
+async function runCatchingAsync<T>(fn: () => Promise<T>): Promise<Try<T>> {
+  try {
+    return { ok: true, value: await fn() }
+  } catch (error) {
+    return { ok: false, error }
+  }
+}
+
+function complainOnBrokenEnv(ctx: ExtensionContext, env: Try<Env>) {
+  if (!env.ok) {
+    const notifier = createUiNotifier(ctx)
+    notifier.notify(`failed to load env: ${formatError(env.error)}`, 'error')
+  }
+}

package/src/models-json.ts

@@ -25,7 +25,7 @@ const ModelsJsonSchema = z
 type ModelsJson = z.infer<typeof ModelsJsonSchema>
 type ModelsJsonProvider = z.infer<typeof ProviderSchema>
 
-type RequestyProvider = ModelsJsonProvider & {
+export type RequestyProvider = ModelsJsonProvider & {
   name: string
   baseUrl: string
   apiKey: string

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({
@@ -30,9 +31,14 @@ type Provider = {
   apiKey: string
 }
 
-export async function discoverModels(provider: Provider): Promise<ProviderModelConfig[]> {
+export async function discoverModels(
+  provider: Provider,
+  options: { timeoutMs?: number } = {},
+): Promise<ProviderModelConfig[]> {
+  const timeoutMs = options.timeoutMs ?? 5_000
   const response = await fetch(`${provider.baseUrl}/models`, {
     headers: { Authorization: `Bearer ${provider.apiKey}` },
+    signal: AbortSignal.timeout(timeoutMs),
   })
 
   if (!response.ok) {
@@ -66,3 +72,33 @@ 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, options: { timeoutMs?: number } = {}): Promise<ApiKeyInfo> {
+  const url = `${REQUESTY_MANAGE_URL}/apikey/self`
+  const timeoutMs = options.timeoutMs ?? 2_000
+  const response = await fetch(url, {
+    headers: { Authorization: `Bearer ${provider.apiKey}` },
+    signal: AbortSignal.timeout(timeoutMs),
+  })
+
+  if (!response.ok) {
+    throw new Error(`HTTP ${response.status} ${response.statusText}`)
+  }
+
+  const rawData = await response.json()
+  return ApiKeyInfoSchema.parse(rawData)
+}