@juspay/neurolink 9.64.0 → 9.65.1

package/dist/adapters/video/runwayVideoHandler.js

@@ -0,0 +1,316 @@
+/**
+ * Runway Video Handler (Gen-3 Alpha / Gen-4 Turbo)
+ *
+ * Async generation: POST /v1/image_to_video → poll /v1/tasks/{id}.
+ *
+ * @module adapters/video/runwayVideoHandler
+ * @see https://docs.dev.runwayml.com/api/
+ */
+import { ErrorCategory, ErrorSeverity } from "../../constants/enums.js";
+import { VIDEO_ERROR_CODES } from "../../constants/videoErrors.js";
+import { logger } from "../../utils/logger.js";
+import { sanitizeForLog } from "../../utils/logSanitize.js";
+import { safeDownload } from "../../utils/safeFetch.js";
+import { VideoError } from "../../utils/videoProcessor.js";
+import { MAX_VIDEO_BYTES } from "../../utils/sizeGuard.js";
+const DEFAULT_BASE_URL = "https://api.dev.runwayml.com/v1";
+const REQUEST_TIMEOUT_MS = 30_000;
+const POLL_INTERVAL_MS = 5_000;
+const TOTAL_TIMEOUT_MS = 5 * 60_000;
+/**
+ * Runway Video Handler.
+ *
+ * Auth: `Authorization: Bearer ${RUNWAY_API_KEY}` + `X-Runway-Version`
+ * header. Models: gen3a_turbo (Gen-3 Alpha Turbo, default), gen4_turbo.
+ */
+export class RunwayVideoHandler {
+    maxDurationSeconds = 10;
+    supportedAspectRatios = [
+        "16:9",
+        "9:16",
+    ];
+    supportedResolutions = [
+        "720p",
+        "1080p",
+    ];
+    apiKey;
+    baseUrl;
+    apiVersion;
+    constructor(apiKey) {
+        const resolved = (apiKey ?? process.env.RUNWAY_API_KEY ?? "").trim();
+        this.apiKey = resolved.length > 0 ? resolved : null;
+        this.baseUrl = (process.env.RUNWAY_BASE_URL ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+        this.apiVersion = process.env.RUNWAY_API_VERSION ?? "2024-11-06";
+    }
+    isConfigured() {
+        return this.apiKey !== null;
+    }
+    async generate(image, prompt, options) {
+        if (!this.apiKey) {
+            throw new VideoError({
+                code: VIDEO_ERROR_CODES.PROVIDER_NOT_CONFIGURED,
+                message: "RUNWAY_API_KEY not configured",
+                category: ErrorCategory.CONFIGURATION,
+                severity: ErrorSeverity.HIGH,
+                retriable: false,
+            });
+        }
+        if (options.aspectRatio !== undefined &&
+            !this.supportedAspectRatios.includes(options.aspectRatio)) {
+            throw new VideoError({
+                code: VIDEO_ERROR_CODES.INVALID_INPUT,
+                message: `Unsupported aspect ratio for Runway: "${options.aspectRatio}". Supported: ${this.supportedAspectRatios.join(", ")}.`,
+                category: ErrorCategory.VALIDATION,
+                severity: ErrorSeverity.MEDIUM,
+                retriable: false,
+                context: {
+                    requested: options.aspectRatio,
+                    supported: this.supportedAspectRatios,
+                },
+            });
+        }
+        const startTime = Date.now();
+        const abortSignal = options.abortSignal;
+        const taskId = await this.submitTask(image, prompt, options);
+        const videoUrl = await this.pollUntilComplete(taskId, abortSignal);
+        const buffer = await this.downloadVideo(videoUrl);
+        const processingTime = Date.now() - startTime;
+        logger.info(`[RunwayVideoHandler] Generated ${buffer.length} bytes in ${processingTime}ms — task ${taskId}`);
+        return {
+            data: buffer,
+            mediaType: "video/mp4",
+            metadata: {
+                duration: options.length ?? 4,
+                dimensions: this.calculateDimensions(options),
+                model: options.model ?? "gen3a_turbo",
+                provider: "runway",
+                aspectRatio: options.aspectRatio ?? "16:9",
+                audioEnabled: false,
+                processingTime,
+            },
+        };
+    }
+    async submitTask(image, prompt, options) {
+        const dataUri = `data:image/${this.detectImageType(image)};base64,${image.toString("base64")}`;
+        const body = {
+            model: options.model ?? "gen3a_turbo",
+            promptImage: dataUri,
+            promptText: prompt,
+            duration: options.length ?? 4,
+            ratio: options.aspectRatio === "9:16" ? "9:16" : "16:9",
+            seed: undefined,
+        };
+        const response = await this.fetchWithTimeout(`${this.baseUrl}/image_to_video`, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${this.apiKey}`,
+                "Content-Type": "application/json",
+                "X-Runway-Version": this.apiVersion,
+            },
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            const raw = await response.text();
+            const retriable = response.status === 408 ||
+                response.status === 429 ||
+                response.status >= 500;
+            throw new VideoError({
+                code: VIDEO_ERROR_CODES.GENERATION_FAILED,
+                message: `Runway submit failed: ${response.status} — ${sanitizeForLog(raw, 500)}`,
+                category: retriable ? ErrorCategory.NETWORK : ErrorCategory.EXECUTION,
+                severity: ErrorSeverity.HIGH,
+                retriable,
+                context: { status: response.status },
+            });
+        }
+        const json = (await response.json());
+        if (!json.id) {
+            throw new VideoError({
+                code: VIDEO_ERROR_CODES.GENERATION_FAILED,
+                message: "Runway submit response missing id",
+                category: ErrorCategory.EXECUTION,
+                severity: ErrorSeverity.HIGH,
+                retriable: false,
+                context: { response: json },
+            });
+        }
+        return json.id;
+    }
+    async pollUntilComplete(taskId, abortSignal) {
+        const startTime = Date.now();
+        while (Date.now() - startTime < TOTAL_TIMEOUT_MS) {
+            if (abortSignal?.aborted) {
+                throw new VideoError({
+                    code: VIDEO_ERROR_CODES.GENERATION_FAILED,
+                    message: `Runway poll for task ${taskId} aborted by caller`,
+                    category: ErrorCategory.NETWORK,
+                    severity: ErrorSeverity.MEDIUM,
+                    retriable: false,
+                    context: { taskId },
+                });
+            }
+            const response = await this.fetchWithTimeout(`${this.baseUrl}/tasks/${taskId}`, {
+                method: "GET",
+                headers: {
+                    Authorization: `Bearer ${this.apiKey}`,
+                    "X-Runway-Version": this.apiVersion,
+                },
+            }, abortSignal);
+            if (!response.ok) {
+                const raw = await response.text();
+                throw new VideoError({
+                    code: VIDEO_ERROR_CODES.GENERATION_FAILED,
+                    message: `Runway poll failed: ${response.status} — ${sanitizeForLog(raw, 500)}`,
+                    category: ErrorCategory.NETWORK,
+                    severity: ErrorSeverity.MEDIUM,
+                    retriable: response.status >= 500,
+                });
+            }
+            const data = (await response.json());
+            if (data.status === "SUCCEEDED" || data.status === "succeeded") {
+                const url = Array.isArray(data.output) ? data.output[0] : data.output;
+                if (typeof url !== "string") {
+                    throw new VideoError({
+                        code: VIDEO_ERROR_CODES.GENERATION_FAILED,
+                        message: `Runway task ${taskId} completed but no output URL`,
+                        category: ErrorCategory.EXECUTION,
+                        severity: ErrorSeverity.HIGH,
+                        retriable: false,
+                        context: { taskId, data },
+                    });
+                }
+                return url;
+            }
+            if (data.status === "FAILED" || data.status === "failed") {
+                throw new VideoError({
+                    code: VIDEO_ERROR_CODES.GENERATION_FAILED,
+                    message: `Runway task ${taskId} failed: ${data.failure ?? data.error ?? "unknown"}`,
+                    category: ErrorCategory.EXECUTION,
+                    severity: ErrorSeverity.HIGH,
+                    retriable: false,
+                    context: { taskId, data },
+                });
+            }
+            // Abortable sleep.
+            await new Promise((resolve, reject) => {
+                const onAbort = () => {
+                    clearTimeout(timer);
+                    reject(new VideoError({
+                        code: VIDEO_ERROR_CODES.GENERATION_FAILED,
+                        message: `Runway poll for task ${taskId} aborted by caller`,
+                        category: ErrorCategory.NETWORK,
+                        severity: ErrorSeverity.MEDIUM,
+                        retriable: false,
+                        context: { taskId },
+                    }));
+                };
+                const timer = setTimeout(() => {
+                    abortSignal?.removeEventListener("abort", onAbort);
+                    resolve();
+                }, POLL_INTERVAL_MS);
+                abortSignal?.addEventListener("abort", onAbort, { once: true });
+            });
+        }
+        throw new VideoError({
+            code: VIDEO_ERROR_CODES.POLL_TIMEOUT,
+            message: `Runway task ${taskId} did not complete within ${TOTAL_TIMEOUT_MS / 1000}s`,
+            category: ErrorCategory.TIMEOUT,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: true,
+            context: { taskId },
+        });
+    }
+    async downloadVideo(url) {
+        try {
+            return await safeDownload(url, {
+                maxBytes: MAX_VIDEO_BYTES,
+                label: "Runway video",
+                timeoutMs: REQUEST_TIMEOUT_MS,
+            });
+        }
+        catch (err) {
+            throw new VideoError({
+                code: VIDEO_ERROR_CODES.GENERATION_FAILED,
+                message: `Runway video download rejected: ${err instanceof Error ? err.message : String(err)}`,
+                category: ErrorCategory.NETWORK,
+                severity: ErrorSeverity.HIGH,
+                retriable: false,
+                context: { url },
+                originalError: err instanceof Error ? err : undefined,
+            });
+        }
+    }
+    async fetchWithTimeout(url, init, callerAbortSignal) {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+        const onCallerAbort = () => controller.abort();
+        callerAbortSignal?.addEventListener("abort", onCallerAbort, { once: true });
+        try {
+            return await fetch(url, { ...init, signal: controller.signal });
+        }
+        catch (err) {
+            if (err instanceof Error && err.name === "AbortError") {
+                throw new VideoError({
+                    code: VIDEO_ERROR_CODES.GENERATION_FAILED,
+                    message: `Runway request to ${url} timed out after ${REQUEST_TIMEOUT_MS / 1000}s`,
+                    category: ErrorCategory.NETWORK,
+                    severity: ErrorSeverity.HIGH,
+                    retriable: true,
+                    originalError: err,
+                });
+            }
+            throw new VideoError({
+                code: VIDEO_ERROR_CODES.GENERATION_FAILED,
+                message: `Runway fetch failed: ${err instanceof Error ? err.message : String(err)}`,
+                category: ErrorCategory.NETWORK,
+                severity: ErrorSeverity.HIGH,
+                retriable: true,
+                originalError: err instanceof Error ? err : undefined,
+            });
+        }
+        finally {
+            callerAbortSignal?.removeEventListener("abort", onCallerAbort);
+            clearTimeout(timeoutId);
+        }
+    }
+    detectImageType(buffer) {
+        if (buffer.length < 4) {
+            return "jpeg";
+        }
+        if (buffer[0] === 0x89 && buffer[1] === 0x50) {
+            return "png";
+        }
+        if (buffer[0] === 0xff && buffer[1] === 0xd8) {
+            return "jpeg";
+        }
+        // RIFF container: check offset 8 to distinguish WebP from WAV so audio
+        // data passed as image is not silently misidentified as WebP.
+        if (buffer.length >= 12 &&
+            buffer[0] === 0x52 &&
+            buffer[1] === 0x49 &&
+            buffer[2] === 0x46 &&
+            buffer[3] === 0x46) {
+            if (buffer[8] === 0x57 &&
+                buffer[9] === 0x45 &&
+                buffer[10] === 0x42 &&
+                buffer[11] === 0x50) {
+                return "webp";
+            }
+            // RIFF but not WEBP (e.g. WAVE audio) — not a valid image.
+            return "jpeg";
+        }
+        return "jpeg";
+    }
+    calculateDimensions(options) {
+        const aspectRatio = options.aspectRatio ?? "16:9";
+        const resolution = options.resolution ?? "720p";
+        if (resolution === "1080p") {
+            return aspectRatio === "9:16"
+                ? { width: 1080, height: 1920 }
+                : { width: 1920, height: 1080 };
+        }
+        return aspectRatio === "9:16"
+            ? { width: 720, height: 1280 }
+            : { width: 1280, height: 720 };
+    }
+}

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

@@ -95,7 +95,25 @@ export declare function generateVideoWithVertex(image: Buffer, prompt: string, o
  * @throws {VideoError} When API returns an error or polling times out
  */
 export declare function generateTransitionWithVertex(firstFrame: Buffer, lastFrame: Buffer, prompt: string, options?: {
-    aspectRatio?: "9:16" | "16:9";
+    aspectRatio?: "9:16" | "16:9" | "1:1" | string;
     resolution?: "720p" | "1080p";
     audio?: boolean;
 }, durationSeconds?: 4 | 6 | 8, region?: string): Promise<Buffer>;
+import type { VideoHandler, VideoTransitionOptions } from "../../types/index.js";
+/**
+ * Class wrapper around the standalone Vertex Veo functions, conforming to
+ * the `VideoHandler` contract so it can register with `VideoProcessor`.
+ *
+ * The free functions (`generateVideoWithVertex`, `generateTransitionWithVertex`,
+ * `isVertexVideoConfigured`) are kept exported for backward compatibility —
+ * external callers (Director's `directorPipeline.ts`, test scripts) reference
+ * them directly.
+ */
+export declare class VertexVideoHandler implements VideoHandler {
+    readonly maxDurationSeconds = 8;
+    readonly supportedAspectRatios: readonly ("9:16" | "16:9")[];
+    readonly supportedResolutions: readonly ("720p" | "1080p")[];
+    isConfigured(): boolean;
+    generate(image: Buffer, prompt: string, options: VideoOutputOptions, region?: string): Promise<VideoGenerationResult>;
+    generateTransition(firstFrame: Buffer, lastFrame: Buffer, prompt: string, options?: VideoTransitionOptions, region?: string): Promise<Buffer>;
+}

package/dist/adapters/video/vertexVideoHandler.js

@@ -609,15 +609,6 @@ async function pollVideoOperation(operationName, accessToken, project, location,
  * @throws {VideoError} When API returns an error or polling times out
  */
 export async function generateTransitionWithVertex(firstFrame, lastFrame, prompt, options = {}, durationSeconds = 4, region) {
-    if (!isVertexVideoConfigured()) {
-        throw new VideoError({
-            code: VIDEO_ERROR_CODES.PROVIDER_NOT_CONFIGURED,
-            message: "Vertex AI credentials not configured for transition generation.",
-            category: ErrorCategory.CONFIGURATION,
-            severity: ErrorSeverity.HIGH,
-            retriable: false,
-        });
-    }
     const config = await getVertexConfig();
     const project = config.project;
     const location = region || config.location;
@@ -774,3 +765,36 @@ async function pollOperation(modelOrEndpoint, operationName, accessToken, projec
 async function pollTransitionOperation(operationName, accessToken, project, location, timeoutMs) {
     return pollOperation(VEO_FAST_MODEL, operationName, accessToken, project, location, timeoutMs);
 }
+/**
+ * Class wrapper around the standalone Vertex Veo functions, conforming to
+ * the `VideoHandler` contract so it can register with `VideoProcessor`.
+ *
+ * The free functions (`generateVideoWithVertex`, `generateTransitionWithVertex`,
+ * `isVertexVideoConfigured`) are kept exported for backward compatibility —
+ * external callers (Director's `directorPipeline.ts`, test scripts) reference
+ * them directly.
+ */
+export class VertexVideoHandler {
+    maxDurationSeconds = 8;
+    supportedAspectRatios = [
+        "9:16",
+        "16:9",
+    ];
+    supportedResolutions = [
+        "720p",
+        "1080p",
+    ];
+    isConfigured() {
+        return isVertexVideoConfigured();
+    }
+    generate(image, prompt, options, region) {
+        return generateVideoWithVertex(image, prompt, options, region);
+    }
+    generateTransition(firstFrame, lastFrame, prompt, options, region) {
+        return generateTransitionWithVertex(firstFrame, lastFrame, prompt, {
+            aspectRatio: options?.aspectRatio,
+            resolution: options?.resolution,
+            audio: options?.audio,
+        }, options?.durationSeconds ?? 4, region);
+    }
+}

package/dist/agent/directTools.js

@@ -547,9 +547,16 @@ export const directAgentTools = {
     // It is only included in directAgentTools when NEUROLINK_ENABLE_BASH_TOOL=true or
     // toolConfig.enableBashTool is explicitly set to true. See shouldEnableBashTool() in toolUtils.ts.
     websearchGrounding: tool({
-        description: "Search the web for current information using Google Search grounding. Returns raw search data for AI processing.",
+        description: "Performs a Google Search and returns a summarized answer with source citations. Always check the current date before constructing the query. Use whenever the answer depends on time-sensitive facts or requires verification against real-world sources.",
         inputSchema: z.object({
-            query: z.string().describe("Search query to find information about"),
+            query: z
+                .string()
+                .trim()
+                .min(1, { message: "must be a non-empty search string" })
+                .refine((v) => v.toLowerCase() !== "undefined", {
+                message: 'must not be the literal string "undefined" — pass a real search query',
+            })
+                .describe("The search query string to look up on the web."),
             maxResults: z
                 .number()
                 .optional()
@@ -581,7 +588,8 @@ export const directAgentTools = {
                     project: hasProjectId,
                     location: projectLocation,
                 });
-                const websearchModel = "gemini-2.5-flash-lite";
+                const websearchModel = process.env.NEUROLINK_WEBSEARCH_MODEL?.trim() ||
+                    "gemini-2.5-flash-lite";
                 const model = vertex_ai.getGenerativeModel({
                     model: websearchModel,
                     tools: createGoogleSearchTools(),

package/dist/autoresearch/runner.js

@@ -14,10 +14,16 @@ export class ExperimentRunner {
     /** Runs the experiment with hard timeout, returns summary */
     async run() {
         const logPath = path.join(this.config.repoPath, this.config.logPath);
-        // Redact potential inline env vars or tokens before logging
+        // Redact potential inline env vars or tokens before logging.
+        // sanitizeForLog handles in-string `Bearer`/`Token`/`sk-` patterns but
+        // not CLI flag forms like `--token foo` (which is a different shape —
+        // separate argv tokens rather than concatenated values). The flag-form
+        // redactor below is narrowly scoped; not the H04 anti-pattern.
         const redactedCmd = this.config.runCommand
             .replace(/[A-Z_]+=\S+\s/g, (m) => m.split("=")[0] + "=*** ")
-            .replace(/--(?:token|key|secret|password)\s+\S+/gi, (m) => m.split(/\s+/)[0] + " ***");
+            .replace(
+        // eslint-disable-next-line neurolink/no-inline-secret-regex -- narrowly-scoped CLI-flag redactor
+        /--(?:token|key|secret|password)\s+\S+/gi, (m) => m.split(/\s+/)[0] + " ***");
         logger.info("[Autoresearch] Starting experiment", {
             command: redactedCmd,
             timeoutMs: this.config.timeoutMs,

package/dist/avatar/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Avatar Module — Talking-Head / Lip-sync Integration for NeuroLink
+ *
+ * Provides avatar-generation capability across providers (D-ID, HeyGen,
+ * Replicate-hosted MuseTalk / SadTalker / Wav2Lip).
+ *
+ * Use `AvatarProcessor.generate(provider, options)` to dispatch to the
+ * registered handler for `provider`.
+ *
+ * @module avatar
+ */
+export { AVATAR_ERROR_CODES, AvatarError, AvatarProcessor, } from "../utils/avatarProcessor.js";
+export { DIDAvatar, DIDAvatar as DIDAvatarHandler, } from "./providers/DIDAvatar.js";

package/dist/avatar/index.js

@@ -0,0 +1,13 @@
+/**
+ * Avatar Module — Talking-Head / Lip-sync Integration for NeuroLink
+ *
+ * Provides avatar-generation capability across providers (D-ID, HeyGen,
+ * Replicate-hosted MuseTalk / SadTalker / Wav2Lip).
+ *
+ * Use `AvatarProcessor.generate(provider, options)` to dispatch to the
+ * registered handler for `provider`.
+ *
+ * @module avatar
+ */
+export { AVATAR_ERROR_CODES, AvatarError, AvatarProcessor, } from "../utils/avatarProcessor.js";
+export { DIDAvatar, DIDAvatar as DIDAvatarHandler, } from "./providers/DIDAvatar.js";

package/dist/avatar/providers/DIDAvatar.d.ts

@@ -0,0 +1,49 @@
+/**
+ * D-ID Avatar / Lip-sync Handler
+ *
+ * Async talking-head generation. Submits a /talks request with a source
+ * image and either an audio URL or a text+voice script, polls the talk
+ * status, and downloads the resulting MP4.
+ *
+ * @module avatar/providers/DIDAvatar
+ * @see https://docs.d-id.com/reference/talks-overview
+ */
+import type { AvatarHandler, AvatarOptions, AvatarResult, AvatarVideoFormat } from "../../types/index.js";
+/**
+ * D-ID Avatar Handler.
+ *
+ * Auth: `Authorization: Basic ${DID_API_KEY}` (the API key is
+ * already a base64-encoded `username:password` from the D-ID console).
+ *
+ * Env vars: `DID_API_KEY` (preferred) / `D_ID_API_KEY` (legacy alias).
+ */
+export declare class DIDAvatar implements AvatarHandler {
+    readonly maxAudioDurationSeconds = 60;
+    readonly supportedFormats: readonly AvatarVideoFormat[];
+    private readonly apiKey;
+    private readonly baseUrl;
+    constructor(apiKey?: string);
+    isConfigured(): boolean;
+    generate(options: AvatarOptions): Promise<AvatarResult>;
+    private uploadImage;
+    private uploadAudio;
+    private submitTalk;
+    private pollUntilDone;
+    private downloadResult;
+    private resolveBuffer;
+    private detectImageMime;
+    /**
+     * Detect the audio subtype from magic bytes.
+     *
+     * Recognised formats:
+     * - WAV  : RIFF header (52 49 46 46)
+     * - OGG  : OggS capture (4F 67 67 53)
+     * - MP3  : ID3 tag (49 44 33) or MPEG sync word (FF Ex)
+     * - M4A  : "ftyp" box at offset 4 (ISO base media / M4A)
+     *
+     * Falls back to "mp3" when detection is inconclusive.
+     */
+    private detectAudioType;
+    private fetchWithTimeout;
+    private assertOk;
+}