@juspay/neurolink 9.64.0 → 9.65.1

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [9.65.1](https://github.com/juspay/neurolink/compare/v9.65.0...v9.65.1) (2026-05-24)
+
+### Bug Fixes
+
+- **(providers):** restore native Vertex tool storage + Claude streaming + Gemini history replay ([7b00e06](https://github.com/juspay/neurolink/commit/7b00e0608a9184e48f3badd90a2238cb330a8128))
+
+## [9.65.0](https://github.com/juspay/neurolink/compare/v9.64.0...v9.65.0) (2026-05-17)
+
+### Features
+
+- **(providers):** add 12 new providers + new modalities (avatar/music/video) + image-gen ([00f88f6](https://github.com/juspay/neurolink/commit/00f88f67161ab170cf2b3b8be3ec683d3cae1c24))
+
 ## [9.64.0](https://github.com/juspay/neurolink/compare/v9.63.1...v9.64.0) (2026-05-16)
 
 ### Features

package/README.md

@@ -40,21 +40,22 @@ Extracted from production systems at Juspay and battle-tested at enterprise scal
 
 ## What's New (Q1 2026)
 
-| Feature                            | Version | Description                                                                                                                                                                    | Guide                                                                                                                                   |
-| ---------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
-| **Multi-Provider Voice (TTS/STT)** | v9.62.0 | 4 TTS providers (OpenAI TTS, ElevenLabs, Google TTS, Azure TTS) + 4 STT providers (Whisper, Deepgram, Azure STT, Google STT) + 2 realtime APIs (OpenAI Realtime, Gemini Live). | [TTS Guide](docs/features/tts.md) \| [STT Guide](docs/features/audio-input.md) \| [Realtime Guide](docs/features/real-time-services.md) |
-| **4 New Providers**                | v9.60.0 | DeepSeek (V3/R1), NVIDIA NIM (400+ catalog), LM Studio (local), llama.cpp (GGUF local).                                                                                        | [Provider Setup](docs/getting-started/provider-setup.md)                                                                                |
-| **ModelAccessDeniedError**         | v9.59.0 | Typed `ModelAccessDeniedError` + `sdk.checkCredentials()` API for proactive credential validation before first call.                                                           | [Error Reference](docs/reference/troubleshooting.md)                                                                                    |
-| **Provider Fallback Policy**       | v9.58.0 | `providerFallback` callback + `modelChain` config for centralized multi-provider fallback logic.                                                                               | [Advanced Guide](docs/advanced/index.md)                                                                                                |
-| **Per-Request Credentials**        | v9.52.0 | Pass credentials per-call or per-instance for all providers. Per-call overrides instance; instance overrides env vars.                                                         | [Credentials Guide](docs/features/per-request-credentials.md)                                                                           |
-| **AutoResearch**                   | v9.53.0 | Autonomous AI experiment engine: proposes code changes, runs experiments, evaluates metrics — unattended for hours.                                                            | [AutoResearch Guide](docs/features/autoresearch.md)                                                                                     |
-| **Gemini 3 Multi-turn Tool Fix**   | v9.49.0 | Fixed multi-step agentic tool calling on Vertex AI Gemini 3. Correct `thoughtSignature` replay, `stepIndex` grouping, `executionId` session isolation, 5-min timeout.          | [Vertex AI Guide](docs/getting-started/providers/google-vertex.md)                                                                      |
-| **MCP Enhancements**               | v9.16.0 | Tool routing (6 strategies), result caching (LRU/FIFO/LFU), request batching, annotations, elicitation protocol, multi-server management.                                      | [MCP Enhancements Guide](docs/features/mcp-enhancements.md)                                                                             |
-| **Memory**                         | v9.12.0 | Per-user condensed memory across conversations. LLM-powered condensation with S3, Redis, or SQLite.                                                                            | [Memory Guide](docs/features/memory.md)                                                                                                 |
-| **Context Window Management**      | v9.2.0  | 4-stage compaction pipeline with budget gate at 80% usage, per-provider token estimation.                                                                                      | [Context Compaction Guide](docs/features/context-compaction.md)                                                                         |
-| **Tool Execution Control**         | v9.3.0  | `prepareStep` and `toolChoice` for per-step tool enforcement in multi-step agentic loops.                                                                                      | [API Reference](docs/api/type-aliases/GenerateOptions.md#preparestep)                                                                   |
-| **File Processor System**          | v9.1.0  | 17+ file type processors with ProcessorRegistry, security sanitization, SVG text injection.                                                                                    | [File Processors Guide](docs/features/file-processors.md)                                                                               |
-| **RAG with generate()/stream()**   | v9.2.0  | Pass `rag: { files }` for automatic document chunking, embedding, and AI-powered search. 10 chunking strategies, hybrid search, reranking.                                     | [RAG Guide](docs/features/rag.md)                                                                                                       |
+| Feature                                      | Version | Description                                                                                                                                                                                                                                                                                                                                                                   | Guide                                                                                                                                   |
+| -------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| **Avatar / Music Modalities + 12 Providers** | next    | New `output: { mode: "avatar" \| "music" }` dispatch with handlers for D-ID, HeyGen, Replicate-MuseTalk (avatar) and Beatoven, ElevenLabs Music, Lyria, Replicate-MusicGen (music). Plus Fish Audio TTS, Kling/Runway/Replicate video, xAI/Groq/Cohere/Together/Fireworks/Perplexity/Cloudflare LLMs, Voyage/Jina embeddings, Stability/Ideogram/Recraft/Replicate image-gen. | [Provider Integration](docs/provider-integration/)                                                                                      |
+| **Multi-Provider Voice (TTS/STT)**           | v9.62.0 | 4 TTS providers (OpenAI TTS, ElevenLabs, Google TTS, Azure TTS) + 4 STT providers (Whisper, Deepgram, Azure STT, Google STT) + 2 realtime APIs (OpenAI Realtime, Gemini Live).                                                                                                                                                                                                | [TTS Guide](docs/features/tts.md) \| [STT Guide](docs/features/audio-input.md) \| [Realtime Guide](docs/features/real-time-services.md) |
+| **4 New Providers**                          | v9.60.0 | DeepSeek (V3/R1), NVIDIA NIM (400+ catalog), LM Studio (local), llama.cpp (GGUF local).                                                                                                                                                                                                                                                                                       | [Provider Setup](docs/getting-started/provider-setup.md)                                                                                |
+| **ModelAccessDeniedError**                   | v9.59.0 | Typed `ModelAccessDeniedError` + `sdk.checkCredentials()` API for proactive credential validation before first call.                                                                                                                                                                                                                                                          | [Error Reference](docs/reference/troubleshooting.md)                                                                                    |
+| **Provider Fallback Policy**                 | v9.58.0 | `providerFallback` callback + `modelChain` config for centralized multi-provider fallback logic.                                                                                                                                                                                                                                                                              | [Advanced Guide](docs/advanced/index.md)                                                                                                |
+| **Per-Request Credentials**                  | v9.52.0 | Pass credentials per-call or per-instance for all providers. Per-call overrides instance; instance overrides env vars.                                                                                                                                                                                                                                                        | [Credentials Guide](docs/features/per-request-credentials.md)                                                                           |
+| **AutoResearch**                             | v9.53.0 | Autonomous AI experiment engine: proposes code changes, runs experiments, evaluates metrics — unattended for hours.                                                                                                                                                                                                                                                           | [AutoResearch Guide](docs/features/autoresearch.md)                                                                                     |
+| **Gemini 3 Multi-turn Tool Fix**             | v9.49.0 | Fixed multi-step agentic tool calling on Vertex AI Gemini 3. Correct `thoughtSignature` replay, `stepIndex` grouping, `executionId` session isolation, 5-min timeout.                                                                                                                                                                                                         | [Vertex AI Guide](docs/getting-started/providers/google-vertex.md)                                                                      |
+| **MCP Enhancements**                         | v9.16.0 | Tool routing (6 strategies), result caching (LRU/FIFO/LFU), request batching, annotations, elicitation protocol, multi-server management.                                                                                                                                                                                                                                     | [MCP Enhancements Guide](docs/features/mcp-enhancements.md)                                                                             |
+| **Memory**                                   | v9.12.0 | Per-user condensed memory across conversations. LLM-powered condensation with S3, Redis, or SQLite.                                                                                                                                                                                                                                                                           | [Memory Guide](docs/features/memory.md)                                                                                                 |
+| **Context Window Management**                | v9.2.0  | 4-stage compaction pipeline with budget gate at 80% usage, per-provider token estimation.                                                                                                                                                                                                                                                                                     | [Context Compaction Guide](docs/features/context-compaction.md)                                                                         |
+| **Tool Execution Control**                   | v9.3.0  | `prepareStep` and `toolChoice` for per-step tool enforcement in multi-step agentic loops.                                                                                                                                                                                                                                                                                     | [API Reference](docs/api/type-aliases/GenerateOptions.md#preparestep)                                                                   |
+| **File Processor System**                    | v9.1.0  | 17+ file type processors with ProcessorRegistry, security sanitization, SVG text injection.                                                                                                                                                                                                                                                                                   | [File Processors Guide](docs/features/file-processors.md)                                                                               |
+| **RAG with generate()/stream()**             | v9.2.0  | Pass `rag: { files }` for automatic document chunking, embedding, and AI-powered search. 10 chunking strategies, hybrid search, reranking.                                                                                                                                                                                                                                    | [RAG Guide](docs/features/rag.md)                                                                                                       |
 
 ```typescript
 // Multi-Provider Voice (v9.62.0) — TTS + STT
@@ -406,7 +407,7 @@ const result = await neurolink.generate({
 ### Next Steps
 
 - **[Complete Documentation](https://docs.neurolink.ink)** - Comprehensive guides and API reference
-- **[Provider Setup Guide](docs/getting-started/provider-setup.md)** - Configure all 21+ providers
+- **[Provider Setup Guide](docs/getting-started/provider-setup.md)** - Configure all 33+ providers
 - **[SDK API Reference](docs/sdk/api-reference.md)** - Full TypeScript API documentation
 - **[CLI Command Reference](docs/cli/commands.md)** - Complete CLI documentation
 - **[Example Projects](docs/examples/index.md)** - Real-world integration examples
@@ -438,7 +439,7 @@ NeuroLink is a comprehensive AI development platform. Every feature below is pro
 
 ### 🤖 AI Provider Integration
 
-**21+ providers unified under one API** - Switch providers with a single parameter change.
+**33+ providers unified under one API** - Switch providers with a single parameter change.
 
 | Provider              | Models                                                                     | Free Tier       | Tool Support | Status        | Documentation                                                                                                                 |
 | --------------------- | -------------------------------------------------------------------------- | --------------- | ------------ | ------------- | ----------------------------------------------------------------------------------------------------------------------------- |

package/dist/adapters/providerImageAdapter.js

@@ -281,7 +281,7 @@ const VISION_CAPABILITIES = {
     openrouter: [
         // OpenRouter provides access to vision-capable models from multiple providers
         // Anthropic Claude models (via OpenRouter)
-        "anthropic/claude-3-5-sonnet",
+        "anthropic/claude-3.7-sonnet",
         "anthropic/claude-3-5-haiku",
         "anthropic/claude-3-opus",
         "anthropic/claude-3-sonnet",
@@ -474,6 +474,34 @@ const VISION_CAPABILITIES = {
         "qwen2-vl",
         "phi-3-vision",
     ],
+    // xAI: only grok-2-vision is multimodal today
+    xai: ["grok-2-vision-latest"],
+    // Groq: vision models are explicit "*-vision-preview" variants
+    groq: ["llama-3.2-90b-vision-preview", "llama-3.2-11b-vision-preview"],
+    // Cohere: command-r* are text-only (no vision); empty list
+    cohere: [],
+    // Together AI: text-only by default; add vision variants if/when used.
+    "together-ai": [],
+    // Fireworks: vision via Phi-3-Vision and Llama 3.2 vision variants.
+    fireworks: [
+        "accounts/fireworks/models/phi-3-vision-128k-instruct",
+        "accounts/fireworks/models/llama-v3p2-90b-vision-instruct",
+        "accounts/fireworks/models/llama-v3p2-11b-vision-instruct",
+    ],
+    // Perplexity Sonar — text-only with web grounding.
+    perplexity: [],
+    // Cloudflare: explicit vision variants only.
+    cloudflare: ["@cf/meta/llama-3.2-11b-vision-instruct"],
+    // Replicate: vision capability depends on the specific model id.
+    replicate: ["llava", "llama-3.2-vision", "moondream", "qwen2-vl"],
+    // Voyage / Jina — embedding-only, not multimodal in this sense.
+    voyage: [],
+    jina: [],
+    // Stability / Ideogram / Recraft — image-OUTPUT, not image-INPUT.
+    // VISION_CAPABILITIES tracks reference-image input support.
+    stability: [],
+    ideogram: [],
+    recraft: [],
 };
 /**
  * Provider Image Adapter - Smart routing and formatting

package/dist/adapters/replicate/auth.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Replicate Auth Helper
+ *
+ * Resolves the Replicate API token + base URL from per-call overrides,
+ * instance credentials, or env vars. Used by every Replicate-backed
+ * handler (LLM, video, avatar, music) so the auth chain is centralised.
+ *
+ * @module adapters/replicate/auth
+ */
+import type { ReplicateAuth } from "../../types/index.js";
+/**
+ * Resolve Replicate auth from override → env vars.
+ *
+ * Returns `null` when `REPLICATE_API_TOKEN` is missing AND no override is
+ * provided. Handlers' `isConfigured()` check `auth !== null`.
+ *
+ * @param override - per-call or instance-level credentials slice
+ */
+export declare function getReplicateAuth(override?: Partial<ReplicateAuth>): ReplicateAuth | null;

package/dist/adapters/replicate/auth.js

@@ -0,0 +1,32 @@
+/**
+ * Replicate Auth Helper
+ *
+ * Resolves the Replicate API token + base URL from per-call overrides,
+ * instance credentials, or env vars. Used by every Replicate-backed
+ * handler (LLM, video, avatar, music) so the auth chain is centralised.
+ *
+ * @module adapters/replicate/auth
+ */
+const DEFAULT_BASE_URL = "https://api.replicate.com";
+/**
+ * Resolve Replicate auth from override → env vars.
+ *
+ * Returns `null` when `REPLICATE_API_TOKEN` is missing AND no override is
+ * provided. Handlers' `isConfigured()` check `auth !== null`.
+ *
+ * @param override - per-call or instance-level credentials slice
+ */
+export function getReplicateAuth(override) {
+    const apiToken = (override?.apiToken ??
+        process.env.REPLICATE_API_TOKEN ??
+        "").trim();
+    if (!apiToken) {
+        return null;
+    }
+    return {
+        apiToken,
+        baseUrl: (override?.baseUrl ??
+            process.env.REPLICATE_BASE_URL ??
+            DEFAULT_BASE_URL).replace(/\/$/, ""),
+    };
+}

package/dist/adapters/replicate/predictionLifecycle.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Replicate Prediction Lifecycle
+ *
+ * Shared async-job helpers used by every Replicate-backed handler. Submits
+ * a prediction, polls until terminal status, downloads the binary output.
+ *
+ * Usage pattern (for handlers — LLM, video, avatar, music):
+ *
+ *   const auth = getReplicateAuth(credentials);
+ *   if (!auth) throw new XxxError({ code: PROVIDER_NOT_CONFIGURED, ... });
+ *   const prediction = await predict(auth, { model, input });
+ *   const buffer = await downloadPredictionOutput(prediction);
+ *
+ * @module adapters/replicate/predictionLifecycle
+ */
+import type { ReplicateAuth, ReplicateCreatePredictionInput, ReplicatePollOptions, ReplicatePrediction } from "../../types/index.js";
+/**
+ * Submit a Replicate prediction. Uses `Prefer: wait=60` so quick
+ * predictions complete in the initial POST and skip polling entirely.
+ */
+export declare function createPrediction(auth: ReplicateAuth, input: ReplicateCreatePredictionInput): Promise<ReplicatePrediction>;
+/**
+ * Poll a Replicate prediction until it reaches a terminal status
+ * (succeeded / failed / canceled) or the total timeout elapses.
+ */
+export declare function pollPrediction(auth: ReplicateAuth, predictionId: string, options?: ReplicatePollOptions): Promise<ReplicatePrediction>;
+/**
+ * Submit + poll. Combines `createPrediction` + `pollPrediction`.
+ *
+ * Uses `Prefer: wait=60` in the submit call so short jobs complete in the
+ * initial POST and bypass polling entirely.
+ */
+export declare function predict(auth: ReplicateAuth, input: ReplicateCreatePredictionInput, options?: ReplicatePollOptions): Promise<ReplicatePrediction>;
+/**
+ * Download a Replicate prediction's binary output.
+ *
+ * Replicate models return either a single URL string or an array of URL
+ * strings (multi-output models). For models that return base64 directly,
+ * use a model-specific helper instead.
+ *
+ * @param prediction  The completed prediction to download.
+ * @param maxBytes    Maximum bytes allowed. Defaults to {@link MAX_VIDEO_BYTES}
+ *                    (256 MiB). Pass {@link MAX_AUDIO_BYTES} for music/TTS
+ *                    outputs or {@link MAX_IMAGE_BYTES} for image outputs.
+ */
+export declare function downloadPredictionOutput(prediction: ReplicatePrediction, maxBytes?: number): Promise<Buffer>;

package/dist/adapters/replicate/predictionLifecycle.js

@@ -0,0 +1,283 @@
+/**
+ * Replicate Prediction Lifecycle
+ *
+ * Shared async-job helpers used by every Replicate-backed handler. Submits
+ * a prediction, polls until terminal status, downloads the binary output.
+ *
+ * Usage pattern (for handlers — LLM, video, avatar, music):
+ *
+ *   const auth = getReplicateAuth(credentials);
+ *   if (!auth) throw new XxxError({ code: PROVIDER_NOT_CONFIGURED, ... });
+ *   const prediction = await predict(auth, { model, input });
+ *   const buffer = await downloadPredictionOutput(prediction);
+ *
+ * @module adapters/replicate/predictionLifecycle
+ */
+import { ErrorCategory, ErrorSeverity } from "../../constants/enums.js";
+import { logger } from "../../utils/logger.js";
+import { NeuroLinkError, ERROR_CODES } from "../../utils/errorHandling.js";
+import { sanitizeForLog } from "../../utils/logSanitize.js";
+import { safeDownload } from "../../utils/safeFetch.js";
+import { MAX_VIDEO_BYTES } from "../../utils/sizeGuard.js";
+// The submit path sends `Prefer: wait=60`, so Replicate can legitimately
+// hold the connection for up to 60s while the prediction warms / runs.
+// A 30s client-side timeout aborts in the middle of that window and
+// produces spurious "submit timed out" errors on cold models (e.g. the
+// MusicGen ones). Bump to 90s to cover the server window plus headroom.
+const REQUEST_TIMEOUT_MS = 90_000;
+const DEFAULT_POLL_INTERVAL_MS = 2_000;
+const DEFAULT_TOTAL_TIMEOUT_MS = 5 * 60_000;
+/**
+ * Submit a Replicate prediction. Uses `Prefer: wait=60` so quick
+ * predictions complete in the initial POST and skip polling entirely.
+ */
+export async function createPrediction(auth, input) {
+    const baseUrl = auth.baseUrl ?? "https://api.replicate.com";
+    const [modelPath, version] = input.model.split(":", 2);
+    const endpoint = version
+        ? `${baseUrl}/v1/predictions`
+        : `${baseUrl}/v1/models/${modelPath}/predictions`;
+    const body = version
+        ? { version, input: input.input }
+        : { input: input.input };
+    if (input.webhook) {
+        body.webhook = input.webhook;
+    }
+    if (input.webhookEventsFilter && input.webhookEventsFilter.length > 0) {
+        body.webhook_events_filter = input.webhookEventsFilter;
+    }
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+    let response;
+    try {
+        response = await fetch(endpoint, {
+            method: "POST",
+            headers: {
+                Authorization: `Token ${auth.apiToken}`,
+                "Content-Type": "application/json",
+                Prefer: "wait=60",
+            },
+            body: JSON.stringify(body),
+            signal: controller.signal,
+        });
+    }
+    catch (err) {
+        if (err instanceof NeuroLinkError) {
+            throw err;
+        }
+        if (err instanceof Error && err.name === "AbortError") {
+            throw new NeuroLinkError({
+                code: ERROR_CODES.OPERATION_ABORTED,
+                message: `Replicate predictions submit timed out after ${REQUEST_TIMEOUT_MS / 1000}s`,
+                category: ErrorCategory.TIMEOUT,
+                severity: ErrorSeverity.HIGH,
+                retriable: true,
+                originalError: err,
+            });
+        }
+        throw err;
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+    if (!response.ok) {
+        const raw = await response.text();
+        throw new NeuroLinkError({
+            code: ERROR_CODES.PROVIDER_NOT_AVAILABLE,
+            message: `Replicate predictions submit failed: ${response.status} — ${sanitizeForLog(raw, 500)}`,
+            category: ErrorCategory.NETWORK,
+            severity: ErrorSeverity.HIGH,
+            retriable: response.status >= 500,
+        });
+    }
+    return (await response.json());
+}
+/**
+ * Poll a Replicate prediction until it reaches a terminal status
+ * (succeeded / failed / canceled) or the total timeout elapses.
+ */
+export async function pollPrediction(auth, predictionId, options = {}) {
+    const baseUrl = auth.baseUrl ?? "https://api.replicate.com";
+    const startTime = Date.now();
+    const totalTimeout = options.timeoutMs ?? DEFAULT_TOTAL_TIMEOUT_MS;
+    const pollInterval = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    while (Date.now() - startTime < totalTimeout) {
+        if (options.abortSignal?.aborted) {
+            throw new NeuroLinkError({
+                code: ERROR_CODES.OPERATION_ABORTED,
+                message: "Replicate poll aborted by caller",
+                category: ErrorCategory.ABORT,
+                severity: ErrorSeverity.LOW,
+                retriable: false,
+            });
+        }
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+        // Forward caller abort into the in-flight fetch request.
+        const onCallerAbort = () => controller.abort();
+        options.abortSignal?.addEventListener("abort", onCallerAbort, {
+            once: true,
+        });
+        let response;
+        try {
+            response = await fetch(`${baseUrl}/v1/predictions/${predictionId}`, {
+                method: "GET",
+                headers: { Authorization: `Token ${auth.apiToken}` },
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            if (err instanceof NeuroLinkError) {
+                throw err;
+            }
+            if (err instanceof Error && err.name === "AbortError") {
+                // Distinguish caller abort from internal timeout abort.
+                if (options.abortSignal?.aborted) {
+                    throw new NeuroLinkError({
+                        code: ERROR_CODES.OPERATION_ABORTED,
+                        message: "Replicate poll aborted by caller",
+                        category: ErrorCategory.ABORT,
+                        severity: ErrorSeverity.LOW,
+                        retriable: false,
+                        originalError: err,
+                    });
+                }
+                throw new NeuroLinkError({
+                    code: ERROR_CODES.OPERATION_ABORTED,
+                    message: `Replicate poll request timed out after ${REQUEST_TIMEOUT_MS / 1000}s`,
+                    category: ErrorCategory.TIMEOUT,
+                    severity: ErrorSeverity.HIGH,
+                    retriable: true,
+                    originalError: err,
+                });
+            }
+            throw err;
+        }
+        finally {
+            options.abortSignal?.removeEventListener("abort", onCallerAbort);
+            clearTimeout(timeoutId);
+        }
+        if (!response.ok) {
+            const raw = await response.text();
+            throw new NeuroLinkError({
+                code: ERROR_CODES.PROVIDER_NOT_AVAILABLE,
+                message: `Replicate poll failed: ${response.status} — ${sanitizeForLog(raw, 500)}`,
+                category: ErrorCategory.NETWORK,
+                severity: ErrorSeverity.HIGH,
+                retriable: response.status >= 500,
+            });
+        }
+        const pred = (await response.json());
+        if (pred.status === "succeeded") {
+            return pred;
+        }
+        if (pred.status === "failed" || pred.status === "canceled") {
+            throw new NeuroLinkError({
+                code: ERROR_CODES.PROVIDER_NOT_AVAILABLE,
+                message: `Replicate prediction ${pred.id} ${pred.status}: ${pred.error ?? "unknown"}`,
+                category: ErrorCategory.EXECUTION,
+                severity: ErrorSeverity.HIGH,
+                retriable: pred.status === "failed",
+            });
+        }
+        // Abortable sleep: resolves after pollInterval but rejects immediately
+        // if the caller's AbortSignal fires, preventing up to pollInterval ms
+        // of unnecessary blocking.
+        await new Promise((resolve, reject) => {
+            const onAbort = () => {
+                clearTimeout(timer);
+                reject(new NeuroLinkError({
+                    code: ERROR_CODES.OPERATION_ABORTED,
+                    message: "Replicate poll aborted by caller",
+                    category: ErrorCategory.ABORT,
+                    severity: ErrorSeverity.LOW,
+                    retriable: false,
+                }));
+            };
+            const timer = setTimeout(() => {
+                // Remove the abort listener when the timer fires normally so stale
+                // listeners do not accumulate across many poll iterations.
+                options.abortSignal?.removeEventListener("abort", onAbort);
+                resolve();
+            }, pollInterval);
+            options.abortSignal?.addEventListener("abort", onAbort, { once: true });
+        });
+    }
+    throw new NeuroLinkError({
+        code: ERROR_CODES.OPERATION_ABORTED,
+        message: `Replicate prediction ${predictionId} did not complete within ${Math.round(totalTimeout / 1000)}s`,
+        category: ErrorCategory.TIMEOUT,
+        severity: ErrorSeverity.HIGH,
+        retriable: true,
+    });
+}
+/**
+ * Submit + poll. Combines `createPrediction` + `pollPrediction`.
+ *
+ * Uses `Prefer: wait=60` in the submit call so short jobs complete in the
+ * initial POST and bypass polling entirely.
+ */
+export async function predict(auth, input, options = {}) {
+    const submitted = await createPrediction(auth, input);
+    if (submitted.status === "succeeded") {
+        return submitted;
+    }
+    if (submitted.status === "failed" || submitted.status === "canceled") {
+        throw new NeuroLinkError({
+            code: ERROR_CODES.PROVIDER_NOT_AVAILABLE,
+            message: `Replicate prediction ${submitted.id} ${submitted.status} on submit: ${submitted.error ?? "unknown"}`,
+            category: ErrorCategory.EXECUTION,
+            severity: ErrorSeverity.HIGH,
+            retriable: submitted.status === "failed",
+        });
+    }
+    return pollPrediction(auth, submitted.id, options);
+}
+/**
+ * Download a Replicate prediction's binary output.
+ *
+ * Replicate models return either a single URL string or an array of URL
+ * strings (multi-output models). For models that return base64 directly,
+ * use a model-specific helper instead.
+ *
+ * @param prediction  The completed prediction to download.
+ * @param maxBytes    Maximum bytes allowed. Defaults to {@link MAX_VIDEO_BYTES}
+ *                    (256 MiB). Pass {@link MAX_AUDIO_BYTES} for music/TTS
+ *                    outputs or {@link MAX_IMAGE_BYTES} for image outputs.
+ */
+export async function downloadPredictionOutput(prediction, maxBytes = MAX_VIDEO_BYTES) {
+    const output = prediction.output;
+    const url = Array.isArray(output) ? output[0] : output;
+    if (typeof url !== "string") {
+        throw new NeuroLinkError({
+            code: ERROR_CODES.PROVIDER_NOT_AVAILABLE,
+            message: `Replicate prediction ${prediction.id} output is not a URL: ${typeof output}`,
+            category: ErrorCategory.EXECUTION,
+            severity: ErrorSeverity.HIGH,
+            retriable: false,
+        });
+    }
+    try {
+        const buffer = await safeDownload(url, {
+            maxBytes,
+            label: `Replicate prediction ${prediction.id}`,
+            timeoutMs: REQUEST_TIMEOUT_MS,
+        });
+        logger.debug(`[Replicate] Downloaded prediction ${prediction.id} output: ${buffer.length} bytes`);
+        return buffer;
+    }
+    catch (err) {
+        if (err instanceof NeuroLinkError) {
+            throw err;
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        throw new NeuroLinkError({
+            code: ERROR_CODES.PROVIDER_NOT_AVAILABLE,
+            message: `Replicate output download failed: ${message} — ${url}`,
+            category: ErrorCategory.NETWORK,
+            severity: ErrorSeverity.HIGH,
+            retriable: true,
+            originalError: err instanceof Error ? err : undefined,
+        });
+    }
+}

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

@@ -0,0 +1,37 @@
+/**
+ * Kling Video Handler (PiAPI)
+ *
+ * Image-to-video generation via PiAPI's Kling endpoint. Async job model:
+ * POST /image-to-video → poll /task/{id} until completed.
+ *
+ * NOTE: PiAPI Kling requires a publicly accessible image URL, not inline
+ * base64 data. Callers must supply `options.imageUrl` (a URL string) when
+ * using KlingVideoHandler. The `image` Buffer parameter is still accepted
+ * for interface compatibility (e.g., metadata / downstream use) but is not
+ * sent to the API. A clear error is thrown if no URL is provided.
+ *
+ * @module adapters/video/klingVideoHandler
+ * @see https://piapi.ai/docs/kling-api
+ */
+import type { VideoGenerationResult, VideoHandler, VideoOutputOptions } from "../../types/index.js";
+/**
+ * Kling Video Handler.
+ *
+ * Auth: `Authorization: Bearer ${KLING_API_KEY}` (PiAPI / Kling key).
+ * Models: kling-1.6-i2v (default), kling-1.5-i2v, kling-1.0.
+ */
+export declare class KlingVideoHandler implements VideoHandler {
+    readonly maxDurationSeconds = 10;
+    readonly supportedAspectRatios: readonly ("9:16" | "16:9" | "1:1")[];
+    readonly supportedResolutions: readonly ("720p" | "1080p")[];
+    private readonly apiKey;
+    private readonly baseUrl;
+    constructor(apiKey?: string);
+    isConfigured(): boolean;
+    generate(image: Buffer, prompt: string, options: VideoOutputOptions): Promise<VideoGenerationResult>;
+    private submitJob;
+    private pollUntilComplete;
+    private downloadVideo;
+    private fetchWithTimeout;
+    private calculateDimensions;
+}