@juspay/neurolink 9.39.0 → 9.41.0

package/dist/tasks/store/redisTaskStore.js

@@ -0,0 +1,188 @@
+/**
+ * RedisTaskStore — Redis-backed persistence for TaskManager.
+ * Used automatically when backend is "bullmq".
+ *
+ * Key patterns:
+ *   neurolink:tasks              (Hash)  — all task definitions
+ *   neurolink:task:{id}:runs     (List)  — run log entries (newest first)
+ *   neurolink:task:{id}:history  (List)  — continuation mode conversation history
+ */
+import { createClient } from "redis";
+import { logger } from "../../utils/logger.js";
+import { TaskError } from "../errors.js";
+import { TASK_DEFAULTS, } from "../../types/taskTypes.js";
+const KEY_PREFIX = "neurolink:";
+const TASKS_HASH = `${KEY_PREFIX}tasks`;
+function taskRunsKey(taskId) {
+    return `${KEY_PREFIX}task:${taskId}:runs`;
+}
+function taskHistoryKey(taskId) {
+    return `${KEY_PREFIX}task:${taskId}:history`;
+}
+export class RedisTaskStore {
+    config;
+    type = "redis";
+    client = null;
+    maxRunLogs;
+    maxHistoryEntries;
+    retentionConfig;
+    constructor(config) {
+        this.config = config;
+        this.maxRunLogs = config.maxRunLogs ?? TASK_DEFAULTS.maxRunLogs;
+        this.maxHistoryEntries =
+            config.maxHistoryEntries ?? TASK_DEFAULTS.maxHistoryEntries;
+        this.retentionConfig = {
+            ...TASK_DEFAULTS.retention,
+            ...config.taskRetention,
+        };
+    }
+    async initialize() {
+        const redis = this.config.redis ?? {};
+        const url = redis.url ??
+            `redis://${redis.host ?? TASK_DEFAULTS.redis.host}:${redis.port ?? TASK_DEFAULTS.redis.port}/${redis.db ?? 0}`;
+        this.client = createClient({
+            url,
+            ...(redis.password ? { password: redis.password } : {}),
+        });
+        this.client.on("error", (err) => {
+            logger.error("[TaskStore:Redis] Connection error", {
+                error: String(err),
+            });
+        });
+        await this.client.connect();
+        logger.info("[TaskStore:Redis] Connected");
+    }
+    async shutdown() {
+        if (this.client?.isOpen) {
+            await this.client.quit();
+            logger.info("[TaskStore:Redis] Disconnected");
+        }
+        this.client = null;
+    }
+    // ── Task CRUD ───────────────────────────────────────────
+    async save(task) {
+        this.ensureConnected();
+        await this.client.hSet(TASKS_HASH, task.id, JSON.stringify(task));
+        this.applyRetentionTTL(task);
+    }
+    async get(taskId) {
+        this.ensureConnected();
+        const data = await this.client.hGet(TASKS_HASH, taskId);
+        if (!data) {
+            return null;
+        }
+        return JSON.parse(String(data));
+    }
+    async list(filter) {
+        this.ensureConnected();
+        const all = await this.client.hGetAll(TASKS_HASH);
+        let tasks = Object.values(all).map((v) => JSON.parse(String(v)));
+        if (filter?.status) {
+            tasks = tasks.filter((t) => t.status === filter.status);
+        }
+        return tasks.sort((a, b) => new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime());
+    }
+    async update(taskId, updates) {
+        this.ensureConnected();
+        const existing = await this.get(taskId);
+        if (!existing) {
+            throw TaskError.create("TASK_NOT_FOUND", `Task not found: ${taskId}`);
+        }
+        const updated = {
+            ...existing,
+            ...updates,
+            id: existing.id, // ID is immutable
+            updatedAt: new Date().toISOString(),
+        };
+        await this.client.hSet(TASKS_HASH, taskId, JSON.stringify(updated));
+        this.applyRetentionTTL(updated);
+        return updated;
+    }
+    async delete(taskId) {
+        this.ensureConnected();
+        await Promise.all([
+            this.client.hDel(TASKS_HASH, taskId),
+            this.client.del(taskRunsKey(taskId)),
+            this.client.del(taskHistoryKey(taskId)),
+        ]);
+    }
+    // ── Run Logs ──────────────────────────────────────────
+    async appendRun(taskId, run) {
+        this.ensureConnected();
+        const key = taskRunsKey(taskId);
+        await this.client.lPush(key, JSON.stringify(run));
+        // Trim to keep only the latest maxRunLogs entries
+        await this.client.lTrim(key, 0, this.maxRunLogs - 1);
+    }
+    async getRuns(taskId, options) {
+        this.ensureConnected();
+        const limit = options?.limit ?? 20;
+        const key = taskRunsKey(taskId);
+        // When a status filter is applied, we need to fetch more items than `limit`
+        // because post-filter may discard many entries. Fetch all (-1) when filtering,
+        // otherwise fetch exactly `limit` items.
+        const fetchEnd = options?.status ? -1 : limit - 1;
+        const items = await this.client.lRange(key, 0, fetchEnd);
+        let runs = items.map((v) => JSON.parse(String(v)));
+        if (options?.status) {
+            runs = runs.filter((r) => r.status === options.status);
+        }
+        return runs.slice(0, limit);
+    }
+    // ── Continuation History ──────────────────────────────
+    async appendHistory(taskId, messages) {
+        this.ensureConnected();
+        const key = taskHistoryKey(taskId);
+        const serialized = messages.map((m) => JSON.stringify(m));
+        if (serialized.length > 0) {
+            await this.client.rPush(key, serialized);
+            // Trim to keep only the most recent entries, preventing unbounded growth
+            await this.client.lTrim(key, -this.maxHistoryEntries, -1);
+        }
+    }
+    async getHistory(taskId) {
+        this.ensureConnected();
+        const key = taskHistoryKey(taskId);
+        const items = await this.client.lRange(key, 0, -1);
+        return items.map((v) => JSON.parse(String(v)));
+    }
+    async clearHistory(taskId) {
+        this.ensureConnected();
+        await this.client.del(taskHistoryKey(taskId));
+    }
+    // ── Internal ──────────────────────────────────────────
+    ensureConnected() {
+        if (!this.client?.isOpen) {
+            throw TaskError.create("BACKEND_NOT_INITIALIZED", "[TaskStore:Redis] Not connected. Call initialize() first.");
+        }
+    }
+    /**
+     * Set Redis TTL on terminal-state tasks so they auto-expire.
+     * Active and paused tasks never expire.
+     */
+    applyRetentionTTL(task) {
+        // We don't set EXPIRE on the hash field directly (Redis doesn't support per-field TTL).
+        // Instead, run logs and history keys get TTL. The task hash field itself must be
+        // cleaned up via manual deletion or BullMQ's built-in job cleanup.
+        const ttlMap = {
+            completed: this.retentionConfig.completedTTL,
+            failed: this.retentionConfig.failedTTL,
+            cancelled: this.retentionConfig.cancelledTTL,
+        };
+        const ttlMs = ttlMap[task.status];
+        if (ttlMs) {
+            const ttlSeconds = Math.ceil(ttlMs / 1000);
+            // Set TTL on associated keys
+            this.client.expire(taskRunsKey(task.id), ttlSeconds).catch((err) => {
+                logger.debug("[TaskStore:Redis] Failed to set TTL", {
+                    error: String(err),
+                });
+            });
+            this.client.expire(taskHistoryKey(task.id), ttlSeconds).catch((err) => {
+                logger.debug("[TaskStore:Redis] Failed to set TTL", {
+                    error: String(err),
+                });
+            });
+        }
+    }
+}

