@juspay/neurolink 10.10.6 → 10.10.7

package/dist/lib/utils/redis.d.ts

@@ -2,7 +2,7 @@
  * Redis Utilities for NeuroLink
  * Helper functions for Redis storage operations
  */
-import type { RedisClient, RedisConversationObject, RedisStorageConfig } from "../types/index.js";
+import type { ChatMessage, RedisClient, RedisConversationObject, RedisStorageConfig } from "../types/index.js";
 /**
  * Get a pooled Redis connection. Multiple callers with the same host:port:db
  * share a single connection, reducing connection count.
@@ -36,6 +36,28 @@ export declare function getUserSessionsKey(config: Required<RedisStorageConfig>,
  * Serializes conversation object for Redis storage
  */
 export declare function serializeConversation(conversation: RedisConversationObject): string;
+/**
+ * True for a complete `ChatMessage` — `id` included, because callers keying
+ * summary pointers and condensation groups off it are entitled to find one.
+ */
+export declare function isStoredChatMessage(value: unknown): value is ChatMessage;
+/**
+ * Coerce a stored entry into a complete `ChatMessage`, or `undefined` when its
+ * shape is unusable.
+ *
+ * Shared by BOTH read paths on purpose. Inline blobs have always been
+ * validated; once messages moved into the companion LIST the split read
+ * bypassed that check, so `null`, a number or a bare string survived
+ * `JSON.parse` and reached callers that dereference `.role`, `.content` and
+ * `.metadata`. The two storage formats must offer the same read guarantee.
+ *
+ * `id` is a separate matter: it is required on `ChatMessage`, but no read path
+ * has ever enforced it, so history written before it existed carries none.
+ * Rejecting those records would empty otherwise-healthy sessions, so a missing
+ * id is backfilled rather than fatal — prefixed, so a synthesized id is never
+ * mistaken for one an existing pointer could reference.
+ */
+export declare function normalizeStoredMessage(value: unknown): ChatMessage | undefined;
 /**
  * Deserializes conversation object from Redis storage
  */
@@ -58,3 +80,40 @@ export declare function scanKeys(client: RedisClient, pattern: string, batchSize
  * Get normalized Redis configuration with defaults
  */
 export declare function getNormalizedConfig(config: RedisStorageConfig): Required<RedisStorageConfig>;
+/**
+ * Suffix of the companion LIST key holding a session's messages.
+ *
+ * Every `storeConversationTurn` used to re-serialize and SET the ENTIRE
+ * conversation, so per-turn write cost grew with history size. Measured
+ * against local Redis: 200 turns of 2KB messages stayed flat at 2ms, but 400
+ * turns of 20KB messages (~16MB blob) went 2ms -> 61ms, a 30x degradation on
+ * exactly the agentic tool-output profile. Splitting messages into an
+ * append-only LIST makes the per-turn write O(1) in conversation size.
+ */
+export declare const MESSAGES_KEY_SUFFIX = ":msgs";
+/**
+ * Marker on a stored blob meaning "messages live in the companion LIST".
+ * A blob WITHOUT it is a legacy record whose inline `messages` array is
+ * authoritative — it is read as-is and converted on its next write, which is
+ * what makes this migration backward compatible.
+ */
+export declare const MESSAGES_IN_LIST_MARKER = "__nlMessagesInList";
+/** Redis key holding a session's messages as an append-only LIST. */
+export declare function getSessionMessagesKey(config: Required<RedisStorageConfig>, sessionId: string, userId?: string): string;
+/**
+ * True for a companion messages LIST key.
+ *
+ * Scan-then-GET paths (`getStats`, session listing) match `${keyPrefix}*`, so
+ * they now also see these LIST keys — and `GET` on a LIST raises WRONGTYPE.
+ * They must filter with this, exactly as they already skip `:sessions` index
+ * keys.
+ */
+export declare function isSessionMessagesKey(key: string): boolean;
+/** Serialize the conversation WITHOUT its messages, flagged for split reads. */
+export declare function serializeConversationMetadata(conversation: RedisConversationObject): string;
+/** True when a deserialized blob's messages live in the companion LIST. */
+export declare function usesSplitMessageStorage(conversation: RedisConversationObject | null | undefined): boolean;
+/** Parse LRANGE entries, skipping any single entry that is not usable. */
+export declare function parseStoredMessages(entries: string[]): ChatMessage[];
+/** Encode messages for RPUSH. */
+export declare function encodeStoredMessages(messages: ChatMessage[]): string[];

package/dist/lib/utils/redis.js

@@ -2,6 +2,7 @@
  * Redis Utilities for NeuroLink
  * Helper functions for Redis storage operations
  */
+import { randomUUID } from "crypto";
 import { createClient } from "redis";
 import { logger } from "./logger.js";
 const SESSION_ONLY_PREFIX = "session-only:";
@@ -198,6 +199,65 @@ export function serializeConversation(conversation) {
         throw error;
     }
 }
