@juspay/neurolink 9.40.0 → 9.41.0

package/dist/tasks/tools/taskTools.js

@@ -0,0 +1,273 @@
+/**
+ * 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 { tool } from "ai";
+import { z } from "zod";
+import { logger } from "../../utils/logger.js";
+import { TaskError } from "../errors.js";
+/**
+ * Parse a schedule object from tool input.
+ * Accepts: { type: "cron", expression } | { type: "interval", every } | { type: "once", at }
+ */
+function parseSchedule(input) {
+    const type = input.type;
+    if (type === "cron") {
+        if (!input.expression || typeof input.expression !== "string") {
+            throw TaskError.create("SCHEDULE_FAILED", "Cron schedule requires an 'expression' field");
+        }
+        return {
+            type: "cron",
+            expression: input.expression,
+            ...(input.timezone ? { timezone: input.timezone } : {}),
+        };
+    }
+    if (type === "interval") {
+        if (typeof input.every !== "number" ||
+            !isFinite(input.every) ||
+            input.every <= 0) {
+            throw TaskError.create("SCHEDULE_FAILED", "Interval schedule requires a positive 'every' field (milliseconds)");
+        }
+        return { type: "interval", every: input.every };
+    }
+    if (type === "once") {
+        if (!input.at) {
+            throw TaskError.create("SCHEDULE_FAILED", "Once schedule requires an 'at' field (ISO 8601 date string)");
+        }
+        return { type: "once", at: input.at };
+    }
+    throw TaskError.create("SCHEDULE_FAILED", `Invalid schedule type: "${type}". Must be "cron", "interval", or "once".`);
+}
+/**
+ * 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 function createTaskTools(manager) {
+    return {
+        createTask: tool({
+            description: 'Schedule a recurring or one-shot task that runs a prompt on a schedule. Use schedule type "cron" for calendar-based (e.g. "0 9 * * *"), "interval" for fixed frequency (every N milliseconds), or "once" for a single future execution.',
+            inputSchema: z.object({
+                name: z.string().describe("Human-readable task name"),
+                prompt: z.string().describe("The prompt to execute on each run"),
+                schedule: z
+                    .object({
+                    type: z.enum(["cron", "interval", "once"]),
+                    expression: z
+                        .string()
+                        .optional()
+                        .describe('Cron expression (for type "cron"), e.g. "0 9 * * *"'),
+                    timezone: z
+                        .string()
+                        .optional()
+                        .describe('IANA timezone for cron, e.g. "America/New_York"'),
+                    every: z
+                        .number()
+                        .optional()
+                        .describe('Interval in milliseconds (for type "interval")'),
+                    at: z
+                        .string()
+                        .optional()
+                        .describe('ISO 8601 timestamp (for type "once")'),
+                })
+                    .describe("When to run the task"),
+                mode: z
+                    .enum(["isolated", "continuation"])
+                    .optional()
+                    .describe('Execution mode. "isolated" = fresh context per run (default). "continuation" = preserves conversation history across runs.'),
+            }),
+            execute: async ({ name, prompt, schedule, mode }) => {
+                try {
+                    const parsedSchedule = parseSchedule(schedule);
+                    const task = await manager.create({
+                        name,
+                        prompt,
+                        schedule: parsedSchedule,
+                        mode: mode,
+                    });
+                    return {
+                        success: true,
+                        taskId: task.id,
+                        name: task.name,
+                        status: task.status,
+                        mode: task.mode,
+                        nextRunAt: task.nextRunAt,
+                        schedule: task.schedule,
+                    };
+                }
+                catch (error) {
+                    logger.error("[taskTools] createTask failed", {
+                        error: String(error),
+                    });
+                    return {
+                        success: false,
+                        error: error instanceof Error ? error.message : String(error),
+                    };
+                }
+            },
+        }),
+        listTasks: tool({
+            description: "List all scheduled tasks and their current status.",
+            inputSchema: z.object({
+                status: z
+                    .enum([
+                    "active",
+                    "paused",
+                    "completed",
+                    "failed",
+                    "cancelled",
+                    "pending",
+                ])
+                    .optional()
+                    .describe("Filter by task status"),
+            }),
+            execute: async ({ status }) => {
+                try {
+                    const tasks = await manager.list(status
+                        ? {
+                            status: status,
+                        }
+                        : undefined);
+                    return {
+                        success: true,
+                        count: tasks.length,
+                        tasks: tasks.map((t) => ({
+                            taskId: t.id,
+                            name: t.name,
+                            status: t.status,
+                            mode: t.mode,
+                            schedule: t.schedule,
+                            runCount: t.runCount,
+                            lastRunAt: t.lastRunAt,
+                            nextRunAt: t.nextRunAt,
+                        })),
+                    };
+                }
+                catch (error) {
+                    logger.error("[taskTools] listTasks failed", {
+                        error: String(error),
+                    });
+                    return {
+                        success: false,
+                        error: error instanceof Error ? error.message : String(error),
+                    };
+                }
+            },
+        }),
+        getTaskRuns: tool({
+            description: "Get the run history of a scheduled task, showing recent executions and their results.",
+            inputSchema: z.object({
+                taskId: z.string().describe("The task ID"),
+                limit: z
+                    .number()
+                    .optional()
+                    .describe("Max results to return (default: 10)"),
+            }),
+            execute: async ({ taskId, limit }) => {
+                try {
+                    const runs = await manager.runs(taskId, { limit: limit ?? 10 });
+                    return {
+                        success: true,
+                        taskId,
+                        count: runs.length,
+                        runs: runs.map((r) => ({
+                            runId: r.runId,
+                            status: r.status,
+                            output: r.output
+                                ? r.output.length > 500
+                                    ? r.output.slice(0, 500) + "..."
+                                    : r.output
+                                : undefined,
+                            durationMs: r.durationMs,
+                            timestamp: r.timestamp,
+                            error: r.error,
+                        })),
+                    };
+                }
+                catch (error) {
+                    logger.error("[taskTools] getTaskRuns failed", {
+                        error: String(error),
+                    });
+                    return {
+                        success: false,
+                        error: error instanceof Error ? error.message : String(error),
+                    };
+                }
+            },
+        }),
+        deleteTask: tool({
+            description: "Cancel and permanently remove a scheduled task.",
+            inputSchema: z.object({
+                taskId: z.string().describe("The task ID to delete"),
+            }),
+            execute: async ({ taskId }) => {
+                try {
+                    const task = await manager.get(taskId);
+                    if (!task) {
+                        return { success: false, error: `Task not found: ${taskId}` };
+                    }
+                    await manager.delete(taskId);
+                    return { success: true, deletedTask: task.name, taskId };
+                }
+                catch (error) {
+                    logger.error("[taskTools] deleteTask failed", {
+                        error: String(error),
+                    });
+                    return {
+                        success: false,
+                        error: error instanceof Error ? error.message : String(error),
+                    };
+                }
+            },
+        }),
+        runTaskNow: tool({
+            description: "Immediately execute a scheduled task outside of its normal schedule. Returns the run result.",
+            inputSchema: z.object({
+                taskId: z.string().describe("The task ID to run"),
+            }),
+            execute: async ({ taskId }) => {
+                try {
+                    const result = await manager.run(taskId);
+                    return {
+                        success: true,
+                        runId: result.runId,
+                        status: result.status,
+                        output: result.output
+                            ? result.output.length > 1000
+                                ? result.output.slice(0, 1000) + "..."
+                                : result.output
+                            : undefined,
+                        durationMs: result.durationMs,
+                        error: result.error,
+                    };
+                }
+                catch (error) {
+                    logger.error("[taskTools] runTaskNow failed", {
+                        error: String(error),
+                    });
+                    return {
+                        success: false,
+                        error: error instanceof Error ? error.message : String(error),
+                    };
+                }
+            },
+        }),
+    };
+}

package/dist/types/configTypes.d.ts

@@ -3,6 +3,7 @@
  * Centralized configuration type definitions following the established architecture pattern
  */
 import { MCPToolRegistry } from "../mcp/toolRegistry.js";
