pi-requesty-discover 2.2.0 → 3.0.2

package/README.adoc

@@ -20,6 +20,7 @@ https://pi.dev/docs/latest/models#value-resolution[pi's full value resolution] c
 * 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
+* Optional Settings file in *json5* format
 
 == When and why use it
 
@@ -60,7 +61,7 @@ pi -e ./pi-requesty-discover
 == Configuration
 
 The extension reads the `requesty-export` provider from `~/.pi/agent/models.json`.
-You can override the provider id with the `REQUESTY_PROVIDER_ID` variable.
+You can override the provider id via the settings.
 
 Example:
 
@@ -83,24 +84,39 @@ IMPORTANT: Health checks are designed to use only a few tokens, but they still m
 
 On startup, the extension fetches `<baseUrl>/models` using the configured `apiKey` as the bearer token and registers discovered and healthy models with Pi.
 
+=== Discovery settings
+
+The discovery workflow reads optional settings from `requesty-discovery-settings.json5` in the Pi config directory (`PI_CODING_AGENT_DIR`).
+The file uses JSON5, so it supports comments.
+It is optional. When missing, it will be created including defaults.
+
+Example:
+
+[source,json5]
+----
+{
+  "$schema": "https://raw.githubusercontent.com/enolive/pi-requesty-discover/main/docs/requesty-discovery-settings.schema.json",
+
+  // override the default provider id
+  providerId: "requesty-export",
+  // configure the health check mode
+  healthCheckMode: "full", // or "basic", "off"
+  // models excluded from discovery; useful for models that keep failing health checks
+  bannedModels: [
+    // hangs on tool calls
+    'requesty/unstable-model',
+  ],
+}
+----
+
+Banned models are excluded before health checks run (so they cost no credits) and are removed from `models.json` on the next discovery write.
+
 === Environment variables
 
 [cols="1,1,1,1,2",options="header"]
 |===
 | Name | Required | Type | Default | Meaning
 
-| `REQUESTY_PROVIDER_ID`
-| no
-| `string`
-| `requesty-export`
-| The id of the provider.
-
-| `REQUESTY_HEALTH_CHECK_MODE`
-| no
-| `off`, `basic`, `full`
-| `full`
-| The health-check mode.
-
 | `PI_CODING_AGENT_DIR`
 | no
 | `string`

package/README.md

