@lleverage-ai/agent-sdk 0.0.1

package/dist/tools/task.js

@@ -0,0 +1,521 @@
+/**
+ * Task tool for delegating work to specialized subagents.
+ *
+ * Provides a single `task` tool for spawning subagents, similar to Claude Code's
+ * Task tool. Supports both foreground and background execution, as well as
+ * streaming subagents that can write to the parent's data stream.
+ *
+ * @packageDocumentation
+ */
+import { tool } from "ai";
+import { z } from "zod";
+import { createSubagent } from "../subagents.js";
+import { createBackgroundTask, updateBackgroundTask } from "../task-store/index.js";
+// =============================================================================
+// Internal Task Tracking
+// =============================================================================
+/** Task ID counter for uniqueness */
+let taskIdCounter = 0;
+/** Internal storage for background tasks (fallback when no task store) */
+const backgroundTasks = new Map();
+/** Task store instance (if configured) */
+let globalTaskStore;
+/**
+ * Set the global task store for background task persistence.
+ *
+ * @param store - The task store to use
+ * @internal
+ */
+function setGlobalTaskStore(store) {
+    globalTaskStore = store;
+}
+/**
+ * Get a background task by ID.
+ *
+ * @param taskId - The task ID
+ * @returns The tracked task or undefined
+ *
+ * @category Subagents
+ */
+export async function getBackgroundTask(taskId) {
+    if (globalTaskStore) {
+        return globalTaskStore.load(taskId);
+    }
+    return backgroundTasks.get(taskId);
+}
+/**
+ * List all background tasks.
+ *
+ * @param filter - Optional filter by status
+ * @returns Array of all tracked tasks
+ *
+ * @category Subagents
+ */
+export async function listBackgroundTasks(filter) {
+    if (globalTaskStore) {
+        return globalTaskStore.listTasks(filter);
+    }
+    // In-memory fallback
+    const tasks = Array.from(backgroundTasks.values());
+    if (!filter?.status) {
+        return tasks;
+    }
+    const statuses = Array.isArray(filter.status) ? filter.status : [filter.status];
+    return tasks.filter((t) => statuses.includes(t.status));
+}
+/**
+ * Clear completed/failed background tasks.
+ *
+ * Removes tasks older than the expiration time (if using task store)
+ * or all completed/failed tasks (if using in-memory storage).
+ *
+ * @returns Number of tasks cleared
+ *
+ * @category Subagents
+ */
+export async function clearCompletedTasks() {
+    if (globalTaskStore) {
+        return globalTaskStore.cleanup();
+    }
+    // In-memory fallback
+    let cleared = 0;
+    for (const [id, task] of backgroundTasks) {
+        if (task.status === "completed" || task.status === "failed") {
+            backgroundTasks.delete(id);
+            cleared++;
+        }
+    }
+    return cleared;
+}
+/**
+ * Recover running tasks on agent restart.
+ *
+ * When using a task store, this function loads all "running" tasks
+ * and marks them as "failed" since they were interrupted by the restart.
+ *
+ * Call this function when initializing your agent to handle crashed tasks.
+ *
+ * @param store - Optional task store to use. If not provided, uses the global task store.
+ * @returns Number of tasks recovered
+ *
+ * @category Subagents
+ * @example
+ * ```typescript
+ * // On agent startup
+ * const recovered = await recoverRunningTasks();
+ * console.log(`Recovered ${recovered} interrupted tasks`);
+ * ```
+ */
+export async function recoverRunningTasks(store) {
+    const taskStore = store ?? globalTaskStore;
+    if (!taskStore) {
+        return 0; // No recovery needed for in-memory tasks
+    }
+    const runningTasks = await taskStore.listTasks({ status: "running" });
+    let recovered = 0;
+    for (const task of runningTasks) {
+        const updated = updateBackgroundTask(task, {
+            status: "failed",
+            error: "Task interrupted by agent restart",
+            completedAt: new Date().toISOString(),
+        });
+        await taskStore.save(updated);
+        recovered++;
+    }
+    return recovered;
+}
+/**
+ * Recover failed tasks for retry.
+ *
+ * Loads all "failed" tasks from the store and returns them for inspection
+ * or automatic retry. Applications can decide which tasks to retry based
+ * on error type, retry count, or other criteria.
+ *
+ * To retry a task, update its status back to "pending" and process it
+ * through your task execution logic.
+ *
+ * @param store - The task store to query
+ * @param options - Optional filter options
+ * @returns Array of failed tasks
+ *
+ * @category Subagents
+ * @example
+ * ```typescript
+ * // Load failed tasks and retry those with transient errors
+ * const failedTasks = await recoverFailedTasks(taskStore);
+ *
+ * for (const task of failedTasks) {
+ *   // Check if error is retryable
+ *   if (task.error?.includes("timeout") || task.error?.includes("network")) {
+ *     // Mark for retry
+ *     const retryTask = updateBackgroundTask(task, {
+ *       status: "pending",
+ *       error: undefined,
+ *     });
+ *     await taskStore.save(retryTask);
+ *   }
+ * }
+ * ```
+ */
+export async function recoverFailedTasks(store, options) {
+    const failedTasks = await store.listTasks({ status: "failed" });
+    let filtered = failedTasks;
+    // Apply error pattern filter
+    if (options?.errorPattern) {
+        filtered = filtered.filter((task) => task.error && options.errorPattern.test(task.error));
+    }
+    // Apply date range filters
+    if (options?.minCreatedAt) {
+        const minTime = options.minCreatedAt.getTime();
+        filtered = filtered.filter((task) => new Date(task.createdAt).getTime() >= minTime);
+    }
+    if (options?.maxCreatedAt) {
+        const maxTime = options.maxCreatedAt.getTime();
+        filtered = filtered.filter((task) => new Date(task.createdAt).getTime() <= maxTime);
+    }
+    return filtered;
+}
+/**
+ * Clean up stale tasks from the task store.
+ *
+ * Removes tasks that have been in a terminal state (completed or failed)
+ * for longer than the specified age. This prevents unbounded storage growth
+ * and maintains system health.
+ *
+ * @param store - The task store to clean
+ * @param maxAge - Maximum age in milliseconds for terminal tasks
+ * @returns Number of tasks cleaned up
+ *
+ * @category Subagents
+ * @example
+ * ```typescript
+ * // Clean up tasks older than 7 days
+ * const sevenDays = 7 * 24 * 60 * 60 * 1000;
+ * const cleaned = await cleanupStaleTasks(taskStore, sevenDays);
+ * console.log(`Cleaned up ${cleaned} stale tasks`);
+ *
+ * // Or use a shorter retention for testing
+ * const oneHour = 60 * 60 * 1000;
+ * await cleanupStaleTasks(taskStore, oneHour);
+ * ```
+ */
+export async function cleanupStaleTasks(store, maxAge) {
+    const terminalTasks = await store.listTasks({
+        status: ["completed", "failed"],
+    });
+    let cleaned = 0;
+    const now = Date.now();
+    for (const task of terminalTasks) {
+        // Use completedAt if available, otherwise use updatedAt
+        const timestampStr = task.completedAt ?? task.updatedAt;
+        const taskTime = new Date(timestampStr).getTime();
+        const age = now - taskTime;
+        if (age > maxAge) {
+            await store.delete(task.id);
+            cleaned++;
+        }
+    }
+    return cleaned;
+}
+// =============================================================================
+// Helper Functions
+// =============================================================================
+/**
+ * Default general-purpose subagent definition.
+ * @internal
+ */
+function createGeneralPurposeSubagent(parentAgent, model, systemPrompt) {
+    return {
+        type: "general-purpose",
+        description: "General-purpose agent for diverse tasks. Use when no specialized agent fits.",
+        model: model, // Will use context.model if not specified
+        create: (ctx) => createSubagent(parentAgent, {
+            name: "general-purpose",
+            description: "General-purpose subagent",
+            model: ctx.model,
+            allowedTools: ctx.allowedTools,
+            systemPrompt: systemPrompt ??
+                `You are a general-purpose assistant. Complete the requested task thoroughly and return a clear summary of what was accomplished.`,
+        }),
+    };
+}
+// =============================================================================
+// Task Tool
+// =============================================================================
+/**
+ * Creates the task tool for delegating work to specialized subagents.
+ *
+ * This tool delegates tasks to subagents with isolated context. It supports
+ * both foreground (blocking) and background execution.
+ *
+ * @param options - Configuration options
+ * @returns An AI SDK tool for task delegation
+ *
+ * @example
+ * ```typescript
+ * import { createTaskTool } from "@lleverage-ai/agent-sdk";
+ *
+ * const task = createTaskTool({
+ *   subagents: [
+ *     {
+ *       type: "researcher",
+ *       description: "Searches for information",
+ *       create: () => createSubagent(parentAgent, { ... }),
+ *     },
+ *     {
+ *       type: "coder",
+ *       description: "Writes and modifies code",
+ *       create: () => createSubagent(parentAgent, { ... }),
+ *     },
+ *   ],
+ *   defaultModel: anthropic("claude-sonnet-4-20250514"),
+ *   parentAgent,
+ *   includeGeneralPurpose: true,
+ * });
+ *
+ * const agent = createAgent({
+ *   model,
+ *   tools: { task },
+ * });
+ * ```
+ *
+ * @category Subagents
+ */
+export function createTaskTool(options) {
+    const { subagents: userSubagents, defaultModel, parentAgent, defaultMaxTurns = 10, includeGeneralPurpose = false, generalPurposeModel, generalPurposePrompt, streamingContext, taskStore, parentSpanContext, } = options;
+    // Set the global task store for persistence
+    setGlobalTaskStore(taskStore);
+    // Build subagent list (optionally include general-purpose)
+    const subagents = [...userSubagents];
+    if (includeGeneralPurpose) {
+        subagents.push(createGeneralPurposeSubagent(parentAgent, generalPurposeModel, generalPurposePrompt));
+    }
+    // Build subagent type enum and descriptions
+    const subagentTypes = subagents.map((s) => s.type);
+    const subagentDescriptions = subagents.map((s) => `- ${s.type}: ${s.description}`).join("\n");
+    const toolDescription = options.description ??
+        `Delegate a task to a specialized subagent. Each subagent runs with isolated context.\n\nAvailable subagent types:\n${subagentDescriptions}`;
+    return tool({
+        description: toolDescription,
+        inputSchema: z.object({
+            description: z.string().describe("The task description for the subagent"),
+            subagent_type: z
+                .enum(subagentTypes)
+                .describe("The type of subagent to use"),
+            max_turns: z
+                .number()
+                .optional()
+                .describe(`Maximum turns for the subagent (default: ${defaultMaxTurns})`),
+            run_in_background: z
+                .boolean()
+                .optional()
+                .describe("Run the task in background without blocking. Returns task ID for later retrieval via get_task_result action."),
+        }),
+        execute: async (params) => {
+            const { description, subagent_type, max_turns, run_in_background } = params;
+            // Find the subagent definition
+            const subagentDef = subagents.find((s) => s.type === subagent_type);
+            if (!subagentDef) {
+                return { error: `Unknown subagent type: ${subagent_type}` };
+            }
+            // Create task entry
+            const taskId = `task-${++taskIdCounter}-${Date.now()}`;
+            const task = createBackgroundTask({
+                id: taskId,
+                subagentType: subagent_type,
+                description,
+            });
+            // Check if this is a streaming subagent
+            const isStreamingSubagent = subagentDef.streaming === true && streamingContext?.writer != null;
+            // Execute task function
+            const executeTask = async () => {
+                const startTime = Date.now();
+                // Update task status to running
+                const runningTask = updateBackgroundTask(task, { status: "running" });
+                if (taskStore) {
+                    await taskStore.save(runningTask);
+                }
+                else {
+                    backgroundTasks.set(taskId, runningTask);
+                }
+                Object.assign(task, runningTask);
+                // Determine the model to use
+                // Priority: subagentDef.model > defaultModel > parentAgent.model
+                let subagentModel = defaultModel;
+                if (subagentDef.model && subagentDef.model !== "inherit") {
+                    subagentModel = subagentDef.model;
+                }
+                // Build streaming metadata for this subagent
+                const subagentMetadata = {
+                    agentType: subagent_type,
+                    agentId: taskId,
+                    parentAgentId: streamingContext?.metadata?.agentId,
+                };
+                // Build context for the subagent factory
+                const createContext = {
+                    model: subagentModel,
+                    allowedTools: subagentDef.allowedTools,
+                    plugins: subagentDef.plugins,
+                    // Only pass streaming context if this is a streaming subagent
+                    streamingContext: isStreamingSubagent
+                        ? {
+                            writer: streamingContext.writer,
+                            metadata: subagentMetadata,
+                        }
+                        : undefined,
+                    // Pass parent span context for distributed tracing
+                    parentSpanContext,
+                };
+                // Create the subagent with resolved context
+                const subagent = await subagentDef.create(createContext);
+                // Wait for subagent's async initialization (MCP connections, plugin setup)
+                await subagent.ready;
+                let resultText;
+                if (isStreamingSubagent) {
+                    // Streaming execution - send subagent output as data chunks
+                    // This keeps the output separate from the assistant message content
+                    // Signal subagent start to client
+                    streamingContext.writer.write({
+                        type: "data-subagent-stream",
+                        data: {
+                            event: "start",
+                            ...subagentMetadata,
+                            prompt: description,
+                        },
+                    });
+                    // Stream the subagent's response
+                    const streamResult = await subagent.streamRaw({
+                        prompt: description,
+                        maxTokens: (max_turns ?? defaultMaxTurns) * 4096,
+                    });
+                    // Stream text chunks as data instead of merging into message
+                    // This allows the client to handle them separately from assistant text
+                    let fullText = "";
+                    for await (const chunk of streamResult.textStream) {
+                        fullText += chunk;
+                        // Send each chunk as a data annotation
+                        streamingContext.writer.write({
+                            type: "data-subagent-stream",
+                            data: {
+                                event: "chunk",
+                                ...subagentMetadata,
+                                chunk,
+                            },
+                        });
+                    }
+                    resultText = fullText;
+                    // Signal subagent completion to client
+                    streamingContext.writer.write({
+                        type: "data-subagent-stream",
+                        data: {
+                            event: "complete",
+                            ...subagentMetadata,
+                            text: resultText,
+                            duration: Date.now() - startTime,
+                        },
+                    });
+                }
+                else {
+                    // Non-streaming execution - use generate() as before
+                    const result = await subagent.generate({
+                        prompt: description,
+                        maxTokens: (max_turns ?? defaultMaxTurns) * 4096,
+                    });
+                    resultText =
+                        result.status === "complete" ? result.text : `Interrupted: ${result.interrupt.type}`;
+                }
+                return resultText;
+            };
+            // Background execution
+            if (run_in_background) {
+                // Streaming subagents cannot run in background
+                if (isStreamingSubagent) {
+                    return {
+                        error: true,
+                        taskId,
+                        message: `Streaming subagent "${subagent_type}" cannot run in background. Remove run_in_background or use a non-streaming subagent.`,
+                    };
+                }
+                // Save initial task state
+                if (taskStore) {
+                    await taskStore.save(task);
+                }
+                else {
+                    backgroundTasks.set(taskId, task);
+                }
+                // Start execution without awaiting
+                executeTask()
+                    .then(async (resultText) => {
+                    const completedTask = updateBackgroundTask(task, {
+                        status: "completed",
+                        result: resultText,
+                        completedAt: new Date().toISOString(),
+                    });
+                    if (taskStore) {
+                        await taskStore.save(completedTask);
+                    }
+                    else {
+                        backgroundTasks.set(taskId, completedTask);
+                    }
+                    Object.assign(task, completedTask);
+                })
+                    .catch(async (error) => {
+                    const errorMessage = error instanceof Error ? error.message : String(error);
+                    const failedTask = updateBackgroundTask(task, {
+                        status: "failed",
+                        error: errorMessage,
+                        completedAt: new Date().toISOString(),
+                    });
+                    if (taskStore) {
+                        await taskStore.save(failedTask);
+                    }
+                    else {
+                        backgroundTasks.set(taskId, failedTask);
+                    }
+                    Object.assign(task, failedTask);
+                });
+                return {
+                    taskId,
+                    status: "running",
+                    message: `Task started in background. Use task tool with action "get_result" and taskId "${taskId}" to retrieve the result later.`,
+                };
+            }
+            // Foreground execution (blocking)
+            try {
+                const resultText = await executeTask();
+                const completedTask = updateBackgroundTask(task, {
+                    status: "completed",
+                    result: resultText,
+                    completedAt: new Date().toISOString(),
+                });
+                // Optional persistence for foreground tasks
+                if (taskStore) {
+                    await taskStore.save(completedTask);
+                }
+                return {
+                    success: true,
+                    taskId,
+                    text: resultText,
+                };
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                const failedTask = updateBackgroundTask(task, {
+                    status: "failed",
+                    error: errorMessage,
+                    completedAt: new Date().toISOString(),
+                });
+                // Optional persistence for foreground tasks
+                if (taskStore) {
+                    await taskStore.save(failedTask);
+                }
+                return {
+                    error: true,
+                    taskId,
+                    message: errorMessage,
+                };
+            }
+        },
+    });
+}
+//# sourceMappingURL=task.js.map

