jeopi-ai 16.2.13

package/src/providers/google-types.ts

@@ -0,0 +1,180 @@
+/**
+ * Local mirror of the subset of `@google/genai` types this package consumes.
+ *
+ * Field shapes match Gemini / Vertex AI wire format 1:1. Enum-shaped values are
+ * modelled as string literal unions so they pass through `JSON.stringify` and
+ * `JSON.parse` unchanged.
+ *
+ * Keep this file in sync with the actual request/response surface of:
+ *   - `POST {generativelanguage,aiplatform}.googleapis.com/.../models/{model}:streamGenerateContent?alt=sse`
+ *   - The Cloud Code Assist endpoint used by `google-gemini-cli.ts`
+ */
+/** Mirror of `@google/genai`'s `FinishReason` string enum. */
+export type FinishReason =
+	| "FINISH_REASON_UNSPECIFIED"
+	| "STOP"
+	| "MAX_TOKENS"
+	| "SAFETY"
+	| "RECITATION"
+	| "LANGUAGE"
+	| "OTHER"
+	| "BLOCKLIST"
+	| "PROHIBITED_CONTENT"
+	| "SPII"
+	| "MALFORMED_FUNCTION_CALL"
+	| "IMAGE_SAFETY"
+	| "IMAGE_PROHIBITED_CONTENT"
+	| "IMAGE_RECITATION"
+	| "IMAGE_OTHER"
+	| "UNEXPECTED_TOOL_CALL"
+	| "NO_IMAGE";
+
+/** Mirror of `@google/genai`'s `FunctionCallingConfigMode` string enum. */
+export type FunctionCallingConfigMode = "MODE_UNSPECIFIED" | "AUTO" | "NONE" | "ANY" | "VALIDATED";
+
+/** Mirror of `@google/genai`'s `ThinkingLevel` string enum. */
+export type ThinkingLevel = "THINKING_LEVEL_UNSPECIFIED" | "MINIMAL" | "LOW" | "MEDIUM" | "HIGH";
+
+/** Inline base64-encoded data part. */
+export interface InlineDataPart {
+	mimeType: string;
+	data: string;
+}
+
+/** Function call emitted by the model. */
+export interface FunctionCallPart {
+	name?: string;
+	args?: Record<string, unknown>;
+	id?: string;
+}
+
+/** Tool execution result fed back to the model. */
+export interface FunctionResponsePart {
+	name: string;
+	response: Record<string, unknown>;
+	parts?: Part[];
+	id?: string;
+}
+
+/**
+ * A single piece of a `Content` message. Mirrors the SDK's union by keeping
+ * every optional field — the model and the wire treat shape as discriminator.
+ */
+export interface Part {
+	text?: string;
+	thought?: boolean;
+	thoughtSignature?: string;
+	inlineData?: InlineDataPart;
+	functionCall?: FunctionCallPart;
+	functionResponse?: FunctionResponsePart;
+}
+
+/** Conversation turn. Roles: `"user"`, `"model"`, optionally absent for system instructions. */
+export interface Content {
+	role?: string;
+	parts?: Part[];
+}
+
+/** Thinking/reasoning configuration shared by Gemini 2.x and 3.x models. */
+export interface ThinkingConfig {
+	includeThoughts?: boolean;
+	thinkingBudget?: number;
+	thinkingLevel?: ThinkingLevel;
+}
+
+/** Function declaration entry inside `tools[].functionDeclarations`. */
+export interface FunctionDeclaration {
+	name: string;
+	description?: string;
+	parameters?: Record<string, unknown>;
+	parametersJsonSchema?: Record<string, unknown>;
+}
+
+/** Tool group as accepted at the request top level. */
+export interface ToolDeclaration {
+	functionDeclarations: Record<string, unknown>[];
+}
+
+/** Tool selection mode container. */
+export interface ToolConfig {
+	functionCallingConfig?: {
+		mode: FunctionCallingConfigMode;
+		allowedFunctionNames?: string[];
+	};
+}
+
+/**
+ * Generation/sampling and request-shape options passed via the SDK's `config`.
+ *
+ * Fields that the wire format places at the request body root (systemInstruction,
+ * tools, toolConfig, safetySettings, cachedContent) live here too — the
+ * transformer in `google-shared.ts` lifts them out when serializing.
+ */
+export interface GenerateContentConfig {
+	temperature?: number;
+	maxOutputTokens?: number;
+	topP?: number;
+	topK?: number;
+	candidateCount?: number;
+	stopSequences?: string[];
+	presencePenalty?: number;
+	frequencyPenalty?: number;
+	seed?: number;
+	responseMimeType?: string;
+	responseSchema?: Record<string, unknown>;
+	responseJsonSchema?: Record<string, unknown>;
+	responseModalities?: string[];
+	systemInstruction?: Content | { role?: string; parts: { text: string }[] };
+	tools?: ToolDeclaration[];
+	toolConfig?: ToolConfig;
+	safetySettings?: Array<Record<string, unknown>>;
+	cachedContent?: string;
+	thinkingConfig?: ThinkingConfig;
+	/**
+	 * Gemini/Vertex serving tier. Serialized to the request body root as
+	 * `serviceTier` (camelCase) by the transformer in `google-shared.ts`.
+	 */
+	serviceTier?: "auto" | "default" | "flex" | "scale" | "priority";
+	abortSignal?: AbortSignal;
+}
+
+/** Top-level argument to `generateContentStream`. */
+export interface GenerateContentParameters {
+	model: string;
+	contents: Content[];
+	config?: GenerateContentConfig;
+}
+
+/** Per-stream candidate envelope. */
+export interface Candidate {
+	content?: Content;
+	finishReason?: FinishReason;
+	index?: number;
+}
+
+/** Cumulative token accounting attached to the trailing chunk. */
+export interface UsageMetadata {
+	promptTokenCount?: number;
+	candidatesTokenCount?: number;
+	thoughtsTokenCount?: number;
+	totalTokenCount?: number;
+	cachedContentTokenCount?: number;
+}
+
+/** Prompt-level safety feedback; `blockReason` is set (with no candidates) when the prompt is blocked. */
+export interface PromptFeedback {
+	blockReason?: string;
+	blockReasonMessage?: string;
+	[key: string]: unknown;
+}
+
+/** Single SSE chunk's parsed JSON body. */
+export interface GenerateContentResponse {
+	candidates?: Candidate[];
+	usageMetadata?: UsageMetadata;
+	modelVersion?: string;
+	responseId?: string;
+	promptFeedback?: PromptFeedback;
+	/** In-band stream failure (quota, internal error) delivered as a final JSON event. */
+	error?: { code?: number; message?: string; status?: string };
+}

