@juspay/neurolink 9.40.0 → 9.41.0

package/dist/lib/types/taskTypes.d.ts

@@ -0,0 +1,275 @@
+/**
+ * Type definitions for the NeuroLink TaskManager system.
+ *
+ * TaskManager provides scheduled and self-running task capabilities,
+ * enabling AI agents to execute prompts on cron, interval, or one-shot schedules.
+ */
+import type { Cron } from "croner";
+import type { createClient } from "redis";
+import type { ThinkingLevel } from "./configTypes.js";
+export type TaskScheduleType = "cron" | "interval" | "once";
+export type CronSchedule = {
+    type: "cron";
+    /** Standard 5-field cron expression, e.g. "0 9 * * *" */
+    expression: string;
+    /** IANA timezone, e.g. "America/New_York" */
+    timezone?: string;
+};
+export type IntervalSchedule = {
+    type: "interval";
+    /** Interval in milliseconds */
+    every: number;
+};
+export type OnceSchedule = {
+    type: "once";
+    /** ISO 8601 timestamp or Date object */
+    at: Date | string;
+};
+export type TaskSchedule = CronSchedule | IntervalSchedule | OnceSchedule;
+/**
+ * - "isolated": Each run gets a fresh context. No memory of previous runs.
+ * - "continuation": Conversation history is preserved across runs.
+ */
+export type TaskExecutionMode = "isolated" | "continuation";
+export type TaskStatus = "pending" | "active" | "paused" | "completed" | "failed" | "cancelled";
+export type TaskDefinition = {
+    name: string;
+    prompt: string;
+    schedule: TaskSchedule;
+    mode?: TaskExecutionMode;
+    provider?: string;
+    model?: string;
+    thinkingLevel?: ThinkingLevel;
+    systemPrompt?: string;
+    /** Enable/disable tools for this task. Default: true */
+    tools?: boolean;
+    maxTokens?: number;
+    temperature?: number;
+    /** Max number of executions. Omit for unlimited. */
+    maxRuns?: number;
+    /** Per-run timeout in ms. Default: 120000 */
+    timeout?: number;
+    retry?: {
+        /** Default: 3 */
+        maxAttempts?: number;
+        /** Default: [30000, 60000, 300000] */
+        backoffMs?: number[];
+    };
+    onSuccess?: (result: TaskRunResult) => void | Promise<void>;
+    onError?: (error: TaskRunError) => void | Promise<void>;
+    /** Called when task reaches a terminal state (completed, failed, cancelled) */
+    onComplete?: (task: Task) => void | Promise<void>;
+    metadata?: Record<string, unknown>;
+};
+export type Task = {
+    id: string;
+    name: string;
+    prompt: string;
+    schedule: TaskSchedule;
+    mode: TaskExecutionMode;
+    status: TaskStatus;
+    provider?: string;
+    model?: string;
+    thinkingLevel?: ThinkingLevel;
+    systemPrompt?: string;
+    tools: boolean;
+    maxTokens?: number;
+    temperature?: number;
+    maxRuns?: number;
+    timeout: number;
+    retry: {
+        maxAttempts: number;
+        backoffMs: number[];
+    };
+    runCount: number;
+    lastRunAt?: string;
+    nextRunAt?: string;
+    createdAt: string;
+    updatedAt: string;
+    /** Conversation session ID for continuation mode */
+    sessionId?: string;
+    metadata?: Record<string, unknown>;
+};
+/** Shape of the tasks.json file used by FileTaskStore */
+export type TasksFile = {
+    version: number;
+    tasks: Record<string, Task>;
+};
+export type TaskRunResult = {
+    taskId: string;
+    runId: string;
+    status: "success" | "error";
+    /** AI response text */
+    output?: string;
+    toolCalls?: Array<{
+        name: string;
+        input: unknown;
+        output: unknown;
+    }>;
+    tokensUsed?: {
+        input: number;
+        output: number;
+    };
+    durationMs: number;
+    /** ISO 8601 */
+    timestamp: string;
+    error?: string;
+};
+export type TaskRunError = {
+    taskId: string;
+    runId: string;
+    error: string;
+    attempt: number;
+    maxAttempts: number;
+    willRetry: boolean;
+    /** ISO 8601 */
+    timestamp: string;
+};
+/**
+ * Abstracts task persistence. Auto-selected based on backend:
+ * - BullMQ → RedisTaskStore
+ * - NodeTimeout → FileTaskStore
+ */
+export interface TaskStore {
+    readonly type: "redis" | "file";
+    initialize(): Promise<void>;
+    shutdown(): Promise<void>;
+    save(task: Task): Promise<void>;
+    get(taskId: string): Promise<Task | null>;
+    list(filter?: {
+        status?: TaskStatus;
+    }): Promise<Task[]>;
+    update(taskId: string, updates: Partial<Task>): Promise<Task>;
+    delete(taskId: string): Promise<void>;
+    appendRun(taskId: string, run: TaskRunResult): Promise<void>;
+    getRuns(taskId: string, options?: {
+        limit?: number;
+        status?: string;
+    }): Promise<TaskRunResult[]>;
+    appendHistory(taskId: string, messages: ConversationEntry[]): Promise<void>;
+    getHistory(taskId: string): Promise<ConversationEntry[]>;
+    clearHistory(taskId: string): Promise<void>;
+}
+export type ConversationEntry = {
+    role: "user" | "assistant";
+    content: string;
+    timestamp: string;
+};
+export type TaskExecutorFn = (task: Task) => Promise<TaskRunResult>;
+/**
+ * Abstracts the scheduling/looping mechanism.
+ * Implementations: BullMQ (production), NodeTimeout (development).
+ */
+export interface TaskBackend {
+    readonly name: string;
+    initialize(): Promise<void>;
+    shutdown(): Promise<void>;
+    /** Schedule a task for execution */
+    schedule(task: Task, executor: TaskExecutorFn): Promise<void>;
+    /** Cancel a scheduled task */
+    cancel(taskId: string): Promise<void>;
+    /** Pause a task's schedule */
+    pause(taskId: string): Promise<void>;
+    /** Resume a paused task */
+    resume(taskId: string): Promise<void>;
+    /** Check if backend is operational */
+    isHealthy(): Promise<boolean>;
+}
+/** Redis client type used by RedisTaskStore */
+export type RedisClient = ReturnType<typeof createClient>;
+/** Minimal interface for the NeuroLink SDK methods needed by TaskExecutor */
+export type NeuroLinkExecutable = {
+    generate(optionsOrPrompt: unknown): Promise<{
+        content: string;
+        toolExecutions?: Array<{
+            name: string;
+            input: unknown;
+            output: unknown;
+        }>;
+        usage?: {
+            input?: number;
+            output?: number;
+        };
+    }>;
+};
+/** Internal scheduling entry used by NodeTimeoutBackend */
+export type ScheduledEntry = {
+    taskId: string;
+    executor: TaskExecutorFn;
+    task: Task;
+    cronJob?: Cron;
+    intervalId?: ReturnType<typeof setInterval>;
+    timeoutId?: ReturnType<typeof setTimeout>;
+};
+export type TaskBackendName = "bullmq" | "node-timeout";
+export type TaskBackendFactoryFn = (config: TaskManagerConfig) => Promise<TaskBackend>;
+export type TaskRetentionConfig = {
+    /** Auto-delete completed tasks after N ms. Default: 30 days */
+    completedTTL?: number;
+    /** Auto-delete failed tasks after N ms. Default: 7 days */
+    failedTTL?: number;
+    /** Auto-delete cancelled tasks after N ms. Default: 7 days */
+    cancelledTTL?: number;
+    /** Auto-expire individual run log entries after N ms. Default: 30 days */
+    runLogTTL?: number;
+};
+export type TaskManagerConfig = {
+    /** Default: true */
+    enabled?: boolean;
+    /** Default: "bullmq" */
+    backend?: TaskBackendName;
+    redis?: {
+        host?: string;
+        port?: number;
+        password?: string;
+        db?: number;
+        /** Alternative: full Redis URL */
+        url?: string;
+    };
+    /** Default: ".neurolink/tasks/tasks.json" */
+    storePath?: string;
+    /** Default: ".neurolink/tasks/runs/" */
+    logsPath?: string;
+    /** Maximum number of tasks that can exist at once. Default: 100 */
+    maxTasks?: number;
+    /** Default: 5 */
+    maxConcurrentRuns?: number;
+    /** Max run log entries per task. Default: 2000 */
+    maxRunLogs?: number;
+    /** Max continuation history entries per task. Default: 200 (100 exchanges) */
+    maxHistoryEntries?: number;
+    taskRetention?: TaskRetentionConfig;
+};
+export declare const TASK_DEFAULTS: {
+    readonly enabled: true;
+    readonly maxTasks: 100;
+    readonly backend: TaskBackendName;
+    readonly mode: TaskExecutionMode;
+    readonly timeout: 120000;
+    readonly maxConcurrentRuns: 5;
+    readonly maxRunLogs: 2000;
+    readonly maxHistoryEntries: 200;
+    readonly tools: true;
+    readonly retry: {
+        readonly maxAttempts: 3;
+        readonly backoffMs: readonly [30000, 60000, 300000];
+    };
+    readonly storePath: ".neurolink/tasks/tasks.json";
+    readonly logsPath: ".neurolink/tasks/runs/";
+    readonly redis: {
+        readonly host: "localhost";
+        readonly port: 6379;
+    };
+    readonly retention: {
+        readonly completedTTL: number;
+        readonly failedTTL: number;
+        readonly cancelledTTL: number;
+        readonly runLogTTL: number;
+    };
+};
+/** State persisted by the CLI task worker daemon */
+export type WorkerState = {
+    pid: number;
+    startedAt: string;
+    logFile: string;
+};

