@juspay/neurolink 9.40.0 → 9.42.0

package/dist/tasks/taskManager.js

@@ -0,0 +1,425 @@
+/**
+ * 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 { nanoid } from "nanoid";
+import { logger } from "../utils/logger.js";
+import { TaskBackendRegistry } from "./backends/taskBackendRegistry.js";
+import { TaskError } from "./errors.js";
+import { TaskExecutor } from "./taskExecutor.js";
+import { TASK_DEFAULTS, } from "../types/taskTypes.js";
+export class TaskManager {
+    neurolink;
+    config;
+    store = null;
+    backend = null;
+    executor = null;
+    initialized = false;
+    initPromise = null;
+    /** In-memory callback registry (not serializable to store) */
+    callbacks = new Map();
+    /** Emitter reference — set by NeuroLink on integration */
+    emitter;
+    constructor(neurolink, config) {
+        this.neurolink = neurolink;
+        this.config = { ...config };
+    }
+    /** Set the event emitter (called by NeuroLink during integration) */
+    setEmitter(emitter) {
+        this.emitter = emitter;
+    }
+    // ── Initialization ──────────────────────────────────────
+    async ensureInitialized() {
+        if (this.initialized) {
+            return;
+        }
+        if (this.initPromise) {
+            return this.initPromise;
+        }
+        this.initPromise = this.doInitialize();
+        await this.initPromise;
+    }
+    async doInitialize() {
+        const backendName = this.config.backend ?? TASK_DEFAULTS.backend;
+        // Create store based on backend
+        if (backendName === "bullmq") {
+            const { RedisTaskStore } = await import("./store/redisTaskStore.js");
+            this.store = new RedisTaskStore(this.config);
+        }
+        else {
+            const { FileTaskStore } = await import("./store/fileTaskStore.js");
+            this.store = new FileTaskStore(this.config);
+        }
+        await this.store.initialize();
+        // Create backend
+        this.backend = await TaskBackendRegistry.create(backendName, this.config);
+        await this.backend.initialize();
+        // Create executor
+        this.executor = new TaskExecutor(this.neurolink, this.store);
+        // Re-schedule active tasks from store (handles restarts)
+        await this.rescheduleActiveTasks();
+        this.initialized = true;
+        logger.info("[TaskManager] Initialized", {
+            backend: backendName,
+            store: this.store.type,
+        });
+    }
+    getStore() {
+        if (!this.store) {
+            throw TaskError.create("BACKEND_NOT_INITIALIZED", "[TaskManager] Store not initialized. Call initialize() first.");
+        }
+        return this.store;
+    }
+    getBackend() {
+        if (!this.backend) {
+            throw TaskError.create("BACKEND_NOT_INITIALIZED", "[TaskManager] Backend not initialized. Call initialize() first.");
+        }
+        return this.backend;
+    }
+    getExecutor() {
+        if (!this.executor) {
+            throw TaskError.create("BACKEND_NOT_INITIALIZED", "[TaskManager] Executor not initialized. Call initialize() first.");
+        }
+        return this.executor;
+    }
+    // ── Public API ────────────────────────────────────────
+    async create(definition) {
+        if (this.config.enabled === false) {
+            throw TaskError.create("TASK_DISABLED", "TaskManager is disabled. Set tasks.enabled to true in config.");
+        }
+        await this.ensureInitialized();
+        const store = this.getStore();
+        const backend = this.getBackend();
+        // Enforce maximum task limit to prevent unbounded task creation
+        const maxTasks = this.config.maxTasks ?? TASK_DEFAULTS.maxTasks;
+        const existingTasks = await store.list();
+        if (existingTasks.length >= maxTasks) {
+            throw TaskError.create("TASK_LIMIT_REACHED", `Task limit reached (${maxTasks}). Delete existing tasks or increase maxTasks config.`);
+        }
+        const now = new Date().toISOString();
+        const task = {
+            id: `task_${nanoid(12)}`,
+            name: definition.name,
+            prompt: definition.prompt,
+            schedule: definition.schedule,
+            mode: definition.mode ?? TASK_DEFAULTS.mode,
+            status: "active",
+            tools: definition.tools ?? TASK_DEFAULTS.tools,
+            timeout: definition.timeout ?? TASK_DEFAULTS.timeout,
+            retry: {
+                maxAttempts: definition.retry?.maxAttempts ?? TASK_DEFAULTS.retry.maxAttempts,
+                backoffMs: definition.retry?.backoffMs ?? [
+                    ...TASK_DEFAULTS.retry.backoffMs,
+                ],
+            },
+            runCount: 0,
+            createdAt: now,
+            updatedAt: now,
+            // Optional overrides
+            ...(definition.provider ? { provider: definition.provider } : {}),
+            ...(definition.model ? { model: definition.model } : {}),
+            ...(definition.thinkingLevel
+                ? { thinkingLevel: definition.thinkingLevel }
+                : {}),
+            ...(definition.systemPrompt
+                ? { systemPrompt: definition.systemPrompt }
+                : {}),
+            ...(definition.maxTokens ? { maxTokens: definition.maxTokens } : {}),
+            ...(definition.temperature !== undefined
+                ? { temperature: definition.temperature }
+                : {}),
+            ...(definition.maxRuns !== undefined
+                ? { maxRuns: definition.maxRuns }
+                : {}),
+            ...(definition.metadata ? { metadata: definition.metadata } : {}),
+        };
+        // Generate session ID for continuation mode
+        if (task.mode === "continuation") {
+            task.sessionId = `session_${nanoid(12)}`;
+        }
+        // Save to store
+        await store.save(task);
+        // Register callbacks (in-memory only)
+        if (definition.onSuccess || definition.onError || definition.onComplete) {
+            this.callbacks.set(task.id, {
+                onSuccess: definition.onSuccess,
+                onError: definition.onError,
+                onComplete: definition.onComplete,
+            });
+        }
+        // Schedule
+        try {
+            await backend.schedule(task, (t) => this.onTaskTick(t));
+        }
+        catch (err) {
+            await store.delete(task.id);
+            throw err;
+        }
+        this.emit("task:created", task);
+        logger.info("[TaskManager] Task created", {
+            taskId: task.id,
+            name: task.name,
+            schedule: task.schedule.type,
+            mode: task.mode,
+        });
+        return task;
+    }
+    async get(taskId) {
+        await this.ensureInitialized();
+        return this.getStore().get(taskId);
+    }
+    async list(filter) {
+        await this.ensureInitialized();
+        return this.getStore().list(filter);
+    }
+    async update(taskId, updates) {
+        await this.ensureInitialized();
+        const store = this.getStore();
+        const backend = this.getBackend();
+        const existing = await store.get(taskId);
+        if (!existing) {
+            throw TaskError.create("TASK_NOT_FOUND", `Task not found: ${taskId}`);
+        }
+        // Apply allowed scalar updates via whitelist
+        const ALLOWED_UPDATE_FIELDS = [
+            "name",
+            "prompt",
+            "schedule",
+            "mode",
+            "provider",
+            "model",
+            "systemPrompt",
+            "maxTokens",
+            "temperature",
+            "timeout",
+            "tools",
+            "maxRuns",
+            "metadata",
+            "thinkingLevel",
+        ];
+        const taskUpdates = {};
+        for (const field of ALLOWED_UPDATE_FIELDS) {
+            if (updates[field] !== undefined) {
+                taskUpdates[field] = updates[field];
+            }
+        }
+        // Special-case: mode changes require sessionId handling
+        if (updates.mode !== undefined) {
+            if (updates.mode === "continuation" && !existing.sessionId) {
+                taskUpdates.sessionId = `session_${nanoid(12)}`;
+            }
+            else if (updates.mode !== "continuation") {
+                taskUpdates.sessionId = undefined;
+                await store.clearHistory(taskId);
+            }
+        }
+        const updated = await store.update(taskId, taskUpdates);
+        // Re-schedule if schedule changed and task is active
+        if (updates.schedule && updated.status === "active") {
+            await backend.cancel(taskId);
+            await backend.schedule(updated, (t) => this.onTaskTick(t));
+        }
+        return updated;
+    }
+    /** Run a task immediately (outside of its schedule) */
+    async run(taskId) {
+        await this.ensureInitialized();
+        const task = await this.getStore().get(taskId);
+        if (!task) {
+            throw TaskError.create("TASK_NOT_FOUND", `Task not found: ${taskId}`);
+        }
+        return this.onTaskTick(task);
+    }
+    async pause(taskId) {
+        await this.ensureInitialized();
+        const store = this.getStore();
+        const backend = this.getBackend();
+        const task = await store.get(taskId);
+        if (!task) {
+            throw TaskError.create("TASK_NOT_FOUND", `Task not found: ${taskId}`);
+        }
+        if (task.status !== "active") {
+            throw TaskError.create("INVALID_TASK_STATUS", `Cannot pause task with status: ${task.status}`);
+        }
+        await backend.pause(taskId);
+        const updated = await store.update(taskId, { status: "paused" });
+        this.emit("task:paused", updated);
+        return updated;
+    }
+    async resume(taskId) {
+        await this.ensureInitialized();
+        const store = this.getStore();
+        const backend = this.getBackend();
+        const task = await store.get(taskId);
+        if (!task) {
+            throw TaskError.create("TASK_NOT_FOUND", `Task not found: ${taskId}`);
+        }
+        if (task.status !== "paused") {
+            throw TaskError.create("INVALID_TASK_STATUS", `Cannot resume task with status: ${task.status}`);
+        }
+        const updated = await store.update(taskId, { status: "active" });
+        await backend.schedule(updated, (t) => this.onTaskTick(t));
+        this.emit("task:resumed", updated);
+        return updated;
+    }
+    async delete(taskId) {
+        await this.ensureInitialized();
+        const backend = this.getBackend();
+        const store = this.getStore();
+        await backend.cancel(taskId);
+        await store.delete(taskId);
+        this.callbacks.delete(taskId);
+        this.emit("task:deleted", taskId);
+    }
+    async runs(taskId, options) {
+        await this.ensureInitialized();
+        return this.getStore().getRuns(taskId, options);
+    }
+    async shutdown() {
+        if (this.backend) {
+            await this.backend.shutdown();
+        }
+        if (this.store) {
+            await this.store.shutdown();
+        }
+        this.callbacks.clear();
+        this.initialized = false;
+        this.initPromise = null;
+        logger.info("[TaskManager] Shut down");
+    }
+    /** Check if the backend is healthy */
+    async isHealthy() {
+        if (!this.backend) {
+            return false;
+        }
+        return this.backend.isHealthy();
+    }
+    // ── Internal ──────────────────────────────────────────
+    /**
+     * Called by the backend on each scheduled tick.
+     * Executes the task, updates state, fires callbacks/events.
+     */
+    async onTaskTick(task) {
+        this.emit("task:started", task);
+        const store = this.getStore();
+        const backend = this.getBackend();
+        const executor = this.getExecutor();
+        // Re-read latest task state (may have been updated/paused since scheduling)
+        const current = await store.get(task.id);
+        if (!current || current.status !== "active") {
+            logger.debug("[TaskManager] Skipping tick for non-active task", {
+                taskId: task.id,
+                status: current?.status,
+            });
+            return {
+                taskId: task.id,
+                runId: "skipped",
+                status: "error",
+                error: "Task is not active",
+                durationMs: 0,
+                timestamp: new Date().toISOString(),
+            };
+        }
+        const result = await executor.execute(current);
+        // Log the run
+        await store.appendRun(task.id, result);
+        // Update task tracking
+        const updates = {
+            runCount: current.runCount + 1,
+            lastRunAt: result.timestamp,
+        };
+        // Check if task should complete
+        if (current.maxRuns && current.runCount + 1 >= current.maxRuns) {
+            updates.status = "completed";
+            await backend.cancel(task.id);
+        }
+        // Mark successful once tasks as completed
+        if (result.status === "success" && current.schedule.type === "once") {
+            updates.status = "completed";
+            await backend.cancel(task.id);
+        }
+        // Mark as failed on permanent error
+        if (result.status === "error" && current.schedule.type === "once") {
+            updates.status = "failed";
+        }
+        await store.update(task.id, updates);
+        // Fire callbacks
+        const cbs = this.callbacks.get(task.id);
+        if (cbs) {
+            try {
+                if (result.status === "success" && cbs.onSuccess) {
+                    await cbs.onSuccess(result);
+                }
+                if (result.status === "error" && cbs.onError) {
+                    await cbs.onError({
+                        taskId: task.id,
+                        runId: result.runId,
+                        error: result.error ?? "Unknown error",
+                        attempt: 1, // Executor handles retries internally and returns final result
+                        maxAttempts: current.retry.maxAttempts,
+                        willRetry: false,
+                        timestamp: result.timestamp,
+                    });
+                }
+                if (updates.status === "completed" || updates.status === "failed") {
+                    const finalTask = await store.get(task.id);
+                    if (finalTask && cbs.onComplete) {
+                        await cbs.onComplete(finalTask);
+                    }
+                }
+            }
+            catch (cbErr) {
+                logger.error("[TaskManager] Callback error", {
+                    taskId: task.id,
+                    error: String(cbErr),
+                });
+            }
+        }
+        // Emit events
+        if (result.status === "success") {
+            this.emit("task:completed", result);
+        }
+        else {
+            this.emit("task:failed", result);
+        }
+        return result;
+    }
+    /**
+     * Re-schedule all active tasks from store.
+     * Called on initialization to handle process restarts.
+     */
+    async rescheduleActiveTasks() {
+        const store = this.getStore();
+        const backend = this.getBackend();
+        const activeTasks = await store.list({ status: "active" });
+        for (const task of activeTasks) {
+            try {
+                await backend.schedule(task, (t) => this.onTaskTick(t));
+                logger.debug("[TaskManager] Re-scheduled task", {
+                    taskId: task.id,
+                    name: task.name,
+                });
+            }
+            catch (err) {
+                logger.error("[TaskManager] Failed to re-schedule task", {
+                    taskId: task.id,
+                    error: String(err),
+                });
+            }
+        }
+        if (activeTasks.length > 0) {
+            logger.info("[TaskManager] Re-scheduled active tasks", {
+                count: activeTasks.length,
+            });
+        }
+    }
+    emit(event, ...args) {
+        this.emitter?.emit(event, ...args);
+    }
+}