package/dist/tasks/taskExecutor.d.ts

@@ -0,0 +1,21 @@
+/**
+ * TaskExecutor — Runs a single task execution against NeuroLink.generate().
+ *
+ * Handles:
+ * - Isolated mode: fresh generate() call with no history
+ * - Continuation mode: loads conversation history, appends new exchange
+ * - Retry with exponential backoff for transient errors
+ * - Run result construction and logging
+ */
+import type { TaskStore, Task, TaskRunResult, NeuroLinkExecutable } from "../types/taskTypes.js";
+export declare class TaskExecutor {
+    private neurolink;
+    private store;
+    constructor(neurolink: NeuroLinkExecutable, store: TaskStore);
+    /**
+     * Execute a task once. Called by the backend on each scheduled tick.
+     * Returns the run result (success or error).
+     */
+    execute(task: Task): Promise<TaskRunResult>;
+    private executeOnce;
+}

package/dist/tasks/taskExecutor.js

@@ -0,0 +1,165 @@
+/**
+ * TaskExecutor — Runs a single task execution against NeuroLink.generate().
+ *
+ * Handles:
+ * - Isolated mode: fresh generate() call with no history
+ * - Continuation mode: loads conversation history, appends new exchange
+ * - Retry with exponential backoff for transient errors
+ * - Run result construction and logging
+ */
+import { nanoid } from "nanoid";
+import { logger } from "../utils/logger.js";
+/** Errors that are transient and should be retried */
+const TRANSIENT_PATTERNS = [
+    "rate limit",
+    "rate_limit",
+    "too many requests",
+    "429",
+    "503",
+    "502",
+    "504",
+    "timeout",
+    "econnreset",
+    "econnrefused",
+    "network",
+    "overloaded",
+];
+function isTransientError(error) {
+    const msg = String(error).toLowerCase();
+    return TRANSIENT_PATTERNS.some((p) => msg.includes(p));
+}
+export class TaskExecutor {
+    neurolink;
+    store;
+    constructor(neurolink, store) {
+        this.neurolink = neurolink;
+        this.store = store;
+    }
+    /**
+     * Execute a task once. Called by the backend on each scheduled tick.
+     * Returns the run result (success or error).
+     */
+    async execute(task) {
+        const runId = `run_${nanoid(12)}`;
+        const startTime = Date.now();
+        let lastError;
+        for (let attempt = 1; attempt <= task.retry.maxAttempts; attempt++) {
+            try {
+                const result = await this.executeOnce(task, runId);
+                return result;
+            }
+            catch (err) {
+                lastError = String(err);
+                const willRetry = attempt < task.retry.maxAttempts && isTransientError(err);
+                logger.warn("[TaskExecutor] Execution attempt failed", {
+                    taskId: task.id,
+                    runId,
+                    attempt,
+                    willRetry,
+                    error: lastError,
+                });
+                if (!willRetry) {
+                    break;
+                }
+                // Backoff before retry
+                const backoffIndex = Math.min(attempt - 1, task.retry.backoffMs.length - 1);
+                const delay = task.retry.backoffMs[backoffIndex];
+                await sleep(delay);
+            }
+        }
+        // All retries exhausted or permanent error
+        const errorResult = {
+            taskId: task.id,
+            runId,
+            status: "error",
+            error: lastError,
+            durationMs: Date.now() - startTime,
+            timestamp: new Date().toISOString(),
+        };
+        return errorResult;
+    }
+    // ── Internal ──────────────────────────────────────────
+    async executeOnce(task, runId) {
+        const startTime = Date.now();
+        // Build generate options
+        const generateOptions = {
+            input: { text: task.prompt },
+            ...(task.provider ? { provider: task.provider } : {}),
+            ...(task.model ? { model: task.model } : {}),
+            ...(task.systemPrompt ? { systemPrompt: task.systemPrompt } : {}),
+            ...(task.maxTokens ? { maxTokens: task.maxTokens } : {}),
+            ...(task.temperature !== undefined
+                ? { temperature: task.temperature }
+                : {}),
+            ...(task.timeout ? { timeout: task.timeout } : {}),
+            ...(!task.tools ? { disableTools: true } : {}),
+        };
+        // Thinking level
+        if (task.thinkingLevel) {
+            generateOptions.thinkingConfig = { thinkingLevel: task.thinkingLevel };
+        }
+        // Continuation mode: pass conversation history as proper multi-turn messages
+        if (task.mode === "continuation" && task.sessionId) {
+            const history = await this.store.getHistory(task.id);
+            // Pass history as proper role-based conversation messages
+            if (history.length > 0) {
+                generateOptions.conversationMessages = history.map((entry, i) => ({
+                    id: `${task.sessionId}_${i}`,
+                    role: entry.role,
+                    content: entry.content,
+                    timestamp: entry.timestamp,
+                }));
+            }
+            // Add continuation context to system prompt
+            const runCount = Math.floor(history.length / 2);
+            const continuationHint = runCount > 0
+                ? `This is a continuation task (run ${runCount + 1}). Your previous ${runCount} exchange(s) are provided as conversation history.`
+                : "This is a continuation task. This is the first execution — no prior history exists yet.";
+            generateOptions.systemPrompt = task.systemPrompt
+                ? `${task.systemPrompt}\n\n${continuationHint}`
+                : continuationHint;
+        }
+        // Execute
+        const result = await this.neurolink.generate(generateOptions);
+        // Build run result
+        const runResult = {
+            taskId: task.id,
+            runId,
+            status: "success",
+            output: result.content,
+            toolCalls: result.toolExecutions?.map((te) => ({
+                name: te.name,
+                input: te.input,
+                output: te.output,
+            })),
+            tokensUsed: result.usage
+                ? {
+                    input: result.usage.input ?? 0,
+                    output: result.usage.output ?? 0,
+                }
+                : undefined,
+            durationMs: Date.now() - startTime,
+            timestamp: new Date().toISOString(),
+        };
+        // Continuation mode: append this exchange to history
+        if (task.mode === "continuation" && task.sessionId) {
+            const newEntries = [
+                {
+                    role: "user",
+                    content: task.prompt,
+                    timestamp: new Date(startTime).toISOString(),
+                },
+                {
+                    role: "assistant",
+                    content: result.content,
+                    timestamp: runResult.timestamp,
+                },
+            ];
+            await this.store.appendHistory(task.id, newEntries);
+        }
+        return runResult;
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/tasks/taskManager.d.ts

@@ -0,0 +1,60 @@
+/**
+ * TaskManager — Main orchestrator for scheduled and self-running tasks.
+ *
+ * Manages the full task lifecycle: create, schedule, execute, pause, resume, delete.
+ * Auto-selects TaskStore and TaskBackend based on config.
+ *
+ * Usage:
+ *   const neurolink = new NeuroLink({ tasks: { backend: "bullmq" } });
+ *   await neurolink.tasks.create({ name: "monitor", prompt: "...", schedule: { type: "interval", every: 60000 } });
+ */
+import { type NeuroLinkExecutable, type Task, type TaskDefinition, type TaskManagerConfig, type TaskRunResult, type TaskStatus } from "../types/taskTypes.js";
+export declare class TaskManager {
+    private neurolink;
+    private config;
+    private store;
+    private backend;
+    private executor;
+    private initialized;
+    private initPromise;
+    /** In-memory callback registry (not serializable to store) */
+    private callbacks;
+    /** Emitter reference — set by NeuroLink on integration */
+    private emitter?;
+    constructor(neurolink: NeuroLinkExecutable, config?: TaskManagerConfig);
+    /** Set the event emitter (called by NeuroLink during integration) */
+    setEmitter(emitter: {
+        emit(event: string, ...args: unknown[]): boolean;
+    }): void;
+    private ensureInitialized;
+    private doInitialize;
+    create(definition: TaskDefinition): Promise<Task>;
+    get(taskId: string): Promise<Task | null>;
+    list(filter?: {
+        status?: TaskStatus;
+    }): Promise<Task[]>;
+    update(taskId: string, updates: Partial<TaskDefinition>): Promise<Task>;
+    /** Run a task immediately (outside of its schedule) */
+    run(taskId: string): Promise<TaskRunResult>;
+    pause(taskId: string): Promise<Task>;
+    resume(taskId: string): Promise<Task>;
+    delete(taskId: string): Promise<void>;
+    runs(taskId: string, options?: {
+        limit?: number;
+        status?: string;
+    }): Promise<TaskRunResult[]>;
+    shutdown(): Promise<void>;
+    /** Check if the backend is healthy */
+    isHealthy(): Promise<boolean>;
+    /**
+     * Called by the backend on each scheduled tick.
+     * Executes the task, updates state, fires callbacks/events.
+     */
+    private onTaskTick;
+    /**
+     * Re-schedule all active tasks from store.
+     * Called on initialization to handle process restarts.
+     */
+    private rescheduleActiveTasks;
+    private emit;
+}