+import type { TaskManagerConfig } from "./taskTypes.js";
 import type { HITLConfig } from "../types/hitlTypes.js";
 import type { ConversationMemoryConfig } from "./conversation.js";
 import type { ObservabilityConfig } from "./observability.js";
@@ -36,6 +37,8 @@ export type NeurolinkConstructorConfig = {
     mcp?: MCPEnhancementsConfig;
     /** Authentication provider configuration */
     auth?: NeuroLinkAuthConfig;
+    /** TaskManager configuration (scheduled and self-running tasks) */
+    tasks?: TaskManagerConfig;
 };
 /**
  * Configuration for MCP enhancement modules wired into generate()/stream() paths.

package/dist/types/generateTypes.d.ts

@@ -315,10 +315,23 @@ export type GenerateOptions = {
     context?: StandardRecord;
     evaluationDomain?: string;
     toolUsageContext?: string;
+    /**
+     * @deprecated Use `conversationMessages` instead. This field uses a simple `{role, content}` shape
+     * that is not consumed by `buildMessagesArray()` — messages passed here will NOT reach the AI model
+     * as proper conversation turns. `conversationMessages` uses the full `ChatMessage` type and is
+     * correctly wired through the entire generate pipeline.
+     */
     conversationHistory?: Array<{
         role: string;
         content: string;
     }>;
