@2tle/pi-provider-manager 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,148 @@
+# Pi Provider Manager
+
+An extension for registering and managing OpenAI-compatible API providers in Pi Agent.
+
+When working with local LLM servers, private gateways, proxies, or hosted APIs, managing each provider through `models.json` and restarting Pi can be cumbersome. This extension keeps managed providers and their model catalogs in one place.
+
+## Features
+
+- Add OpenAI-compatible providers from the Pi TUI
+- List managed providers without exposing API keys
+- Edit a provider's display name, Base URL, or API key
+- Refresh one provider's model catalog or every managed catalog
+- Delete a managed provider and its stored API key
+- Keep provider metadata and credentials in separate files
+
+## Commands
+
+### Add a provider
+
+```text
+/provider add
+```
+
+The interactive flow requests:
+
+1. Provider ID — lowercase letters, numbers, `.`, `_`, and `-` only
+2. Provider display name
+3. OpenAI-compatible Base URL — for example, `http://localhost:1234/v1`
+4. API key — local servers can use a placeholder such as `local`
+
+After the provider is added, its `/models` endpoint is queried immediately.
+
+### List managed providers
+
+```text
+/provider list
+```
+
+Displays each provider's ID, display name, Base URL, API key status, and the number of currently loaded models. API key values are never displayed.
+
+### Edit a provider
+
+```text
+/provider edit <provider_name>
+```
+
+Use a provider ID (recommended) or a unique display name. Select the fields to change, then choose **Save changes**. The extension refreshes the provider's model catalog after saving.
+
+In TUI mode, API key input is masked with `*` characters. In RPC mode, the connected client is responsible for secret masking.
+
+### Refresh model catalogs
+
+```text
+/provider reload <provider_name>
+/provider reload --all
+```
+
+The extension sends a request to `<baseUrl>/models` and accepts the OpenAI-style response shape:
+
+```json
+{
+  "data": [{ "id": "model-name" }]
+}
+```
+
+This is different from Pi's `/reload`, which reloads extension code and resources.
+
+### Delete a provider
+
+```text
+/provider delete <provider_name>
+```
+
+After confirmation, the extension removes the managed provider and its stored API key. Built-in providers and providers owned by other extensions cannot be deleted.
+
+## Supported APIs
+
+The extension targets OpenAI Chat Completions-compatible services that provide a model-listing endpoint and support Pi's OpenAI-compatible transport, including:
+
+- OpenAI-compatible gateways and proxies
+- vLLM
+- LM Studio
+- llama.cpp server
+- Ollama's OpenAI-compatible endpoint
+- Private or internal LLM gateways
+
+Provider implementations differ in support for developer roles, reasoning options, token fields, and streaming usage. This extension currently uses Pi's standard `openai-completions` transport.
+
+## Stored configuration
+
+Provider metadata and API keys are stored separately:
+
+```text
+~/.pi/agent/pi-provider-manager.json
+~/.pi/agent/pi-provider-manager-secrets.json
+```
+
+The first file contains provider IDs, display names, and Base URLs. The second contains API keys. The extension creates its directory with `0700` permissions and the secrets file with `0600` permissions. API keys are not included in model-list output or notifications.
+
+## Operational behavior
+
+- Provider IDs are stable identifiers. `/provider edit` changes the display name, Base URL, and API key, but does not rename the provider ID.
+- Cancelling the edit menu discards all unsaved changes.
+- Saving an edit persists the new settings first, then refreshes that provider's model catalog. A failed catalog refresh does not discard an otherwise valid saved edit.
+- `/provider list` reports the model count currently loaded in Pi. It can be `0` before a successful refresh.
+- The extension starts by refreshing every managed provider with a 30-second timeout per refresh operation.
+
+## Development
+
+Install dependencies from the repository root:
+
+```bash
+npm install
+```
+
+Run only this local extension during development:
+
+```bash
+pi -ne -e .
+```
+
+For a single-file load:
+
+```bash
+pi -ne -e ./index.ts
+```
+
+After changing code, run `/reload` in Pi or restart Pi. To refresh model catalogs without reloading the extension, use:
+
+```text
+/provider reload --all
+```
+
+To register the package in Pi's user settings instead of passing `-e` every time:
+
+```bash
+pi install "$PWD"
+```
+
+## Security
+
+Pi extensions can run with full system permissions. Review source code and packages before installing them.
+
+Protect API keys, refresh tokens, custom authorization headers, and sensitive endpoint query parameters. The extension avoids printing raw API keys and sends only the credential required for model-list requests.
+
+## License
+
+Licensed under the [Apache License 2.0](LICENSE).