package/src/providers/google-vertex.ts

@@ -0,0 +1,183 @@
+import { $env } from "jeopi-utils";
+import * as AIError from "../error";
+import type { Context, Model, StreamFunction } from "../types";
+import type { AssistantMessageEventStream } from "../utils/event-stream";
+import { getVertexAccessToken, hasVertexBearerCredentialsHint } from "./google-auth";
+import {
+	type GoogleInteractionsPlan,
+	modelSupportsInteractions,
+	resolveInteractionDispatch,
+	streamGoogleInteractions,
+} from "./google-interactions";
+import {
+	buildGoogleGenerateContentParams,
+	type GoogleGenAIRequestPlan,
+	type GoogleSharedStreamOptions,
+	streamGoogleGenAI,
+} from "./google-shared";
+
+export interface GoogleVertexOptions extends GoogleSharedStreamOptions {
+	project?: string;
+	location?: string;
+}
+
+const API_VERSION = "v1";
+const INTERACTIONS_API_VERSION = "v1beta1";
+const INTERACTIONS_API_REVISION = "2026-05-20";
+
+export const streamGoogleVertex: StreamFunction<"google-vertex"> = (
+	model: Model<"google-vertex">,
+	context: Context,
+	options?: GoogleVertexOptions,
+): AssistantMessageEventStream => {
+	const runGenerateContent = (): AssistantMessageEventStream =>
+		streamGoogleGenAI({
+			model,
+			options,
+			api: "google-vertex",
+			retainTextSignature: true,
+			prepare: async (): Promise<GoogleGenAIRequestPlan> => {
+				const apiKey = resolveApiKey(options);
+				const params = buildGoogleGenerateContentParams(model, context, options ?? {});
+				params.config ||= {};
+				if (!params.config.safetySettings) {
+					params.config.safetySettings = [
+						{
+							category: "HARM_CATEGORY_HATE_SPEECH",
+							threshold: "OFF",
+						},
+						{
+							category: "HARM_CATEGORY_DANGEROUS_CONTENT",
+							threshold: "OFF",
+						},
+						{
+							category: "HARM_CATEGORY_SEXUALLY_EXPLICIT",
+							threshold: "OFF",
+						},
+						{
+							category: "HARM_CATEGORY_HARASSMENT",
+							threshold: "OFF",
+						},
+					];
+				}
+				const baseHeaders: Record<string, string> = {
+					...(model.headers ?? {}),
+					...(options?.headers ?? {}),
+				};
+				// Vertex AI ignores a `serviceTier` request-body field (unlike the direct
+				// Gemini API); priority must travel as a request header. Only `priority`
+				// has a documented Vertex request control — `flex` has none, so it's a no-op.
+				if (options?.serviceTier === "priority") {
+					baseHeaders["X-Vertex-AI-LLM-Shared-Request-Type"] = "priority";
+				}
+
+				if (apiKey) {
+					// Explicit `location` is a deliberate residency choice: honor it and let
+					// a 404 surface. An ambient env-derived region falls back to the global
+					// endpoint so a stray GOOGLE_*_LOCATION never breaks a previously-working
+					// global-only request.
+					const explicitLocation = options?.location;
+					const location = explicitLocation ?? resolveAmbientLocation() ?? "global";
+					const host = resolveEndpointHost(location);
+					const path = `${API_VERSION}/publishers/google/models/${model.id}:streamGenerateContent?alt=sse`;
+					const useGlobalFallback = !explicitLocation && host !== "aiplatform.googleapis.com";
+					return {
+						params,
+						url: `https://${host}/${path}`,
+						fallbackUrl: useGlobalFallback ? `https://aiplatform.googleapis.com/${path}` : undefined,
+						headers: {
+							...baseHeaders,
+							"x-goog-api-key": apiKey,
+						},
+						fetch: options?.fetch,
+					};
+				}
+
+				const project = resolveProject(options);
+				const location = resolveLocation(options);
+				const accessToken = await getVertexAccessToken({ signal: options?.signal, fetch: options?.fetch });
+				const host = resolveEndpointHost(location);
+				const url = `https://${host}/${API_VERSION}/projects/${project}/locations/${location}/publishers/google/models/${model.id}:streamGenerateContent?alt=sse`;
+				return {
+					params,
+					url,
+					headers: { ...baseHeaders, Authorization: `Bearer ${accessToken}` },
+					fetch: options?.fetch,
+				};
+			},
+		});
+
+	// Default Gemini 3+ onto Interactions whenever a bearer credential source exists (ADC file,
+	// `GOOGLE_APPLICATION_CREDENTIALS`, or an explicit access-token env). Interactions needs bearer
+	// auth, so express API-key-only setups stay on generateContent — and an express key, when
+	// present, still serves the generateContent fallback. Interactions always targets the official
+	// global `aiplatform` host; the fallback also recovers ids the endpoint rejects.
+	const { useInteractions, auto, anchor, state } = resolveInteractionDispatch({
+		context,
+		options,
+		provider: model.provider,
+		autoEligible: modelSupportsInteractions(model) && hasVertexBearerCredentialsHint(),
+	});
+	if (!useInteractions) return runGenerateContent();
+
+	return streamGoogleInteractions({
+		model,
+		context,
+		options,
+		api: "google-vertex",
+		anchor,
+		state,
+		prepare: async (): Promise<GoogleInteractionsPlan> => {
+			const project = resolveProject(options);
+			const accessToken = await getVertexAccessToken({ signal: options?.signal, fetch: options?.fetch });
+			return {
+				url: `https://aiplatform.googleapis.com/${INTERACTIONS_API_VERSION}/projects/${project}/locations/global/interactions`,
+				headers: {
+					...(model.headers ?? {}),
+					...(options?.headers ?? {}),
+					Authorization: `Bearer ${accessToken}`,
+					"Api-Revision": INTERACTIONS_API_REVISION,
+				},
+				fetch: options?.fetch,
+			};
+		},
+		fallback: auto ? runGenerateContent : undefined,
+	});
+};
+
+function resolveApiKey(options?: GoogleVertexOptions): string | undefined {
+	// options.apiKey may contain sentinel values like "<authenticated>" or "N/A"
+	// leaked from the agent loop — only use it if it looks like a real API key.
+	const optKey = options?.apiKey;
+	const realKey = optKey && !optKey.startsWith("<") && optKey !== "N/A" ? optKey : undefined;
+	return realKey || $env.GOOGLE_CLOUD_API_KEY;
+}
+
+function resolveProject(options?: GoogleVertexOptions): string {
+	const project = options?.project || $env.GOOGLE_CLOUD_PROJECT || $env.GCP_PROJECT || $env.GCLOUD_PROJECT;
+	if (!project) {
+		throw new AIError.ConfigurationError(
+			"Vertex AI requires a project ID. Set GOOGLE_CLOUD_PROJECT/GCP_PROJECT/GCLOUD_PROJECT or pass project in options.",
+		);
+	}
+	return project;
+}
+
+function resolveEndpointHost(location: string): string {
+	return location === "global" ? "aiplatform.googleapis.com" : `${location}-aiplatform.googleapis.com`;
+}
+function resolveAmbientLocation(): string | undefined {
+	return $env.GOOGLE_VERTEX_LOCATION || $env.GOOGLE_CLOUD_LOCATION || $env.VERTEX_LOCATION || undefined;
+}
+function resolveOptionalLocation(options?: GoogleVertexOptions): string | undefined {
+	return options?.location || resolveAmbientLocation();
+}
+function resolveLocation(options?: GoogleVertexOptions): string {
+	const location = resolveOptionalLocation(options);
+	if (!location) {
+		throw new AIError.ConfigurationError(
+			"Vertex AI requires a location. Set GOOGLE_VERTEX_LOCATION/GOOGLE_CLOUD_LOCATION/VERTEX_LOCATION or pass location in options.",
+		);
+	}
+	return location;
+}

