@lenylvt/pi-coding-agent 0.64.0

package/docs/custom-provider.md

@@ -0,0 +1,327 @@
+# Custom Providers
+
+Extensions can register custom model providers via `pi.registerProvider()`.
+
+Use this when you want to:
+
+- route requests through a proxy or internal gateway
+- add a private endpoint
+- add an OAuth flow for an internal provider
+- implement streaming for a non-standard API
+
+## Example Extensions
+
+- [`examples/extensions/custom-provider-anthropic/`](../examples/extensions/custom-provider-anthropic/)
+- [`examples/extensions/custom-provider-gitlab-duo/`](../examples/extensions/custom-provider-gitlab-duo/)
+
+## Quick Reference
+
+```typescript
+import type { ExtensionAPI } from "@lenylvt/pi-coding-agent";
+
+export default function (pi: ExtensionAPI) {
+	pi.registerProvider("anthropic", {
+		baseUrl: "https://proxy.example.com",
+	});
+
+	pi.registerProvider("my-provider", {
+		baseUrl: "https://api.example.com/v1",
+		apiKey: "MY_API_KEY",
+		api: "openai-completions",
+		models: [
+			{
+				id: "my-model",
+				name: "My Model",
+				reasoning: false,
+				input: ["text", "image"],
+				cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+				contextWindow: 128000,
+				maxTokens: 4096,
+			},
+		],
+	});
+}
+```
+
+## Override Existing Provider
+
+```typescript
+pi.registerProvider("anthropic", {
+	baseUrl: "https://proxy.example.com",
+});
+
+pi.registerProvider("openrouter", {
+	headers: {
+		"X-Custom-Header": "value",
+	},
+});
+```
+
+When only `baseUrl` and/or `headers` are provided, built-in models for that provider are preserved.
+
+## Register New Provider
+
+```typescript
+pi.registerProvider("my-llm", {
+	baseUrl: "https://api.my-llm.com/v1",
+	apiKey: "MY_LLM_API_KEY",
+	api: "openai-completions",
+	models: [
+		{
+			id: "my-llm-large",
+			name: "My LLM Large",
+			reasoning: true,
+			input: ["text", "image"],
+			cost: {
+				input: 3,
+				output: 15,
+				cacheRead: 0.3,
+				cacheWrite: 3.75,
+			},
+			contextWindow: 200000,
+			maxTokens: 16384,
+		},
+	],
+});
+```
+
+When `models` is provided, it replaces existing models for that provider.
+
+## Unregister Provider
+
+```typescript
+pi.unregisterProvider("my-llm");
+```
+
+Unregistering removes dynamic models, auth overrides, OAuth provider registration, and custom stream handlers registered for that provider.
+
+## API Types
+
+The `api` field selects the streaming implementation:
+
+| API | Use for |
+|-----|---------|
+| `anthropic-messages` | Anthropic-compatible APIs |
+| `openai-completions` | OpenAI Chat Completions compatible APIs |
+| `openai-responses` | OpenAI Responses compatible APIs |
+| `openai-codex-responses` | Codex Responses compatible APIs |
+
+Most proxy or local providers should use `openai-completions`. Use `compat` to handle request quirks:
+
+```typescript
+models: [{
+	id: "custom-model",
+	compat: {
+		supportsDeveloperRole: false,
+		supportsReasoningEffort: true,
+		reasoningEffortMap: {
+			minimal: "default",
+			high: "max",
+		},
+		maxTokensField: "max_tokens",
+		requiresToolResultName: true,
+		thinkingFormat: "openrouter",
+	},
+}]
+```
+
+## Auth Header
+
+```typescript
+pi.registerProvider("custom-api", {
+	baseUrl: "https://api.example.com",
+	apiKey: "MY_API_KEY",
+	authHeader: true,
+	api: "openai-completions",
+	models: [...],
+});
+```
+
+## OAuth Support
+
+```typescript
+import type { OAuthCredentials, OAuthLoginCallbacks } from "@lenylvt/pi-ai";
+
+pi.registerProvider("corporate-ai", {
+	baseUrl: "https://ai.corp.com/v1",
+	api: "openai-responses",
+	models: [...],
+	oauth: {
+		name: "Corporate AI (SSO)",
+
+		async login(callbacks: OAuthLoginCallbacks): Promise<OAuthCredentials> {
+			callbacks.onAuth({ url: "https://sso.corp.com/authorize?..." });
+			const code = await callbacks.onPrompt({ message: "Enter SSO code:" });
+			const tokens = await exchangeCodeForTokens(code);
+			return {
+				refresh: tokens.refreshToken,
+				access: tokens.accessToken,
+				expires: Date.now() + tokens.expiresIn * 1000,
+			};
+		},
+
+		async refreshToken(credentials: OAuthCredentials): Promise<OAuthCredentials> {
+			const tokens = await refreshAccessToken(credentials.refresh);
+			return {
+				refresh: tokens.refreshToken ?? credentials.refresh,
+				access: tokens.accessToken,
+				expires: Date.now() + tokens.expiresIn * 1000,
+			};
+		},
+
+		getApiKey(credentials: OAuthCredentials): string {
+			return credentials.access;
+		},
+	},
+});
+```
+
+After registration, users can authenticate via `/login corporate-ai`.
+
+## Custom Streaming API
+
+Study existing retained implementations before writing your own:
+
+- [anthropic.ts](../../ai/src/providers/anthropic.ts)
+- [openai-completions.ts](../../ai/src/providers/openai-completions.ts)
+- [openai-responses.ts](../../ai/src/providers/openai-responses.ts)
+- [openai-codex-responses.ts](../../ai/src/providers/openai-codex-responses.ts)
+
+All providers follow the same pattern:
+
+```typescript
+import {
+	type AssistantMessage,
+	type AssistantMessageEventStream,
+	type Context,
+	type Model,
+	type SimpleStreamOptions,
+	calculateCost,
+	createAssistantMessageEventStream,
+} from "@lenylvt/pi-ai";
+
+function streamMyProvider(
+	model: Model<any>,
+	context: Context,
+	options?: SimpleStreamOptions,
+): AssistantMessageEventStream {
+	const stream = createAssistantMessageEventStream();
+
+	(async () => {
+		const output: AssistantMessage = {
+			role: "assistant",
+			content: [],
+			api: model.api,
+			provider: model.provider,
+			model: model.id,
+			usage: {
+				input: 0,
+				output: 0,
+				cacheRead: 0,
+				cacheWrite: 0,
+				totalTokens: 0,
+				cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+			},
+			stopReason: "stop",
+			timestamp: Date.now(),
+		};
+
+		try {
+			stream.push({ type: "start", partial: output });
+			stream.push({ type: "done", reason: output.stopReason, message: output });
+			stream.end();
+		} catch (error) {
+			output.stopReason = options?.signal?.aborted ? "aborted" : "error";
+			output.errorMessage = error instanceof Error ? error.message : String(error);
+			stream.push({ type: "error", reason: output.stopReason, error: output });
+			stream.end();
+		}
+	})();
+
+	return stream;
+}
+```
+
+Update usage from the provider response and call `calculateCost(model, output.usage)` before emitting the final message.
+
+## Testing Your Implementation
+
+Match the retained provider test surface in [packages/ai/test/](../../ai/test):
+
+| Test | Purpose |
+|------|---------|
+| `stream.test.ts` | Streaming basics |
+| `tokens.test.ts` | Token accounting |
+| `abort.test.ts` | AbortSignal handling |
+| `empty.test.ts` | Empty/minimal responses |
+| `context-overflow.test.ts` | Context window limits |
+| `image-limits.test.ts` | Image input handling |
+| `unicode-surrogate.test.ts` | Unicode edge cases |
+| `tool-call-without-result.test.ts` | Tool-call edge cases |
+| `image-tool-result.test.ts` | Images in tool results |
+| `total-tokens.test.ts` | Total token calculation |
+| `cross-provider-handoff.test.ts` | Context handoff between providers |
+
+## Config Reference
+
+```typescript
+interface ProviderConfig {
+	baseUrl?: string;
+	apiKey?: string;
+	api?: Api;
+	streamSimple?: (
+		model: Model<Api>,
+		context: Context,
+		options?: SimpleStreamOptions,
+	) => AssistantMessageEventStream;
+	headers?: Record<string, string>;
+	authHeader?: boolean;
+	models?: ProviderModelConfig[];
+	oauth?: {
+		name: string;
+		login(callbacks: OAuthLoginCallbacks): Promise<OAuthCredentials>;
+		refreshToken(credentials: OAuthCredentials): Promise<OAuthCredentials>;
+		getApiKey(credentials: OAuthCredentials): string;
+		modifyModels?(models: Model<Api>[], credentials: OAuthCredentials): Model<Api>[];
+	};
+}
+```
+
+## Model Definition Reference
+
+```typescript
+interface ProviderModelConfig {
+	id: string;
+	name: string;
+	api?: Api;
+	reasoning: boolean;
+	input: ("text" | "image")[];
+	cost: {
+		input: number;
+		output: number;
+		cacheRead: number;
+		cacheWrite: number;
+	};
+	contextWindow: number;
+	maxTokens: number;
+	headers?: Record<string, string>;
+	compat?: {
+		supportsStore?: boolean;
+		supportsDeveloperRole?: boolean;
+		supportsReasoningEffort?: boolean;
+		reasoningEffortMap?: Partial<Record<"minimal" | "low" | "medium" | "high" | "xhigh", string>>;
+		supportsUsageInStreaming?: boolean;
+		maxTokensField?: "max_completion_tokens" | "max_tokens";
+		requiresToolResultName?: boolean;
+		requiresAssistantAfterToolResult?: boolean;
+		requiresThinkingAsText?: boolean;
+		thinkingFormat?: "openai" | "openrouter";
+		supportsStrictMode?: boolean;
+		openRouterRouting?: {
+			only?: string[];
+			order?: string[];
+			fallbacks?: string[];
+		};
+	};
+}
+```