+/** The exact role set `ChatMessage` allows. */
+const STORED_MESSAGE_ROLES = new Set([
+    "user",
+    "assistant",
+    "system",
+    "tool_call",
+    "tool_result",
+]);
+function isStoredMessageRole(role) {
+    return typeof role === "string" && STORED_MESSAGE_ROLES.has(role);
+}
+/**
+ * True for a complete `ChatMessage` — `id` included, because callers keying
+ * summary pointers and condensation groups off it are entitled to find one.
+ */
+export function isStoredChatMessage(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const candidate = value;
+    return (typeof candidate.id === "string" &&
+        typeof candidate.content === "string" &&
+        isStoredMessageRole(candidate.role));
+}
+/**
+ * Coerce a stored entry into a complete `ChatMessage`, or `undefined` when its
+ * shape is unusable.
+ *
+ * Shared by BOTH read paths on purpose. Inline blobs have always been
+ * validated; once messages moved into the companion LIST the split read
+ * bypassed that check, so `null`, a number or a bare string survived
+ * `JSON.parse` and reached callers that dereference `.role`, `.content` and
+ * `.metadata`. The two storage formats must offer the same read guarantee.
+ *
+ * `id` is a separate matter: it is required on `ChatMessage`, but no read path
+ * has ever enforced it, so history written before it existed carries none.
+ * Rejecting those records would empty otherwise-healthy sessions, so a missing
+ * id is backfilled rather than fatal — prefixed, so a synthesized id is never
+ * mistaken for one an existing pointer could reference.
+ */
+export function normalizeStoredMessage(value) {
+    if (isStoredChatMessage(value)) {
+        return value;
+    }
+    if (typeof value !== "object" || value === null) {
+        return undefined;
+    }
+    const candidate = value;
+    if (typeof candidate.content !== "string" ||
+        !isStoredMessageRole(candidate.role)) {
+        return undefined;
+    }
+    return {
+        ...candidate,
+        id: `legacy-${randomUUID()}`,
+        role: candidate.role,
+        content: candidate.content,
+    };
+}
 /**
  * Deserializes conversation object from Redis storage
  */
@@ -235,18 +295,8 @@ export function deserializeConversation(data) {
             return null;
         }
         // Validate each message in the messages array