package/src/providers/google.ts

@@ -0,0 +1,87 @@
+import * as AIError from "../error";
+import { getEnvApiKey } from "../stream";
+import type { Context, Model, StreamFunction } from "../types";
+import type { AssistantMessageEventStream } from "../utils/event-stream";
+import { modelSupportsInteractions, resolveInteractionDispatch, streamGoogleInteractions } from "./google-interactions";
+import {
+	buildGoogleGenerateContentParams,
+	type GoogleGenAIRequestPlan,
+	type GoogleSharedStreamOptions,
+	streamGoogleGenAI,
+} from "./google-shared";
+
+export type GoogleOptions = GoogleSharedStreamOptions;
+
+const DEFAULT_GENERATIVE_LANGUAGE_BASE = "https://generativelanguage.googleapis.com/v1beta";
+
+export const streamGoogle: StreamFunction<"google-generative-ai"> = (
+	model: Model<"google-generative-ai">,
+	context: Context,
+	options?: GoogleOptions,
+): AssistantMessageEventStream => {
+	const apiKey = options?.apiKey || getEnvApiKey(model.provider);
+	if (!apiKey) {
+		throw new AIError.MissingApiKeyError(
+			undefined,
+			"Google Generative AI requires an API key (GEMINI_API_KEY or options.apiKey).",
+		);
+	}
+
+	const runGenerateContent = (): AssistantMessageEventStream =>
+		streamGoogleGenAI({
+			model,
+			options,
+			api: "google-generative-ai",
+			prepare: (): GoogleGenAIRequestPlan => {
+				const params = buildGoogleGenerateContentParams(model, context, options ?? {});
+				// `model.baseUrl` already includes the API version segment when set (mirrors the
+				// `apiVersion: ""` reset that the SDK relied on for custom base URLs).
+				const base = model.baseUrl?.trim() || DEFAULT_GENERATIVE_LANGUAGE_BASE;
+				const url = `${base}/models/${model.id}:streamGenerateContent?alt=sse`;
+				const headers: Record<string, string> = {
+					"x-goog-api-key": apiKey,
+					...(model.headers ?? {}),
+					...(options?.headers ?? {}),
+				};
+				return { params, url, headers, fetch: options?.fetch };
+			},
+		});
+
+	// Default Gemini 3+ on the official endpoint onto Interactions (custom proxy base URLs keep
+	// generateContent, which serves the full catalog). The fallback recovers ids the endpoint rejects.
+	const trimmedBase = model.baseUrl?.trim();
+	let officialEndpoint = !trimmedBase;
+	if (trimmedBase) {
+		try {
+			officialEndpoint = new URL(trimmedBase).hostname === "generativelanguage.googleapis.com";
+		} catch {
+			officialEndpoint = false;
+		}
+	}
+	const { useInteractions, auto, anchor, state } = resolveInteractionDispatch({
+		context,
+		options,
+		provider: model.provider,
+		autoEligible: officialEndpoint && modelSupportsInteractions(model),
+	});
+	if (!useInteractions) return runGenerateContent();
+
+	return streamGoogleInteractions({
+		model,
+		context,
+		options,
+		api: "google-generative-ai",
+		anchor,
+		state,
+		prepare: () => ({
+			url: `${trimmedBase || DEFAULT_GENERATIVE_LANGUAGE_BASE}/interactions`,
+			headers: {
+				"x-goog-api-key": apiKey,
+				...(model.headers ?? {}),
+				...(options?.headers ?? {}),
+			},
+			fetch: options?.fetch,
+		}),
+		fallback: auto ? runGenerateContent : undefined,
+	});
+};

