pi-bob 0.2.0 → 0.2.1

package/README.md

@@ -8,8 +8,8 @@ The package registers Bob through Pi's built-in compatible provider APIs and dis
 
 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`
@@ -43,7 +43,7 @@ The extension registers provider id `ibm-bob`. It uses an isolated `ibm-bob-comp
 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 each token refresh. A sanitized, non-secret copy is cached with Pi's OAuth credentials so the models can be restored on later startups.
+- 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.
 
@@ -54,7 +54,7 @@ Discovered context limits, output limits, vision support, reasoning support, bac
 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
@@ -67,8 +67,8 @@ For non-interactive use with an approved Bob API key, run:
 ```bash
 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.
@@ -109,7 +109,7 @@ 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
 
@@ -141,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
 
@@ -197,24 +198,43 @@ 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

package/extensions/bob.ts

@@ -239,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;
@@ -282,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;
@@ -497,18 +501,23 @@ async function fetchBobModelCatalog(
 	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.1.0",
+		"User-Agent": env("IBM_BOB_USER_AGENT") ?? "pi-bob/0.2.0",
 	};
-	const instanceId = env("IBM_BOB_INSTANCE_ID") ?? settings?.ibm?.instanceId;
+	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`, {
@@ -521,11 +530,16 @@ async function fetchBobModelCatalog(
 				`IBM Bob model discovery failed: ${response.status} ${truncateHttpBody(await readBoundedResponseBody(response))}`.trim(),
 			);
 		}
-		return parseBobModelCatalog(await readJsonResponse(response));
+		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);
@@ -572,6 +586,21 @@ function jwtExpiry(accessToken: string): number | undefined {
 	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,
@@ -666,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");
@@ -679,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."));
@@ -686,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}`));
@@ -693,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."));
@@ -712,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) => {
@@ -733,13 +769,15 @@ async function startCallbackServer(state: string): Promise<CallbackServer> {
 }
 
 async function postToken(path: "/authn/v1/auth/token" | "/authn/v1/auth/refresh", body: unknown): Promise<BobTokenResponse> {
+	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.1.0" },
+			headers: { "Content-Type": "application/json", "User-Agent": env("IBM_BOB_USER_AGENT") ?? "pi-bob/0.2.0" },
 			body: JSON.stringify(body),
 			signal: controller.signal,
 		});
@@ -750,6 +788,7 @@ async function postToken(path: "/authn/v1/auth/token" | "/authn/v1/auth/refresh"
 			);
 		}
 
+		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.`);
@@ -760,26 +799,73 @@ async function postToken(path: "/authn/v1/auth/token" | "/authn/v1/auth/refresh"
 }
 
 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() });
+		bobLog(`login: browser opened for SSO (+${elapsed()})`);
 
 		const timeoutMs = envInt("IBM_BOB_LOGIN_TIMEOUT_MS", 180_000);
 		const timeout = new Promise<never>((_resolve, reject) => {
-			loginTimeout = 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]);
+		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 }));
-		return attachBobModelCatalog(credentials);
+		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();
 	}
 }
@@ -790,6 +876,15 @@ async function refreshBobToken(credentials: OAuthCredentials): Promise<OAuthCred
 		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);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-bob",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "type": "module",
   "description": "Pi provider extension for IBM Bob / IBM-approved compatible model endpoints.",
   "keywords": [
@@ -24,7 +24,7 @@
   "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"