@@ -12,6 +12,7 @@ This is a fork of [pi-requesty](https://github.com/requestyai/pi-requesty) with
 * 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
+* Optional Settings file in **json5** format
 
 ## When and why use it
 
@@ -49,7 +50,7 @@ pi -e ./pi-requesty-discover
 ## Configuration
 
 The extension reads the `requesty-export` provider from `~/.pi/agent/models.json`.
-You can override the provider id with the `REQUESTY_PROVIDER_ID` variable.
+You can override the provider id via the settings.
 
 Example:
 
@@ -72,12 +73,36 @@ Health checks are designed to use only a few tokens, but they still make real Re
 
 On startup, the extension fetches `<baseUrl>/models` using the configured `apiKey` as the bearer token and registers discovered and healthy models with Pi.
 
+### Discovery settings
+
+The discovery workflow reads optional settings from `requesty-discovery-settings.json5` in the Pi config directory (`PI_CODING_AGENT_DIR`).
+The file uses JSON5, so it supports comments.
+It is optional. When missing, it will be created including defaults.
+
+Example:
+
+```json5
+{
+  "$schema": "https://raw.githubusercontent.com/enolive/pi-requesty-discover/main/docs/requesty-discovery-settings.schema.json",
+
+  // override the default provider id
+  providerId: "requesty-export",
+  // configure the health check mode
+  healthCheckMode: "full", // or "basic", "off"
+  // models excluded from discovery; useful for models that keep failing health checks
+  bannedModels: [
+    // hangs on tool calls
+    'requesty/unstable-model',
+  ],
+}
+```
+
+Banned models are excluded before health checks run (so they cost no credits) and are removed from `models.json` on the next discovery write.
+
 ### Environment variables
 
 | Name | Required | Type | Default | Meaning |
 | --- | --- | --- | --- | --- |
-| `REQUESTY_PROVIDER_ID` | no | `string` | `requesty-export` | The id of the provider. |
-| `REQUESTY_HEALTH_CHECK_MODE` | no | `off`, `basic`, `full` | `full` | The health-check mode. |
 | `PI_CODING_AGENT_DIR` | no | `string` | `~/.pi/agent` | pi configuration directory |
 
 ## Command

package/docs/DECISIONS.adoc

@@ -4,50 +4,43 @@ Short notes for non-obvious decisions: context, decision, why not the obvious al
 
 == 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.
+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.
+`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.
+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.
+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/discovery.ts`, and documents intent just as well.
+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 `utils.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.
+Decision: keep the hand-rolled `Try<T>`.
+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.
+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.
+- 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.
+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/docs/requesty-discovery-settings.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "bannedModels": {
+      "default": [],
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "healthCheckMode": {
+      "default": "full",
+      "type": "string",
+      "enum": [
+        "off",
+        "basic",
+        "full"
+      ]
+    },
+    "providerId": {
+      "default": "requesty-export",
+      "type": "string"
+    }
+  },
+  "required": [
+    "bannedModels",
+    "healthCheckMode",
+    "providerId"
+  ],
+  "additionalProperties": false,
+  "$id": "https://raw.githubusercontent.com/enolive/pi-requesty/main/docs/requesty-discovery-settings.schema.json",
+  "title": "Requesty discovery settings",
+  "description": "Settings for the pi-requesty discovery extension. The file uses JSON5, so comments are allowed."
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-requesty-discover",
-  "version": "2.2.0",
+  "version": "3.0.2",
   "description": "Discover available Requesty models for the Pi Coding Agent",
   "repository": {
     "type": "git",
@@ -34,7 +34,10 @@
     "test:unit:coverage": "vitest run src --coverage",
     "test:integration": "vitest run test/integration.test.ts",
     "test:watch": "vitest",
-    "prepack": "downdoc README.adoc"
+    "prepack": "downdoc README.adoc",
+    "preversion": "npm run check && npm test",
+    "version": "npm run generate:schema && git add docs/requesty-discovery-settings.schema.json",
+    "generate:schema": "jiti scripts/generate-settings-schema.ts"
   },
   "license": "MIT",
   "peerDependencies": {
@@ -64,6 +67,7 @@
     "vitest": "^4.1.9"
   },
   "dependencies": {
+    "json5": "^2.2.3",
     "zod": "^4.4.3"
   }
 }

package/scripts/generate-settings-schema.ts

@@ -0,0 +1,17 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { z } from 'zod'
+import { DiscoverySettingsSchema } from '../src/settings'
+
+const OUT_PATH = path.resolve('docs/requesty-discovery-settings.schema.json')
+const SCHEMA_URL =
+  'https://raw.githubusercontent.com/enolive/pi-requesty/main/docs/requesty-discovery-settings.schema.json'
+
+const schema = z.toJSONSchema(DiscoverySettingsSchema, { target: 'draft-2020-12', io: 'output' })
+schema.$id = SCHEMA_URL
+schema.title = 'Requesty discovery settings'
+schema.description = 'Settings for the pi-requesty discovery extension. The file uses JSON5, so comments are allowed.'
+
+fs.mkdirSync(path.dirname(OUT_PATH), { recursive: true })
+fs.writeFileSync(OUT_PATH, `${JSON.stringify(schema, null, 2)}\n`, 'utf8')
+console.log(`wrote ${OUT_PATH}`)

package/src/discovery.ts

@@ -1,16 +1,18 @@
-import { ProviderModelConfig } from '@earendil-works/pi-coding-agent'
+import type { ProviderModelConfig } from '@earendil-works/pi-coding-agent'
 import { type Env } from './env'
 import {
+  type GetApiKey,
+  type ModelsDiff,
+  type ModelsJson,
   diffModels,
   formatModelsDiffSummary,
-  GetApiKey,
   getRequestyConfig,
-  type ModelsDiff,
-  ModelsJson,
   updateModelsJson,
 } from './models-json'
 import { checkModels, formatHealthSummary, writeHealthCheckLog } from './health-check'
 import { discoverModels } from './requesty-api'
+import type { DiscoverySettings } from './settings'
+import { formatErrorMessage, runCatchingAsync } from './utils'
 
 const DRY_RUN_ARG = '--dry-run'
 
@@ -35,6 +37,7 @@ export type DiscoveryEvaluation = {
   dryRun: boolean
   modelCount: number
   failedCount: number
+  warningCount: number
   passing: ProviderModelConfig[]
   diff: ModelsDiff
   healthCheckSummary: string
@@ -42,15 +45,14 @@ export type DiscoveryEvaluation = {
   data: ModelsJson
 }
 
-export type Try<T> = { ok: true; value: T } | { ok: false; error: unknown }
-
 export function formatDiscoveryFailure(error: unknown): string {
-  const detail = formatError(error)
+  const detail = formatErrorMessage(error)
   return `Discovery failed: ${detail}`
 }
 
 export async function evaluateDiscovery(
   args: string,
+  settings: DiscoverySettings,
   env: Env,
   ui: DiscoveryUi,
   getApiKey: GetApiKey,
@@ -58,32 +60,52 @@ export async function evaluateDiscovery(
   ui.setStatus('Discovering Requesty models...')
   const dryRun = args.split(' ').includes(DRY_RUN_ARG)
 
-  const { data, provider, existingModelIds } = await getRequestyConfig(getApiKey, env)
-  const models = await discoverModels(provider)
+  const { data, provider, existingModelIds } = await getRequestyConfig(getApiKey, settings, env)
+  const bannedModels = new Set(settings.bannedModels)
+  const allModels = await discoverModels(provider)
+  const foundBannedModels = allModels
+    .filter(model => bannedModels.has(model.id))
+    .map(model => model.id)
+    .toSorted()
+  const models = allModels.filter(model => !bannedModels.has(model.id))
   const modelsMap = new Map(models.map(m => [m.id, m]))
 
   let diff: ModelsDiff
   let failedCount = 0
-  let passing: ProviderModelConfig[]
+  let warningCount = 0
+  let passing: ProviderModelConfig[] = []
   let logNote = ''
   let healthCheckSummary = ''
 
-  if (env.health_check_mode !== 'off') {
-    ui.setStatus(`Checking models 0/${models.length}...`)
-    const healthResults = await checkModels(provider, models, env.health_check_mode === 'full', {
-      onProgress: ({ completed, total }) => {
-        ui.setStatus(`Checking models ${completed}/${total}...`)
-      },
-    })
-    const sortedResults = healthResults.toSorted((a, b) => a.modelId.localeCompare(b.modelId))
-    failedCount = sortedResults.filter(r => !r.ok).length
-    passing = sortedResults.flatMap(r => {
-      const model = modelsMap.get(r.modelId)
-      return r.ok && model ? [model] : []
-    })
+  if (settings.healthCheckMode !== 'off') {
+    if (models.length > 0) {
+      ui.setStatus(`Checking models 0/${models.length}...`)
+      const healthResults = await checkModels(provider, models, settings.healthCheckMode === 'full', {
+        onProgress: ({ completed, total }) => {
+          ui.setStatus(`Checking models ${completed}/${total}...`)
+        },
+      })
+      const sortedResults = healthResults.toSorted((a, b) => a.modelId.localeCompare(b.modelId))
+      failedCount = sortedResults.filter(r => r.status === 'error').length
+      warningCount = sortedResults.filter(r => r.status === 'warning').length
+      passing = sortedResults.flatMap(r => {
+        const model = modelsMap.get(r.modelId)
+        if (!model) return []
+        if (r.status === 'ok') return [model]
+        // warnings are transient: assume that the error will go away and add them anyway
+        if (r.status === 'warning') return [model]
+        return []
+      })
+      healthCheckSummary = formatHealthSummary(sortedResults)
+      writeHealthCheckLog(
+        provider,
+        sortedResults,
+        diffModels(existingModelIds, passing),
+        { providerId: settings.providerId, bannedModels: foundBannedModels },
+        env,
+      )
+    }
     diff = diffModels(existingModelIds, passing)
-    healthCheckSummary = formatHealthSummary(sortedResults)
-    writeHealthCheckLog(provider, sortedResults, diff, env)
     logNote = `Full health check log: ${env.health_check_log_path}\n`
   } else {
     passing = models
@@ -94,6 +116,7 @@ export async function evaluateDiscovery(
     dryRun,
     modelCount: models.length,
     failedCount,
+    warningCount,
     passing,
     diff,
     healthCheckSummary,
@@ -104,6 +127,7 @@ export async function evaluateDiscovery(
 
 export async function finalizeDiscovery(
   evaluation: DiscoveryEvaluation,
+  settings: DiscoverySettings,
   env: Env,
   ui: DiscoveryUi,
   refresh?: RefreshModelsRegistry,
@@ -134,7 +158,7 @@ Left models.json unchanged.`,
   const { title, message } = buildConfirmPrompt(evaluation)
   const shouldUpdate = await ui.confirm(title, message)
   if (shouldUpdate) {
-    updateModelsJson(evaluation.data, evaluation.passing, env)
+    updateModelsJson(evaluation.data, evaluation.passing, settings, env)
     if (!refresh) {
       ui.notify('Updated models.json.', 'info')
       return
@@ -144,7 +168,7 @@ Left models.json unchanged.`,
       ui.notify('Updated models.json. New models are available in /model.', 'info')
     } else {
       ui.notify(
-        `Updated models.json, but the model registry could not be refreshed: ${formatError(refreshResult.error)}. Run /reload or restart Pi to use the changes.`,
+        `Updated models.json, but the model registry could not be refreshed: ${formatErrorMessage(refreshResult.error)}. Run /reload or restart Pi to use the changes.`,
         'warning',
       )
     }
@@ -180,9 +204,9 @@ function buildConfirmPrompt(evaluation: DiscoveryEvaluation): { title: string; m
 }
 
 function notificationLevel(evaluation: DiscoveryEvaluation): NotificationLevel {
-  if (evaluation.failedCount === 0) return 'info'
-  if (evaluation.failedCount < evaluation.modelCount) return 'warning'
-  return 'error'
+  if (evaluation.failedCount > 0) return 'error'
+  if (evaluation.warningCount > 0) return 'warning'
+  return 'info'
 }
 
 export function getArgumentCompletions(prefix: string): AutocompleteItem[] {
@@ -196,29 +220,3 @@ export function getArgumentCompletions(prefix: string): AutocompleteItem[] {
   if (!prefix) return options
   return options.filter(o => o.value.toLowerCase().startsWith(prefix.toLowerCase()))
 }
-
-export function formatError(error: unknown) {
-  return error instanceof Error ? error.message : String(error)
-}
-
-export function runCatching<T>(fn: () => T): Try<T> {
-  try {
-    return { ok: true, value: fn() }
-  } catch (error) {
-    return { ok: false, error }
-  }
-}
-
-export async function runCatchingAsync<T>(fn: () => Promise<T>): Promise<Try<T>> {
-  try {
-    return { ok: true, value: await fn() }
-  } catch (error) {
-    return { ok: false, error }
-  }
-}
-
-export function complainOnBrokenEnv(ui: DiscoveryUi, env: Try<Env>) {
-  if (!env.ok) {
-    ui.notify(`failed to load env: ${formatError(env.error)}`, 'error')
-  }
-}

package/src/env.ts

@@ -1,31 +1,17 @@
 import path from 'node:path'
-import process from 'node:process'
-import { prettifyError, z } from 'zod'
 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
-  provider_id: string
-  health_check_mode: z.infer<typeof HealthCheckModeSchema>
+  settings_path: string
 }
 
 export function getEnv(): Env {
-  const envVars = process.env
-  const result = HealthCheckModeSchema.safeParse(envVars.REQUESTY_HEALTH_CHECK_MODE)
-  if (!result.success) {
-    throw new Error(prettifyError(result.error))
-  }
-
   const agentPath = getAgentDir()
   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 ?? DEFAULT_PROVIDER_ID,
-    health_check_mode: result.data,
+    settings_path: path.join(agentPath, 'requesty-discovery-settings.json5'),
   }
 }

package/src/health-check.ts

@@ -1,7 +1,7 @@
 import type { ProviderModelConfig } from '@earendil-works/pi-coding-agent'
 import fs from 'node:fs'
 import path from 'node:path'
-import { getEnv, type Env } from './env'
+import { type Env, getEnv } from './env'
 import { formatModelsDiffSummary, type ModelsDiff } from './models-json'
 
 const HEALTH_CHECK_CONCURRENCY = 10
@@ -23,9 +23,11 @@ export type Provider = {
   apiKey: string
 }
 
+export type HealthCheckStatus = 'ok' | 'warning' | 'error'
+
 export type HealthCheckResult = {
   modelId: string
-  ok: boolean
+  status: HealthCheckStatus
   latencyMs: number
   error?: string
 }
@@ -38,6 +40,11 @@ export type HealthCheckProgress = {
   modelId: string
 }
 
+export type HealthCheckLogContext = {
+  providerId: string
+  bannedModels: string[]
+}
+
 export type HealthCheckOptions = {
   concurrency?: number
   timeoutMs?: number
@@ -87,53 +94,73 @@ export async function checkModels(
 }
 
 export function formatHealthSummary(results: HealthCheckResult[]): string {
-  const passed = results.filter(r => r.ok)
-  const failed = results.filter(r => !r.ok)
-
-  if (failed.length === 0) {
-    return `Health check: all ${passed.length} OK.`
-  }
+  const passed = results.filter(r => r.status === 'ok')
+  const warned = results.filter(r => r.status === 'warning')
+  const failed = results.filter(r => r.status === 'error')
 
-  const failedModels = failed.map(r => `- ${r.modelId}`).join('\n')
+  const parts = [`${passed.length} OK`]
+  if (warned.length > 0) parts.push(`${warned.length} warning${warned.length === 1 ? '' : 's'}`)
+  if (failed.length > 0) parts.push(`${failed.length} failed`)
 
-  return `Health check: ${passed.length} OK, ${failed.length} failed:\n${failedModels}\n`
+  return `Health check: ${parts.join(', ')}.`
 }
 
 export function writeHealthCheckLog(
   provider: Provider,
   results: HealthCheckResult[],
   diff: ModelsDiff,
+  context: HealthCheckLogContext,
   envConfig: Env = getEnv(),
 ): void {
-  const passed = results.filter(r => r.ok)
-  const failed = results.filter(r => !r.ok)
+  const passed = results.filter(r => r.status === 'ok')
+  const warned = results.filter(r => r.status === 'warning')
+  const failed = results.filter(r => r.status === 'error')
   const lines = [
     `Requesty health check log`,
     `Timestamp: ${new Date().toISOString()}`,
-    `Provider: ${envConfig.provider_id}`,
+    `Provider: ${context.providerId}`,
     `Base URL: ${provider.baseUrl}`,
     `Total: ${results.length}`,
     `Passed: ${passed.length}`,
+    `Warnings: ${warned.length}`,
     `Failed: ${failed.length}`,
+    `Banned: ${context.bannedModels.length}`,
+    ...context.bannedModels.map(id => `- ${id}`),
     '',
     formatModelsDiffSummary(diff),
     '',
   ]
 
-  if (failed.length === 0) {
+  if (warned.length === 0 && failed.length === 0) {
     lines.push('No failed models.')
   } else {
-    lines.push('Failed models:', '')
-    for (const result of failed) {
-      lines.push(
-        `Model: ${result.modelId}`,
-        `Latency: ${result.latencyMs}ms`,
-        'Error:',
-        result.error || 'Unknown error',
-        '',
-        '---',
-        '',
-      )
+    if (warned.length > 0) {
+      lines.push('Models with warnings:', '')
+      for (const result of warned) {
+        lines.push(
+          `Model: ${result.modelId}`,
+          `Latency: ${result.latencyMs}ms`,
+          'Error:',
+          result.error || 'Unknown error',
+          '',
+          '---',
+          '',
+        )
+      }
+    }
+    if (failed.length > 0) {
+      lines.push('Failed models:', '')
+      for (const result of failed) {
+        lines.push(
+          `Model: ${result.modelId}`,
+          `Latency: ${result.latencyMs}ms`,
+          'Error:',
+          result.error || 'Unknown error',
+          '',
+          '---',
+          '',
+        )
+      }
     }
   }
 
@@ -166,8 +193,10 @@ export async function postChatCompletion(
 
       if (!response.ok) {
         const text = await response.text().catch(() => '')
+        // rate limits are transient - a warning, not an error
+        const status: HealthCheckStatus = response.status === 429 ? 'warning' : 'error'
         return {
-          ok: false,
+          status,
           latencyMs,
           error: `HTTP ${response.status} ${response.statusText}${text ? `: ${text}` : ''}`,
         }
@@ -183,7 +212,7 @@ export async function postChatCompletion(
       }
       const attempts = attempt + 1
       return {
-        ok: false,
+        status: 'error',
         latencyMs: Date.now() - start,
         error: isTimeoutError(err)
           ? `Timed out after ${attempts} attempt(s); per-attempt timeout is ${healthCheckOptions.timeoutMs / 1000}s`
@@ -192,7 +221,7 @@ export async function postChatCompletion(
     }
   }
 
-  return { ok: false, latencyMs: Date.now() - start, error: 'Unknown error' }
+  return { status: 'error', latencyMs: Date.now() - start, error: 'Unknown error' }
 }
 
 async function verifyFirstStreamChunk(body: ReadableStream<Uint8Array>, start: number): Promise<ModelCheckResult> {
@@ -219,14 +248,14 @@ async function verifyFirstStreamChunk(body: ReadableStream<Uint8Array>, start: n
         try {
           const parsed = JSON.parse(payload) as { choices?: unknown }
           if (Array.isArray(parsed.choices) && parsed.choices.length > 0) {
-            return { ok: true, latencyMs: Date.now() - start }
+            return { status: 'ok', latencyMs: Date.now() - start }
           }
         } catch {
           // partial JSON or non-choices chunk — keep reading
         }
       }
     }
-    return { ok: false, latencyMs: Date.now() - start, error: 'Stream ended without content' }
+    return { status: 'error', latencyMs: Date.now() - start, error: 'Stream ended without content' }
   } finally {
     await reader.cancel()
   }
@@ -248,7 +277,7 @@ async function checkModel(
     options,
   )
 
-  if (!basicResult.ok || !model.reasoning || !checkReasoning) {
+  if (basicResult.status !== 'ok' || !model.reasoning || !checkReasoning) {
     return basicResult
   }
 
@@ -276,16 +305,16 @@ async function checkModel(
     options,
   )
 
-  if (!reasoningResult.ok) {
+  if (reasoningResult.status !== 'ok') {
     return {
-      ok: false,
+      status: 'error',
       latencyMs: reasoningResult.latencyMs,
       error: `Reasoning/tool check failed: ${reasoningResult.error}`,
     }
   }
 
   return {
-    ok: true,
+    status: 'ok',
     latencyMs: basicResult.latencyMs + reasoningResult.latencyMs,
   }
 }

package/src/index.ts

@@ -1,23 +1,19 @@
-import { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from '@earendil-works/pi-coding-agent'
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from '@earendil-works/pi-coding-agent'
 import { type Env, getEnv } from './env'
-import { GetApiKey, getRequestyConfig } from './models-json'
+import { type GetApiKey, getRequestyConfig } from './models-json'
 import { type ApiKeyInfo, fetchApiUsage } from './requesty-api'
-import { RequestyStatusLoader } from './ui/requesty-status-loader.ts'
+import { RequestyStatusLoader } from './ui/requesty-status-loader'
 import {
-  complainOnBrokenEnv,
   type DiscoveryEvaluation,
   type DiscoveryUi,
+  type RefreshModelsRegistry,
   evaluateDiscovery,
   finalizeDiscovery,
   formatDiscoveryFailure,
   getArgumentCompletions,
-  RefreshModelsRegistry,
-  runCatching,
-  runCatchingAsync,
-  type Try,
 } from './discovery'
-
-export { type Try }
+import { type DiscoverySettings, readDiscoverySettings } from './settings'
+import { runCatching, runCatchingAsync, type Try } from './utils'
 
 const COMMAND_NAME = 'requesty-discover'
 export const USAGE_STATUS_KEY = 'requesty-usage'
@@ -28,64 +24,81 @@ let latestToken: object = {}
 // noinspection JSUnusedGlobalSymbols
 export default function (pi: ExtensionAPI) {
   const env = runCatching(() => getEnv())
+  if (!env.ok) {
+    console.error('env loading failed', env.error)
+    return
+  }
+  const settings = runCatching(() => readDiscoverySettings(env.value))
+  if (!settings.ok) {
+    console.error('settings loading failed', settings.error)
+    return
+  }
 
   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, env, args)
+      await runDiscoveryWorkflow(ctx, settings.value, env.value, args)
     },
   })
 
   pi.on('turn_end', (_event, ctx) => {
-    void updateUsageStatus(ctx, env)
+    void updateUsageStatus(ctx, settings.value, env.value)
   })
 
   pi.on('session_start', (_event, ctx) => {
-    const ui = createTuiUi(ctx)
-    complainOnBrokenEnv(ui, env)
-    void updateUsageStatus(ctx, env)
+    void updateUsageStatus(ctx, settings.value, env.value)
   })
 
   pi.on('model_select', (_event, ctx) => {
-    void updateUsageStatus(ctx, env)
+    void updateUsageStatus(ctx, settings.value, env.value)
   })
 }
 
-export async function runDiscoveryWorkflow(ctx: ExtensionCommandContext, env: Try<Env>, args: string) {
+export async function runDiscoveryWorkflow(
+  ctx: ExtensionCommandContext,
+  settings: DiscoverySettings,
+  env: Env,
+  args: string,
+) {
   const ui = ctx.mode === 'tui' ? createTuiUi(ctx) : createConsoleUi()
-  complainOnBrokenEnv(ui, env)
-  if (!env.ok) {
-    return
-  }
-
   if (ctx.mode !== 'tui') {
-    return runSilentDiscoveryWorkflow(ctx, env.value, args, ui)
+    return runSilentDiscoveryWorkflow(ctx, settings, env, args, ui)
   } else {
-    return runInteractiveDiscoverWorkflow(ctx, env.value, args, ui)
+    return runInteractiveDiscoverWorkflow(ctx, settings, env, args, ui)
   }
 }
 
 async function runSilentDiscoveryWorkflow(
   ctx: ExtensionCommandContext,
+  settings: DiscoverySettings,
   env: Env,
   args: string,
   ui: DiscoveryUi,
 ): Promise<void> {
-  const evaluationResult = await runCatchingAsync(() => evaluateDiscovery(args, env, ui, createGetApiKey(ctx)))
+  const evaluationResult = await runCatchingAsync(() =>
+    evaluateDiscovery(args, settings, env, ui, createGetApiKey(ctx)),
+  )
   if (!evaluationResult.ok) {
     ui.notify(formatDiscoveryFailure(evaluationResult.error), 'error')
     return
   }
 
-  await finalizeDiscovery(evaluationResult.value, env, ui)
+  await finalizeDiscovery(evaluationResult.value, settings, env, ui)
 }
 
-async function runInteractiveDiscoverWorkflow(ctx: ExtensionCommandContext, env: Env, args: string, ui: DiscoveryUi) {
+async function runInteractiveDiscoverWorkflow(
+  ctx: ExtensionCommandContext,
+  settings: DiscoverySettings,
+  env: Env,
+  args: string,
+  ui: DiscoveryUi,
+) {
   const evaluationResult: Try<DiscoveryEvaluation> = await runWithStatusUi(
     ctx,
     'Discovering models...',
-    async statusUi => await runCatchingAsync(() => evaluateDiscovery(args, env, statusUi, createGetApiKey(ctx))),
+    async statusUi =>
+      await runCatchingAsync(() => evaluateDiscovery(args, settings, env, statusUi, createGetApiKey(ctx))),
   )
 
   if (!evaluationResult.ok) {
@@ -93,7 +106,8 @@ async function runInteractiveDiscoverWorkflow(ctx: ExtensionCommandContext, env:
     return
   }
 
-  await finalizeDiscovery(evaluationResult.value, env, ui, createRefreshRegistry(ctx))
+  await finalizeDiscovery(evaluationResult.value, settings, env, ui, createRefreshRegistry(ctx))
+  await updateUsageStatus(ctx, settings, env)
 }
 
 async function runWithStatusUi<T>(
@@ -111,18 +125,17 @@ async function runWithStatusUi<T>(
   })
 }
 
-async function updateUsageStatus(ctx: ExtensionContext, env: Try<Env>): Promise<void> {
-  if (!env.ok) return
+async function updateUsageStatus(ctx: ExtensionContext, settings: DiscoverySettings, env: Env): Promise<void> {
   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
+  const shouldClear = ctx.model?.provider !== settings.providerId
   try {
     if (shouldClear) {
       ctx.ui.setStatus(USAGE_STATUS_KEY, undefined)
       return
     }
-    const info = await fetchUsageStatus(createGetApiKey(ctx), env.value)
+    const info = await fetchUsageStatus(createGetApiKey(ctx), settings, env)
     if (latestToken !== token) return
     ctx.ui.setStatus(USAGE_STATUS_KEY, formatUsageStatus(info))
   } catch {
@@ -142,12 +155,12 @@ export function formatUsageStatus(info: ApiKeyInfo): string {
 
 let lastFetched: { value: ApiKeyInfo; time: Date } | undefined
 
-async function fetchUsageStatus(getApiKey: GetApiKey, env: Env): Promise<ApiKeyInfo> {
+async function fetchUsageStatus(getApiKey: GetApiKey, settings: DiscoverySettings, env: Env): Promise<ApiKeyInfo> {
   const now = new Date()
   if (lastFetched?.time && now.getTime() - lastFetched.time.getTime() < 2000) {
     return lastFetched.value
   }
-  const { provider } = await getRequestyConfig(getApiKey, env)
+  const { provider } = await getRequestyConfig(getApiKey, settings, env)
   const value = await fetchApiUsage(provider)
   lastFetched = { value, time: new Date() }
   return value

package/src/models-json.ts

@@ -1,8 +1,9 @@
-import { ProviderConfig, ProviderModelConfig } from '@earendil-works/pi-coding-agent'
+import type { ProviderConfig, ProviderModelConfig } from '@earendil-works/pi-coding-agent'
 import fs from 'node:fs'
 import path from 'node:path'
 import { z } from 'zod'
 import { type Env, getEnv } from './env'
+import type { DiscoverySettings } from './settings'
 
 const DEFAULT_BASE_URL = 'https://router.requesty.ai/v1'
 const DEFAULT_NAME = 'Requesty'
@@ -46,17 +47,21 @@ export type ModelsDiff = {
   removed: string[]
 }
 
-export async function getRequestyConfig(getApiKey: GetApiKey, envConfig: Env = getEnv()): Promise<RequestyConfig> {
+export async function getRequestyConfig(
+  getApiKey: GetApiKey,
+  settings: DiscoverySettings,
+  envConfig: Env = getEnv(),
+): Promise<RequestyConfig> {
   const data = readModelsJson(envConfig)
-  const provider = data.providers[envConfig.provider_id]
+  const provider = data.providers[settings.providerId]
 
   if (!provider) {
-    throw new Error(`${envConfig.models_json_path} does not define providers.${envConfig.provider_id}`)
+    throw new Error(`${envConfig.models_json_path} does not define providers.${settings.providerId}`)
   }
 
-  const apiKey = await getApiKey(envConfig.provider_id)
+  const apiKey = await getApiKey(settings.providerId)
   if (!apiKey) {
-    throw new Error(`No API key found for provider ${envConfig.provider_id}`)
+    throw new Error(`No API key found for provider ${settings.providerId}`)
   }
   return {
     data,
@@ -88,10 +93,15 @@ export function formatModelsDiffSummary(diff: ModelsDiff): string {
   ].join('\n')
 }
 
-export function updateModelsJson(data: ModelsJson, models: ProviderModelConfig[], envConfig: Env = getEnv()): void {
-  const provider = data.providers[envConfig.provider_id]
+export function updateModelsJson(
+  data: ModelsJson,
+  models: ProviderModelConfig[],
+  settings: DiscoverySettings,
+  envConfig = getEnv(),
+): void {
+  const provider = data.providers[settings.providerId]
   const { name, baseUrl, api, apiKey, models: _existingModels, ...passthrough } = provider
-  data.providers[envConfig.provider_id] = {
+  data.providers[settings.providerId] = {
     name,
     baseUrl,
     api,

package/src/settings.ts

@@ -0,0 +1,68 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { parse as JSON5Parse } from 'json5'
+import { prettifyError, z } from 'zod'
+import { type Env } from './env'
+import { formatErrorMessage } from './utils'
+
+export const DEFAULT_PROVIDER_ID = 'requesty-export'
+
+const HealthCheckModeSchema = z.enum(['off', 'basic', 'full']).default('full')
+
+export const DiscoverySettingsSchema = z
+  .object({
+    bannedModels: z.array(z.string().min(1)).default([]),
+    healthCheckMode: HealthCheckModeSchema,
+    providerId: z.string().default(DEFAULT_PROVIDER_ID),
+  })
+  .strip()
+
+export type DiscoverySettings = z.infer<typeof DiscoverySettingsSchema>
+
+const SCHEMA_URL =
+  'https://raw.githubusercontent.com/enolive/pi-requesty-discover/main/docs/requesty-discovery-settings.schema.json'
+
+/**
+ * Reads the discovery settings file (JSON5, so it supports comments).
+ * Writes a commented default file (including the $schema editor reference) when it does not
+ * exist yet; throws when it exists but is invalid.
+ */
+export function readDiscoverySettings(envConfig: Env): DiscoverySettings {
+  if (!fs.existsSync(envConfig.settings_path)) {
+    writeDefaultSettingsFile(envConfig)
+    return {
+      bannedModels: [],
+      healthCheckMode: 'full',
+      providerId: DEFAULT_PROVIDER_ID,
+    }
+  }
+
+  const raw = fs.readFileSync(envConfig.settings_path, 'utf8')
+  let data: unknown
+  try {
+    data = JSON5Parse(raw)
+  } catch (error) {
+    throw new Error(`Failed to parse ${envConfig.settings_path}: ${formatErrorMessage(error)}`, { cause: error })
+  }
+
+  const result = DiscoverySettingsSchema.safeParse(data)
+  if (!result.success) {
+    throw new Error(`${envConfig.settings_path} is invalid: ${prettifyError(result.error)}`)
+  }
+  return result.data
+}
+
+function writeDefaultSettingsFile(envConfig: Env): void {
+  const content = `{
+  $schema: "${SCHEMA_URL}",
+  // the provider id in models.json whose models are managed by this extension
+  providerId: "${DEFAULT_PROVIDER_ID}",
+  // health check mode: "full" (basic + reasoning/tool check), "basic", or "off"
+  healthCheckMode: "full",
+  // models excluded from discovery; useful for models that keep failing health checks
+  bannedModels: []
+}
+`
+  fs.mkdirSync(path.dirname(envConfig.settings_path), { recursive: true })
+  fs.writeFileSync(envConfig.settings_path, content, 'utf8')
+}

package/src/ui/requesty-status-loader.ts

@@ -1,5 +1,5 @@
 import { DynamicBorder, Theme } from '@earendil-works/pi-coding-agent'
-import { Container, Loader, Spacer, TUI } from '@earendil-works/pi-tui'
+import { Container, Loader, Spacer, type TUI } from '@earendil-works/pi-tui'
 
 /**
  * A loader that allows us to change the displayed message.

package/src/utils.ts

@@ -0,0 +1,24 @@
+export type Try<T> = { ok: true; value: T } | { ok: false; error: unknown }
+
+export function runCatching<T>(fn: () => T): Try<T> {
+  try {
+    return { ok: true, value: fn() }
+  } catch (error) {
+    return { ok: false, error }
+  }
+}
+
+export async function runCatchingAsync<T>(fn: () => Promise<T>): Promise<Try<T>> {
+  try {
+    return { ok: true, value: await fn() }
+  } catch (error) {
+    return { ok: false, error }
+  }
+}
+
+export function formatErrorMessage(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message
+  }
+  return String(error)
+}