+    /**
+     * Previous conversation as a ChatMessage array.
+     * Messages are injected as proper multi-turn conversation history before the current prompt,
+     * so the AI model sees them as real prior exchanges (not text dumped into the prompt).
+     * Used by task continuation mode and available to external callers.
+     */
+    conversationMessages?: ChatMessage[];
     factoryConfig?: {
         domainType?: string;
         domainConfig?: StandardRecord;

package/dist/types/index.d.ts

@@ -46,3 +46,4 @@ export type { ClientConfig, RequestOptions as ClientRequestOptions, RetryConfig
 export type { TokenRefresher } from "./subscriptionTypes.js";
 export * from "./proxyTypes.js";
 export type { AuthProviderType, AuthProviderConfig, MastraAuthProvider, BetterAuthConfig, Auth0Config, ClerkConfig, FirebaseConfig, SupabaseConfig, WorkOSConfig, JWTConfig, OAuth2Config, CognitoConfig, KeycloakConfig, CustomAuthConfig, BaseAuthProviderConfig, AuthUser, AuthSession, TokenType, TokenValidationResult as AuthTokenValidationResult, TokenClaims, JWK, JWKS, TokenRefreshResult, TokenValidationConfig, TokenExtractionConfig, SessionValidationResult, SessionStorage, AuthorizationResult, AuthRequestContext, AuthenticatedContext, TokenExtractionStrategy, SessionConfig, SessionStorageType, RBACConfig, PermissionDefinition, AuthCacheConfig, AuthMiddlewareOptions, AuthMiddlewareConfig, RBACMiddlewareConfig, AuthErrorCode, AuthErrorInfo, AuthErrorInfo as AuthErrorType, AuthEventType, AuthEventData, AuthEventHandler, AuthProviderFactoryFn, AuthProviderRegistration, AuthHealthCheck, AuthProviderHealthCheck, AuthEvents, AuthProviderMetadata, AuthProviderHealthStatus, AuthTokenValidator, AuthUserAuthorizer, AuthSessionManager, AuthRequestHandler, AuthUserManager, AuthLifecycle, } from "./authTypes.js";
+export type { Task, TaskDefinition, TaskSchedule, TaskScheduleType, CronSchedule, IntervalSchedule, OnceSchedule, TaskExecutionMode, TaskStatus, TaskRunResult, TaskRunError, TaskStore, TaskBackend, TaskBackendName, TaskManagerConfig, TaskRetentionConfig, ConversationEntry as TaskConversationEntry, } from "./taskTypes.js";

package/dist/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/types/taskTypes.js

@@ -0,0 +1,36 @@
+/**
+ * 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,
+    },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "9.40.0",
+  "version": "9.41.0",
   "description": "Universal AI Development Platform with working MCP integration, multi-provider support, and professional CLI. Built-in tools operational, 58+ external MCP servers discoverable. Connect to filesystem, GitHub, database operations, and more. Build, test, and deploy AI applications with 13 providers: OpenAI, Anthropic, Google AI, AWS Bedrock, Azure, Hugging Face, Ollama, and Mistral AI.",
   "author": {
     "name": "Juspay Technologies",
@@ -212,6 +212,8 @@
     "@opentelemetry/semantic-conventions": "^1.40.0",
     "adm-zip": "^0.5.16",
     "ai": "^6.0.134",
+    "bullmq": "^5.52.2",
+    "croner": "^9.1.0",
     "chalk": "^5.6.2",
     "csv-parser": "^3.2.0",
     "dotenv": "^17.3.1",