@gajae-code/ai 0.1.1

package/src/providers/google-types.ts

@@ -0,0 +1,167 @@
+/**
+ * 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;
+	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;
+}
+
+/** Single SSE chunk's parsed JSON body. */
+export interface GenerateContentResponse {
+	candidates?: Candidate[];
+	usageMetadata?: UsageMetadata;
+	modelVersion?: string;
+	responseId?: string;
+	promptFeedback?: Record<string, unknown>;
+}

package/src/providers/google-vertex.ts

@@ -0,0 +1,88 @@
+import { $env } from "@gajae-code/utils";
+import type { Context, Model, StreamFunction } from "../types";
+import type { AssistantMessageEventStream } from "../utils/event-stream";
+import { getVertexAccessToken } from "./google-auth";
+import {
+	buildGoogleGenerateContentParams,
+	type GoogleGenAIRequestPlan,
+	type GoogleSharedStreamOptions,
+	streamGoogleGenAI,
+} from "./google-shared";
+
+export interface GoogleVertexOptions extends GoogleSharedStreamOptions {
+	project?: string;
+	location?: string;
+}
+
+const API_VERSION = "v1";
+
+export const streamGoogleVertex: StreamFunction<"google-vertex"> = (
+	model: Model<"google-vertex">,
+	context: Context,
+	options?: GoogleVertexOptions,
+): AssistantMessageEventStream =>
+	streamGoogleGenAI({
+		model,
+		options,
+		api: "google-vertex",
+		retainTextSignature: true,
+		prepare: async (): Promise<GoogleGenAIRequestPlan> => {
+			const apiKey = resolveApiKey(options);
+			const params = buildGoogleGenerateContentParams(model, context, options ?? {});
+			const baseHeaders: Record<string, string> = {
+				...(model.headers ?? {}),
+				...(options?.headers ?? {}),
+			};
+
+			if (apiKey) {
+				const url = `https://aiplatform.googleapis.com/${API_VERSION}/publishers/google/models/${model.id}:streamGenerateContent?alt=sse`;
+				return {
+					params,
+					url,
+					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,
+			};
+		},
+	});
+
+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.GCLOUD_PROJECT;
+	if (!project) {
+		throw new Error(
+			"Vertex AI requires a project ID. Set GOOGLE_CLOUD_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 resolveLocation(options?: GoogleVertexOptions): string {
+	const location = options?.location || $env.GOOGLE_CLOUD_LOCATION;
+	if (!location) {
+		throw new Error("Vertex AI requires a location. Set GOOGLE_CLOUD_LOCATION or pass location in options.");
+	}
+	return location;
+}

package/src/providers/google.ts

@@ -0,0 +1,41 @@
+import { getEnvApiKey } from "../stream";
+import type { Context, Model, StreamFunction } from "../types";
+import type { AssistantMessageEventStream } from "../utils/event-stream";
+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 =>
+	streamGoogleGenAI({
+		model,
+		options,
+		api: "google-generative-ai",
+		prepare: (): GoogleGenAIRequestPlan => {
+			const apiKey = options?.apiKey || getEnvApiKey(model.provider);
+			if (!apiKey) {
+				throw new Error("Google Generative AI requires an API key (GEMINI_API_KEY or options.apiKey).");
+			}
+			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 };
+		},
+	});

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 type { Api, Context, Model } from "../types";
+import type { AssistantMessageEventStream } from "../utils/event-stream";
+import { getKimiCommonHeaders } from "../utils/oauth/kimi";
+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";
+}