package/src/providers/grammar.ts

@@ -0,0 +1,70 @@
+export function compactGrammarDefinition(syntax: "lark" | "regex", definition: string): string {
+	if (syntax !== "lark") {
+		return definition;
+	}
+
+	return compactLarkGrammarDefinition(definition);
+}
+
+function compactLarkGrammarDefinition(definition: string): string {
+	const lines: string[] = [];
+
+	for (const line of definition.split(/\r?\n/)) {
+		const uncommented = stripLarkLineComment(line).trimEnd();
+		if (uncommented.trim()) {
+			lines.push(uncommented);
+		}
+	}
+
+	return lines.join("\n");
+}
+
+function stripLarkLineComment(line: string): string {
+	let inString: string | undefined;
+	let inRegex = false;
+	let escaped = false;
+
+	for (let i = 0; i < line.length; i++) {
+		const char = line[i];
+		const next = line[i + 1];
+
+		if (escaped) {
+			escaped = false;
+			continue;
+		}
+
+		if (char === "\\") {
+			escaped = true;
+			continue;
+		}
+
+		if (inString) {
+			if (char === inString) {
+				inString = undefined;
+			}
+			continue;
+		}
+
+		if (inRegex) {
+			if (char === "/") {
+				inRegex = false;
+			}
+			continue;
+		}
+
+		if (char === "/" && next === "/") {
+			return line.slice(0, i);
+		}
+
+		if (char === '"' || char === "'") {
+			inString = char;
+			continue;
+		}
+
+		if (char === "/") {
+			inRegex = true;
+		}
+	}
+
+	return line;
+}