package/index.ts

@@ -0,0 +1,673 @@
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { chmod, mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import type { RefreshModelsContext } from "@earendil-works/pi-ai";
+import { DynamicBorder, keyHint, type ExtensionAPI, type ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { Container, CURSOR_MARKER, getKeybindings, Input, Spacer, Text, truncateToWidth } from "@earendil-works/pi-tui";
+
+const CONFIG_PATH = join(homedir(), ".pi", "agent", "pi-provider-manager.json");
+const SECRETS_PATH = join(homedir(), ".pi", "agent", "pi-provider-manager-secrets.json");
+const API = "openai-completions" as const;
+const DEFAULT_CONTEXT_WINDOW = 128_000;
+const DEFAULT_MAX_TOKENS = 16_384;
+const REFRESH_TIMEOUT_MS = 30_000;
+
+interface StoredProvider {
+	id: string;
+	name: string;
+	baseUrl: string;
+}
+
+interface StoredState {
+	providers: StoredProvider[];
+}
+
+interface StoredSecrets {
+	apiKeys: Record<string, string>;
+}
+
+interface ProviderModelConfig {
+	id: string;
+	name: string;
+	api: typeof API;
+	reasoning: boolean;
+	input: ("text" | "image")[];
+	cost: {
+		input: number;
+		output: number;
+		cacheRead: number;
+		cacheWrite: number;
+	};
+	contextWindow: number;
+	maxTokens: number;
+}
+
+interface ManagedProviderConfig {
+	name: string;
+	baseUrl: string;
+	api: typeof API;
+	apiKey: string;
+	models: ProviderModelConfig[];
+	refreshModels(context: RefreshModelsContext): Promise<ProviderModelConfig[]>;
+}
+
+interface OpenAIModelPayload {
+	id?: unknown;
+	name?: unknown;
+	context_window?: unknown;
+	contextWindow?: unknown;
+	max_tokens?: unknown;
+	maxTokens?: unknown;
+	reasoning?: unknown;
+	supports_reasoning?: unknown;
+	input?: unknown;
+	cost?: unknown;
+}
+
+interface OpenAIModelsPayload {
+	data?: unknown;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+	return typeof value === "object" && value !== null ? (value as Record<string, unknown>) : undefined;
+}
+
+function asNonEmptyString(value: unknown): string | undefined {
+	return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function asPositiveNumber(value: unknown, fallback: number): number {
+	return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : fallback;
+}
+
+function normalizeBaseUrl(value: string): string {
+	return value.trim().replace(/\/+$/, "");
+}
+
+function validateProviderId(id: string): void {
+	if (!/^[a-z0-9][a-z0-9._-]*$/.test(id)) {
+		throw new Error("Provider ID may contain only lowercase letters, numbers, '.', '_' or '-'.");
+	}
+}
+
+function validateBaseUrl(value: string): string {
+	const baseUrl = normalizeBaseUrl(value);
+	let parsed: URL;
+	try {
+		parsed = new URL(baseUrl);
+	} catch {
+		throw new Error("Base URL is not a valid URL.");
+	}
+	if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+		throw new Error("Base URL must use the http or https protocol.");
+	}
+	return baseUrl;
+}
+
+function modelsUrl(baseUrl: string): string {
+	return new URL("models", `${normalizeBaseUrl(baseUrl)}/`).toString();
+}
+
+async function loadState(): Promise<StoredState> {
+	try {
+		const raw = await readFile(CONFIG_PATH, "utf8");
+		const parsed = asRecord(JSON.parse(raw));
+		const providers = Array.isArray(parsed?.providers) ? parsed.providers : [];
+		const normalized: StoredProvider[] = [];
+		for (const item of providers) {
+			const record = asRecord(item);
+			const id = asNonEmptyString(record?.id);
+			const name = asNonEmptyString(record?.name);
+			const baseUrl = asNonEmptyString(record?.baseUrl);
+			if (!id || !name || !baseUrl) continue;
+			try {
+				validateProviderId(id);
+				normalized.push({ id, name, baseUrl: validateBaseUrl(baseUrl) });
+			} catch {
+				// Ignore malformed entries so one broken provider does not prevent startup.
+			}
+		}
+		return { providers: normalized };
+	} catch (error) {
+		if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+			return { providers: [] };
+		}
+		throw new Error(`Unable to read provider configuration: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+
+async function loadSecrets(): Promise<StoredSecrets> {
+	try {
+		const raw = await readFile(SECRETS_PATH, "utf8");
+		const parsed = asRecord(JSON.parse(raw));
+		const apiKeys: Record<string, string> = {};
+		const rawApiKeys = asRecord(parsed?.apiKeys);
+		for (const [id, value] of Object.entries(rawApiKeys ?? {})) {
+			if (typeof value === "string" && value.trim()) apiKeys[id] = value;
+		}
+		return { apiKeys };
+	} catch (error) {
+		if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+			return { apiKeys: {} };
+		}
+		throw new Error(`Unable to read provider API keys: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+
+async function saveJsonFile(path: string, value: object): Promise<void> {
+	await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+	const temporaryPath = `${path}.${process.pid}.${Date.now()}.tmp`;
+	const content = `${JSON.stringify(value, null, 2)}\n`;
+	try {
+		await writeFile(temporaryPath, content, { encoding: "utf8", mode: 0o600 });
+		await chmod(temporaryPath, 0o600);
+		await rename(temporaryPath, path);
+	} finally {
+		await unlink(temporaryPath).catch(() => undefined);
+	}
+}
+
+async function saveState(state: StoredState): Promise<void> {
+	await saveJsonFile(CONFIG_PATH, state);
+}
+
+async function saveSecrets(secrets: StoredSecrets): Promise<void> {
+	await saveJsonFile(SECRETS_PATH, secrets);
+}
+
+function modelFromPayload(
+	provider: StoredProvider,
+	payload: OpenAIModelPayload,
+): ProviderModelConfig | undefined {
+	const id = asNonEmptyString(payload.id);
+	if (!id) return undefined;
+
+	const cost = asRecord(payload.cost);
+	const input: ("text" | "image")[] =
+		Array.isArray(payload.input) && payload.input.includes("image") ? ["text", "image"] : ["text"];
+
+	return {
+		id,
+		name: asNonEmptyString(payload.name) ?? id,
+		api: API,
+		reasoning: payload.reasoning === true || payload.supports_reasoning === true,
+		input,
+		cost: {
+			input: asPositiveNumber(cost?.input, 0),
+			output: asPositiveNumber(cost?.output, 0),
+			cacheRead: asPositiveNumber(cost?.cacheRead, 0),
+			cacheWrite: asPositiveNumber(cost?.cacheWrite, 0),
+		},
+		contextWindow: asPositiveNumber(payload.context_window ?? payload.contextWindow, DEFAULT_CONTEXT_WINDOW),
+		maxTokens: asPositiveNumber(payload.max_tokens ?? payload.maxTokens, DEFAULT_MAX_TOKENS),
+	};
+}
+
+async function fetchProviderModels(
+	provider: StoredProvider,
+	context: RefreshModelsContext,
+	getApiKey: () => string | undefined,
+): Promise<ProviderModelConfig[]> {
+	const apiKey = getApiKey();
+	if (!apiKey) {
+		throw new Error(`API key for provider '${provider.id}' is not configured.`);
+	}
+
+	const response = await fetch(modelsUrl(provider.baseUrl), {
+		signal: context.signal,
+		headers: {
+			Accept: "application/json",
+			Authorization: `Bearer ${apiKey}`,
+		},
+	});
+
+	if (!response.ok) {
+		throw new Error(`Failed to fetch model list (${response.status} ${response.statusText})`);
+	}
+
+	const payload = (await response.json()) as OpenAIModelsPayload | unknown[];
+	const data = Array.isArray(payload) ? payload : asRecord(payload)?.data;
+	if (!Array.isArray(data)) {
+		throw new Error("Model list response does not contain a data array.");
+	}
+
+	return data
+		.map((item) => {
+			const record = asRecord(item);
+			return record ? modelFromPayload(provider, record as OpenAIModelPayload) : undefined;
+		})
+		.filter((model): model is ProviderModelConfig => model !== undefined);
+}
+
+function createManagedProvider(
+	config: StoredProvider,
+	getApiKey: () => string | undefined,
+): ManagedProviderConfig {
+	return {
+		name: config.name,
+		baseUrl: config.baseUrl,
+		api: API,
+		// The API key is held outside the regular provider config and is only
+		// read when the provider is registered or refreshed.
+		apiKey: getApiKey() ?? "local",
+		models: [],
+		refreshModels: (context) => fetchProviderModels(config, context, getApiKey),
+	};
+}
+
+export function maskInputLine(line: string): string {
+	const prompt = line.startsWith("> ") ? "> " : "";
+	let result = "";
+	for (let index = prompt.length; index < line.length; ) {
+		// Keep Input's zero-width APC cursor marker intact. Masking only CSI/SGR
+		// codes previously turned the marker bytes into visible bullets.
+		if (line.startsWith(CURSOR_MARKER, index)) {
+			result += CURSOR_MARKER;
+			index += CURSOR_MARKER.length;
+			continue;
+		}
+
+		if (line[index] === "\x1b") {
+			const ansi = line.slice(index).match(/^\x1b\[[0-9;?]*[ -/]*[@-~]/)?.[0];
+			if (ansi) {
+				result += ansi;
+				index += ansi.length;
+				continue;
+			}
+		}
+
+		const character = line[index++];
+		result += /\s/u.test(character) ? character : "*";
+	}
+	return prompt + result;
+}
+
+class MaskedInput extends Input {
+	override render(width: number): string[] {
+		const terminalWidth = process.stdout.columns;
+		const safeWidth = Math.max(1, Number.isFinite(terminalWidth) ? Math.min(width, terminalWidth) : width);
+		return super.render(safeWidth).map((line) => truncateToWidth(maskInputLine(line), safeWidth, "", false));
+	}
+}
+
+class SecretInputDialog extends Container {
+	private readonly input = new MaskedInput();
+	private _focused = false;
+
+	constructor(
+		done: (value: string | undefined) => void,
+		title: string,
+		helpText: string,
+		border: (text: string) => string,
+	) {
+		super();
+		// Match Pi's built-in ctx.ui.input() layout while keeping the secret masked.
+		this.addChild(new DynamicBorder(border));
+		this.addChild(new Spacer(1));
+		this.addChild(new Text(title, 1, 0));
+		this.addChild(new Spacer(1));
+		this.addChild(this.input);
+		this.addChild(new Spacer(1));
+		this.addChild(new Text(helpText, 1, 0));
+		this.addChild(new Spacer(1));
+		this.addChild(new DynamicBorder(border));
+		this.done = done;
+	}
+
+	private readonly done: (value: string | undefined) => void;
+
+	get focused(): boolean {
+		return this._focused;
+	}
+
+	set focused(value: boolean) {
+		this._focused = value;
+		this.input.focused = value;
+	}
+
+	handleInput(data: string): void {
+		const keybindings = getKeybindings();
+		if (keybindings.matches(data, "tui.select.confirm") || data === "\n") {
+			this.done(this.input.getValue());
+		} else if (keybindings.matches(data, "tui.select.cancel")) {
+			this.done(undefined);
+		} else {
+			this.input.handleInput(data);
+		}
+	}
+}
+
+function parseArgs(args: string): string[] {
+	return args.trim().split(/\s+/).filter(Boolean);
+}
+
+function usage(): string {
+	return [
+		"Usage:",
+		"  /provider add",
+		"  /provider list",
+		"  /provider edit <provider_name>",
+		"  /provider reload --all",
+		"  /provider reload <provider_name>",
+		"  /provider delete <provider_name>",
+	].join("\n");
+}
+
+function commandNotify(ctx: ExtensionCommandContext, message: string, type: "info" | "warning" | "error" = "info"): void {
+	if (ctx.hasUI) ctx.ui.notify(message, type);
+}
+
+async function refreshProviders(
+	ctx: ExtensionCommandContext,
+	providerIds: readonly string[],
+): Promise<void> {
+	if (providerIds.length === 0) {
+		commandNotify(ctx, "No providers to refresh.", "warning");
+		return;
+	}
+
+	const signal = AbortSignal.timeout(REFRESH_TIMEOUT_MS);
+	const result = await ctx.modelRegistry.refresh({
+		providers: providerIds,
+		allowNetwork: true,
+		force: true,
+		signal,
+	});
+
+	if (result.aborted) {
+		throw new Error("Model list refresh was cancelled or timed out.");
+	}
+
+	const messages: string[] = [];
+	for (const providerId of providerIds) {
+		const error = result.errors.get(providerId);
+		if (error) {
+			messages.push(`${providerId}: failed — ${error.message}`);
+			continue;
+		}
+		const provider = ctx.modelRegistry.getProvider(providerId);
+		const count = provider?.getModels().length ?? 0;
+		messages.push(`${providerId}: ${count} model${count === 1 ? "" : "s"}`);
+	}
+
+	const failed = result.errors.size > 0;
+	commandNotify(ctx, `Model list refresh complete\n${messages.join("\n")}`, failed ? "warning" : "info");
+}
+
+async function promptForProvider(ctx: ExtensionCommandContext): Promise<StoredProvider | undefined> {
+	if (!ctx.hasUI) throw new Error("/provider add requires an interactive UI.");
+
+	const id = (await ctx.ui.input("Provider ID", "e.g. lmstudio"))?.trim();
+	if (!id) return undefined;
+	validateProviderId(id);
+
+	const name = (await ctx.ui.input("Provider display name", id))?.trim() || id;
+	const baseUrlInput = await ctx.ui.input("OpenAI-compatible Base URL", "e.g. http://localhost:1234/v1");
+	if (!baseUrlInput?.trim()) return undefined;
+
+	return { id, name, baseUrl: validateBaseUrl(baseUrlInput) };
+}
+
+async function promptForApiKey(ctx: ExtensionCommandContext): Promise<string | undefined> {
+	if (!ctx.hasUI) throw new Error("API key entry requires an interactive UI.");
+
+	const apiKey =
+		ctx.mode === "tui"
+			? await ctx.ui.custom<string | undefined>((_tui, theme, _keybindings, done) =>
+				new SecretInputDialog(
+					done,
+					theme.fg("accent", "API key"),
+					`${keyHint("tui.select.confirm", "submit")}  ${keyHint("tui.select.cancel", "cancel")}`,
+					(text: string) => theme.fg("accent", text),
+				),
+			)
+			: await ctx.ui.input("API key", "sk-... or local");
+
+	if (apiKey === undefined) return undefined;
+	if (!apiKey.trim()) throw new Error("API key cannot be empty.");
+	return apiKey;
+}
+
+interface ProviderEdit {
+	provider: StoredProvider;
+	apiKey?: string;
+}
+
+async function promptForProviderEdit(
+	ctx: ExtensionCommandContext,
+	provider: StoredProvider,
+): Promise<ProviderEdit | undefined> {
+	if (!ctx.hasUI) throw new Error("/provider edit requires an interactive UI.");
+
+	let updatedProvider = { ...provider };
+	let updatedApiKey: string | undefined;
+
+	while (true) {
+		const choice = await ctx.ui.select(`Edit provider: ${provider.id}`, [
+			`Change display name (${updatedProvider.name})`,
+			`Change Base URL (${updatedProvider.baseUrl})`,
+			"Change API key",
+			"Save changes",
+		]);
+		if (choice === undefined) return undefined;
+		if (choice === "Save changes") return { provider: updatedProvider, apiKey: updatedApiKey };
+
+		if (choice.startsWith("Change display name")) {
+			const name = await ctx.ui.input("Provider display name", `Current value: ${updatedProvider.name}`);
+			if (name?.trim()) updatedProvider = { ...updatedProvider, name: name.trim() };
+			continue;
+		}
+
+		if (choice.startsWith("Change Base URL")) {
+			const baseUrlInput = await ctx.ui.input("OpenAI-compatible Base URL", `Current value: ${updatedProvider.baseUrl}`);
+			if (!baseUrlInput?.trim()) continue;
+			try {
+				updatedProvider = { ...updatedProvider, baseUrl: validateBaseUrl(baseUrlInput) };
+			} catch (error) {
+				commandNotify(ctx, error instanceof Error ? error.message : String(error), "error");
+			}
+			continue;
+		}
+
+		const apiKey = await promptForApiKey(ctx);
+		if (apiKey !== undefined) updatedApiKey = apiKey;
+	}
+}
+
+function findManagedProvider(managed: ReadonlyMap<string, StoredProvider>, name: string): StoredProvider | undefined {
+	const providerById = managed.get(name);
+	if (providerById) return providerById;
+
+	const matches = [...managed.values()].filter((provider) => provider.name === name);
+	if (matches.length > 1) {
+		throw new Error(`Multiple providers have the display name '${name}'. Use a provider ID instead.`);
+	}
+	return matches[0];
+}
+
+function providerListMessage(
+	providers: readonly StoredProvider[],
+	secrets: StoredSecrets,
+	ctx: ExtensionCommandContext,
+): string {
+	if (providers.length === 0) return "No managed providers.";
+
+	return ["Managed providers:", ...providers.map((provider) => {
+		const modelCount = ctx.modelRegistry.getProvider(provider.id)?.getModels().length ?? 0;
+		const apiKeyStatus = secrets.apiKeys[provider.id] ? "configured" : "missing";
+		return `- ${provider.id} (${provider.name})\n  Base URL: ${provider.baseUrl}\n  API key: ${apiKeyStatus} · Models: ${modelCount}`;
+	})].join("\n");
+}
+
+export default async function (pi: ExtensionAPI) {
+	const state = await loadState();
+	const secrets = await loadSecrets();
+	const managed = new Map<string, StoredProvider>();
+
+	for (const provider of state.providers) {
+		if (managed.has(provider.id)) continue;
+		managed.set(provider.id, provider);
+		pi.registerProvider(provider.id, createManagedProvider(provider, () => secrets.apiKeys[provider.id]));
+	}
+
+	pi.registerCommand("provider", {
+		description: "Add, list, edit, refresh, and delete OpenAI-compatible providers",
+		handler: async (args, ctx) => {
+			try {
+				const [subcommand, ...rest] = parseArgs(args);
+
+				if (!subcommand) {
+					commandNotify(ctx, usage(), "warning");
+					return;
+				}
+
+				if (subcommand === "list") {
+					if (rest.length > 0) throw new Error("/provider list does not accept arguments.");
+					commandNotify(ctx, providerListMessage([...managed.values()], secrets, ctx));
+					return;
+				}
+
+				if (subcommand === "add") {
+					if (rest.length > 0) throw new Error("/provider add does not accept arguments.");
+					const provider = await promptForProvider(ctx);
+					if (!provider) return;
+					if (managed.has(provider.id) || ctx.modelRegistry.getProvider(provider.id)) {
+						throw new Error(`Provider '${provider.id}' is already registered.`);
+					}
+					const apiKey = await promptForApiKey(ctx);
+					if (!apiKey) return;
+
+					const nextState: StoredState = { providers: [...state.providers, provider] };
+					const previousApiKey = secrets.apiKeys[provider.id];
+					secrets.apiKeys[provider.id] = apiKey;
+					try {
+						await saveState(nextState);
+						await saveSecrets(secrets);
+						pi.registerProvider(provider.id, createManagedProvider(provider, () => secrets.apiKeys[provider.id]));
+						state.providers = nextState.providers;
+						managed.set(provider.id, provider);
+					} catch (error) {
+						if (previousApiKey === undefined) delete secrets.apiKeys[provider.id];
+						else secrets.apiKeys[provider.id] = previousApiKey;
+						await saveState({ providers: state.providers }).catch(() => undefined);
+						await saveSecrets(secrets).catch(() => undefined);
+						pi.unregisterProvider(provider.id);
+						throw error;
+					}
+
+					commandNotify(ctx, `Provider '${provider.id}' was added. Fetching its model list.`);
+					await refreshProviders(ctx, [provider.id]);
+					return;
+				}
+
+				if (subcommand === "edit") {
+					if (rest.length !== 1) throw new Error("Usage: /provider edit <provider_name>");
+					const currentProvider = findManagedProvider(managed, rest[0]);
+					if (!currentProvider) throw new Error(`Managed provider '${rest[0]}' was not found.`);
+
+					const edit = await promptForProviderEdit(ctx, currentProvider);
+					if (!edit) return;
+					const providerChanged =
+						edit.provider.name !== currentProvider.name || edit.provider.baseUrl !== currentProvider.baseUrl;
+					if (!providerChanged && edit.apiKey === undefined) {
+						commandNotify(ctx, "No provider settings were changed.", "warning");
+						return;
+					}
+
+					const previousState: StoredState = { providers: [...state.providers] };
+					const previousApiKey = secrets.apiKeys[currentProvider.id];
+					const nextState: StoredState = {
+						providers: state.providers.map((provider) =>
+							provider.id === currentProvider.id ? edit.provider : provider,
+						),
+					};
+					if (edit.apiKey !== undefined) secrets.apiKeys[currentProvider.id] = edit.apiKey;
+
+					try {
+						await saveState(nextState);
+						if (edit.apiKey !== undefined) await saveSecrets(secrets);
+						pi.registerProvider(
+							currentProvider.id,
+							createManagedProvider(edit.provider, () => secrets.apiKeys[currentProvider.id]),
+						);
+						state.providers = nextState.providers;
+						managed.set(currentProvider.id, edit.provider);
+					} catch (error) {
+						if (previousApiKey === undefined) delete secrets.apiKeys[currentProvider.id];
+						else secrets.apiKeys[currentProvider.id] = previousApiKey;
+						await saveState(previousState).catch(() => undefined);
+						if (edit.apiKey !== undefined) await saveSecrets(secrets).catch(() => undefined);
+						pi.registerProvider(
+							currentProvider.id,
+							createManagedProvider(currentProvider, () => secrets.apiKeys[currentProvider.id]),
+						);
+						throw error;
+					}
+
+					commandNotify(ctx, `Saved settings for provider '${currentProvider.id}'. Fetching its model list.`);
+					await refreshProviders(ctx, [currentProvider.id]);
+					return;
+				}
+
+				if (subcommand === "reload") {
+					if (rest.length !== 1) throw new Error("Usage: /provider reload --all | <provider_name>");
+					const providerIds = rest[0] === "--all" ? [...managed.keys()] : [rest[0]];
+					for (const providerId of providerIds) {
+						if (!managed.has(providerId)) throw new Error(`Managed provider '${providerId}' was not found.`);
+					}
+					await refreshProviders(ctx, providerIds);
+					return;
+				}
+
+				if (subcommand === "delete") {
+					if (rest.length !== 1) throw new Error("Usage: /provider delete <provider_name>");
+					const providerId = rest[0];
+					if (!managed.has(providerId)) throw new Error(`Managed provider '${providerId}' was not found.`);
+					if (!ctx.hasUI) throw new Error("/provider delete requires an interactive UI.");
+					const shouldDelete = await ctx.ui.confirm(
+						"Delete provider",
+						`Delete provider '${providerId}' and its stored API key?`,
+					);
+					if (!shouldDelete) return;
+
+					const previousState: StoredState = { providers: [...state.providers] };
+					const previousApiKey = secrets.apiKeys[providerId];
+					const nextState: StoredState = {
+						providers: state.providers.filter((provider) => provider.id !== providerId),
+					};
+					delete secrets.apiKeys[providerId];
+					try {
+						await saveState(nextState);
+						await saveSecrets(secrets);
+						pi.unregisterProvider(providerId);
+						managed.delete(providerId);
+						state.providers = nextState.providers;
+					} catch (error) {
+						if (previousApiKey !== undefined) secrets.apiKeys[providerId] = previousApiKey;
+						await saveState(previousState).catch(() => undefined);
+						await saveSecrets(secrets).catch(() => undefined);
+						throw error;
+					}
+					commandNotify(ctx, `Provider '${providerId}' was deleted.`);
+					return;
+				}
+
+				throw new Error(`Unknown provider command: ${subcommand}\n\n${usage()}`);
+			} catch (error) {
+				commandNotify(ctx, error instanceof Error ? error.message : String(error), "error");
+			}
+		},
+	});
+
+	pi.on("session_start", async (_event, ctx) => {
+		if (managed.size === 0) return;
+		const result = await ctx.modelRegistry.refresh({
+			providers: [...managed.keys()],
+			allowNetwork: true,
+			signal: AbortSignal.timeout(REFRESH_TIMEOUT_MS),
+		});
+		if (result.errors.size > 0 && ctx.hasUI) {
+			ctx.ui.notify(`Could not refresh model lists for: ${[...result.errors.keys()].join(", ")}`, "warning");
+		}
+	});
+}

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@2tle/pi-provider-manager",
+  "version": "0.1.0",
+  "description": "Manage OpenAI-compatible providers and model catalogs in Pi Agent",
+  "license": "Apache-2.0",
+  "type": "module",
+  "keywords": ["pi-package"],
+  "pi": {
+    "extensions": ["./index.ts"]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  }
+}