package/dist/lib/types/taskTypes.js

@@ -0,0 +1,37 @@
+/**
+ * Type definitions for the NeuroLink TaskManager system.
+ *
+ * TaskManager provides scheduled and self-running task capabilities,
+ * enabling AI agents to execute prompts on cron, interval, or one-shot schedules.
+ */
+// ── Defaults ────────────────────────────────────────────
+const THIRTY_DAYS_MS = 30 * 24 * 60 * 60 * 1000;
+const SEVEN_DAYS_MS = 7 * 24 * 60 * 60 * 1000;
+export const TASK_DEFAULTS = {
+    enabled: true,
+    maxTasks: 100,
+    backend: "bullmq",
+    mode: "isolated",
+    timeout: 120_000,
+    maxConcurrentRuns: 5,
+    maxRunLogs: 2000,
+    maxHistoryEntries: 200,
+    tools: true,
+    retry: {
+        maxAttempts: 3,
+        backoffMs: [30_000, 60_000, 300_000],
+    },
+    storePath: ".neurolink/tasks/tasks.json",
+    logsPath: ".neurolink/tasks/runs/",
+    redis: {
+        host: "localhost",
+        port: 6379,
+    },
+    retention: {
+        completedTTL: THIRTY_DAYS_MS,
+        failedTTL: SEVEN_DAYS_MS,
+        cancelledTTL: SEVEN_DAYS_MS,
+        runLogTTL: THIRTY_DAYS_MS,
+    },
+};
+//# sourceMappingURL=taskTypes.js.map