package/dist/tools/task.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task.js","sourceRoot":"","sources":["../../src/tools/task.ts"],"names":[],"mappings":"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"}

package/dist/tools/todos.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Todo tool for task planning and tracking.
+ *
+ * Provides a single `todo_write` tool for managing task lists, similar to
+ * Claude Code's TodoWrite. Agents replace the entire todo list with each call.
+ *
+ * @packageDocumentation
+ */
+import type { AgentState, TodoStatus } from "../backends/state.js";
+/**
+ * Type of change that occurred to the todo list.
+ *
+ * @category Tools
+ */
+export type TodoChangeType = "replaced" | "cleared";
+/**
+ * Data for todo change events.
+ *
+ * @category Tools
+ */
+export interface TodosChangedData {
+    /** Discriminator type */
+    type: "todosChanged";
+    /** Type of change */
+    changeType: TodoChangeType;
+    /** IDs of affected todos */
+    affectedIds: string[];
+    /** Total count of todos */
+    totalCount: number;
+    /** Summary of current todos */
+    summary: {
+        pending: number;
+        inProgress: number;
+        completed: number;
+    };
+}
+/**
+ * Callback type for todo change events.
+ *
+ * When provided to the todo tool, this callback is invoked whenever the todo list changes.
+ * This enables integration with the hook system for emitting `todos:changed` events.
+ *
+ * @param data - The change event data
+ *
+ * @category Tools
+ */
+export type OnTodosChanged = (data: TodosChangedData) => void | Promise<void>;
+/**
+ * Input for a todo item.
+ *
+ * @category Tools
+ */
+export interface TodoInput {
+    /** Description of the task */
+    content: string;
+    /** Current status of the task */
+    status: TodoStatus;
+}
+/**
+ * Options for creating the todo_write tool.
+ *
+ * @category Tools
+ */
+export interface TodoWriteToolOptions {
+    /** The agent state containing the todo list */
+    state: AgentState;
+    /**
+     * Callback invoked when todos change.
+     *
+     * Use this to integrate with the hook system for emitting `todos:changed` events.
+     *
+     * @example
+     * ```typescript
+     * const todoWrite = createTodoWriteTool({
+     *   state,
+     *   onTodosChanged: (data) => {
+     *     console.log("Todos changed:", data);
+     *   },
+     * });
+     * ```
+     */
+    onTodosChanged?: OnTodosChanged;
+}
+/**
+ * Creates the todo_write tool for managing task lists.
+ *
+ * This tool replaces the entire todo list with the provided items. It's designed
+ * to match Claude Code's TodoWrite behavior where the agent always provides the
+ * complete list state.
+ *
+ * @param options - Configuration options
+ * @returns An AI SDK compatible tool for writing todos
+ *
+ * @example
+ * ```typescript
+ * import { createTodoWriteTool, createAgentState } from "@lleverage-ai/agent-sdk";
+ *
+ * const state = createAgentState();
+ * const todoWrite = createTodoWriteTool({ state });
+ *
+ * const agent = createAgent({
+ *   model,
+ *   tools: { todo_write: todoWrite },
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With change callback for UI integration
+ * const todoWrite = createTodoWriteTool({
+ *   state,
+ *   onTodosChanged: (data) => {
+ *     console.log(`Todos updated: ${data.summary.completed}/${data.totalCount} completed`);
+ *   },
+ * });
+ * ```
+ *
+ * @category Tools
+ */
+export declare function createTodoWriteTool(options: TodoWriteToolOptions): import("ai").Tool<{
+    todos: TodoInput[];
+}, {
+    success: boolean;
+    count: number;
+    summary: {
+        pending: number;
+        inProgress: number;
+        completed: number;
+    };
+}>;
+//# sourceMappingURL=todos.d.ts.map

package/dist/tools/todos.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"todos.d.ts","sourceRoot":"","sources":["../../src/tools/todos.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAY,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAM7E;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,SAAS,CAAC;AAEpD;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,yBAAyB;IACzB,IAAI,EAAE,cAAc,CAAC;IACrB,qBAAqB;IACrB,UAAU,EAAE,cAAc,CAAC;IAC3B,4BAA4B;IAC5B,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,2BAA2B;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,+BAA+B;IAC/B,OAAO,EAAE;QACP,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,IAAI,EAAE,gBAAgB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE9E;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAC;IAEhB,iCAAiC;IACjC,MAAM,EAAE,UAAU,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,+CAA+C;IAC/C,KAAK,EAAE,UAAU,CAAC;IAElB;;;;;;;;;;;;;;OAcG;IACH,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AA6CD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB;WAczB,SAAS,EAAE;;;;;iBAvJtC,MAAM;oBACH,MAAM;mBACP,MAAM;;GA+LpB"}