pi-bob 0.1.0 → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Larry Song
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,14 +2,14 @@
 
 Pi provider package for IBM Bob / IBM-approved enterprise model endpoints.
 
-This first pass implements **Option 1** from `PLAN.md`: register Bob as a Pi provider using Pi's built-in compatible provider APIs. It does not scrape Bob, extract browser/session credentials, or bypass IBM-approved access paths.
+The package registers Bob through Pi's built-in compatible provider APIs and discovers the currently exposed model catalog from Bob's authenticated `/inference/v1/model/info` endpoint. It does not scrape Bob, extract browser/session credentials, or bypass IBM-approved access paths.
 
 ## Discovered local Bob Shell settings
 
 From the installed `bobshell@1.0.6` package and the local redacted Bob configuration:
 
-- Bob Shell CLI: `/opt/homebrew/bin/bob`
-- Bob Shell package: `/opt/homebrew/lib/node_modules/bobshell`
+- Bob Shell CLI: `bob`
+- Bob Shell package: `bobshell`
 - Installed auth method: `sso`
 - Default Bob API host: `https://api.us-east.bob.ibm.com`
 - OpenAI-compatible chat base URL: `https://api.us-east.bob.ibm.com/inference/v1`
@@ -36,14 +36,25 @@ Set `IBM_BOB_API` to one of Pi's compatible API adapters:
 - `openai-responses` — OpenAI Responses-compatible routes.
 - `anthropic-messages` — Anthropic Messages-compatible routes.
 
