@oh-my-pi/pi-ai 3.20.1 → 3.35.0

package/README.md

@@ -4,17 +4,61 @@ Unified LLM API with automatic model discovery, provider configuration, token an
 
 **Note**: This library only includes models that support tool calling (function calling), as this is essential for agentic workflows.
 
+## Table of Contents
+
+- [Supported Providers](#supported-providers)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Tools](#tools)
+  - [Defining Tools](#defining-tools)
+  - [Handling Tool Calls](#handling-tool-calls)
+  - [Streaming Tool Calls with Partial JSON](#streaming-tool-calls-with-partial-json)
+  - [Validating Tool Arguments](#validating-tool-arguments)
+  - [Complete Event Reference](#complete-event-reference)
+- [Image Input](#image-input)
+- [Thinking/Reasoning](#thinkingreasoning)
+  - [Unified Interface](#unified-interface-streamsimplecompletesimple)
+  - [Provider-Specific Options](#provider-specific-options-streamcomplete)
+  - [Streaming Thinking Content](#streaming-thinking-content)
+- [Stop Reasons](#stop-reasons)
+- [Error Handling](#error-handling)
+  - [Aborting Requests](#aborting-requests)
+  - [Continuing After Abort](#continuing-after-abort)
+- [APIs, Models, and Providers](#apis-models-and-providers)
+  - [Providers and Models](#providers-and-models)
+  - [Querying Providers and Models](#querying-providers-and-models)
+  - [Custom Models](#custom-models)
+  - [OpenAI Compatibility Settings](#openai-compatibility-settings)
+  - [Type Safety](#type-safety)
+- [Cross-Provider Handoffs](#cross-provider-handoffs)
+- [Context Serialization](#context-serialization)
+- [Browser Usage](#browser-usage)
+  - [Environment Variables](#environment-variables-nodejs-only)
+  - [Checking Environment Variables](#checking-environment-variables)
+- [OAuth Providers](#oauth-providers)
+  - [Vertex AI (ADC)](#vertex-ai-adc)
+  - [CLI Login](#cli-login)
+  - [Programmatic OAuth](#programmatic-oauth)
+  - [Login Flow Example](#login-flow-example)
+  - [Using OAuth Tokens](#using-oauth-tokens)
+  - [Provider Notes](#provider-notes)
+- [License](#license)
+
 ## Supported Providers
 
 - **OpenAI**
+- **OpenAI Codex** (ChatGPT Plus/Pro subscription, requires OAuth, see below)
 - **Anthropic**
 - **Google**
+- **Vertex AI** (Gemini via Vertex AI)
 - **Mistral**
 - **Groq**
 - **Cerebras**
 - **xAI**
 - **OpenRouter**
 - **GitHub Copilot** (requires OAuth, see below)
+- **Google Gemini CLI** (requires OAuth, see below)
+- **Antigravity** (requires OAuth, see below)
 - **Any OpenAI-compatible API**: Ollama, vLLM, LM Studio, etc.
 
 ## Installation
@@ -121,6 +165,7 @@ for (const call of toolCalls) {
 		toolCallId: call.id,
 		toolName: call.name,
 		content: [{ type: "text", text: result }],
+		isError: false,
 		timestamp: Date.now(),
 	});
 }
@@ -208,6 +253,7 @@ for (const block of response.content) {
 			toolCallId: block.id,
 			toolName: block.name,
 			content: [{ type: "text", text: JSON.stringify(result) }],
+			isError: false,
 			timestamp: Date.now(),
 		});
 	}
@@ -223,6 +269,7 @@ context.messages.push({
 		{ type: "text", text: "Generated chart showing temperature trends" },
 		{ type: "image", data: imageBuffer.toString("base64"), mimeType: "image/png" },
 	],
+	isError: false,
 	timestamp: Date.now(),
 });
 ```
@@ -819,17 +866,19 @@ const response = await complete(
 
 In Node.js environments, you can set environment variables to avoid passing API keys:
 
-```bash
-OPENAI_API_KEY=sk-...
-ANTHROPIC_API_KEY=sk-ant-...
-GEMINI_API_KEY=...
-MISTRAL_API_KEY=...
-GROQ_API_KEY=gsk_...
-CEREBRAS_API_KEY=csk-...
-XAI_API_KEY=xai-...
-ZAI_API_KEY=...
-OPENROUTER_API_KEY=sk-or-...
-```
+| Provider       | Environment Variable(s)                                                      |
+| -------------- | ---------------------------------------------------------------------------- |
+| OpenAI         | `OPENAI_API_KEY`                                                             |
+| Anthropic      | `ANTHROPIC_API_KEY` or `ANTHROPIC_OAUTH_TOKEN`                               |
+| Google         | `GEMINI_API_KEY`                                                             |
+| Vertex AI      | `GOOGLE_CLOUD_PROJECT` (or `GCLOUD_PROJECT`) + `GOOGLE_CLOUD_LOCATION` + ADC |
+| Mistral        | `MISTRAL_API_KEY`                                                            |
+| Groq           | `GROQ_API_KEY`                                                               |
+| Cerebras       | `CEREBRAS_API_KEY`                                                           |
+| xAI            | `XAI_API_KEY`                                                                |
+| OpenRouter     | `OPENROUTER_API_KEY`                                                         |
+| zAI            | `ZAI_API_KEY`                                                                |
+| GitHub Copilot | `COPILOT_GITHUB_TOKEN` or `GH_TOKEN` or `GITHUB_TOKEN`                       |
 
 When set, the library automatically uses these keys:
 
@@ -858,10 +907,15 @@ const key = getEnvApiKey("openai"); // checks OPENAI_API_KEY
 Several providers require OAuth authentication instead of static API keys:
 
 - **Anthropic** (Claude Pro/Max subscription)
+- **OpenAI Codex** (ChatGPT Plus/Pro subscription, access to GPT-5.x Codex models)
 - **GitHub Copilot** (Copilot subscription)
 - **Google Gemini CLI** (Free Gemini 2.0/2.5 via Google Cloud Code Assist)
 - **Antigravity** (Free Gemini 3, Claude, GPT-OSS via Google Cloud)
 
+### Vertex AI (ADC)
+
+Vertex AI models use Application Default Credentials. Run `gcloud auth application-default login`, set `GOOGLE_CLOUD_PROJECT` (or `GCLOUD_PROJECT`), and `GOOGLE_CLOUD_LOCATION`. You can also pass `project`/`location` in the call options.
+
 ### CLI Login
 
 The quickest way to authenticate:
@@ -882,6 +936,7 @@ The library provides login and token refresh functions. Credential storage is th
 import {
 	// Login functions (return credentials, do not store)
 	loginAnthropic,
+	loginOpenAICodex,
 	loginGitHubCopilot,
 	loginGeminiCli,
 	loginAntigravity,
@@ -891,7 +946,7 @@ import {
 	getOAuthApiKey, // (provider, credentialsMap) => { newCredentials, apiKey } | null
 
 	// Types
-	type OAuthProvider, // 'anthropic' | 'github-copilot' | 'google-gemini-cli' | 'google-antigravity'
+	type OAuthProvider, // 'anthropic' | 'openai-codex' | 'github-copilot' | 'google-gemini-cli' | 'google-antigravity'
 	type OAuthCredentials,
 } from "@oh-my-pi/pi-ai";
 ```
@@ -950,6 +1005,8 @@ const response = await complete(
 
 ### Provider Notes
 
+**OpenAI Codex**: Requires a ChatGPT Plus or Pro subscription. Provides access to GPT-5.x Codex models with extended context windows and reasoning capabilities. The library automatically handles session-based prompt caching when `sessionId` is provided in stream options.
+
 **GitHub Copilot**: If you get "The requested model is not supported" error, enable the model manually in VS Code: open Copilot Chat, click the model selector, select the model (warning icon), and click "Enable".
 
 **Google Gemini CLI / Antigravity**: These use Google Cloud OAuth. The `apiKey` returned by `getOAuthApiKey()` is a JSON string containing both the token and project ID, which the library handles automatically.

package/package.json

@@ -1,14 +1,10 @@
 {
 	"name": "@oh-my-pi/pi-ai",
-	"version": "3.20.1",
+	"version": "3.35.0",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"type": "module",
 	"main": "./src/index.ts",
 	"types": "./src/index.ts",
-	"exports": {
-		".": "./src/index.ts",
-		"./utils/json-parse": "./src/utils/json-parse.ts"
-	},
 	"bin": {
 		"pi-ai": "./src/cli.ts"
 	},
@@ -18,8 +14,7 @@
 	],
 	"scripts": {
 		"generate-models": "bun scripts/generate-models.ts",
-		"test": "vitest --run",
-		"prepublishOnly": "bun run generate-models"
+		"test": "bun test"
 	},
 	"dependencies": {
 		"@anthropic-ai/sdk": "0.71.2",
@@ -53,8 +48,6 @@
 		"bun": ">=1.0.0"
 	},
 	"devDependencies": {
-		"@types/node": "^24.3.0",
-		"canvas": "^3.2.0",
-		"vitest": "^3.2.4"
+		"@types/node": "^24.3.0"
 	}
 }

package/src/cli.ts

@@ -1,6 +1,7 @@
-#!/usr/bin/env bun
+#!/usr/bin/env node
 
-import { logger } from "@oh-my-pi/pi-coding-agent";
+import { existsSync, readFileSync, writeFileSync } from "fs";
+import { createInterface } from "readline";
 import { loginAnthropic } from "./utils/oauth/anthropic";
 import { loginGitHubCopilot } from "./utils/oauth/github-copilot";
 import { loginAntigravity } from "./utils/oauth/google-antigravity";
@@ -12,104 +13,101 @@ import type { OAuthCredentials, OAuthProvider } from "./utils/oauth/types";
 const AUTH_FILE = "auth.json";
 const PROVIDERS = getOAuthProviders();
 
-function prompt(question: string): Promise<string> {
-	return new Promise((resolve) => {
-		process.stdout.write(question);
-		process.stdin.resume();
-		process.stdin.once("data", (data) => {
-			process.stdin.pause();
-			resolve(data.toString().trim());
-		});
-	});
+function prompt(rl: ReturnType<typeof createInterface>, question: string): Promise<string> {
+	return new Promise((resolve) => rl.question(question, resolve));
 }
 
-async function loadAuth(): Promise<Record<string, { type: "oauth" } & OAuthCredentials>> {
-	const file = Bun.file(AUTH_FILE);
-	if (!(await file.exists())) return {};
+function loadAuth(): Record<string, { type: "oauth" } & OAuthCredentials> {
+	if (!existsSync(AUTH_FILE)) return {};
 	try {
-		return await file.json();
-	} catch (err) {
-		logger.debug("Failed to parse config file", { error: String(err) });
+		return JSON.parse(readFileSync(AUTH_FILE, "utf-8"));
+	} catch {
 		return {};
 	}
 }
 
-async function saveAuth(auth: Record<string, { type: "oauth" } & OAuthCredentials>): Promise<void> {
-	await Bun.write(AUTH_FILE, JSON.stringify(auth, null, 2));
+function saveAuth(auth: Record<string, { type: "oauth" } & OAuthCredentials>): void {
+	writeFileSync(AUTH_FILE, JSON.stringify(auth, null, 2), "utf-8");
 }
 
 async function login(provider: OAuthProvider): Promise<void> {
-	const promptFn = (msg: string) => prompt(`${msg} `);
-
-	let credentials: OAuthCredentials;
-
-	switch (provider) {
-		case "anthropic":
-			credentials = await loginAnthropic(
-				(url) => {
-					console.log(`\nOpen this URL in your browser:\n${url}\n`);
-				},
-				async () => {
-					return await promptFn("Paste the authorization code:");
-				},
-			);
-			break;
-
-		case "github-copilot":
-			credentials = await loginGitHubCopilot({
-				onAuth: (url, instructions) => {
-					console.log(`\nOpen this URL in your browser:\n${url}`);
-					if (instructions) console.log(instructions);
-					console.log();
-				},
-				onPrompt: async (p) => {
-					return await promptFn(`${p.message}${p.placeholder ? ` (${p.placeholder})` : ""}:`);
-				},
-				onProgress: (msg) => console.log(msg),
-			});
-			break;
-
-		case "google-gemini-cli":
-			credentials = await loginGeminiCli(
-				(info) => {
-					console.log(`\nOpen this URL in your browser:\n${info.url}`);
-					if (info.instructions) console.log(info.instructions);
-					console.log();
-				},
-				(msg) => console.log(msg),
-			);
-			break;
-
-		case "google-antigravity":
-			credentials = await loginAntigravity(
-				(info) => {
-					console.log(`\nOpen this URL in your browser:\n${info.url}`);
-					if (info.instructions) console.log(info.instructions);
-					console.log();
-				},
-				(msg) => console.log(msg),
-			);
-			break;
-		case "openai-codex":
-			credentials = await loginOpenAICodex({
-				onAuth: (info) => {
-					console.log(`\nOpen this URL in your browser:\n${info.url}`);
-					if (info.instructions) console.log(info.instructions);
-					console.log();
-				},
-				onPrompt: async (p) => {
-					return await promptFn(`${p.message}${p.placeholder ? ` (${p.placeholder})` : ""}:`);
-				},
-				onProgress: (msg) => console.log(msg),
-			});
-			break;
-	}
+	const rl = createInterface({ input: process.stdin, output: process.stdout });
+
+	const promptFn = (msg: string) => prompt(rl, `${msg} `);
+
+	try {
+		let credentials: OAuthCredentials;
+
+		switch (provider) {
+			case "anthropic":
+				credentials = await loginAnthropic(
+					(url) => {
+						console.log(`\nOpen this URL in your browser:\n${url}\n`);
+					},
+					async () => {
+						return await promptFn("Paste the authorization code:");
+					},
+				);
+				break;
+
+			case "github-copilot":
+				credentials = await loginGitHubCopilot({
+					onAuth: (url, instructions) => {
+						console.log(`\nOpen this URL in your browser:\n${url}`);
+						if (instructions) console.log(instructions);
+						console.log();
+					},
+					onPrompt: async (p) => {
+						return await promptFn(`${p.message}${p.placeholder ? ` (${p.placeholder})` : ""}:`);
+					},
+					onProgress: (msg) => console.log(msg),
+				});
+				break;
+
+			case "google-gemini-cli":
+				credentials = await loginGeminiCli(
+					(info) => {
+						console.log(`\nOpen this URL in your browser:\n${info.url}`);
+						if (info.instructions) console.log(info.instructions);
+						console.log();
+					},
+					(msg) => console.log(msg),
+				);
+				break;
+
+			case "google-antigravity":
+				credentials = await loginAntigravity(
+					(info) => {
+						console.log(`\nOpen this URL in your browser:\n${info.url}`);
+						if (info.instructions) console.log(info.instructions);
+						console.log();
+					},
+					(msg) => console.log(msg),
+				);
+				break;
+			case "openai-codex":
+				credentials = await loginOpenAICodex({
+					onAuth: (info) => {
+						console.log(`\nOpen this URL in your browser:\n${info.url}`);
+						if (info.instructions) console.log(info.instructions);
+						console.log();
+					},
+					onPrompt: async (p) => {
+						return await promptFn(`${p.message}${p.placeholder ? ` (${p.placeholder})` : ""}:`);
+					},
+					onProgress: (msg) => console.log(msg),
+				});
+				break;
+		}
 
-	const auth = await loadAuth();
-	auth[provider] = { type: "oauth", ...credentials };
-	await saveAuth(auth);
+		const auth = loadAuth();
+		auth[provider] = { type: "oauth", ...credentials };
+		saveAuth(auth);
 
-	console.log(`\nCredentials saved to ${AUTH_FILE}`);
+		console.log(`\nCredentials saved to ${AUTH_FILE}`);
+	} finally {
+		rl.close();
+	}
 }
 
 async function main(): Promise<void> {
@@ -150,13 +148,15 @@ Examples:
 		let provider = args[1] as OAuthProvider | undefined;
 
 		if (!provider) {
+			const rl = createInterface({ input: process.stdin, output: process.stdout });
 			console.log("Select a provider:\n");
 			for (let i = 0; i < PROVIDERS.length; i++) {
 				console.log(`  ${i + 1}. ${PROVIDERS[i].name}`);
 			}
 			console.log();
 
-			const choice = await prompt(`Enter number (1-${PROVIDERS.length}): `);
+			const choice = await prompt(rl, `Enter number (1-${PROVIDERS.length}): `);
+			rl.close();
 
 			const index = parseInt(choice, 10) - 1;
 			if (index < 0 || index >= PROVIDERS.length) {

package/src/index.ts

@@ -1,9 +1,9 @@
-/// <reference path="./bun-imports.d.ts" />
-
 export * from "./models";
 export * from "./providers/anthropic";
 export * from "./providers/google";
 export * from "./providers/google-gemini-cli";
+export * from "./providers/google-vertex";
+export * from "./providers/openai-codex/index";
 export * from "./providers/openai-completions";
 export * from "./providers/openai-responses";
 export * from "./stream";