package/dist/neurolink.d.ts

@@ -25,11 +25,14 @@ import type { ObservabilityConfig } from "./types/observability.js";
 import type { StreamOptions, StreamResult } from "./types/streamTypes.js";
 import type { ToolExecutionContext, ToolExecutionSummary, ToolInfo, ToolRegistrationOptions } from "./types/tools.js";
 import type { BatchOperationResult } from "./types/typeAliases.js";
+import { TaskManager } from "./tasks/taskManager.js";
 export declare class NeuroLink {
     private mcpInitialized;
     private mcpSkipped;
     private mcpInitPromise;
     private emitter;
+    private _taskManager?;
+    private _taskManagerConfig?;
     private toolRegistry;
     private autoDiscoveredServerInfos;
     private externalServerManager;
@@ -148,6 +151,13 @@ export declare class NeuroLink {
      */
     private get _metricsTraceContext();
     constructor(config?: NeurolinkConstructorConfig);
+    /**
+     * TaskManager — scheduled and self-running tasks.
+     * Lazy-initialized on first access. Configurable via constructor `tasks` option.
+     * The actual async initialization (Redis connect, backend start) happens
+     * lazily inside TaskManager on first operation.
+     */
+    get tasks(): TaskManager;
     /**
      * Initialize provider registry with security settings
      */
@@ -173,6 +183,12 @@ export declare class NeuroLink {
      * and registers them as direct tools so they're available to LLMs.
      */
     private registerFileTools;
+    /**
+     * Register task management tools bound to a TaskManager instance.
+     * Follows the same factory + registry pattern as registerFileTools().
+     * Called when TaskManager is created (eagerly or lazily via the `tasks` getter).
+     */
+    private registerTaskTools;
     /**
      * Register memory retrieval tools that allow the AI to access
      * conversation history, including full tool outputs.

package/dist/neurolink.js

@@ -75,6 +75,8 @@ import { isNonNullObject } from "./utils/typeUtils.js";
 import { resolveModel } from "./utils/modelAliasResolver.js";
 import { getWorkflow } from "./workflow/core/workflowRegistry.js";
 import { runWorkflow } from "./workflow/core/workflowRunner.js";
+import { TaskManager } from "./tasks/taskManager.js";
+import { createTaskTools } from "./tasks/tools/taskTools.js";
 /**
  * NL-002: Classify MCP error messages into categories for AI disambiguation.
  * Returns a human-readable error category based on error message content.
@@ -187,6 +189,9 @@ export class NeuroLink {
     mcpSkipped = false;
     mcpInitPromise = null;
     emitter = new EventEmitter();
+    // TaskManager — lazy-initialized on first access via `this.tasks`
+    _taskManager;
+    _taskManagerConfig;
     toolRegistry;
     autoDiscoveredServerInfos = [];
     // External MCP server management
@@ -459,6 +464,28 @@ export class NeuroLink {
         if (config?.auth) {
             this.pendingAuthConfig = config.auth;
         }
+        // Store task config for lazy initialization
+        this._taskManagerConfig = config?.tasks;
+        // Eagerly create TaskManager and register tools if config is provided
+        if (this._taskManagerConfig) {
+            this._taskManager = new TaskManager(this, this._taskManagerConfig);
+            this._taskManager.setEmitter(this.emitter);
+            this.registerTaskTools(this._taskManager);
+        }
+    }
+    /**
+     * TaskManager — scheduled and self-running tasks.
+     * Lazy-initialized on first access. Configurable via constructor `tasks` option.
+     * The actual async initialization (Redis connect, backend start) happens
+     * lazily inside TaskManager on first operation.
+     */
+    get tasks() {
+        if (!this._taskManager) {
+            this._taskManager = new TaskManager(this, this._taskManagerConfig);
+            this._taskManager.setEmitter(this.emitter);
+            this.registerTaskTools(this._taskManager);
+        }
+        return this._taskManager;
     }
     /**
      * Initialize provider registry with security settings
@@ -716,6 +743,52 @@ export class NeuroLink {
             logger.debug(`[NeuroLink] Registered ${Object.keys(fileTools).length} file reference tools`);
         });
     }
+    /**
+     * Register task management tools bound to a TaskManager instance.
+     * Follows the same factory + registry pattern as registerFileTools().
+     * Called when TaskManager is created (eagerly or lazily via the `tasks` getter).
+     */
+    registerTaskTools(manager) {
+        const taskTools = createTaskTools(manager);
+        for (const [toolName, toolDef] of Object.entries(taskTools)) {
+            const toolId = `direct.${toolName}`;
+            const toolInfo = {
+                name: toolName,
+                description: toolDef.description || `Task tool: ${toolName}`,
+                inputSchema: {},
+                serverId: "direct",
+                category: "built-in",
+            };
+            // registerTool is async but its core logic is synchronous (Map.set).
+            // We fire-and-forget here but tools are available immediately after
+            // the synchronous validation + map insertion completes.
+            void this.toolRegistry.registerTool(toolId, toolInfo, {
+                execute: async (params) => {
+                    try {
+                        const result = await toolDef.execute(params, {
+                            toolCallId: "task-tool",
+                            messages: [],
+                        });
+                        return {
+                            success: true,
+                            data: result,
+                            metadata: { toolName, serverId: "direct", executionTime: 0 },
+                        };
+                    }
+                    catch (error) {
+                        return {
+                            success: false,
+                            error: error instanceof Error ? error.message : String(error),
+                            metadata: { toolName, serverId: "direct", executionTime: 0 },
+                        };
+                    }
+                },
+                description: toolDef.description,
+                inputSchema: {},
+            });
+        }
+        logger.debug(`[NeuroLink] Registered ${Object.keys(taskTools).length} task tools`);
+    }
     /**
      * Register memory retrieval tools that allow the AI to access
      * conversation history, including full tool outputs.
@@ -1906,6 +1979,18 @@ Current user's request: ${currentInput}`;
                     logger.warn("[NeuroLink] MCP servers shutdown failed:", error);
                 }
             }
+            // Shutdown TaskManager
+            if (this._taskManager) {
+                try {
+                    await withTimeout(this._taskManager.shutdown(), 5000, new Error("TaskManager shutdown timed out"));
+                }
+                catch (error) {
+                    logger.warn("[NeuroLink] TaskManager shutdown error:", error);
+                }
+                finally {
+                    this._taskManager = undefined;
+                }
+            }
             // Close conversation memory manager (release Redis connections, etc.)
             if (this.conversationMemory?.close) {
                 try {
@@ -2521,6 +2606,8 @@ Current user's request: ${currentInput}`;
                             abortSignal: options.abortSignal,
                             skipToolPromptInjection: options.skipToolPromptInjection,
                             middleware: options.middleware,
+                            // Pass through conversation messages for task continuation and external callers
+                            conversationMessages: options.conversationMessages,
                         };
                         // Auto-map top-level sessionId/userId to context for convenience
                         // Tests and users may pass sessionId/userId as top-level options
@@ -2745,7 +2832,15 @@ Current user's request: ${currentInput}`;
         // Execute workflow
         const workflowResult = await runWorkflow(workflowConfig, {
             prompt: options.input.text,
-            conversationHistory: options.conversationHistory,
+            conversationHistory: options.conversationMessages
+                ?.filter((m) => m.role === "user" || m.role === "assistant")
+                .map((m) => ({
+                role: m.role,
+                content: typeof m.content === "string"
+                    ? m.content
+                    : JSON.stringify(m.content),
+            })) ??
+                options.conversationHistory,
             timeout: options.timeout,
             verbose: false,
             metadata: options.context,
@@ -2836,7 +2931,15 @@ Current user's request: ${currentInput}`;
         // Execute workflow with progressive streaming
         const workflowStream = runWorkflowWithStreaming(workflowConfig, {
             prompt: options.input.text,
-            conversationHistory: options.conversationHistory,
+            conversationHistory: options.conversationMessages
+                ?.filter((m) => m.role === "user" || m.role === "assistant")
+                .map((m) => ({
+                role: m.role,
+                content: typeof m.content === "string"
+                    ? m.content
+                    : JSON.stringify(m.content),
+            })) ??
+                options.conversationHistory,
             timeout: options.timeout,
             verbose: false,
             metadata: options.context,
@@ -5046,6 +5149,7 @@ Current user's request: ${currentInput}`;
             model: options.model,
             temperature: options.temperature,
             maxTokens: options.maxTokens,
+            conversationMessages: options.conversationMessages,
         });
         // Create a wrapper around the fallback stream that accumulates content
         let fallbackAccumulatedContent = "";
@@ -8396,6 +8500,19 @@ Current user's request: ${currentInput}`;
                 cleanupErrors.push(err);
                 logger.warn("[NeuroLink] Error clearing caches:", error);
             }
+            // 5b. Shutdown TaskManager
+            if (this._taskManager) {
+                try {
+                    logger.debug("[NeuroLink] Shutting down TaskManager...");
+                    await withTimeout(this._taskManager.shutdown(), 5000, new Error("TaskManager shutdown timed out"));
+                }
+                catch (error) {
+                    logger.warn("[NeuroLink] TaskManager shutdown error:", error);
+                }
+                finally {
+                    this._taskManager = undefined;
+                }
+            }
             // 6. Reset initialization flags
             try {
                 logger.debug("[NeuroLink] Resetting initialization state...");

package/dist/tasks/backends/bullmqBackend.d.ts

@@ -0,0 +1,32 @@
+/**
+ * BullMQ Backend — Production-grade task scheduling via Redis.
+ *
+ * - Cron tasks → BullMQ repeatable jobs with cron pattern
+ * - Interval tasks → BullMQ repeatable jobs with `every` option
+ * - One-shot tasks → BullMQ delayed jobs
+ * - Survives process restarts (Redis-persisted)
+ */
+import { type Task, type TaskBackend, type TaskExecutorFn, type TaskManagerConfig } from "../../types/taskTypes.js";
+export declare class BullMQBackend implements TaskBackend {
+    readonly name = "bullmq";
+    private queue;
+    private worker;
+    private executors;
+    private config;
+    constructor(config: TaskManagerConfig);
+    initialize(): Promise<void>;
+    shutdown(): Promise<void>;
+    schedule(task: Task, executor: TaskExecutorFn): Promise<void>;
+    cancel(taskId: string): Promise<void>;
+    pause(taskId: string): Promise<void>;
+    resume(taskId: string): Promise<void>;
+    isHealthy(): Promise<boolean>;
+    /**
+     * Returns a connection options object for BullMQ / ioredis.
+     * When a URL is provided we parse it fully, preserving TLS (`rediss://`),
+     * ACL username, password, db index, and any query-string parameters so
+     * nothing is silently dropped.
+     */
+    private getConnectionConfig;
+    private ensureInitialized;
+}