-        const isValidHistory = conversation.messages.every((m) => typeof m === "object" &&
-            m !== null &&
-            "role" in m &&
-            "content" in m &&
-            typeof m.role === "string" &&
-            typeof m.content === "string" &&
-            (m.role === "user" ||
-                m.role === "assistant" ||
-                m.role === "system" ||
-                m.role === "tool_call" ||
-                m.role === "tool_result"));
-        if (!isValidHistory) {
+        const normalizedMessages = conversation.messages.map(normalizeStoredMessage);
+        if (normalizedMessages.some((message) => message === undefined)) {
             logger.warn("[redisUtils] Invalid messages structure", {
                 messageCount: conversation.messages.length,
                 firstMessage: conversation.messages.length > 0
@@ -255,6 +305,7 @@ export function deserializeConversation(data) {
             });
             return null;
         }
+        conversation.messages = normalizedMessages.filter((message) => message !== undefined);
         logger.debug("[redisUtils] Conversation deserialized successfully", {
             sessionId: conversation.sessionId,
             userId: conversation.userId,
@@ -396,4 +447,84 @@ export function getNormalizedConfig(config) {
         },
     };
 }
+// ---------------------------------------------------------------------------
+// Split message storage
+// ---------------------------------------------------------------------------
+/**
+ * Suffix of the companion LIST key holding a session's messages.
+ *
+ * Every `storeConversationTurn` used to re-serialize and SET the ENTIRE
+ * conversation, so per-turn write cost grew with history size. Measured
+ * against local Redis: 200 turns of 2KB messages stayed flat at 2ms, but 400
+ * turns of 20KB messages (~16MB blob) went 2ms -> 61ms, a 30x degradation on
+ * exactly the agentic tool-output profile. Splitting messages into an
+ * append-only LIST makes the per-turn write O(1) in conversation size.
+ */
+export const MESSAGES_KEY_SUFFIX = ":msgs";
+/**
+ * Marker on a stored blob meaning "messages live in the companion LIST".
+ * A blob WITHOUT it is a legacy record whose inline `messages` array is
+ * authoritative — it is read as-is and converted on its next write, which is
+ * what makes this migration backward compatible.
+ */
+export const MESSAGES_IN_LIST_MARKER = "__nlMessagesInList";
+/** Redis key holding a session's messages as an append-only LIST. */
+export function getSessionMessagesKey(config, sessionId, userId) {
+    return `${getSessionKey(config, sessionId, userId)}${MESSAGES_KEY_SUFFIX}`;
+}
+/**
+ * True for a companion messages LIST key.
+ *
+ * Scan-then-GET paths (`getStats`, session listing) match `${keyPrefix}*`, so
+ * they now also see these LIST keys — and `GET` on a LIST raises WRONGTYPE.
+ * They must filter with this, exactly as they already skip `:sessions` index
+ * keys.
+ */
+export function isSessionMessagesKey(key) {
+    return key.endsWith(MESSAGES_KEY_SUFFIX);
+}
+/** Serialize the conversation WITHOUT its messages, flagged for split reads. */
+export function serializeConversationMetadata(conversation) {
+    return JSON.stringify({
+        ...conversation,
+        messages: [],
+        [MESSAGES_IN_LIST_MARKER]: true,
+    });
+}
+/** True when a deserialized blob's messages live in the companion LIST. */
+export function usesSplitMessageStorage(conversation) {
+    if (!conversation) {
+        return false;
+    }
+    const record = conversation;
+    return record[MESSAGES_IN_LIST_MARKER] === true;
+}
+/** Parse LRANGE entries, skipping any single entry that is not usable. */
+export function parseStoredMessages(entries) {
+    const messages = [];
+    for (const entry of entries) {
+        try {
+            // `JSON.parse` succeeds for `null`, numbers and bare strings, so the
+            // catch below cannot filter them — the shape has to be checked.
+            const parsed = JSON.parse(entry);
+            const message = normalizeStoredMessage(parsed);
+            if (!message) {
+                logger.warn("[redisUtils] Skipping stored message with invalid shape");
+                continue;
+            }
+            messages.push(message);
+        }
+        catch (error) {
+            // One corrupt entry must not destroy a whole session's history.
+            logger.warn("[redisUtils] Skipping unparseable stored message", {
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    return messages;
+}
+/** Encode messages for RPUSH. */
+export function encodeStoredMessages(messages) {
+    return messages.map((message) => JSON.stringify(message));
+}
 //# sourceMappingURL=redis.js.map

package/dist/providers/googleAiStudio/client.d.ts

@@ -2,37 +2,6 @@ import { type AIProviderName } from "../../constants/enums.js";
 import { BaseProvider } from "../../core/baseProvider.js";
 import type { ZodUnknownSchema, EnhancedGenerateResult, TextGenerationOptions, StreamOptions, StreamResult } from "../../types/index.js";
 import type { LanguageModel, Schema } from "../../types/index.js";
-/**
- * Google AI Studio provider implementation using BaseProvider
- * Migrated from original GoogleAIStudio class to new factory pattern
- *
- * @important Structured Output Limitation
- * Google Gemini models cannot combine function calling (tools) with structured
- * output (JSON schema). When using schemas with output.format: "json", you MUST
- * set disableTools: true.
- *
- * Error without disableTools:
- * "Function calling with a response mime type: 'application/json' is unsupported"
- *
- * This is a Google API limitation documented at:
- * https://ai.google.dev/gemini-api/docs/function-calling
- *
- * @example
- * ```typescript
- * // ✅ Correct usage with schemas
- * const provider = new GoogleAIStudioProvider("gemini-2.5-flash");
- * const result = await provider.generate({
- *   input: { text: "Analyze data" },
- *   schema: MySchema,
- *   output: { format: "json" },
- *   disableTools: true  // Required
- * });
- * ```
- *
- * @note Gemini 3 Pro Preview (November 2025) will support combining tools + schemas
- * @note "Too many states for serving" errors can occur with complex schemas + tools.
- *       Solution: Simplify schema or use disableTools: true
- */
 export declare class GoogleAIStudioProvider extends BaseProvider {
     private credentials?;
     constructor(modelName?: string, sdk?: unknown, credentials?: {

package/dist/providers/googleAiStudio/client.js

@@ -6,12 +6,14 @@ import { ATTR, tracers, withClientSpan, withClientStreamSpan, withSpan, } from "
 import { AuthenticationError, InvalidModelError, NetworkError, ProviderError, RateLimitError, } from "../../types/index.js";
 import { ERROR_CODES, NeuroLinkError } from "../../utils/errorHandling.js";
 import { logger } from "../../utils/logger.js";
+import { GEMINI_ELISION_NOTE, planGeminiLoopReclaim, previewGeminiToolResponseText, } from "../../context/geminiLoopGuard.js";
+import { getAvailableInputTokens, getContextWindowSize, } from "../../constants/contextWindows.js";
 import { composeAbortSignals, createTimeoutController, TimeoutError, } from "../../utils/timeout.js";
 import { withTimeout } from "../../utils/async/index.js";
 import { estimateTokens } from "../../utils/tokenEstimation.js";
 import { transformToolExecutions } from "../../utils/transformationUtils.js";
 import { resolveToolExecutionRecords } from "../../core/toolExecutionRecorder.js";
-import { buildGeminiResponseSchema, buildNativeConfig, buildNativeToolDeclarations, collectStreamChunks, collectStreamChunksIncremental, computeMaxSteps, createTextChannel, buildUserPartsWithMultimodal, executeNativeToolCalls, extractTextFromParts, extractThoughtSignature, handleMaxStepsTermination, prependConversationMessages, pushModelResponseToHistory, refreshNativeToolDeclarations, DedupExecuteMap, } from "../googleNativeGemini3/index.js";
+import { buildGeminiResponseSchema, buildNativeConfig, buildNativeToolDeclarations, collectStreamChunks, collectStreamChunksIncremental, computeMaxSteps, createContextGuard, createTextChannel, buildUserPartsWithMultimodal, executeNativeToolCalls, extractTextFromParts, extractThoughtSignature, handleMaxStepsTermination, prependConversationMessages, pushModelResponseToHistory, refreshNativeToolDeclarations, DedupExecuteMap, } from "../googleNativeGemini3/index.js";
 import { createProxyFetch } from "../../proxy/proxyFetch.js";
 // Google AI Live API types now imported from ../types/providerSpecific.js
 // Import proper types for multimodal message handling
@@ -69,6 +71,74 @@ async function createGoogleGenAIClient(apiKey) {
  * @note "Too many states for serving" errors can occur with complex schemas + tools.
  *       Solution: Simplify schema or use disableTools: true
  */
+/**
+ * Reclaim context from an AI Studio loop history IN PLACE.
+ *
+ * This loop had NO in-turn guard at all — it appended a model turn plus a tool
+ * turn every step with nothing bounding growth, so a long agentic run walked
+ * into a provider "context length exceeded" and lost every completed step.
+ * Shares its reclaim policy with the other provider loops via loopGuardCore.
+ *
+ * Returns true when something was reclaimed.
+ */
+function reclaimAiStudioContext(contents, modelName, observedPromptTokens) {
+    const plan = planGeminiLoopReclaim({
+        contents,
+        availableInputTokens: getAvailableInputTokens("googleAiStudio", modelName),
+        provider: "googleAiStudio",
+        ...(observedPromptTokens ? { observedPromptTokens } : {}),
+    });
+    if (!plan) {
+        return false;
+    }
+    const dropSet = new Set(plan.drop);
+    const truncateSet = new Set(plan.truncate);
+    const rebuilt = [];
+    for (let i = 0; i < contents.length; i++) {
+        if (dropSet.has(i)) {
+            continue;
+        }
+        const content = contents[i];
+        if (truncateSet.has(i) && Array.isArray(content.parts)) {
+            rebuilt.push({
+                ...content,
+                parts: content.parts.map((part) => {
+                    const record = part;
+                    if (!record.functionResponse) {
+                        return part;
+                    }
+                    const text = JSON.stringify(record.functionResponse.response) ?? "";
+                    if (text.length <= 2048) {
+                        return part;
+                    }
+                    return {
+                        functionResponse: {
+                            name: record.functionResponse.name,
+                            response: { result: previewGeminiToolResponseText(text) },
+                        },
+                    };
+                }),
+            });
+            continue;
+        }
+        rebuilt.push(content);
+    }
+    if (dropSet.size > 0) {
+        let noteIndex = rebuilt.findIndex((c) => Array.isArray(c.parts) &&
+            c.parts.some((part) => !!part.functionCall ||
+                !!part.functionResponse));
+        if (noteIndex < 0) {
+            noteIndex = Math.min(1, rebuilt.length);
+        }
+        rebuilt.splice(noteIndex, 0, {
+            role: "user",
+            parts: [{ text: GEMINI_ELISION_NOTE }],
+        });
+    }
+    contents.length = 0;
+    contents.push(...rebuilt);
+    return true;
+}
 export class GoogleAIStudioProvider extends BaseProvider {
     credentials;
     constructor(modelName, sdk, credentials) {
@@ -595,9 +665,27 @@ export class GoogleAIStudioProvider extends BaseProvider {
                     let step = 0;
                     let completedWithFinalAnswer = false;
                     const failedTools = new Map();
+                    // Cheap trigger for the in-turn reclaim, mirroring the Vertex twin.
+                    // Planning serializes the WHOLE accumulated history to estimate it,
+                    // so running it unconditionally charges that once per step for the
+                    // life of the turn; the guard tracks real prompt counts plus
+                    // measured growth instead, and it supplies the observed count that
+                    // calibrates the planner's char estimate.
+                    const contextGuard = createContextGuard(getContextWindowSize("googleAiStudio", modelName));
                     try {
                         // Agentic loop for tool calling
                         while (step < maxSteps) {
+                            // In-turn context guard: this loop appends a model turn plus a
+                            // tool turn every step with nothing bounding growth. No-op
+                            // while the request still fits, so a loop that fits never pays
+                            // a cache invalidation. Step 0 still plans unconditionally —
+                            // the guard has no usage to go on yet, and the incoming history
+                            // can already be oversized before the first call.
+                            if (step === 0 || contextGuard.shouldStop()) {
+                                if (reclaimAiStudioContext(currentContents, modelName, contextGuard.projectedNextPromptTokens)) {
+                                    contextGuard.resetAfterReclaim();
+                                }
+                            }
                             if (composedSignal?.aborted) {
                                 throw composedSignal.reason instanceof Error
                                     ? composedSignal.reason
@@ -629,6 +717,10 @@ export class GoogleAIStudioProvider extends BaseProvider {
                                 totalOutputTokens += chunkResult.outputTokens;
                                 totalCacheReadTokens += chunkResult.cacheReadTokens ?? 0;
                                 totalReasoningTokens += chunkResult.reasoningTokens ?? 0;
+                                // `inputTokens` is this step's promptTokenCount — the FULL
+                                // prompt size for the request just made, which is what the
+                                // guard projects the next request from.
+                                contextGuard.noteUsage(chunkResult.inputTokens, chunkResult.outputTokens);
                                 const stepText = extractTextFromParts(chunkResult.rawResponseParts);
                                 // If no function calls, this was the final step — channel
                                 // already received all text parts incrementally.
@@ -691,6 +783,14 @@ export class GoogleAIStudioProvider extends BaseProvider {
                                     role: "user",
                                     parts: functionResponses,
                                 });
+                                // Project this step's growth: the appended tool results ride
+                                // the next prompt, which the provider has not reported on yet.
+                                try {
+                                    contextGuard.noteAppendedChars(JSON.stringify(functionResponses).length);
+                                }
+                                catch {
+                                    /* estimation is best-effort — never break the loop */
+                                }
                             }
                             catch (error) {
                                 logger.error("[GoogleAIStudio] Native SDK error", error);
@@ -877,8 +977,16 @@ export class GoogleAIStudioProvider extends BaseProvider {
                 const toolExecutions = [];
                 let step = 0;
                 const failedTools = new Map();
+                // Cheap reclaim trigger — see the stream twin.
+                const contextGuard = createContextGuard(getContextWindowSize("googleAiStudio", modelName));
                 // Agentic loop for tool calling
                 while (step < maxSteps) {
+                    // In-turn context guard — see the stream twin.
+                    if (step === 0 || contextGuard.shouldStop()) {
+                        if (reclaimAiStudioContext(currentContents, modelName, contextGuard.projectedNextPromptTokens)) {
+                            contextGuard.resetAfterReclaim();
+                        }
+                    }
                     if (composedSignal?.aborted) {
                         throw composedSignal.reason instanceof Error
                             ? composedSignal.reason
@@ -904,6 +1012,7 @@ export class GoogleAIStudioProvider extends BaseProvider {
                         totalOutputTokens += chunkResult.outputTokens;
                         totalCacheReadTokens += chunkResult.cacheReadTokens ?? 0;
                         totalReasoningTokens += chunkResult.reasoningTokens ?? 0;
+                        contextGuard.noteUsage(chunkResult.inputTokens, chunkResult.outputTokens);
                         const stepText = extractTextFromParts(chunkResult.rawResponseParts);
                         // If no function calls, we're done
                         if (chunkResult.stepFunctionCalls.length === 0) {
@@ -961,6 +1070,14 @@ export class GoogleAIStudioProvider extends BaseProvider {
                             role: "user",
                             parts: functionResponses,
                         });
+                        // Project this step's growth: the appended tool results ride
+                        // the next prompt, which the provider has not reported on yet.
+                        try {
+                            contextGuard.noteAppendedChars(JSON.stringify(functionResponses).length);
+                        }
+                        catch {
+                            /* estimation is best-effort — never break the loop */
+                        }
                     }
                     catch (error) {
                         logger.error("[GoogleAIStudio] Native SDK generate error", error);

package/dist/providers/googleNativeGemini3/utils.d.ts

@@ -385,6 +385,15 @@ export declare function createContextGuard(contextWindowTokens: number, threshol
      * results, nudge text) using the ~4 chars/token heuristic.
      */
     noteAppendedChars(chars: number): void;
+    /**
+     * Clear the projection after the caller has reclaimed context.
+     *
+     * The observed prompt size reflects the pre-reclaim conversation, so
+     * leaving it in place would keep `shouldStop()` true forever and defeat
+     * the reclaim. Resetting to the fail-open state means the guard stays
+     * quiet until the next real usage report re-establishes the truth.
+     */
+    resetAfterReclaim(): void;
     /** True when issuing another model call risks crossing the threshold. */
     shouldStop(): boolean;
 };

package/dist/providers/googleNativeGemini3/utils.js

@@ -1229,6 +1229,18 @@ export function createContextGuard(contextWindowTokens, thresholdRatio = DEFAULT
                 projectedGrowthTokens += Math.ceil(chars / 4);
             }
         },
+        /**
+         * Clear the projection after the caller has reclaimed context.
+         *
+         * The observed prompt size reflects the pre-reclaim conversation, so
+         * leaving it in place would keep `shouldStop()` true forever and defeat
+         * the reclaim. Resetting to the fail-open state means the guard stays
+         * quiet until the next real usage report re-establishes the truth.
+         */
+        resetAfterReclaim() {
+            observedPromptTokens = 0;
+            projectedGrowthTokens = 0;
+        },
         /** True when issuing another model call risks crossing the threshold. */
         shouldStop() {
             return (observedPromptTokens > 0 &&

package/dist/providers/googleVertex/client.d.ts

@@ -51,51 +51,6 @@ export declare function stripAdditionalPropertiesDeep(schema: Record<string, unk
  * @returns The region string to pass to the @google/genai client.
  */
 export declare const resolveVertexLocation: (modelName: string | undefined, configuredLocation?: string) => string;
-/**
- * Google Vertex AI Provider v2 - BaseProvider Implementation
- *
- * Features:
- * - Extends BaseProvider for shared functionality
- * - Preserves existing Google Cloud authentication
- * - Maintains Anthropic model support via dynamic imports
- * - Fresh model creation for each request
- * - Enhanced error handling with setup guidance
- * - Tool registration and context management
- *
- * @important Tools + Schema Support (Fixed)
- * Gemini models on Vertex AI now support combining function calling (tools) with
- * structured output (JSON schema) simultaneously. The fix works by NOT setting
- * `responseMimeType: "application/json"` when tools are present, which was
- * causing the Google API error.
- *
- * The `responseSchema` is still set to guide the output structure, allowing
- * tools to execute AND the final output to follow the schema format.
- *
- * @example Gemini models with tools + schemas
- * ```typescript
- * const provider = new GoogleVertexProvider("gemini-2.5-flash");
- * const result = await provider.generate({
- *   input: { text: "Analyze data using tools" },
- *   schema: MySchema,
- *   output: { format: "json" },
- *   // No need for disableTools: true anymore!
- * });
- * ```
- *
- * @example Claude models (always supported both)
- * ```typescript
- * const provider = new GoogleVertexProvider("claude-3-5-sonnet-20241022");
- * const result = await provider.generate({
- *   input: { text: "Analyze data" },
- *   schema: MySchema,
- *   output: { format: "json" }
- * });
- * ```
- *
- * @note "Too many states for serving" errors can still occur with very complex schemas + tools.
- *       Solution: Simplify schema or reduce number of tools if this occurs.
- * @see https://cloud.google.com/vertex-ai/docs/generative-ai/learn/models
- */
 export declare class GoogleVertexProvider extends BaseProvider {
     private projectId;
     private location;