pi-bob 0.1.0

package/PLAN.md

@@ -0,0 +1,96 @@
+# 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.

package/README.md

@@ -0,0 +1,212 @@
+# pi-bob
+
+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.
+
+## 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`
+- 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`
+- Chat completions route used by Bob Shell: `/inference/v1/chat/completions`
+- Model-info route used by Bob Shell: `/inference/v1/model/info`
+- Default model alias used by Bob Shell: `premium`
+- Other visible aliases/constants in the installed client: `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`.
+- Default context window advertised to Pi: `200000`, so Pi compacts before Bob rejects oversized requests.
+- Default max output token constant in the installed client: `8192`
+
+Bob Shell sends non-secret instance/team routing headers. This extension reads only these non-secret fields from `~/.bob/settings.json` by default:
+
+- `ibm.instanceId` -> `x-instance-id`
+- `ibm.teamId` -> `x-team-id`
+
+It intentionally ignores Bob's stored SSO secrets.
+
+## What it supports
+
+Set `IBM_BOB_API` to one of Pi's compatible API adapters:
+
+- `openai-completions` — default; OpenAI Chat Completions-compatible routes.
+- `openai-responses` — OpenAI Responses-compatible routes.
+- `anthropic-messages` — Anthropic Messages-compatible routes.
+
+The extension registers provider id `ibm-bob`.
+
+## Quick start for the discovered Bob endpoint
+
+Use Bob SSO through Pi:
+
+```bash
+pi -e /Users/larry.song/work/hashicorp/pi-bob
+# inside Pi:
+#   /login ibm-bob
+#   /model ibm-bob/premium
+```
+
+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:
+
+```bash
+export IBM_BOB_API_KEY="..." # do not commit this
+
+pi -e /Users/larry.song/work/hashicorp/pi-bob --list-models
+pi -e /Users/larry.song/work/hashicorp/pi-bob --model ibm-bob/premium
+```
+
+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"
+```
+
+For IBM Bob API keys that require `Authorization: Apikey ...` rather than `Authorization: Bearer ...`:
+
+```bash
+export IBM_BOB_AUTH_SCHEME="Apikey"
+```
+
+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.
+
+## Configuration
+
+### Core
+
+| 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_API_KEY` | unset | Approved API key/token. Keep it out of repo files. |
+| `IBM_BOB_API` | `openai-completions` | One of `openai-completions`, `openai-responses`, `anthropic-messages`. |
+
+### Bob routing headers
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `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. |
+
+### 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_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. |
+
+Pricing is set to zero until IBM-specific metering details are known.
+
+### OpenAI compatibility toggles
+
+```bash
+export IBM_BOB_SUPPORTS_DEVELOPER_ROLE=false
+export IBM_BOB_SUPPORTS_REASONING_EFFORT=false
+export IBM_BOB_SUPPORTS_USAGE_IN_STREAMING=true
+export IBM_BOB_SUPPORTS_STRICT_MODE=false
+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.
+
+## Validation performed
+
+Bob Shell SSO itself works locally:
+
+```bash
+bob --auth-method sso -m premium -p 'Reply with exactly: bob-ok' --hide-intermediary-output --output-format json
+```
+
+The response included `bob-ok` and successful usage stats for model `premium`.
+
+The unauthenticated Bob model-info endpoint responds as expected when called with a normal User-Agent:
+
+```bash
+curl -H 'User-Agent: pi-bob/0.1.0' \
+  https://api.us-east.bob.ibm.com/inference/v1/model/info
+```
+
+Result: HTTP `401` with `Authentication required`, confirming the discovered route exists and requires auth.
+
+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:
+
+```bash
+IBM_BOB_API_KEY=dummy pi -e . --list-models | grep ibm-bob
+```
+
+Result:
+
+```text
+ibm-bob         premium                 200K     8.2K     no        no
+```
+
+A dummy-token Pi request reaches the Bob endpoint and fails with the expected auth error:
+
+```bash
+IBM_BOB_API_KEY=dummy IBM_BOB_AUTH_SCHEME=Apikey \
+  pi -e . --model ibm-bob/premium -p 'Say hi'
+```
+
+Result: HTTP `401 unauthorized`.
+
+End-to-end smoke with a fresh Bob SSO token succeeded:
+
+```text
+pi -e . --model ibm-bob/premium -p 'Reply with exactly: pi-bob-ok'
+```
+
+Result:
+
+```text
+pi-bob-ok
+```
+
+## Install options
+
+Temporary test load:
+
+```bash
+pi -e /Users/larry.song/work/hashicorp/pi-bob
+```
+
+Install as a local Pi package:
+
+```bash
+pi install /Users/larry.song/work/hashicorp/pi-bob
+```
+
+Remove later:
+
+```bash
+pi remove /Users/larry.song/work/hashicorp/pi-bob
+```
+
+## Next steps
+
+Option 1 is wired to the discovered Bob OpenAI-compatible route and `/login ibm-bob` is 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.

package/extensions/bob.ts

@@ -0,0 +1,455 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { OAuthCredentials, OAuthLoginCallbacks } from "@earendil-works/pi-ai";
+import { randomBytes } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { createServer, type Server } from "node:http";
+import { createServer as createNetServer } from "node:net";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+type CompatibleApi = "openai-completions" | "openai-responses" | "anthropic-messages";
+type InputType = "text" | "image";
+type MaxTokensField = "max_tokens" | "max_completion_tokens";
+
+interface BobModelConfig {
+	id: string;
+	name: string;
+	reasoning: boolean;
+	input: InputType[];
+	contextWindow: number;
+	maxTokens: number;
+	cost: {
+		input: number;
+		output: number;
+		cacheRead: number;
+		cacheWrite: number;
+	};
+	compat?: Record<string, unknown>;
+}
+
+interface BobShellSettings {
+	ibm?: {
+		instanceId?: string;
+		teamId?: string;
+	};
+}
+
+interface BobTokenResponse {
+	token: string;
+	refresh_token?: string;
+	expires_in?: number;
+	expires_at?: number;
+}
+
+interface CallbackServer {
+	port: number;
+	callbackUri: string;
+	code: Promise<string>;
+	close(): void;
+}
+
+const PROVIDER_ID = "ibm-bob";
+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 SUPPORTED_APIS = new Set<CompatibleApi>(["openai-completions", "openai-responses", "anthropic-messages"]);
+
+function env(name: string): string | undefined {
+	const value = process.env[name]?.trim();
+	return value ? value : undefined;
+}
+
+function envInt(name: string, fallback: number): number {
+	const value = env(name);
+	if (!value) return fallback;
+	const parsed = Number.parseInt(value, 10);
+	return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+function envBool(name: string, fallback: boolean): boolean {
+	const value = env(name);
+	if (!value) return fallback;
+	if (["1", "true", "yes", "y", "on"].includes(value.toLowerCase())) return true;
+	if (["0", "false", "no", "n", "off"].includes(value.toLowerCase())) return false;
+	return fallback;
+}
+
+function envCsv(name: string, fallback: string[] = []): string[] {
+	const value = env(name);
+	if (!value) return fallback;
+	return value
+		.split(",")
+		.map((item) => item.trim())
+		.filter(Boolean);
+}
+
+function readBobShellSettings(): BobShellSettings | undefined {
+	if (!envBool("IBM_BOB_READ_BOBSHELL_SETTINGS", true)) return undefined;
+
+	try {
+		const raw = readFileSync(join(homedir(), ".bob", "settings.json"), "utf8");
+		const parsed = JSON.parse(raw) as unknown;
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return undefined;
+
+		const ibm = (parsed as BobShellSettings).ibm;
+		return {
+			ibm: {
+				instanceId: typeof ibm?.instanceId === "string" ? ibm.instanceId : undefined,
+				teamId: typeof ibm?.teamId === "string" ? ibm.teamId : undefined,
+			},
+		};
+	} catch {
+		return undefined;
+	}
+}
+
+function providerBaseUrl(): string {
+	return env("IBM_BOB_BASE_URL") ?? DEFAULT_BASE_URL;
+}
+
+function bobOrigin(): string {
+	const explicit = env("IBM_BOB_AUTH_BASE_URL");
+	if (explicit) return explicit.replace(/\/$/, "");
+	try {
+		return new URL(providerBaseUrl()).origin;
+	} catch {
+		return DEFAULT_BOB_ORIGIN;
+	}
+}
+
+function bobWebLoginUrl(): string {
+	if (env("IBM_BOB_WEB_LOGIN_URL")) return env("IBM_BOB_WEB_LOGIN_URL")!;
+	try {
+		const host = new URL(bobOrigin()).host;
+		if (host === "api.dev.bob.ibm.com") return "https://public-dev.bob.ibm.com/login";
+		if (host === "api.qa-test.bob.ibm.com") return "https://qa.bob.ibm.com/login";
+		return DEFAULT_WEB_LOGIN_URL;
+	} catch {
+		return DEFAULT_WEB_LOGIN_URL;
+	}
+}
+
+function parseApi(): CompatibleApi {
+	const requested = env("IBM_BOB_API") ?? "openai-completions";
+	if (SUPPORTED_APIS.has(requested as CompatibleApi)) return requested as CompatibleApi;
+	console.warn(
+		`pi-bob: unsupported IBM_BOB_API=${JSON.stringify(requested)}; falling back to openai-completions.`,
+	);
+	return "openai-completions";
+}
+
+function parseInputTypes(): InputType[] {
+	const values = envCsv("IBM_BOB_INPUT", ["text"]);
+	const input = values.filter((value): value is InputType => value === "text" || value === "image");
+	return input.length > 0 ? [...new Set(input)] : ["text"];
+}
+
+function parseJsonHeaders(): Record<string, string> | undefined {
+	const json = env("IBM_BOB_HEADERS_JSON");
+	if (!json) return undefined;
+
+	try {
+		const parsed = JSON.parse(json) as unknown;
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+			console.warn("pi-bob: IBM_BOB_HEADERS_JSON must be a JSON object; ignoring it.");
+			return undefined;
+		}
+
+		const headers: Record<string, string> = {};
+		for (const [key, value] of Object.entries(parsed)) {
+			if (typeof value === "string") headers[key] = value;
+			else console.warn(`pi-bob: header ${JSON.stringify(key)} is not a string; ignoring it.`);
+		}
+
+		return Object.keys(headers).length > 0 ? headers : undefined;
+	} catch (error) {
+		console.warn(
+			`pi-bob: failed to parse IBM_BOB_HEADERS_JSON; ignoring it. ${
+				error instanceof Error ? error.message : String(error)
+			}`,
+		);
+		return 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",
+	};
+
+	const instanceId = env("IBM_BOB_INSTANCE_ID") ?? settings?.ibm?.instanceId;
+	const teamId = env("IBM_BOB_TEAM_ID") ?? settings?.ibm?.teamId;
+	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);
+
+	return Object.keys(headers).length > 0 ? headers : undefined;
+}
+
+function modelName(id: string): string {
+	const known: Record<string, string> = {
+		premium: "IBM Bob Premium",
+		pro: "IBM Bob Pro",
+		flash: "IBM Bob Flash",
+		"flash-lite": "IBM Bob Flash Lite",
+		"bob-3-pro-preview": "IBM Bob 3 Pro Preview",
+	};
+	if (known[id]) return known[id];
+
+	return id
+		.split(/[/:._-]+/)
+		.filter(Boolean)
+		.map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+		.join(" ");
+}
+
+function parseReasoningModels(): Set<string> {
+	return new Set(envCsv("IBM_BOB_REASONING_MODELS"));
+}
+
+function buildOpenAiCompat(api: CompatibleApi): Record<string, unknown> | undefined {
+	if (api === "anthropic-messages") return undefined;
+
+	const compat: Record<string, unknown> = {
+		supportsDeveloperRole: envBool("IBM_BOB_SUPPORTS_DEVELOPER_ROLE", false),
+		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),
+	};
+
+	const maxTokensField = env("IBM_BOB_MAX_TOKENS_FIELD") as MaxTokensField | undefined;
+	if (maxTokensField === "max_tokens" || maxTokensField === "max_completion_tokens") {
+		compat.maxTokensField = maxTokensField;
+	} else {
+		compat.maxTokensField = api === "openai-completions" ? "max_tokens" : "max_completion_tokens";
+	}
+
+	return compat;
+}
+
+function buildAnthropicCompat(api: CompatibleApi): Record<string, unknown> | undefined {
+	if (api !== "anthropic-messages") return undefined;
+
+	return {
+		supportsEagerToolInputStreaming: envBool("IBM_BOB_SUPPORTS_EAGER_TOOL_INPUT_STREAMING", false),
+		supportsLongCacheRetention: envBool("IBM_BOB_SUPPORTS_LONG_CACHE_RETENTION", true),
+		supportsCacheControlOnTools: envBool("IBM_BOB_SUPPORTS_CACHE_CONTROL_ON_TOOLS", true),
+		forceAdaptiveThinking: envBool("IBM_BOB_FORCE_ADAPTIVE_THINKING", false),
+		allowEmptySignature: envBool("IBM_BOB_ALLOW_EMPTY_SIGNATURE", false),
+	};
+}
+
+function buildModels(api: CompatibleApi): BobModelConfig[] {
+	const ids = envCsv("IBM_BOB_MODELS", DEFAULT_MODELS);
+	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 compat = buildOpenAiCompat(api) ?? buildAnthropicCompat(api);
+
+	return ids.map((id) => ({
+		id,
+		name: modelName(id),
+		reasoning: allReasoning || reasoningModels.has(id),
+		input,
+		contextWindow,
+		maxTokens,
+		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+		...(compat ? { compat } : {}),
+	}));
+}
+
+function jwtExpiry(accessToken: string): number | undefined {
+	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;
+	} catch {
+		return undefined;
+	}
+}
+
+function credentialsFromTokenResponse(response: BobTokenResponse, previousRefresh?: string): OAuthCredentials {
+	if (!response.token) throw new Error("IBM Bob SSO response did not include an access token.");
+	return {
+		access: response.token,
+		refresh: response.refresh_token ?? previousRefresh ?? "",
+		expires:
+			jwtExpiry(response.token) ??
+			(typeof response.expires_at === "number"
+				? response.expires_at - 5 * 60 * 1000
+				: Date.now() + (response.expires_in ?? 55 * 60) * 1000 - 5 * 60 * 1000),
+	};
+}
+
+async function choosePort(): Promise<number> {
+	const configured = envInt("SSO_PORT", 0) || envInt("IBM_BOB_SSO_PORT", 0);
+	if (configured) return configured;
+
+	return new Promise((resolve, reject) => {
+		const server = createNetServer();
+		server.on("error", reject);
+		server.listen(0, () => {
+			const address = server.address();
+			const port = typeof address === "object" && address ? address.port : undefined;
+			server.close(() => (port ? resolve(port) : reject(new Error("Failed to allocate callback port."))));
+		});
+	});
+}
+
+async function startCallbackServer(state: string): Promise<CallbackServer> {
+	const port = await choosePort();
+	const server = createServer();
+
+	const code = new Promise<string>((resolve, reject) => {
+		server.on("request", (req, res) => {
+			if (!req.url?.startsWith("/bob-callback")) {
+				res.writeHead(404, { "Content-Type": "text/plain" });
+				res.end("Not Found");
+				return;
+			}
+
+			try {
+				const url = new URL(req.url, `http://localhost:${port}`);
+				const returnedState = url.searchParams.get("state");
+				const authCode = url.searchParams.get("code");
+				const error = url.searchParams.get("error");
+
+				if (returnedState !== state) {
+					res.writeHead(400, { "Content-Type": "text/plain" });
+					res.end("Invalid state parameter");
+					reject(new Error("Invalid state parameter from IBM Bob SSO callback."));
+					return;
+				}
+
+				if (error) {
+					res.writeHead(400, { "Content-Type": "text/plain" });
+					res.end("Authentication failed");
+					reject(new Error(`IBM Bob SSO failed: ${error}`));
+					return;
+				}
+
+				if (!authCode) {
+					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."));
+					return;
+				}
+
+				res.writeHead(200, { "Content-Type": "text/html" });
+				res.end(`<!doctype html>
+<html><body style="font-family: system-ui; margin: 3rem;">
+<h1>IBM Bob authentication successful</h1>
+<p>You can close this window and return to Pi.</p>
+<script>setTimeout(() => window.close(), 1000);</script>
+</body></html>`);
+				resolve(authCode);
+				setTimeout(() => server.close(), 500);
+			} catch (error) {
+				reject(error);
+			}
+		});
+		server.on("error", reject);
+	});
+
+	await new Promise<void>((resolve, reject) => {
+		server.once("error", reject);
+		server.listen(port, () => {
+			server.off("error", reject);
+			resolve();
+		});
+	});
+
+	return {
+		port,
+		callbackUri: `http://localhost:${port}/bob-callback`,
+		code,
+		close() {
+			server.close();
+		},
+	};
+}
+
+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),
+	});
+
+	if (!response.ok) {
+		throw new Error(`IBM Bob SSO token request failed: ${response.status} ${await response.text()}`);
+	}
+
+	return (await response.json()) as BobTokenResponse;
+}
+
+async function loginBob(callbacks: OAuthLoginCallbacks): Promise<OAuthCredentials> {
+	const state = randomBytes(16).toString("hex");
+	const callbackServer = await startCallbackServer(state);
+	const loginUrl = new URL(bobWebLoginUrl());
+	loginUrl.searchParams.set("callback_uri", callbackServer.callbackUri);
+	loginUrl.searchParams.set("state", state);
+
+	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),
+		});
+
+		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);
+		});
+
+		const code = await Promise.race([callbackServer.code, timeout]);
+		return credentialsFromTokenResponse(await postToken("/authn/v1/auth/token", { code }));
+	} finally {
+		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(
+		await postToken("/authn/v1/auth/refresh", { refresh_token: credentials.refresh }),
+		credentials.refresh,
+	);
+}
+
+export default function (pi: ExtensionAPI) {
+	const api = parseApi();
+	const settings = readBobShellSettings();
+	const headers = buildHeaders(settings);
+
+	pi.registerProvider(PROVIDER_ID, {
+		name: "IBM Bob",
+		baseUrl: providerBaseUrl(),
+		apiKey: "$IBM_BOB_API_KEY",
+		api,
+		...(headers ? { headers } : {}),
+		models: buildModels(api),
+		oauth: {
+			name: "IBM Bob SSO",
+			login: loginBob,
+			refreshToken: refreshBobToken,
+			getApiKey: (credentials) => credentials.access,
+		},
+	});
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "pi-bob",
+  "version": "0.1.0",
+
+  "type": "module",
+  "description": "Pi provider extension for IBM Bob / IBM-approved compatible model endpoints.",
+  "keywords": [
+    "pi-package",
+    "pi-coding-agent",
+    "ibm",
+    "bob",
+    "llm-provider"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/bob.ts"
+    ]
+  },
+  "author": "Larry Song",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/songlining/pi-bob.git"
+  },
+  "bugs": {
+    "url": "https://github.com/songlining/pi-bob/issues"
+  },
+  "homepage": "https://github.com/songlining/pi-bob#readme",
+  "scripts": {
+    "check": "pi -e . --list-models >/dev/null",
+    "clean": "echo 'nothing to clean'",
+    "build": "echo 'nothing to build'"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  }
+}