package/dist/tasks/tools/taskTools.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Built-in agent tools for TaskManager.
+ *
+ * These tools allow the AI to self-schedule, manage, and inspect tasks
+ * during conversations. Created per-instance via `createTaskTools()` factory,
+ * following the same pattern as `createFileTools()` in files/fileTools.ts.
+ *
+ * @module tasks/tools/taskTools
+ */
+import type { TaskManager } from "../taskManager.js";
+import type { TaskSchedule } from "../../types/taskTypes.js";
+/**
+ * Create task management tools bound to a TaskManager instance.
+ *
+ * These tools follow the same factory pattern as `createFileTools()` in
+ * `src/lib/files/fileTools.ts`. The `manager` is captured via closure,
+ * eliminating the need for module-level singleton state.
+ *
+ * @param manager - The TaskManager instance to bind to
+ * @returns Record of tool name to tool definition
+ *
+ * @example
+ * ```typescript
+ * const manager = new TaskManager(neurolink, config);
+ * const tools = createTaskTools(manager);
+ * // tools.createTask, tools.listTasks, tools.getTaskRuns, etc.
+ * ```
+ */
+export declare function createTaskTools(manager: TaskManager): {
+    createTask: import("ai").Tool<{
+        name: string;
+        prompt: string;
+        schedule: {
+            type: "once" | "cron" | "interval";
+            expression?: string | undefined;
+            timezone?: string | undefined;
+            every?: number | undefined;
+            at?: string | undefined;
+        };
+        mode?: "isolated" | "continuation" | undefined;
+    }, {
+        success: boolean;
+        taskId: string;
+        name: string;
+        status: import("../../index.js").TaskStatus;
+        mode: import("../../index.js").TaskExecutionMode;
+        nextRunAt: string | undefined;
+        schedule: TaskSchedule;
+        error?: undefined;
+    } | {
+        success: boolean;
+        error: string;
+        taskId?: undefined;
+        name?: undefined;
+        status?: undefined;
+        mode?: undefined;
+        nextRunAt?: undefined;
+        schedule?: undefined;
+    }>;
+    listTasks: import("ai").Tool<{
+        status?: "failed" | "pending" | "active" | "paused" | "completed" | "cancelled" | undefined;
+    }, {
+        success: boolean;
+        count: number;
+        tasks: {
+            taskId: string;
+            name: string;
+            status: import("../../index.js").TaskStatus;
+            mode: import("../../index.js").TaskExecutionMode;
+            schedule: TaskSchedule;
+            runCount: number;
+            lastRunAt: string | undefined;
+            nextRunAt: string | undefined;
+        }[];
+        error?: undefined;
+    } | {
+        success: boolean;
+        error: string;
+        count?: undefined;
+        tasks?: undefined;
+    }>;
+    getTaskRuns: import("ai").Tool<{
+        taskId: string;
+        limit?: number | undefined;
+    }, {
+        success: boolean;
+        taskId: string;
+        count: number;
+        runs: {
+            runId: string;
+            status: "error" | "success";
+            output: string | undefined;
+            durationMs: number;
+            timestamp: string;
+            error: string | undefined;
+        }[];
+        error?: undefined;
+    } | {
+        success: boolean;
+        error: string;
+        taskId?: undefined;
+        count?: undefined;
+        runs?: undefined;
+    }>;
+    deleteTask: import("ai").Tool<{
+        taskId: string;
+    }, {
+        success: boolean;
+        error: string;
+        deletedTask?: undefined;
+        taskId?: undefined;
+    } | {
+        success: boolean;
+        deletedTask: string;
+        taskId: string;
+        error?: undefined;
+    }>;
+    runTaskNow: import("ai").Tool<{
+        taskId: string;
+    }, {
+        success: boolean;
+        runId: string;
+        status: "error" | "success";
+        output: string | undefined;
+        durationMs: number;
+        error: string | undefined;
+    } | {
+        success: boolean;
+        error: string;
+        runId?: undefined;
+        status?: undefined;
+        output?: undefined;
+        durationMs?: undefined;
+    }>;
+};