@juspay/neurolink 8.28.0 → 8.30.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [8.30.0](https://github.com/juspay/neurolink/compare/v8.29.0...v8.30.0) (2026-01-03)
+
+### Features
+
+- **(video):** add video generation support to NeuroLink SDK with Vertex AI ([6b490a1](https://github.com/juspay/neurolink/commit/6b490a1f436a823ff6bad41fc77f98d62be08c68))
+
+## [8.29.0](https://github.com/juspay/neurolink/compare/v8.28.0...v8.29.0) (2026-01-02)
+
+### Features
+
+- **(mcp):** add HTTP/Streamable HTTP transport support for MCP servers ([67f1c23](https://github.com/juspay/neurolink/commit/67f1c23ac2d5e687b7455c627da952a820af773b))
+
 ## [8.28.0](https://github.com/juspay/neurolink/compare/v8.27.0...v8.28.0) (2026-01-02)
 
 ### Features

package/README.md

@@ -25,6 +25,7 @@ Extracted from production systems at Juspay and battle-tested at enterprise scal
 
 ## What's New (Q4 2025)
 
+- **HTTP/Streamable HTTP Transport for MCP** – Connect to remote MCP servers via HTTP with authentication headers, retry logic, and rate limiting. → [HTTP Transport Guide](docs/MCP-HTTP-TRANSPORT.md)
 - 🧠 **Gemini 3 Preview Support** - Full support for gemini-3-flash-preview and gemini-3-pro-preview with extended thinking capabilities
 - **Structured Output with Zod Schemas** – Type-safe JSON generation with automatic validation using `schema` + `output.format: "json"` in `generate()`. → [Structured Output Guide](docs/features/structured-output.md)
 - **CSV File Support** – Attach CSV files to prompts for AI-powered data analysis with auto-detection. → [CSV Guide](docs/features/multimodal-chat.md#csv-file-support)
@@ -96,7 +97,7 @@ NeuroLink is a comprehensive AI development platform. Every feature below is pro
 **58+ External MCP Servers** supported (GitHub, PostgreSQL, Google Drive, Slack, and more):
 
 ```typescript
-// Add any MCP server dynamically
+// stdio transport - local MCP servers via command execution
 await neurolink.addExternalMCPServer("github", {
   command: "npx",
   args: ["-y", "@modelcontextprotocol/server-github"],
@@ -104,13 +105,32 @@ await neurolink.addExternalMCPServer("github", {
   env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN },
 });
 
+// HTTP transport - remote MCP servers via URL
+await neurolink.addExternalMCPServer("github-copilot", {
+  transport: "http",
+  url: "https://api.githubcopilot.com/mcp",
+  headers: { Authorization: "Bearer YOUR_COPILOT_TOKEN" },
+  timeout: 15000,
+  retries: 5,
+});
+
 // Tools automatically available to AI
 const result = await neurolink.generate({
   input: { text: 'Create a GitHub issue titled "Bug in auth flow"' },
 });
 ```
 
+**MCP Transport Options:**
+
+| Transport   | Use Case       | Key Features                                    |
+| ----------- | -------------- | ----------------------------------------------- |
+| `stdio`     | Local servers  | Command execution, environment variables        |
+| `http`      | Remote servers | URL-based, auth headers, retries, rate limiting |
+| `sse`       | Event streams  | Server-Sent Events, real-time updates           |
+| `websocket` | Bi-directional | Full-duplex communication                       |
+
 **[📖 MCP Integration Guide](docs/advanced/mcp-integration.md)** - Setup external servers
+**[📖 HTTP Transport Guide](docs/MCP-HTTP-TRANSPORT.md)** - Remote MCP server configuration
 
 ---
 
@@ -327,7 +347,7 @@ Full command and API breakdown lives in [`docs/cli/commands.md`](docs/cli/comman
 | **Memory & context**     | Conversation memory, Mem0 integration, Redis history export (Q4), context summarization (Q4).                            |
 | **CLI tooling**          | Loop sessions (Q3), setup wizard, config validation, Redis auto-detect, JSON output.                                     |
 | **Enterprise ops**       | Proxy support, regional routing (Q3), telemetry hooks, configuration management.                                         |
-| **Tool ecosystem**       | MCP auto discovery, LiteLLM hub access, SageMaker custom deployment, web search.                                         |
+| **Tool ecosystem**       | MCP auto discovery, HTTP/stdio/SSE/WebSocket transports, LiteLLM hub access, SageMaker custom deployment, web search.    |
 
 ## Documentation Map
 
@@ -349,6 +369,7 @@ Full command and API breakdown lives in [`docs/cli/commands.md`](docs/cli/comman
 - **Enterprise proxy & security** – Configure outbound policies and compliance posture. → [`docs/ENTERPRISE-PROXY-SETUP.md`](docs/ENTERPRISE-PROXY-SETUP.md)
 - **Configuration automation** – Manage environments, regions, and credentials safely. → [`docs/CONFIGURATION-MANAGEMENT.md`](docs/CONFIGURATION-MANAGEMENT.md)
 - **MCP tool ecosystem** – Auto-discover Model Context Protocol tools and extend workflows. → [`docs/advanced/mcp-integration.md`](docs/advanced/mcp-integration.md)
+- **Remote MCP via HTTP** – Connect to HTTP-based MCP servers with authentication, retries, and rate limiting. → [`docs/MCP-HTTP-TRANSPORT.md`](docs/MCP-HTTP-TRANSPORT.md)
 
 ## Contributing & Support
 

package/dist/adapters/video/vertexVideoHandler.d.ts

@@ -16,8 +16,12 @@ import { NeuroLinkError } from "../../utils/errorHandling.js";
  * Video generation runtime error codes
  *
  * These are for runtime/execution errors during video generation.
- * Input validation errors (missing image, invalid options, etc.) are handled
- * by parameterValidation.ts using ERROR_CODES from errorHandling.ts.
+ * Pure option/shape validation (missing image option, invalid config values, etc.)
+ * is handled by parameterValidation.ts using ERROR_CODES from errorHandling.ts.
+ *
+ * Error categorization:
+ * - INVALID_INPUT → ErrorCategory.execution (runtime I/O failures)
+ * - parameterValidation errors → ErrorCategory.validation (schema/option issues)
  *
  * Following TTS pattern (TTS_ERROR_CODES + TTSError in ttsProcessor.ts)
  */
@@ -28,6 +32,12 @@ export declare const VIDEO_ERROR_CODES: {
     readonly PROVIDER_NOT_CONFIGURED: "VIDEO_PROVIDER_NOT_CONFIGURED";
     /** Polling for video completion timed out */
     readonly POLL_TIMEOUT: "VIDEO_POLL_TIMEOUT";
+    /**
+     * Runtime I/O error during input processing.
+     * Used for: failed URL fetch, failed file read, corrupt/unreadable buffer.
+     * NOT for: missing options or invalid config shapes (use parameterValidation).
+     */
+    readonly INVALID_INPUT: "VIDEO_INVALID_INPUT";
 };
 /**
  * Video generation error class

package/dist/adapters/video/vertexVideoHandler.js

@@ -21,8 +21,12 @@ import { logger } from "../../utils/logger.js";
  * Video generation runtime error codes
  *
  * These are for runtime/execution errors during video generation.
- * Input validation errors (missing image, invalid options, etc.) are handled
- * by parameterValidation.ts using ERROR_CODES from errorHandling.ts.
+ * Pure option/shape validation (missing image option, invalid config values, etc.)
+ * is handled by parameterValidation.ts using ERROR_CODES from errorHandling.ts.
+ *
+ * Error categorization:
+ * - INVALID_INPUT → ErrorCategory.execution (runtime I/O failures)
+ * - parameterValidation errors → ErrorCategory.validation (schema/option issues)
  *
  * Following TTS pattern (TTS_ERROR_CODES + TTSError in ttsProcessor.ts)
  */
@@ -33,6 +37,12 @@ export const VIDEO_ERROR_CODES = {
     PROVIDER_NOT_CONFIGURED: "VIDEO_PROVIDER_NOT_CONFIGURED",
     /** Polling for video completion timed out */
     POLL_TIMEOUT: "VIDEO_POLL_TIMEOUT",
+    /**
+     * Runtime I/O error during input processing.
+     * Used for: failed URL fetch, failed file read, corrupt/unreadable buffer.
+     * NOT for: missing options or invalid config shapes (use parameterValidation).
+     */
+    INVALID_INPUT: "VIDEO_INVALID_INPUT",
 };
 /**
  * Video generation error class

package/dist/core/baseProvider.d.ts

@@ -226,6 +226,25 @@ export declare abstract class BaseProvider implements AIProvider {
      */
     protected normalizeStreamOptions(optionsOrPrompt: StreamOptions | string): StreamOptions;
     protected enhanceResult(result: EnhancedGenerateResult, options: TextGenerationOptions, startTime: number): Promise<EnhancedGenerateResult>;
+    /**
+     * Handle video generation mode
+     *
+     * Generates video from input image + text prompt using Vertex AI Veo 3.1.
+     *
+     * @param options - Text generation options with video configuration
+     * @param startTime - Generation start timestamp for metrics
+     * @returns Enhanced result with video data
+     *
+     * @example
+     * ```typescript
+     * const result = await provider.generate({
+     *   input: { text: "Product showcase", images: [imageBuffer] },
+     *   output: { mode: "video", video: { resolution: "1080p" } }
+     * });
+     * // result.video contains the generated video
+     * ```
+     */
+    private handleVideoGeneration;
     /**
      * Create analytics - delegated to TelemetryHandler
      */

package/dist/core/baseProvider.js

@@ -323,6 +323,11 @@ export class BaseProvider {
         this.validateOptions(options);
         const startTime = Date.now();
         try {
+            // ===== VIDEO GENERATION MODE =====
+            // Generate video from image + prompt using Veo 3.1
+            if (options.output?.mode === "video") {
+                return await this.handleVideoGeneration(options, startTime);
+            }
             // ===== TTS MODE 1: Direct Input Synthesis (useAiResponse=false) =====
             // Synthesize input text directly without AI generation
             // This is optimal for simple read-aloud scenarios
@@ -659,6 +664,175 @@ export class BaseProvider {
         }
         return enhancedResult;
     }
+    /**
+     * Handle video generation mode
+     *
+     * Generates video from input image + text prompt using Vertex AI Veo 3.1.
+     *
+     * @param options - Text generation options with video configuration
+     * @param startTime - Generation start timestamp for metrics
+     * @returns Enhanced result with video data
+     *
+     * @example
+     * ```typescript
+     * const result = await provider.generate({
+     *   input: { text: "Product showcase", images: [imageBuffer] },
+     *   output: { mode: "video", video: { resolution: "1080p" } }
+     * });
+     * // result.video contains the generated video
+     * ```
+     */
+    async handleVideoGeneration(options, startTime) {
+        // Dynamic imports to avoid loading video dependencies unless needed
+        const { generateVideoWithVertex, VideoError, VIDEO_ERROR_CODES } = await import("../adapters/video/vertexVideoHandler.js");
+        const { validateVideoGenerationInput, validateImageForVideo } = await import("../utils/parameterValidation.js");
+        const { ErrorFactory } = await import("../utils/errorHandling.js");
+        // Build GenerateOptions for validation
+        const generateOptions = {
+            input: options.input || { text: options.prompt || "" },
+            output: options.output,
+            provider: options.provider,
+            model: options.model,
+        };
+        // Validate video generation input
+        const validation = validateVideoGenerationInput(generateOptions);
+        if (!validation.isValid) {
+            throw ErrorFactory.invalidParameters("video-generation", new Error(validation.errors.map((e) => e.message).join("; ")), { errors: validation.errors });
+        }
+        // Log warnings if any
+        if (validation.warnings.length > 0) {
+            for (const warning of validation.warnings) {
+                logger.warn(`Video generation warning: ${warning}`);
+            }
+        }
+        // Extract image from input
+        const imageInput = options.input?.images?.[0];
+        if (!imageInput) {
+            throw new VideoError({
+                code: VIDEO_ERROR_CODES.INVALID_INPUT,
+                message: "Video generation requires an input image. Provide via input.images array.",
+                retriable: false,
+                context: { field: "input.images" },
+            });
+        }
+        // Timeout for image IO operations (15 seconds)
+        const IMAGE_IO_TIMEOUT_MS = 15000;
+        // Load image buffer if path/URL
+        let imageBuffer;
+        if (typeof imageInput === "string") {
+            if (imageInput.startsWith("http://") ||
+                imageInput.startsWith("https://")) {
+                // URL - fetch the image with timeout
+                logger.debug("Fetching image from URL for video generation", {
+                    url: imageInput.substring(0, 100),
+                });
+                let response;
+                try {
+                    response = await this.executeWithTimeout(() => fetch(imageInput), {
+                        timeout: IMAGE_IO_TIMEOUT_MS,
+                        operationType: "generate", // Part of video generation flow
+                    });
+                }
+                catch (error) {
+                    throw new VideoError({
+                        code: VIDEO_ERROR_CODES.INVALID_INPUT,
+                        message: `Failed to fetch image from URL: ${error instanceof Error ? error.message : "Request timed out"}`,
+                        retriable: true,
+                        context: { url: imageInput, timeout: IMAGE_IO_TIMEOUT_MS },
+                        originalError: error instanceof Error ? error : undefined,
+                    });
+                }
+                if (!response.ok) {
+                    throw new VideoError({
+                        code: VIDEO_ERROR_CODES.INVALID_INPUT,
+                        message: `Failed to fetch image from URL: ${response.status} ${response.statusText}`,
+                        retriable: response.status >= 500,
+                        context: { url: imageInput, status: response.status },
+                    });
+                }
+                imageBuffer = Buffer.from(await response.arrayBuffer());
+            }
+            else {
+                // File path - read from disk with timeout
+                logger.debug("Reading image from path for video generation", {
+                    path: imageInput,
+                });
+                const fs = await import("node:fs/promises");
+                try {
+                    imageBuffer = await this.executeWithTimeout(() => fs.readFile(imageInput), { timeout: IMAGE_IO_TIMEOUT_MS, operationType: "generate" });
+                }
+                catch (error) {
+                    throw new VideoError({
+                        code: VIDEO_ERROR_CODES.INVALID_INPUT,
+                        message: `Failed to read image file: ${error instanceof Error ? error.message : String(error)}`,
+                        retriable: false,
+                        context: { path: imageInput, timeout: IMAGE_IO_TIMEOUT_MS },
+                        originalError: error instanceof Error ? error : undefined,
+                    });
+                }
+            }
+        }
+        else if (Buffer.isBuffer(imageInput)) {
+            imageBuffer = imageInput;
+        }
+        else if (typeof imageInput === "object" && "data" in imageInput) {
+            // ImageWithAltText type
+            const imgData = imageInput.data;
+            if (typeof imgData === "string") {
+                imageBuffer = Buffer.from(imgData, "base64");
+            }
+            else if (Buffer.isBuffer(imgData)) {
+                imageBuffer = imgData;
+            }
+            else {
+                throw new VideoError({
+                    code: VIDEO_ERROR_CODES.INVALID_INPUT,
+                    message: "ImageWithAltText.data must be a base64 string or Buffer.",
+                    retriable: false,
+                    context: { field: "input.images[0].data", type: typeof imgData },
+                });
+            }
+        }
+        else {
+            throw new VideoError({
+                code: VIDEO_ERROR_CODES.INVALID_INPUT,
+                message: "Invalid image input type. Provide Buffer, path string, URL, or ImageWithAltText.",
+                retriable: false,
+                context: { field: "input.images[0]", type: typeof imageInput },
+            });
+        }
+        // Validate image format and size (for Buffer inputs)
+        const imageValidation = validateImageForVideo(imageBuffer);
+        if (imageValidation) {
+            throw ErrorFactory.invalidParameters("video-generation", new Error(imageValidation.message), { field: "input.images[0]", validation: imageValidation });
+        }
+        // Get prompt text
+        const prompt = options.prompt || options.input?.text || "";
+        logger.info("Starting video generation", {
+            provider: "vertex",
+            model: options.model || "veo-3.1-generate-001",
+            promptLength: prompt.length,
+            imageSize: imageBuffer.length,
+            resolution: options.output?.video?.resolution || "720p",
+            duration: options.output?.video?.length || 6,
+        });
+        // Generate video using Vertex handler (no processor abstraction)
+        const videoResult = await generateVideoWithVertex(imageBuffer, prompt, options.output?.video);
+        logger.info("Video generation complete", {
+            videoSize: videoResult.data.length,
+            duration: videoResult.metadata?.duration,
+            processingTime: videoResult.metadata?.processingTime,
+        });
+        // Build result
+        const baseResult = {
+            content: prompt, // Echo the prompt as content
+            provider: "vertex",
+            model: options.model || "veo-3.1-generate-001",
+            usage: { input: 0, output: 0, total: 0 },
+            video: videoResult,
+        };
+        return await this.enhanceResult(baseResult, options, startTime);
+    }
     /**
      * Create analytics - delegated to TelemetryHandler
      */

package/dist/index.d.ts

@@ -10,7 +10,7 @@ import { AIProviderFactory } from "./core/factory.js";
 export { AIProviderFactory };
 export type { AIProvider, AIModelProviderConfig, StreamingOptions, ProviderAttempt, SupportedModelName, } from "./types/index.js";
 export type { GenerateOptions, GenerateResult, EnhancedProvider, } from "./types/generateTypes.js";
-export type { ToolContext } from "./sdk/toolRegistration.js";
+export type { ToolContext } from "./types/tools.js";
 export { validateTool } from "./sdk/toolRegistration.js";
 export type { ToolResult, ToolDefinition } from "./types/tools.js";
 export { DEFAULT_PROVIDER_CONFIGS } from "./types/index.js";
@@ -83,8 +83,8 @@ export declare function createBestAIProvider(requestedProvider?: string, modelNa
  * await writeFile('output.txt', 'Hello from MCP!');
  * ```
  */
-export { initializeMCPEcosystem, listMCPs, executeMCP, getMCPStats, mcpLogger, } from "./mcp/index.js";
-export type { McpMetadata, DiscoveredMcp } from "./types/mcpTypes.js";
+export { initializeMCPEcosystem, listMCPs, executeMCP, getMCPStats, mcpLogger, HTTPRateLimiter, RateLimiterManager, globalRateLimiterManager, DEFAULT_RATE_LIMIT_CONFIG, DEFAULT_HTTP_RETRY_CONFIG, isRetryableStatusCode, isRetryableHTTPError, withHTTPRetry, InMemoryTokenStorage, FileTokenStorage, isTokenExpired, calculateExpiresAt, NeuroLinkOAuthProvider, createOAuthProviderFromConfig, MCPCircuitBreaker, CircuitBreakerManager, globalCircuitBreakerManager, } from "./mcp/index.js";
+export type { McpMetadata, DiscoveredMcp, RateLimitConfig, HTTPRetryConfig, OAuthTokens, TokenStorage, MCPOAuthConfig, OAuthClientInformation, AuthorizationUrlResult, TokenExchangeRequest, } from "./types/mcpTypes.js";
 export type { ExecutionContext, ToolInfo, ToolExecutionResult, } from "./types/tools.js";
 export type { LogLevel } from "./types/utilities.js";
 export declare function initializeTelemetry(): Promise<boolean>;

package/dist/index.js

@@ -94,7 +94,13 @@ export async function createBestAIProvider(requestedProvider, modelName) {
 export { 
 // Core MCP ecosystem
 // Simplified MCP exports
-initializeMCPEcosystem, listMCPs, executeMCP, getMCPStats, mcpLogger, } from "./mcp/index.js";
+initializeMCPEcosystem, listMCPs, executeMCP, getMCPStats, mcpLogger, 
+// HTTP Transport utilities
+HTTPRateLimiter, RateLimiterManager, globalRateLimiterManager, DEFAULT_RATE_LIMIT_CONFIG, DEFAULT_HTTP_RETRY_CONFIG, isRetryableStatusCode, isRetryableHTTPError, withHTTPRetry, 
+// OAuth Authentication
+InMemoryTokenStorage, FileTokenStorage, isTokenExpired, calculateExpiresAt, NeuroLinkOAuthProvider, createOAuthProviderFromConfig, 
+// Circuit Breaker
+MCPCircuitBreaker, CircuitBreakerManager, globalCircuitBreakerManager, } from "./mcp/index.js";
 // ============================================================================
 // REAL-TIME SERVICES & TELEMETRY - Enterprise Platform Features
 // ============================================================================

package/dist/lib/adapters/video/vertexVideoHandler.d.ts

@@ -16,8 +16,12 @@ import { NeuroLinkError } from "../../utils/errorHandling.js";
  * Video generation runtime error codes
  *
  * These are for runtime/execution errors during video generation.
- * Input validation errors (missing image, invalid options, etc.) are handled
- * by parameterValidation.ts using ERROR_CODES from errorHandling.ts.
+ * Pure option/shape validation (missing image option, invalid config values, etc.)
+ * is handled by parameterValidation.ts using ERROR_CODES from errorHandling.ts.
+ *
+ * Error categorization:
+ * - INVALID_INPUT → ErrorCategory.execution (runtime I/O failures)
+ * - parameterValidation errors → ErrorCategory.validation (schema/option issues)
  *
  * Following TTS pattern (TTS_ERROR_CODES + TTSError in ttsProcessor.ts)
  */
@@ -28,6 +32,12 @@ export declare const VIDEO_ERROR_CODES: {
     readonly PROVIDER_NOT_CONFIGURED: "VIDEO_PROVIDER_NOT_CONFIGURED";
     /** Polling for video completion timed out */
     readonly POLL_TIMEOUT: "VIDEO_POLL_TIMEOUT";
+    /**
+     * Runtime I/O error during input processing.
+     * Used for: failed URL fetch, failed file read, corrupt/unreadable buffer.
+     * NOT for: missing options or invalid config shapes (use parameterValidation).
+     */
+    readonly INVALID_INPUT: "VIDEO_INVALID_INPUT";
 };
 /**
  * Video generation error class

package/dist/lib/adapters/video/vertexVideoHandler.js

@@ -21,8 +21,12 @@ import { logger } from "../../utils/logger.js";
  * Video generation runtime error codes
  *
  * These are for runtime/execution errors during video generation.
- * Input validation errors (missing image, invalid options, etc.) are handled
- * by parameterValidation.ts using ERROR_CODES from errorHandling.ts.
+ * Pure option/shape validation (missing image option, invalid config values, etc.)
+ * is handled by parameterValidation.ts using ERROR_CODES from errorHandling.ts.
+ *
+ * Error categorization:
+ * - INVALID_INPUT → ErrorCategory.execution (runtime I/O failures)
+ * - parameterValidation errors → ErrorCategory.validation (schema/option issues)
  *
  * Following TTS pattern (TTS_ERROR_CODES + TTSError in ttsProcessor.ts)
  */
@@ -33,6 +37,12 @@ export const VIDEO_ERROR_CODES = {
     PROVIDER_NOT_CONFIGURED: "VIDEO_PROVIDER_NOT_CONFIGURED",
     /** Polling for video completion timed out */
     POLL_TIMEOUT: "VIDEO_POLL_TIMEOUT",
+    /**
+     * Runtime I/O error during input processing.
+     * Used for: failed URL fetch, failed file read, corrupt/unreadable buffer.
+     * NOT for: missing options or invalid config shapes (use parameterValidation).
+     */
+    INVALID_INPUT: "VIDEO_INVALID_INPUT",
 };
 /**
  * Video generation error class

package/dist/lib/core/baseProvider.d.ts

@@ -226,6 +226,25 @@ export declare abstract class BaseProvider implements AIProvider {
      */
     protected normalizeStreamOptions(optionsOrPrompt: StreamOptions | string): StreamOptions;
     protected enhanceResult(result: EnhancedGenerateResult, options: TextGenerationOptions, startTime: number): Promise<EnhancedGenerateResult>;
+    /**
+     * Handle video generation mode
+     *
+     * Generates video from input image + text prompt using Vertex AI Veo 3.1.
+     *
+     * @param options - Text generation options with video configuration
+     * @param startTime - Generation start timestamp for metrics
+     * @returns Enhanced result with video data
+     *
+     * @example
+     * ```typescript
+     * const result = await provider.generate({
+     *   input: { text: "Product showcase", images: [imageBuffer] },
+     *   output: { mode: "video", video: { resolution: "1080p" } }
+     * });
+     * // result.video contains the generated video
+     * ```
+     */
+    private handleVideoGeneration;
     /**
      * Create analytics - delegated to TelemetryHandler
      */

package/dist/lib/core/baseProvider.js

@@ -323,6 +323,11 @@ export class BaseProvider {
         this.validateOptions(options);
         const startTime = Date.now();
         try {
+            // ===== VIDEO GENERATION MODE =====
+            // Generate video from image + prompt using Veo 3.1
+            if (options.output?.mode === "video") {
+                return await this.handleVideoGeneration(options, startTime);
+            }
             // ===== TTS MODE 1: Direct Input Synthesis (useAiResponse=false) =====
             // Synthesize input text directly without AI generation
             // This is optimal for simple read-aloud scenarios
@@ -659,6 +664,175 @@ export class BaseProvider {
         }
         return enhancedResult;
     }
+    /**
+     * Handle video generation mode
+     *
+     * Generates video from input image + text prompt using Vertex AI Veo 3.1.
+     *
+     * @param options - Text generation options with video configuration
+     * @param startTime - Generation start timestamp for metrics
+     * @returns Enhanced result with video data
+     *
+     * @example
+     * ```typescript
+     * const result = await provider.generate({
+     *   input: { text: "Product showcase", images: [imageBuffer] },
+     *   output: { mode: "video", video: { resolution: "1080p" } }
+     * });
+     * // result.video contains the generated video
+     * ```
+     */
+    async handleVideoGeneration(options, startTime) {
+        // Dynamic imports to avoid loading video dependencies unless needed
+        const { generateVideoWithVertex, VideoError, VIDEO_ERROR_CODES } = await import("../adapters/video/vertexVideoHandler.js");
+        const { validateVideoGenerationInput, validateImageForVideo } = await import("../utils/parameterValidation.js");
+        const { ErrorFactory } = await import("../utils/errorHandling.js");
+        // Build GenerateOptions for validation
+        const generateOptions = {
+            input: options.input || { text: options.prompt || "" },
+            output: options.output,
+            provider: options.provider,
+            model: options.model,
+        };
+        // Validate video generation input
+        const validation = validateVideoGenerationInput(generateOptions);
+        if (!validation.isValid) {
+            throw ErrorFactory.invalidParameters("video-generation", new Error(validation.errors.map((e) => e.message).join("; ")), { errors: validation.errors });
+        }
+        // Log warnings if any
+        if (validation.warnings.length > 0) {
+            for (const warning of validation.warnings) {
+                logger.warn(`Video generation warning: ${warning}`);
+            }
+        }
+        // Extract image from input
+        const imageInput = options.input?.images?.[0];
+        if (!imageInput) {
+            throw new VideoError({
+                code: VIDEO_ERROR_CODES.INVALID_INPUT,
+                message: "Video generation requires an input image. Provide via input.images array.",
+                retriable: false,
+                context: { field: "input.images" },
+            });
+        }
+        // Timeout for image IO operations (15 seconds)
+        const IMAGE_IO_TIMEOUT_MS = 15000;
+        // Load image buffer if path/URL
+        let imageBuffer;
+        if (typeof imageInput === "string") {
+            if (imageInput.startsWith("http://") ||
+                imageInput.startsWith("https://")) {
+                // URL - fetch the image with timeout
+                logger.debug("Fetching image from URL for video generation", {
+                    url: imageInput.substring(0, 100),
+                });
+                let response;
+                try {
+                    response = await this.executeWithTimeout(() => fetch(imageInput), {
+                        timeout: IMAGE_IO_TIMEOUT_MS,
+                        operationType: "generate", // Part of video generation flow
+                    });
+                }
+                catch (error) {
+                    throw new VideoError({
+                        code: VIDEO_ERROR_CODES.INVALID_INPUT,
+                        message: `Failed to fetch image from URL: ${error instanceof Error ? error.message : "Request timed out"}`,
+                        retriable: true,
+                        context: { url: imageInput, timeout: IMAGE_IO_TIMEOUT_MS },
+                        originalError: error instanceof Error ? error : undefined,
+                    });
+                }
+                if (!response.ok) {
+                    throw new VideoError({
+                        code: VIDEO_ERROR_CODES.INVALID_INPUT,
+                        message: `Failed to fetch image from URL: ${response.status} ${response.statusText}`,
+                        retriable: response.status >= 500,
+                        context: { url: imageInput, status: response.status },
+                    });
+                }
+                imageBuffer = Buffer.from(await response.arrayBuffer());
+            }
+            else {
+                // File path - read from disk with timeout
+                logger.debug("Reading image from path for video generation", {
+                    path: imageInput,
+                });
+                const fs = await import("node:fs/promises");
+                try {
+                    imageBuffer = await this.executeWithTimeout(() => fs.readFile(imageInput), { timeout: IMAGE_IO_TIMEOUT_MS, operationType: "generate" });
+                }
+                catch (error) {
+                    throw new VideoError({
+                        code: VIDEO_ERROR_CODES.INVALID_INPUT,
+                        message: `Failed to read image file: ${error instanceof Error ? error.message : String(error)}`,
+                        retriable: false,
+                        context: { path: imageInput, timeout: IMAGE_IO_TIMEOUT_MS },
+                        originalError: error instanceof Error ? error : undefined,
+                    });
+                }
+            }
+        }
+        else if (Buffer.isBuffer(imageInput)) {
+            imageBuffer = imageInput;
+        }
+        else if (typeof imageInput === "object" && "data" in imageInput) {
+            // ImageWithAltText type
+            const imgData = imageInput.data;
+            if (typeof imgData === "string") {
+                imageBuffer = Buffer.from(imgData, "base64");
+            }
+            else if (Buffer.isBuffer(imgData)) {
+                imageBuffer = imgData;
+            }
+            else {
+                throw new VideoError({
+                    code: VIDEO_ERROR_CODES.INVALID_INPUT,
+                    message: "ImageWithAltText.data must be a base64 string or Buffer.",
+                    retriable: false,
+                    context: { field: "input.images[0].data", type: typeof imgData },
+                });
+            }
+        }
+        else {
+            throw new VideoError({
+                code: VIDEO_ERROR_CODES.INVALID_INPUT,
+                message: "Invalid image input type. Provide Buffer, path string, URL, or ImageWithAltText.",
+                retriable: false,
+                context: { field: "input.images[0]", type: typeof imageInput },
+            });
+        }
+        // Validate image format and size (for Buffer inputs)
+        const imageValidation = validateImageForVideo(imageBuffer);
+        if (imageValidation) {
+            throw ErrorFactory.invalidParameters("video-generation", new Error(imageValidation.message), { field: "input.images[0]", validation: imageValidation });
+        }
+        // Get prompt text
+        const prompt = options.prompt || options.input?.text || "";
+        logger.info("Starting video generation", {
+            provider: "vertex",
+            model: options.model || "veo-3.1-generate-001",
+            promptLength: prompt.length,
+            imageSize: imageBuffer.length,
+            resolution: options.output?.video?.resolution || "720p",
+            duration: options.output?.video?.length || 6,
+        });
+        // Generate video using Vertex handler (no processor abstraction)
+        const videoResult = await generateVideoWithVertex(imageBuffer, prompt, options.output?.video);
+        logger.info("Video generation complete", {
+            videoSize: videoResult.data.length,
+            duration: videoResult.metadata?.duration,
+            processingTime: videoResult.metadata?.processingTime,
+        });
+        // Build result
+        const baseResult = {
+            content: prompt, // Echo the prompt as content
+            provider: "vertex",
+            model: options.model || "veo-3.1-generate-001",
+            usage: { input: 0, output: 0, total: 0 },
+            video: videoResult,
+        };
+        return await this.enhanceResult(baseResult, options, startTime);
+    }
     /**
      * Create analytics - delegated to TelemetryHandler
      */