-The extension registers provider id `ibm-bob`.
+The extension registers provider id `ibm-bob`. It uses an isolated `ibm-bob-compatible` Pi API adapter internally, then delegates serialization and streaming to the selected built-in adapter. This prevents Bob-specific authentication rules from affecting other providers.
+
+## Dynamic model discovery
+
+Model discovery is enabled by default:
+
+- With `IBM_BOB_API_KEY` or `IBM_BOB_KEY`, the extension fetches `/inference/v1/model/info` during Pi's async extension startup. This makes current models available to `--list-models` and `/model` immediately.
+- With `/login ibm-bob`, the extension fetches the catalog after login, and on token refresh only when no catalog is already cached (reusing a cached catalog avoids holding Pi's global auth-store lock across a network call). A sanitized, non-secret copy is cached with Pi's OAuth credentials so the models can be restored on later startups.
+- Entries returned by the authenticated catalog are registered when `model_info.exposed` is omitted or `true`. Routes explicitly marked `exposed: false` are ignored.
+- HTTP failures, timeouts, malformed responses, empty catalogs, and catalogs with no visible models retain the previous SSO catalog or fall back to `IBM_BOB_MODELS`. Bob still enforces route access during inference.
+
+Discovered context limits, output limits, vision support, reasoning support, backend identifiers, and token prices are mapped into Pi model definitions. Bob reports prices per token; Pi displays prices per million tokens, so the extension performs that conversion.
 
 ## Quick start for the discovered Bob endpoint
 
 Use Bob SSO through Pi:
 
 ```bash
-pi -e /Users/larry.song/work/hashicorp/pi-bob
+pi -e .
 # inside Pi:
 #   /login ibm-bob
 #   /model ibm-bob/premium
@@ -51,30 +62,28 @@ pi -e /Users/larry.song/work/hashicorp/pi-bob
 
 Pi stores the resulting Bob SSO access/refresh tokens in Pi's normal auth store (`~/.pi/agent/auth.json`). This extension obtains those tokens only through Bob's browser SSO endpoints; it does not read Bob Shell's stored SSO secrets.
 
-For non-interactive/API-key use, if you have an approved Bob bearer token/API token available outside Bob Shell, run:
+For non-interactive use with an approved Bob API key, run:
 
 ```bash
-export IBM_BOB_API_KEY="..." # do not commit this
+export IBM_BOB_API_KEY="..." # IBM_BOB_KEY is also accepted; do not commit either
 
-pi -e /Users/larry.song/work/hashicorp/pi-bob --list-models
-pi -e /Users/larry.song/work/hashicorp/pi-bob --model ibm-bob/premium
+pi -e . --list-models
+pi -e . --model ibm-bob/premium
 ```
 
+API keys use Bob's `Authorization: Apikey ...` scheme by default. If your approved credential is instead a bearer token, set `IBM_BOB_AUTH_SCHEME=Bearer`. Pi resolves credentials in this order: runtime `--api-key`, a stored credential (including SSO), then the provider's environment-key fallback. The model catalog follows stored SSO metadata when SSO remains configured. Run `/logout ibm-bob` before switching from SSO to either `IBM_BOB_API_KEY` or runtime `--api-key`; runtime-only keys cannot drive startup discovery.
+
 Defaults are already set to:
 
 ```bash
 IBM_BOB_BASE_URL="https://api.us-east.bob.ibm.com/inference/v1"
 IBM_BOB_API="openai-completions"
-IBM_BOB_MODELS="premium"
-IBM_BOB_CONTEXT_WINDOW="200000"
-IBM_BOB_MAX_TOKENS="8192"
+IBM_BOB_DISCOVER_MODELS="true"
+IBM_BOB_MODELS="premium"                  # fallback catalog
+IBM_BOB_MODEL_DISCOVERY_TIMEOUT_MS="5000"
 ```
 
-For IBM Bob API keys that require `Authorization: Apikey ...` rather than `Authorization: Bearer ...`:
-
-```bash
-export IBM_BOB_AUTH_SCHEME="Apikey"
-```
+Discovered metadata is used unless a corresponding metadata override is set. Without a discovered catalog, fallback models use a 200,000-token context window and 8,192-token output limit.
 
 For SSO, do **not** copy a token out of Bob's local credential store unless IBM policy explicitly permits it. Use `/login ibm-bob` instead.
 
@@ -84,10 +93,14 @@ For SSO, do **not** copy a token out of Bob's local credential store unless IBM
 
 | Variable | Default | Description |
 | --- | --- | --- |
-| `IBM_BOB_BASE_URL` | `https://api.us-east.bob.ibm.com/inference/v1` | Approved Bob/IBM endpoint base URL. |
-| `IBM_BOB_MODELS` | `premium` | Comma-separated model IDs exposed by the endpoint. |
+| `IBM_BOB_BASE_URL` | `https://api.us-east.bob.ibm.com/inference/v1` | Approved Bob/IBM endpoint base URL. For `anthropic-messages`, a trailing `/inference/v1` is normalized so the adapter sends requests to `/inference/v1/messages` rather than `/inference/v1/v1/messages`. |
+| `IBM_BOB_MODELS` | `premium` | Comma-separated fallback model IDs used when discovery is unavailable. |
 | `IBM_BOB_API_KEY` | unset | Approved API key/token. Keep it out of repo files. |
+| `IBM_BOB_KEY` | unset | Alias for `IBM_BOB_API_KEY`, matching Bob/OpenCode configuration. |
 | `IBM_BOB_API` | `openai-completions` | One of `openai-completions`, `openai-responses`, `anthropic-messages`. |
+| `IBM_BOB_DISCOVER_MODELS` | `true` | Discover visible models from `/model/info`; entries explicitly marked `exposed: false` are excluded. |
+| `IBM_BOB_MODEL_DISCOVERY_TIMEOUT_MS` | `5000` | Startup/login discovery timeout in milliseconds. |
+| `IBM_BOB_TOKEN_REQUEST_TIMEOUT_MS` | `10000` | SSO token exchange and refresh timeout in milliseconds. |
 
 ### Bob routing headers
 
@@ -96,26 +109,26 @@ For SSO, do **not** copy a token out of Bob's local credential store unless IBM
 | `IBM_BOB_READ_BOBSHELL_SETTINGS` | `true` | Read non-secret `instanceId`/`teamId` from `~/.bob/settings.json`. |
 | `IBM_BOB_INSTANCE_ID` | Bob setting | Override `x-instance-id`. |
 | `IBM_BOB_TEAM_ID` | Bob setting | Override `x-team-id`. |
-| `IBM_BOB_USER_AGENT` | `pi-bob/0.1.0` | User-Agent header sent to Bob endpoint. |
+| `IBM_BOB_USER_AGENT` | `pi-bob/0.2.0` | User-Agent header sent to Bob endpoint. |
 
 ### Auth headers
 
 | Variable | Default | Description |
 | --- | --- | --- |
-| `IBM_BOB_AUTH_SCHEME` | unset/Bearer via Pi's OpenAI adapter | Set to `Apikey` when the Bob token must be sent as `Authorization: Apikey $IBM_BOB_API_KEY`. Do not set this for `/login ibm-bob` SSO. |
+| `IBM_BOB_AUTH_SCHEME` | `Apikey` for environment API keys | Override with `Bearer` when the environment credential is a bearer token. SSO always uses Bearer automatically. |
 | `IBM_BOB_HEADERS_JSON` | unset | JSON object of extra headers. Values may use Pi env interpolation such as `"$IBM_BOB_API_KEY"`. |
 
 ### Model metadata
 
 | Variable | Default | Description |
 | --- | --- | --- |
-| `IBM_BOB_CONTEXT_WINDOW` | `200000` | Context window Pi should assume. Keep this at or below Bob's backend max input tokens so Pi compacts before Bob rejects the request. |
-| `IBM_BOB_MAX_TOKENS` | `8192` | Max output tokens Pi should request/allow. |
-| `IBM_BOB_INPUT` | `text` | Comma-separated input types: `text` or `text,image`. |
-| `IBM_BOB_REASONING` | `false` | Mark all configured models as reasoning-capable. |
-| `IBM_BOB_REASONING_MODELS` | empty | Comma-separated subset of model IDs that support reasoning. |
+| `IBM_BOB_CONTEXT_WINDOW` | discovered; fallback `200000` | Override the context window for every Bob model. Keep it at or below the backend limit so Pi compacts before Bob rejects the request. |
+| `IBM_BOB_MAX_TOKENS` | discovered; fallback `8192` | Override maximum output tokens for every Bob model. |
+| `IBM_BOB_INPUT` | discovered; fallback `text` | Override input types with `text` or `text,image`. |
+| `IBM_BOB_REASONING` | discovered; fallback `false` | Explicitly enable or disable reasoning for all models. |
+| `IBM_BOB_REASONING_MODELS` | empty | Comma-separated model IDs to mark as reasoning-capable. |
 
-Pricing is set to zero until IBM-specific metering details are known.
+Discovered pricing comes from Bob's model-info response and is converted to Pi's per-million-token units. Fallback models retain zero pricing.
 
 ### OpenAI compatibility toggles
 
@@ -128,6 +141,7 @@ export IBM_BOB_MAX_TOKENS_FIELD=max_tokens
 ```
 
 Bob's OpenAI-compatible route currently rejects `tools[].function.strict`, so `IBM_BOB_SUPPORTS_STRICT_MODE=false` is the default.
+It also rejects OpenAI-specific `store` and `prompt_cache_key` request properties with a bare `422`, so both are always disabled for the OpenAI adapters.
 
 ## Validation performed
 
@@ -150,16 +164,17 @@ Result: HTTP `401` with `Authentication required`, confirming the discovered rou
 
 The Bob SSO endpoint flow was smoke-tested independently: browser SSO callback succeeded, token exchange succeeded, and `GET /inference/v1/model/info` returned HTTP `200` using the fresh SSO token.
 
-The Pi provider registers with default settings when an env token is present:
+The Pi provider registers with fallback settings when no authenticated catalog is available:
 
 ```bash
-IBM_BOB_API_KEY=dummy pi -e . --list-models | grep ibm-bob
+pi -e . --list-models | grep ibm-bob
 ```
 
-Result:
+Automated tests cover LiteLLM response validation, hidden-model filtering, per-million cost conversion, API-key discovery, `IBM_BOB_KEY` compatibility, fallback behavior, SSO refresh discovery, routing headers, cached catalog replacement, and final authentication headers/routes through all three advertised adapters:
 
-```text
-ibm-bob         premium                 200K     8.2K     no        no
+```bash
+bun test
+npm run check
 ```
 
 A dummy-token Pi request reaches the Bob endpoint and fails with the expected auth error:
@@ -183,30 +198,48 @@ Result:
 pi-bob-ok
 ```
 
+## Troubleshooting
+
+**`/login ibm-bob` freezes after the browser returns to Pi.** Pi refreshes
+model catalogs for built-in providers after every login by fetching
+`https://pi.dev/api/models/providers/<id>` (the remote-catalog provider). If
+pi.dev's API is unreachable or hangs from your network, that post-login fetch
+blocks with no timeout for roughly 5 minutes, and Ctrl-C cannot cancel it.
+Run Pi with `PI_OFFLINE=1` to skip Pi's network catalog refresh entirely; the
+login then returns to the prompt immediately after SSO, and ibm-bob's own
+model discovery still runs.
+
+**Debugging the login flow.** Run with `IBM_BOB_DEBUG=1` and stderr
+redirected to a file to see per-step timing for the SSO callback, token
+exchange, and model discovery:
+
+```bash
+IBM_BOB_DEBUG=1 pi 2>/tmp/pi-bob-debug.log
+```
+
 ## Install options
 
 Temporary test load:
 
 ```bash
-pi -e /Users/larry.song/work/hashicorp/pi-bob
+pi -e .
 ```
 
 Install as a local Pi package:
 
 ```bash
-pi install /Users/larry.song/work/hashicorp/pi-bob
+pi install npm:pi-bob
 ```
 
 Remove later:
 
 ```bash
-pi remove /Users/larry.song/work/hashicorp/pi-bob
+pi remove npm:pi-bob
 ```
 
 ## Next steps
 
-Option 1 is wired to the discovered Bob OpenAI-compatible route and `/login ibm-bob` is implemented. Next useful improvements:
+The compatible provider, `/login ibm-bob`, and dynamic model discovery are implemented. Next useful improvements:
 
 1. Add a `/bob-status` command that checks auth, model-info, selected instance, and selected team without printing secrets.
-2. Add optional dynamic model discovery from `/inference/v1/model/info` after login.
-3. Add tests around Bob's SSO callback and token refresh helpers.
+2. Run periodic compatibility smoke tests against representative Claude, GPT, and Gemini routes exposed by Bob.

package/extensions/bob.ts

@@ -1,8 +1,17 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import type { OAuthCredentials, OAuthLoginCallbacks } from "@earendil-works/pi-ai";
+import type {
+	Api,
+	AssistantMessageEventStream,
+	Context,
+	Model,
+	OAuthCredentials,
+	OAuthLoginCallbacks,
+	SimpleStreamOptions,
+} from "@earendil-works/pi-ai";
+import { anthropicMessagesApi, openAICompletionsApi, openAIResponsesApi } from "@earendil-works/pi-ai/compat";
 import { randomBytes } from "node:crypto";
 import { readFileSync } from "node:fs";
-import { createServer, type Server } from "node:http";
+import { createServer } from "node:http";
 import { createServer as createNetServer } from "node:net";
 import { homedir } from "node:os";
 import { join } from "node:path";
@@ -27,6 +36,20 @@ interface BobModelConfig {
 	compat?: Record<string, unknown>;
 }
 
+export interface BobDiscoveredModel {
+	id: string;
+	backend: string;
+	reasoning: boolean;
+	supportsVision: boolean;
+	contextWindow?: number;
+	maxTokens?: number;
+	cost: BobModelConfig["cost"];
+}
+
+interface BobOAuthCredentials extends OAuthCredentials {
+	bobModelCatalog?: BobDiscoveredModel[];
+}
+
 interface BobShellSettings {
 	ibm?: {
 		instanceId?: string;
@@ -42,19 +65,26 @@ interface BobTokenResponse {
 }
 
 interface CallbackServer {
-	port: number;
 	callbackUri: string;
 	code: Promise<string>;
 	close(): void;
 }
 
 const PROVIDER_ID = "ibm-bob";
+const BOB_API = "ibm-bob-compatible" as Api;
 const DEFAULT_BOB_ORIGIN = "https://api.us-east.bob.ibm.com";
 const DEFAULT_BASE_URL = `${DEFAULT_BOB_ORIGIN}/inference/v1`;
 const DEFAULT_WEB_LOGIN_URL = "https://bob.ibm.com/login";
 const DEFAULT_MODELS = ["premium"];
 const DEFAULT_CONTEXT_WINDOW = 200_000;
 const DEFAULT_MAX_TOKENS = 8192;
+const DEFAULT_MODEL_DISCOVERY_TIMEOUT_MS = 5000;
+const DEFAULT_TOKEN_REQUEST_TIMEOUT_MS = 10_000;
+const MAX_RESPONSE_BYTES = 1_048_576;
+const MAX_CATALOG_ENTRIES = 500;
+const MAX_CATALOG_LABEL_LENGTH = 512;
+const CATALOG_CONTROL_CHARACTER = /[\u0000-\u001f\u007f-\u009f]/;
+const CATALOG_CONTROL_CHARACTERS = /[\u0000-\u001f\u007f-\u009f]/g;
 const SUPPORTED_APIS = new Set<CompatibleApi>(["openai-completions", "openai-responses", "anthropic-messages"]);
 
 function env(name: string): string | undefined {
@@ -63,10 +93,14 @@ function env(name: string): string | undefined {
 }
 
 function envInt(name: string, fallback: number): number {
+	return envOptionalInt(name) ?? fallback;
+}
+
+function envOptionalInt(name: string): number | undefined {
 	const value = env(name);
-	if (!value) return fallback;
+	if (!value) return undefined;
 	const parsed = Number.parseInt(value, 10);
-	return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+	return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
 }
 
 function envBool(name: string, fallback: boolean): boolean {
@@ -77,6 +111,14 @@ function envBool(name: string, fallback: boolean): boolean {
 	return fallback;
 }
 
+function envOptionalBool(name: string): boolean | undefined {
+	const value = env(name);
+	if (!value) return undefined;
+	if (["1", "true", "yes", "y", "on"].includes(value.toLowerCase())) return true;
+	if (["0", "false", "no", "n", "off"].includes(value.toLowerCase())) return false;
+	return undefined;
+}
+
 function envCsv(name: string, fallback: string[] = []): string[] {
 	const value = env(name);
 	if (!value) return fallback;
@@ -110,6 +152,26 @@ function providerBaseUrl(): string {
 	return env("IBM_BOB_BASE_URL") ?? DEFAULT_BASE_URL;
 }
 
+function providerRequestBaseUrl(api: CompatibleApi): string {
+	const baseUrl = providerBaseUrl().replace(/\/+$/, "");
+	return api === "anthropic-messages" ? baseUrl.replace(/\/inference\/v1$/, "/inference") : baseUrl;
+}
+
+function configuredApiKey(): { envName: "IBM_BOB_API_KEY" | "IBM_BOB_KEY"; value: string } | undefined {
+	const primary = env("IBM_BOB_API_KEY");
+	if (primary) return { envName: "IBM_BOB_API_KEY", value: primary };
+	const alias = env("IBM_BOB_KEY");
+	return alias ? { envName: "IBM_BOB_KEY", value: alias } : undefined;
+}
+
+function providerApiKeyReference(): string {
+	return `$${configuredApiKey()?.envName ?? "IBM_BOB_API_KEY"}`;
+}
+
+function apiKeyAuthScheme(): string {
+	return env("IBM_BOB_AUTH_SCHEME") ?? "Apikey";
+}
+
 function bobOrigin(): string {
 	const explicit = env("IBM_BOB_AUTH_BASE_URL");
 	if (explicit) return explicit.replace(/\/$/, "");
@@ -177,7 +239,7 @@ function parseJsonHeaders(): Record<string, string> | undefined {
 
 function buildHeaders(settings?: BobShellSettings): Record<string, string> | undefined {
 	const headers: Record<string, string> = {
-		"User-Agent": env("IBM_BOB_USER_AGENT") ?? "pi-bob/0.1.0",
+		"User-Agent": env("IBM_BOB_USER_AGENT") ?? "pi-bob/0.2.0",
 	};
 
 	const instanceId = env("IBM_BOB_INSTANCE_ID") ?? settings?.ibm?.instanceId;
@@ -185,11 +247,6 @@ function buildHeaders(settings?: BobShellSettings): Record<string, string> | und
 	if (instanceId) headers["x-instance-id"] = instanceId;
 	if (teamId) headers["x-team-id"] = teamId;
 
-	const authScheme = env("IBM_BOB_AUTH_SCHEME");
-	if (authScheme && authScheme.toLowerCase() !== "bearer") {
-		headers.Authorization = `${authScheme} $IBM_BOB_API_KEY`;
-	}
-
 	const jsonHeaders = parseJsonHeaders();
 	if (jsonHeaders) Object.assign(headers, jsonHeaders);
 
@@ -225,6 +282,10 @@ function buildOpenAiCompat(api: CompatibleApi): Record<string, unknown> | undefi
 		supportsReasoningEffort: envBool("IBM_BOB_SUPPORTS_REASONING_EFFORT", false),
 		supportsUsageInStreaming: envBool("IBM_BOB_SUPPORTS_USAGE_IN_STREAMING", true),
 		supportsStrictMode: envBool("IBM_BOB_SUPPORTS_STRICT_MODE", false),
+		// pi-ai auto-detect defaults these to true for unknown endpoints; Bob's
+		// strict validator rejects `store` and `prompt_cache_key` with a bare 422.
+		supportsStore: false,
+		supportsLongCacheRetention: false,
 	};
 
 	const maxTokensField = env("IBM_BOB_MAX_TOKENS_FIELD") as MaxTokensField | undefined;
@@ -249,19 +310,143 @@ function buildAnthropicCompat(api: CompatibleApi): Record<string, unknown> | und
 	};
 }
 
-function buildModels(api: CompatibleApi): BobModelConfig[] {
-	const ids = envCsv("IBM_BOB_MODELS", DEFAULT_MODELS);
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function positiveNumber(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : undefined;
+}
+
+function perMillionCost(value: unknown): number {
+	if (typeof value !== "number" || !Number.isFinite(value) || value < 0) return 0;
+	const scaled = value * 1_000_000;
+	return Number.isFinite(scaled) ? scaled : 0;
+}
+
+function safeCatalogLabel(value: unknown): string {
+	if (typeof value !== "string") return "";
+	const label = value.trim();
+	return label && label.length <= MAX_CATALOG_LABEL_LENGTH && !CATALOG_CONTROL_CHARACTER.test(label) ? label : "";
+}
+
+export function parseBobModelCatalog(payload: unknown): BobDiscoveredModel[] {
+	if (!isRecord(payload) || !Array.isArray(payload.data)) {
+		throw new Error("IBM Bob model-info response did not contain a data array.");
+	}
+	if (payload.data.length > MAX_CATALOG_ENTRIES) {
+		throw new Error(`IBM Bob model-info response exceeded ${MAX_CATALOG_ENTRIES} entries.`);
+	}
+
+	const models: BobDiscoveredModel[] = [];
+	const seen = new Set<string>();
+	let structurallyValidEntries = 0;
+	for (const entry of payload.data) {
+		if (!isRecord(entry) || !isRecord(entry.model_info) || !isRecord(entry.litellm_params)) continue;
+		const id = safeCatalogLabel(entry.model_name);
+		const backend = safeCatalogLabel(entry.litellm_params.model);
+		if (!id || !backend) continue;
+		const exposed = entry.model_info.exposed;
+		if (exposed !== undefined && typeof exposed !== "boolean") continue;
+		structurallyValidEntries++;
+
+		const visible = exposed === undefined || exposed === true;
+		if (!visible || seen.has(id)) continue;
+
+		seen.add(id);
+		models.push({
+			id,
+			backend,
+			reasoning:
+				entry.model_info.supports_reasoning === true ||
+				entry.model_info.supports_reasoning_effort === true ||
+				entry.model_info.supports_thinking === true,
+			supportsVision: entry.model_info.supports_vision === true,
+			contextWindow: positiveNumber(entry.model_info.max_input_tokens),
+			maxTokens: positiveNumber(entry.model_info.max_tokens),
+			cost: {
+				input: perMillionCost(entry.model_info.input_cost_per_token),
+				output: perMillionCost(entry.model_info.output_cost_per_token),
+				cacheRead: perMillionCost(entry.model_info.cache_read_input_token_cost),
+				cacheWrite: perMillionCost(entry.model_info.cache_creation_input_token_cost),
+			},
+		});
+	}
+
+	if (structurallyValidEntries === 0) {
+		throw new Error("IBM Bob model-info response contained no structurally valid model entries.");
+	}
+	if (models.length === 0) {
+		throw new Error("IBM Bob model-info response contained no visible models.");
+	}
+	return models;
+}
+
+function sanitizeCachedCatalog(value: unknown): BobDiscoveredModel[] | undefined {
+	if (!Array.isArray(value)) return undefined;
+	const models: BobDiscoveredModel[] = [];
+	const seen = new Set<string>();
+	for (const entry of value) {
+		if (!isRecord(entry) || !isRecord(entry.cost)) continue;
+		const id = safeCatalogLabel(entry.id);
+		const backend = safeCatalogLabel(entry.backend);
+		if (!id || !backend || seen.has(id)) continue;
+		seen.add(id);
+		models.push({
+			id,
+			backend,
+			reasoning: entry.reasoning === true,
+			supportsVision: entry.supportsVision === true,
+			contextWindow: positiveNumber(entry.contextWindow),
+			maxTokens: positiveNumber(entry.maxTokens),
+			cost: {
+				input: positiveNumber(entry.cost.input) ?? 0,
+				output: positiveNumber(entry.cost.output) ?? 0,
+				cacheRead: positiveNumber(entry.cost.cacheRead) ?? 0,
+				cacheWrite: positiveNumber(entry.cost.cacheWrite) ?? 0,
+			},
+		});
+	}
+	return models.length > 0 ? models : undefined;
+}
+
+function cachedCatalog(credentials: OAuthCredentials | undefined): BobDiscoveredModel[] | undefined {
+	return sanitizeCachedCatalog((credentials as BobOAuthCredentials | undefined)?.bobModelCatalog);
+}
+
+export function buildModels(api: CompatibleApi, discovered?: BobDiscoveredModel[]): BobModelConfig[] {
 	const reasoningModels = parseReasoningModels();
-	const allReasoning = envBool("IBM_BOB_REASONING", false);
-	const input = parseInputTypes();
-	const contextWindow = envInt("IBM_BOB_CONTEXT_WINDOW", DEFAULT_CONTEXT_WINDOW);
-	const maxTokens = envInt("IBM_BOB_MAX_TOKENS", DEFAULT_MAX_TOKENS);
+	const reasoningOverride = envOptionalBool("IBM_BOB_REASONING");
+	const inputOverride = env("IBM_BOB_INPUT") ? parseInputTypes() : undefined;
+	const contextOverride = envOptionalInt("IBM_BOB_CONTEXT_WINDOW");
+	const maxTokensOverride = envOptionalInt("IBM_BOB_MAX_TOKENS");
 	const compat = buildOpenAiCompat(api) ?? buildAnthropicCompat(api);
 
+	if (discovered && discovered.length > 0) {
+		return discovered.map((model) => ({
+			id: model.id,
+			name: model.backend === model.id ? modelName(model.id) : `${modelName(model.id)} — ${model.backend}`,
+			reasoning:
+				reasoningOverride === true ||
+				reasoningModels.has(model.id) ||
+				(reasoningOverride === undefined && model.reasoning),
+			input: inputOverride ?? (model.supportsVision ? ["text", "image"] : ["text"]),
+			contextWindow: contextOverride ?? model.contextWindow ?? DEFAULT_CONTEXT_WINDOW,
+			maxTokens: maxTokensOverride ?? model.maxTokens ?? DEFAULT_MAX_TOKENS,
+			cost: model.cost,
+			...(compat ? { compat } : {}),
+		}));
+	}
+
+	const configuredIds = envCsv("IBM_BOB_MODELS", DEFAULT_MODELS);
+	const ids = configuredIds.length > 0 ? configuredIds : DEFAULT_MODELS;
+	const input = inputOverride ?? parseInputTypes();
+	const contextWindow = contextOverride ?? DEFAULT_CONTEXT_WINDOW;
+	const maxTokens = maxTokensOverride ?? DEFAULT_MAX_TOKENS;
 	return ids.map((id) => ({
 		id,
 		name: modelName(id),
-		reasoning: allReasoning || reasoningModels.has(id),
+		reasoning: reasoningOverride === true || reasoningModels.has(id),
 		input,
 		contextWindow,
 		maxTokens,
@@ -270,19 +455,212 @@ function buildModels(api: CompatibleApi): BobModelConfig[] {
 	}));
 }
 
-function jwtExpiry(accessToken: string): number | undefined {
+async function readBoundedResponseBody(response: Response): Promise<string> {
+	const declaredLength = Number(response.headers.get("content-length"));
+	if (Number.isFinite(declaredLength) && declaredLength > MAX_RESPONSE_BYTES) {
+		throw new Error(`IBM Bob response exceeded ${MAX_RESPONSE_BYTES} bytes.`);
+	}
+	if (!response.body) return "";
+
+	const reader = response.body.getReader();
+	const decoder = new TextDecoder();
+	let bytesRead = 0;
+	let body = "";
 	try {
-		const [, payload] = accessToken.split(".");
-		if (!payload) return undefined;
-		const json = Buffer.from(payload.replace(/-/g, "+").replace(/_/g, "/"), "base64").toString("utf8");
-		const parsed = JSON.parse(json) as { exp?: unknown };
-		if (typeof parsed.exp !== "number") return undefined;
-		return parsed.exp * 1000 - 5 * 60 * 1000;
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			bytesRead += value.byteLength;
+			if (bytesRead > MAX_RESPONSE_BYTES) {
+				await reader.cancel();
+				throw new Error(`IBM Bob response exceeded ${MAX_RESPONSE_BYTES} bytes.`);
+			}
+			body += decoder.decode(value, { stream: true });
+		}
+		return body + decoder.decode();
+	} finally {
+		reader.releaseLock();
+	}
+}
+
+async function readJsonResponse(response: Response): Promise<unknown> {
+	const body = await readBoundedResponseBody(response);
+	return JSON.parse(body);
+}
+
+function truncateHttpBody(body: string): string {
+	const trimmed = body.trim();
+	const truncated = trimmed.length > 512 ? `${trimmed.slice(0, 512)}…` : trimmed;
+	return truncated.replace(CATALOG_CONTROL_CHARACTERS, (character) =>
+		`\\u${character.charCodeAt(0).toString(16).padStart(4, "0")}`,
+	);
+}
+
+async function fetchBobModelCatalog(
+	accessToken: string,
+	authScheme: string,
+	settings?: BobShellSettings,
+): Promise<BobDiscoveredModel[]> {
+	const startedAt = Date.now();
+	const controller = new AbortController();
+	const timeoutMs = envInt("IBM_BOB_MODEL_DISCOVERY_TIMEOUT_MS", DEFAULT_MODEL_DISCOVERY_TIMEOUT_MS);
+	const timeout = setTimeout(() => controller.abort(), timeoutMs);
+	const headers: Record<string, string> = {
+		Accept: "application/json",
+		Authorization: `${authScheme} ${accessToken}`,
+		"User-Agent": env("IBM_BOB_USER_AGENT") ?? "pi-bob/0.2.0",
+	};
+	const instanceId =
+		env("IBM_BOB_INSTANCE_ID") ?? settings?.ibm?.instanceId ?? readInstanceFromJwt(accessToken);
+	const teamId = env("IBM_BOB_TEAM_ID") ?? settings?.ibm?.teamId;
+	if (instanceId) headers["x-instance-id"] = instanceId;
+	if (teamId) headers["x-team-id"] = teamId;
+	bobLog(
+		`model discovery → ${providerBaseUrl().replace(/\/+$/, "")}/model/info (instance=${instanceId ?? "none"}, timeout=${timeoutMs}ms)`,
+	);
+
+	try {
+		const response = await fetch(`${providerBaseUrl().replace(/\/+$/, "")}/model/info`, {
+			method: "GET",
+			headers,
+			signal: controller.signal,
+		});
+		if (!response.ok) {
+			throw new Error(
+				`IBM Bob model discovery failed: ${response.status} ${truncateHttpBody(await readBoundedResponseBody(response))}`.trim(),
+			);
+		}
+		const catalog = parseBobModelCatalog(await readJsonResponse(response));
+		bobLog(`model discovery ok: ${catalog.length} models in ${Date.now() - startedAt}ms`);
+		return catalog;
+	} catch (error) {
+		if (controller.signal.aborted) {
+			throw new Error(`IBM Bob model discovery timed out after ${timeoutMs}ms.`);
+		}
+		bobLog(
+			`model discovery failed in ${Date.now() - startedAt}ms: ${error instanceof Error ? error.message : String(error)}`,
+		);
+		throw error;
+	} finally {
+		clearTimeout(timeout);
+	}
+}
+
+async function attachBobModelCatalog(
+	credentials: OAuthCredentials,
+	previous?: OAuthCredentials,
+): Promise<BobOAuthCredentials> {
+	if (!envBool("IBM_BOB_DISCOVER_MODELS", true)) {
+		const previousCatalog = cachedCatalog(previous);
+		return previousCatalog ? { ...credentials, bobModelCatalog: previousCatalog } : credentials;
+	}
+
+	try {
+		const catalog = await fetchBobModelCatalog(credentials.access, "Bearer", readBobShellSettings());
+		return { ...credentials, bobModelCatalog: catalog };
+	} catch (error) {
+		const previousCatalog = cachedCatalog(previous);
+		console.warn(
+			`pi-bob: ${error instanceof Error ? error.message : String(error)} Using ${
+				previousCatalog ? "the previously cached catalog" : "configured fallback models"
+			}.`,
+		);
+		return previousCatalog ? { ...credentials, bobModelCatalog: previousCatalog } : credentials;
+	}
+}
+
+function jwtPayload(accessToken: string): Record<string, unknown> | undefined {
+	try {
+		const parts = accessToken.split(".");
+		if (parts.length !== 3 || !parts[1]) return undefined;
+		const json = Buffer.from(parts[1].replace(/-/g, "+").replace(/_/g, "/"), "base64").toString("utf8");
+		const parsed = JSON.parse(json) as unknown;
+		return isRecord(parsed) ? parsed : undefined;
 	} catch {
 		return undefined;
 	}
 }
 
+function jwtExpiry(accessToken: string): number | undefined {
+	const exp = jwtPayload(accessToken)?.exp;
+	return typeof exp === "number" ? exp * 1000 - 5 * 60 * 1000 : undefined;
+}
+
+function readInstanceFromJwt(accessToken: string | undefined): string | undefined {
+	if (!accessToken) return undefined;
+	const instances = jwtPayload(accessToken)?.instances;
+	if (!Array.isArray(instances) || instances.length === 0) return undefined;
+	for (const entry of instances) {
+		if (isRecord(entry) && typeof entry.id === "string" && entry.id) return entry.id;
+	}
+	return undefined;
+}
+
+function bobLog(message: string): void {
+	if (!envBool("IBM_BOB_DEBUG", false)) return;
+	console.warn(`[pi-bob] ${new Date().toISOString()} ${message}`);
+}
+
+export function applyBobAuthHeaders(
+	headers: Record<string, string | null | undefined>,
+	resolvedCredential?: string,
+): void {
+	let token = resolvedCredential;
+	if (!token) {
+		for (const [name, value] of Object.entries(headers)) {
+			if (typeof value !== "string") continue;
+			const lowerName = name.toLowerCase();
+			if (lowerName === "authorization") {
+				const match = value.match(/^\s*(?:Bearer|Apikey)\s+(.+)\s*$/iu);
+				if (match?.[1]) token = match[1];
+			} else if (lowerName === "x-api-key" && value.trim()) {
+				token ??= value.trim();
+			}
+		}
+	}
+	if (!token) return;
+
+	for (const name of Object.keys(headers)) {
+		const lowerName = name.toLowerCase();
+		if (lowerName === "authorization" || lowerName === "x-api-key") headers[name] = null;
+	}
+	const scheme = jwtPayload(token) ? "Bearer" : apiKeyAuthScheme();
+	headers.Authorization = `${scheme} ${token}`;
+}
+
+function streamBob(
+	adapter: CompatibleApi,
+	model: Model<Api>,
+	context: Context,
+	options?: SimpleStreamOptions,
+): AssistantMessageEventStream {
+	const mutableHeaders: Record<string, string | null | undefined> = { ...options?.headers };
+	applyBobAuthHeaders(mutableHeaders, options?.apiKey);
+	const headers = Object.fromEntries(
+		Object.entries(mutableHeaders).filter((entry): entry is [string, string] => typeof entry[1] === "string"),
+	);
+	const hasHeaderAuth = Object.keys(headers).some((name) => name.toLowerCase() === "authorization");
+	const forwardedOptions: SimpleStreamOptions = { ...options, headers };
+
+	switch (adapter) {
+		case "anthropic-messages":
+			return anthropicMessagesApi().streamSimple(model as Model<"anthropic-messages">, context, {
+				...forwardedOptions,
+				apiKey: hasHeaderAuth ? undefined : options?.apiKey,
+			});
+		case "openai-responses":
+			return openAIResponsesApi().streamSimple(model as Model<"openai-responses">, context, {
+				...forwardedOptions,
+				apiKey: hasHeaderAuth ? "pi-bob-header-auth" : options?.apiKey,
+			});
+		default:
+			return openAICompletionsApi().streamSimple(model as Model<"openai-completions">, context, {
+				...forwardedOptions,
+				apiKey: hasHeaderAuth ? "pi-bob-header-auth" : options?.apiKey,
+			});
+	}
+}
+
 function credentialsFromTokenResponse(response: BobTokenResponse, previousRefresh?: string): OAuthCredentials {
 	if (!response.token) throw new Error("IBM Bob SSO response did not include an access token.");
 	return {
@@ -317,6 +695,7 @@ async function startCallbackServer(state: string): Promise<CallbackServer> {
 
 	const code = new Promise<string>((resolve, reject) => {
 		server.on("request", (req, res) => {
+			bobLog(`login: callback request received: ${(req.url ?? "").split("?")[0] || "(no path)"}`);
 			if (!req.url?.startsWith("/bob-callback")) {
 				res.writeHead(404, { "Content-Type": "text/plain" });
 				res.end("Not Found");
@@ -330,6 +709,7 @@ async function startCallbackServer(state: string): Promise<CallbackServer> {
 				const error = url.searchParams.get("error");
 
 				if (returnedState !== state) {
+					bobLog(`login: callback state mismatch (expected ${state}, got ${returnedState})`);
 					res.writeHead(400, { "Content-Type": "text/plain" });
 					res.end("Invalid state parameter");
 					reject(new Error("Invalid state parameter from IBM Bob SSO callback."));
@@ -337,6 +717,7 @@ async function startCallbackServer(state: string): Promise<CallbackServer> {
 				}
 
 				if (error) {
+					bobLog(`login: callback auth error: ${error}`);
 					res.writeHead(400, { "Content-Type": "text/plain" });
 					res.end("Authentication failed");
 					reject(new Error(`IBM Bob SSO failed: ${error}`));
@@ -344,6 +725,7 @@ async function startCallbackServer(state: string): Promise<CallbackServer> {
 				}
 
 				if (!authCode) {
+					bobLog("login: callback missing authorization code");
 					res.writeHead(400, { "Content-Type": "text/plain" });
 					res.end("Missing authorization code");
 					reject(new Error("IBM Bob SSO callback did not include an authorization code."));
@@ -363,7 +745,10 @@ async function startCallbackServer(state: string): Promise<CallbackServer> {
 				reject(error);
 			}
 		});
-		server.on("error", reject);
+		server.on("error", (error) => {
+			bobLog(`login: callback server error: ${error instanceof Error ? error.message : String(error)}`);
+			reject(error);
+		});
 	});
 
 	await new Promise<void>((resolve, reject) => {
@@ -375,7 +760,6 @@ async function startCallbackServer(state: string): Promise<CallbackServer> {
 	});
 
 	return {
-		port,
 		callbackUri: `http://localhost:${port}/bob-callback`,
 		code,
 		close() {
@@ -385,71 +769,175 @@ async function startCallbackServer(state: string): Promise<CallbackServer> {
 }
 
 async function postToken(path: "/authn/v1/auth/token" | "/authn/v1/auth/refresh", body: unknown): Promise<BobTokenResponse> {
-	const response = await fetch(`${bobOrigin()}${path}`, {
-		method: "POST",
-		headers: { "Content-Type": "application/json", "User-Agent": env("IBM_BOB_USER_AGENT") ?? "pi-bob/0.1.0" },
-		body: JSON.stringify(body),
-	});
+	const startedAt = Date.now();
+	const controller = new AbortController();
+	const timeoutMs = envInt("IBM_BOB_TOKEN_REQUEST_TIMEOUT_MS", DEFAULT_TOKEN_REQUEST_TIMEOUT_MS);
+	const timeout = setTimeout(() => controller.abort(), timeoutMs);
+	bobLog(`token request → ${bobOrigin()}${path} (timeout=${timeoutMs}ms)`);
+	try {
+		const response = await fetch(`${bobOrigin()}${path}`, {
+			method: "POST",
+			headers: { "Content-Type": "application/json", "User-Agent": env("IBM_BOB_USER_AGENT") ?? "pi-bob/0.2.0" },
+			body: JSON.stringify(body),
+			signal: controller.signal,
+		});
 
-	if (!response.ok) {
-		throw new Error(`IBM Bob SSO token request failed: ${response.status} ${await response.text()}`);
-	}
+		if (!response.ok) {
+			throw new Error(
+				`IBM Bob SSO token request failed: ${response.status} ${truncateHttpBody(await readBoundedResponseBody(response))}`,
+			);
+		}
 
-	return (await response.json()) as BobTokenResponse;
+		bobLog(`token request ok in ${Date.now() - startedAt}ms`);
+		return (await readJsonResponse(response)) as BobTokenResponse;
+	} catch (error) {
+		if (controller.signal.aborted) throw new Error(`IBM Bob SSO token request timed out after ${timeoutMs}ms.`);
+		throw error;
+	} finally {
+		clearTimeout(timeout);
+	}
 }
 
 async function loginBob(callbacks: OAuthLoginCallbacks): Promise<OAuthCredentials> {
+	const startedAt = Date.now();
+	const elapsed = () => `${((Date.now() - startedAt) / 1000).toFixed(1)}s`;
+	bobLog("login: starting IBM Bob SSO");
+
 	const state = randomBytes(16).toString("hex");
 	const callbackServer = await startCallbackServer(state);
+	bobLog(`login: callback server listening at ${callbackServer.callbackUri} (+${elapsed()})`);
+
 	const loginUrl = new URL(bobWebLoginUrl());
 	loginUrl.searchParams.set("callback_uri", callbackServer.callbackUri);
 	loginUrl.searchParams.set("state", state);
 
+	const signal = callbacks.signal;
+	let loginTimeout: ReturnType<typeof setTimeout> | undefined;
+	let progressInterval: ReturnType<typeof setInterval> | undefined;
+	let onAbort: (() => void) | undefined;
 	try {
 		callbacks.onAuth({ url: loginUrl.toString() });
-		callbacks.onDeviceCode?.({
-			userCode: "Browser SSO",
-			verificationUri: loginUrl.toString(),
-			expiresInSeconds: Math.floor(envInt("IBM_BOB_LOGIN_TIMEOUT_MS", 180_000) / 1000),
-		});
+		bobLog(`login: browser opened for SSO (+${elapsed()})`);
 
 		const timeoutMs = envInt("IBM_BOB_LOGIN_TIMEOUT_MS", 180_000);
 		const timeout = new Promise<never>((_resolve, reject) => {
-			setTimeout(() => reject(new Error("IBM Bob SSO timed out.")), timeoutMs);
+			loginTimeout = setTimeout(() => {
+				bobLog(`login: SSO timed out after ${timeoutMs}ms (+${elapsed()})`);
+				reject(new Error("IBM Bob SSO timed out."));
+			}, timeoutMs);
 		});
 
-		const code = await Promise.race([callbackServer.code, timeout]);
-		return credentialsFromTokenResponse(await postToken("/authn/v1/auth/token", { code }));
+		const abort =
+			signal === undefined
+				? undefined
+				: new Promise<never>((_resolve, reject) => {
+						if (signal.aborted) {
+							bobLog("login: cancelled (abort signal already fired)");
+							reject(new Error("Login cancelled"));
+							return;
+						}
+						onAbort = () => {
+							bobLog(`login: cancelled via abort signal (+${elapsed()})`);
+							reject(new Error("Login cancelled"));
+						};
+						signal.addEventListener("abort", onAbort, { once: true });
+					});
+
+		progressInterval = setInterval(() => {
+			bobLog(`login: still waiting for SSO browser callback (+${elapsed()})`);
+		}, Math.min(15_000, Math.max(5_000, Math.floor(timeoutMs / 12))));
+
+		const races: Array<Promise<string | never>> = [callbackServer.code, timeout];
+		if (abort) races.push(abort);
+		const code = await Promise.race(races);
+		bobLog(`login: SSO callback received (+${elapsed()})`);
+
+		const credentials = credentialsFromTokenResponse(await postToken("/authn/v1/auth/token", { code }));
+		bobLog(`login: access token exchanged (+${elapsed()})`);
+
+		const withCatalog = await attachBobModelCatalog(credentials);
+		bobLog(`login: model catalog attached (+${elapsed()})`);
+
+		return withCatalog;
+	} catch (error) {
+		bobLog(`login: failed (+${elapsed()}): ${error instanceof Error ? error.message : String(error)}`);
+		throw error;
 	} finally {
+		if (loginTimeout) clearTimeout(loginTimeout);
+		if (progressInterval) clearInterval(progressInterval);
+		if (onAbort && signal) signal.removeEventListener("abort", onAbort);
 		callbackServer.close();
 	}
 }
 
 async function refreshBobToken(credentials: OAuthCredentials): Promise<OAuthCredentials> {
 	if (!credentials.refresh) throw new Error("No IBM Bob refresh token is available. Run /login ibm-bob again.");
-	return credentialsFromTokenResponse(
+	const refreshed = credentialsFromTokenResponse(
 		await postToken("/authn/v1/auth/refresh", { refresh_token: credentials.refresh }),
 		credentials.refresh,
 	);
+	// Token refresh runs inside pi-ai's locked credentials.modify (auth.json lock).
+	// Avoid holding that global lock across a model-discovery network call when a
+	// catalog is already cached; rediscovery still happens on login and whenever
+	// no cached catalog exists.
+	const existingCatalog = cachedCatalog(credentials);
+	if (existingCatalog) {
+		bobLog(`refresh: reusing cached catalog (${existingCatalog.length} models); skipping rediscovery`);
+		return { ...refreshed, bobModelCatalog: existingCatalog };
+	}
+	return attachBobModelCatalog(refreshed, credentials);
+}
+
+function modifyModelsFromCachedCatalog(
+	models: Model<Api>[],
+	credentials: OAuthCredentials,
+	api: CompatibleApi,
+): Model<Api>[] {
+	if (!envBool("IBM_BOB_DISCOVER_MODELS", true)) return models;
+	const catalog = cachedCatalog(credentials);
+	const otherProviders = models.filter((model) => model.provider !== PROVIDER_ID);
+	const discovered = buildModels(api, catalog).map(
+		(model) =>
+			({
+				...model,
+				api: BOB_API,
+				provider: PROVIDER_ID,
+				baseUrl: providerRequestBaseUrl(api),
+			}) as Model<Api>,
+	);
+	return [...otherProviders, ...discovered];
 }
 
-export default function (pi: ExtensionAPI) {
+export default async function (pi: ExtensionAPI) {
 	const api = parseApi();
 	const settings = readBobShellSettings();
 	const headers = buildHeaders(settings);
+	let catalog: BobDiscoveredModel[] | undefined;
+	const apiKey = configuredApiKey();
+	if (apiKey && envBool("IBM_BOB_DISCOVER_MODELS", true)) {
+		try {
+			catalog = await fetchBobModelCatalog(apiKey.value, apiKeyAuthScheme(), settings);
+		} catch (error) {
+			console.warn(
+				`pi-bob: ${error instanceof Error ? error.message : String(error)} Using configured fallback models.`,
+			);
+		}
+	}
 
 	pi.registerProvider(PROVIDER_ID, {
 		name: "IBM Bob",
-		baseUrl: providerBaseUrl(),
-		apiKey: "$IBM_BOB_API_KEY",
-		api,
+		baseUrl: providerRequestBaseUrl(api),
+		apiKey: providerApiKeyReference(),
+		api: BOB_API,
 		...(headers ? { headers } : {}),
-		models: buildModels(api),
+		models: buildModels(api, catalog),
+		streamSimple: (model, context, options) => streamBob(api, model, context, options),
 		oauth: {
 			name: "IBM Bob SSO",
 			login: loginBob,
 			refreshToken: refreshBobToken,
 			getApiKey: (credentials) => credentials.access,
+			modifyModels: (models, credentials) => modifyModelsFromCachedCatalog(models, credentials, api),
 		},
 	});
 }

package/package.json

@@ -1,7 +1,6 @@
 {
   "name": "pi-bob",
-  "version": "0.1.0",
-
+  "version": "0.2.1",
   "type": "module",
   "description": "Pi provider extension for IBM Bob / IBM-approved compatible model endpoints.",
   "keywords": [
@@ -16,11 +15,16 @@
       "./extensions/bob.ts"
     ]
   },
+  "files": [
+    "extensions/bob.ts",
+    "README.md",
+    "LICENSE"
+  ],
   "author": "Larry Song",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/songlining/pi-bob.git"
+    "url": "git+https://github.com/songlining/pi-bob.git"
   },
   "bugs": {
     "url": "https://github.com/songlining/pi-bob/issues"
@@ -28,10 +32,16 @@
   "homepage": "https://github.com/songlining/pi-bob#readme",
   "scripts": {
     "check": "pi -e . --list-models >/dev/null",
+    "test": "bun test",
     "clean": "echo 'nothing to clean'",
     "build": "echo 'nothing to build'"
   },
   "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "0.80.7",
+    "@earendil-works/pi-coding-agent": "0.80.7"
   }
 }

package/PLAN.md

@@ -1,96 +0,0 @@
-# IBM Bob provider plan
-
-## Safety boundaries
-
-- Use only IBM-approved Bob/model endpoints and credentials the user is authorised to use.
-- Do not scrape, extract, copy, or reuse Bob browser/session credentials.
-- Do not store secrets in this repository or in chat transcripts.
-- Prefer environment variables, password-manager commands, formal Pi `/login` support, or approved local auth helpers for credentials.
-
-## Implementation strategy
-
-### Option 1 — compatible provider first
-
-Implement a Pi package that registers IBM Bob as a normal Pi provider using Pi's built-in compatible API adapters:
-
-- `openai-completions` for OpenAI Chat Completions-compatible Bob routes.
-- `openai-responses` for OpenAI Responses-compatible Bob routes.
-- `anthropic-messages` for Anthropic Messages-compatible Bob routes.
-
-This avoids custom streaming code and keeps the integration transparent: Pi serializes messages, tools, streaming, and usage exactly as it already does for compatible providers.
-
-### Option 2 — approved SSO/auth wrapper
-
-If Bob uses short-lived IBM SSO/IAM/direct-access tokens but still exposes an OpenAI/Anthropic-compatible model API, add a Pi `/login ibm-bob` flow or an approved auth-helper integration that obtains tokens, injects headers, and delegates to Pi's built-in streamers.
-
-Implemented: `/login ibm-bob` uses Bob's browser SSO endpoints (`/authn/v1/auth/token` and `/authn/v1/auth/refresh`) and Pi's standard OAuth credential store. It does not extract Bob Shell's stored token from `~/.bob/settings.json` or Bob's credential store.
-
-### Option 3 — native Bob/watsonx adapter
-
-Only if Bob exposes a non-compatible native API, implement a full `streamSimple` adapter that maps Pi context and tool calls to Bob requests and Bob streaming events back to Pi assistant-message events.
-
-## Discovered local Bob Shell facts
-
-From `bobshell@1.0.6` installed at `/opt/homebrew/lib/node_modules/bobshell`:
-
-- CLI path: `/opt/homebrew/bin/bob`
-- Local auth method: `sso`
-- Default Bob API host: `https://api.us-east.bob.ibm.com`
-- OpenAI-compatible base URL: `https://api.us-east.bob.ibm.com/inference/v1`
-- Chat route: `/inference/v1/chat/completions`
-- Model-info route: `/inference/v1/model/info`
-- Default model alias: `premium`
-- Other visible aliases/constants: `pro`, `flash`, `flash-lite`, `bob-3-pro-preview`
-- Installed Bob Shell contains a broad ~1M context-window default, but the observed `premium` backend route maps to Claude Sonnet 4.5 with `Max Input Tokens=200000`.
-- Provider default context window for Pi: `200000`, so Pi compacts before Bob rejects oversized requests.
-- Default max output token constant: `8192`
-- Non-secret routing headers: `x-instance-id`, `x-team-id`
-- SSO browser login URL: `https://bob.ibm.com/login?callback_uri=...&state=...`
-- SSO token endpoint: `/authn/v1/auth/token`
-- SSO refresh endpoint: `/authn/v1/auth/refresh`
-
-## Option 1 execution
-
-This repository now contains a local Pi package:
-
-- `package.json` declares a Pi package.
-- `extensions/bob.ts` registers provider `ibm-bob` and Pi `/login ibm-bob` SSO.
-- `README.md` documents discovered settings, setup, and validation.
-
-Defaults now target the discovered Bob Shell route:
-
-- `IBM_BOB_BASE_URL=https://api.us-east.bob.ibm.com/inference/v1`
-- `IBM_BOB_API=openai-completions`
-- `IBM_BOB_MODELS=premium`
-- `IBM_BOB_CONTEXT_WINDOW=200000`
-- `IBM_BOB_MAX_TOKENS=8192`
-
-The extension reads only non-secret `ibm.instanceId` and `ibm.teamId` from `~/.bob/settings.json` unless `IBM_BOB_READ_BOBSHELL_SETTINGS=false`.
-
-Secret configuration remains external:
-
-- Pi `/login ibm-bob`, which stores fresh SSO credentials in `~/.pi/agent/auth.json`, or
-- `IBM_BOB_API_KEY`, or
-- `IBM_BOB_HEADERS_JSON` with environment-variable placeholders, or
-- future approved local auth-helper support.
-
-## Validation completed
-
-- Bob Shell SSO test succeeded with `bob --auth-method sso -m premium`.
-- Direct unauthenticated model-info call reached the discovered endpoint and returned expected `401 Authentication required`.
-- Pi provider lists `ibm-bob/premium` with dummy token.
-- Pi request with dummy token reaches Bob and returns expected `401 unauthorized`.
-- Independent Bob SSO smoke test succeeded: callback received, token exchange succeeded, and authenticated model-info returned HTTP `200`.
-- Direct minimal chat completion returned `direct-bob-ok`.
-- Direct tool payload test showed Bob rejects `tools[].function.strict`; provider default now sets `supportsStrictMode=false`.
-- Pi end-to-end with fresh SSO token succeeded: `pi-bob-ok`.
-- After a real context overflow from Bob (`Max Input Tokens=200000, Got=236458`), the provider default context window was lowered from `1048576` to `200000` so Pi's own compaction/overflow handling can engage before Bob rejects the request.
-
-## Remaining work
-
-The provider works end-to-end for a basic Pi prompt through Bob's OpenAI-compatible route. Useful next steps:
-
-1. Run interactive `/login ibm-bob` once inside Pi to persist SSO credentials in Pi's auth store.
-2. Add `/bob-status` for no-secret health checks.
-3. Add dynamic model discovery from `/inference/v1/model/info`.
-4. Add regression tests for SSO callback, refresh, and strict-tool compatibility.