package/src/providers/kimi.ts

@@ -0,0 +1,52 @@
+/**
+ * Kimi Code provider - wraps OpenAI or Anthropic API based on format setting.
+ *
+ * Kimi offers both OpenAI-compatible and Anthropic-compatible APIs:
+ * - OpenAI: https://api.kimi.com/coding/v1/chat/completions
+ * - Anthropic: https://api.kimi.com/coding/v1/messages
+ *
+ * The Anthropic API is generally more stable and recommended.
+ * Note: Kimi calculates TPM rate limits based on max_tokens, not actual output.
+ */
+
+import { getKimiCommonHeaders } from "../registry/oauth/kimi";
+import type { Api, Context, Model } from "../types";
+import type { AssistantMessageEventStream } from "../utils/event-stream";
+import {
+	type OpenAIAnthropicApiFormat,
+	type OpenAIAnthropicShimOptions,
+	streamOpenAIAnthropicShim,
+} from "./openai-anthropic-shim";
+
+export type KimiApiFormat = OpenAIAnthropicApiFormat;
+
+// Note: Anthropic SDK appends /v1/messages, so base URL should not include /v1
+const KIMI_ANTHROPIC_BASE_URL = "https://api.kimi.com/coding";
+
+export interface KimiOptions extends OpenAIAnthropicShimOptions {
+	/** API format: "openai" or "anthropic". Default: "anthropic" */
+	format?: KimiApiFormat;
+}
+
+/**
+ * Stream from Kimi Code, routing to either OpenAI or Anthropic API based on format.
+ * Returns synchronously like other providers - async header fetching happens internally.
+ */
+export function streamKimi(
+	model: Model<"openai-completions">,
+	context: Context,
+	options?: KimiOptions,
+): AssistantMessageEventStream {
+	return streamOpenAIAnthropicShim(model, context, options, {
+		anthropicBaseUrl: KIMI_ANTHROPIC_BASE_URL,
+		defaultFormat: "anthropic",
+		extraHeaders: getKimiCommonHeaders,
+	});
+}
+
+/**
+ * Check if a model is a Kimi Code model.
+ */
+export function isKimiModel(model: Model<Api>): boolean {
+	return model.provider === "kimi-code";
+}