@compilr-dev/agents 0.0.1

package/dist/tools/builtin/todo.d.ts

@@ -0,0 +1,207 @@
+/**
+ * Todo Tools - Task management for agents
+ *
+ * Provides in-memory task tracking with TodoRead and TodoWrite tools.
+ * Useful for planning and tracking multi-step tasks.
+ */
+import type { Tool } from '../types.js';
+/**
+ * Task status
+ */
+export type TodoStatus = 'pending' | 'in_progress' | 'completed';
+/**
+ * A single todo item
+ */
+export interface TodoItem {
+    /**
+     * Unique identifier for the todo
+     */
+    id: string;
+    /**
+     * Task content/description (imperative form)
+     */
+    content: string;
+    /**
+     * Current status of the task
+     */
+    status: TodoStatus;
+    /**
+     * Active form of the task (present continuous, e.g., "Implementing feature")
+     */
+    activeForm?: string;
+    /**
+     * Optional priority (higher = more important)
+     */
+    priority?: number;
+    /**
+     * Creation timestamp
+     */
+    createdAt: Date;
+    /**
+     * Last update timestamp
+     */
+    updatedAt: Date;
+}
+/**
+ * Input for TodoWrite tool
+ */
+export interface TodoWriteInput {
+    /**
+     * The complete list of todos (replaces existing list)
+     */
+    todos: Array<{
+        content: string;
+        status: TodoStatus;
+        activeForm?: string;
+        priority?: number;
+    }>;
+}
+/**
+ * Input for TodoRead tool
+ */
+export interface TodoReadInput {
+    /**
+     * Filter by status (optional)
+     */
+    status?: TodoStatus;
+    /**
+     * Include completed tasks (default: true)
+     */
+    includeCompleted?: boolean;
+}
+/**
+ * TodoStore manages the in-memory task list
+ */
+export declare class TodoStore {
+    private readonly todos;
+    private nextId;
+    /**
+     * Get all todos
+     */
+    getAll(): TodoItem[];
+    /**
+     * Get todos filtered by status
+     */
+    getByStatus(status: TodoStatus): TodoItem[];
+    /**
+     * Replace all todos with a new list
+     */
+    setAll(todos: Array<{
+        content: string;
+        status: TodoStatus;
+        activeForm?: string;
+        priority?: number;
+    }>): void;
+    /**
+     * Add a single todo
+     */
+    add(todo: {
+        content: string;
+        status: TodoStatus;
+        activeForm?: string;
+        priority?: number;
+    }): TodoItem;
+    /**
+     * Update a todo by ID
+     */
+    update(id: string, updates: Partial<Omit<TodoItem, 'id' | 'createdAt'>>): TodoItem | null;
+    /**
+     * Remove a todo by ID
+     */
+    remove(id: string): boolean;
+    /**
+     * Clear all todos
+     */
+    clear(): void;
+    /**
+     * Get count by status
+     */
+    getCounts(): Record<TodoStatus, number>;
+}
+/**
+ * TodoWrite tool - Update the task list
+ */
+export declare const todoWriteTool: Tool<TodoWriteInput>;
+/**
+ * TodoRead tool - Get the current task list
+ */
+export declare const todoReadTool: Tool<TodoReadInput>;
+/**
+ * Factory to create todo tools with a custom store
+ */
+export declare function createTodoTools(store?: TodoStore): {
+    todoWrite: Tool<TodoWriteInput>;
+    todoRead: Tool<TodoReadInput>;
+    store: TodoStore;
+};
+/**
+ * Reset the default store (useful for testing)
+ */
+export declare function resetDefaultTodoStore(): void;
+/**
+ * Get the default store (useful for testing or direct access)
+ */
+export declare function getDefaultTodoStore(): TodoStore;
+/**
+ * Create a new isolated TodoStore instance.
+ *
+ * Use this when you need state isolation between parallel operations,
+ * such as concurrent sub-agent executions. This prevents state leakage
+ * between parallel runs.
+ *
+ * Inspired by LangGraph issue #6446: Parallel subgraphs with shared
+ * state keys cause InvalidUpdateError.
+ *
+ * @example
+ * ```typescript
+ * // For parallel sub-agents, create isolated stores
+ * const store1 = createIsolatedTodoStore();
+ * const store2 = createIsolatedTodoStore();
+ *
+ * // Each sub-agent uses its own store
+ * await Promise.all([
+ *   runWithStore(store1, task1),
+ *   runWithStore(store2, task2),
+ * ]);
+ * ```
+ */
+export declare function createIsolatedTodoStore(): TodoStore;
+/**
+ * Context cleanup options for todo tool calls
+ */
+export interface TodoContextCleanupOptions {
+    /**
+     * Keep only the last N todo_write calls (default: 1)
+     */
+    keepLastN?: number;
+    /**
+     * Also clean up todo_read calls (default: false)
+     */
+    cleanReads?: boolean;
+}
+/**
+ * Filter messages to remove redundant todo tool calls.
+ * This helps prevent context bloat from repeated todo_write calls.
+ *
+ * The function keeps only the last N todo_write calls (default: 1),
+ * removing earlier ones to reduce context size.
+ *
+ * @param messages - Array of messages to filter
+ * @param options - Cleanup options
+ * @returns Filtered messages with redundant todo calls removed
+ */
+export declare function cleanupTodoContextMessages<T extends {
+    role: string;
+    content: unknown;
+}>(messages: T[], options?: TodoContextCleanupOptions): T[];
+/**
+ * Get statistics about todo tool usage in messages
+ */
+export declare function getTodoContextStats(messages: Array<{
+    role: string;
+    content: unknown;
+}>): {
+    todoWriteCalls: number;
+    todoReadCalls: number;
+    estimatedTokensSaved: number;
+};

package/dist/tools/builtin/todo.js

@@ -0,0 +1,453 @@
+/**
+ * Todo Tools - Task management for agents
+ *
+ * Provides in-memory task tracking with TodoRead and TodoWrite tools.
+ * Useful for planning and tracking multi-step tasks.
+ */
+import { defineTool, createSuccessResult, createErrorResult } from '../define.js';
+/**
+ * TodoStore manages the in-memory task list
+ */
+export class TodoStore {
+    todos = new Map();
+    nextId = 1;
+    /**
+     * Get all todos
+     */
+    getAll() {
+        return Array.from(this.todos.values()).sort((a, b) => {
+            // Sort by status priority: in_progress > pending > completed
+            const statusOrder = {
+                in_progress: 0,
+                pending: 1,
+                completed: 2,
+            };
+            if (statusOrder[a.status] !== statusOrder[b.status]) {
+                return statusOrder[a.status] - statusOrder[b.status];
+            }
+            // Then by priority (higher first)
+            if ((a.priority ?? 0) !== (b.priority ?? 0)) {
+                return (b.priority ?? 0) - (a.priority ?? 0);
+            }
+            // Then by creation order
+            return a.createdAt.getTime() - b.createdAt.getTime();
+        });
+    }
+    /**
+     * Get todos filtered by status
+     */
+    getByStatus(status) {
+        return this.getAll().filter((t) => t.status === status);
+    }
+    /**
+     * Replace all todos with a new list
+     */
+    setAll(todos) {
+        this.todos.clear();
+        const now = new Date();
+        for (const todo of todos) {
+            const id = `todo-${String(this.nextId++)}`;
+            this.todos.set(id, {
+                id,
+                content: todo.content,
+                status: todo.status,
+                activeForm: todo.activeForm,
+                priority: todo.priority,
+                createdAt: now,
+                updatedAt: now,
+            });
+        }
+    }
+    /**
+     * Add a single todo
+     */
+    add(todo) {
+        const id = `todo-${String(this.nextId++)}`;
+        const now = new Date();
+        const item = {
+            id,
+            content: todo.content,
+            status: todo.status,
+            activeForm: todo.activeForm,
+            priority: todo.priority,
+            createdAt: now,
+            updatedAt: now,
+        };
+        this.todos.set(id, item);
+        return item;
+    }
+    /**
+     * Update a todo by ID
+     */
+    update(id, updates) {
+        const existing = this.todos.get(id);
+        if (!existing)
+            return null;
+        const updated = {
+            ...existing,
+            ...updates,
+            updatedAt: new Date(),
+        };
+        this.todos.set(id, updated);
+        return updated;
+    }
+    /**
+     * Remove a todo by ID
+     */
+    remove(id) {
+        return this.todos.delete(id);
+    }
+    /**
+     * Clear all todos
+     */
+    clear() {
+        this.todos.clear();
+    }
+    /**
+     * Get count by status
+     */
+    getCounts() {
+        const counts = {
+            pending: 0,
+            in_progress: 0,
+            completed: 0,
+        };
+        for (const todo of this.todos.values()) {
+            counts[todo.status]++;
+        }
+        return counts;
+    }
+}
+/**
+ * Global default store (can be overridden with factory functions)
+ */
+const defaultStore = new TodoStore();
+/**
+ * TodoWrite tool - Update the task list
+ */
+export const todoWriteTool = defineTool({
+    name: 'todo_write',
+    description: 'Update the task list. Provide the complete list of todos. ' +
+        'Use this to track progress on multi-step tasks.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            todos: {
+                type: 'array',
+                description: 'The complete list of todos',
+                items: {
+                    type: 'object',
+                    properties: {
+                        content: {
+                            type: 'string',
+                            description: 'Task description (imperative form, e.g., "Fix bug in login")',
+                        },
+                        status: {
+                            type: 'string',
+                            enum: ['pending', 'in_progress', 'completed'],
+                            description: 'Task status',
+                        },
+                        activeForm: {
+                            type: 'string',
+                            description: 'Active form (present continuous, e.g., "Fixing bug in login")',
+                        },
+                        priority: {
+                            type: 'number',
+                            description: 'Priority (higher = more important)',
+                        },
+                    },
+                    required: ['content', 'status'],
+                },
+            },
+        },
+        required: ['todos'],
+    },
+    execute: (input) => {
+        // Validate todos
+        for (const todo of input.todos) {
+            if (!todo.content || todo.content.trim() === '') {
+                return Promise.resolve(createErrorResult('Todo content cannot be empty'));
+            }
+            if (!['pending', 'in_progress', 'completed'].includes(todo.status)) {
+                return Promise.resolve(createErrorResult(`Invalid status: ${todo.status}`));
+            }
+        }
+        defaultStore.setAll(input.todos);
+        const counts = defaultStore.getCounts();
+        return Promise.resolve(createSuccessResult({
+            message: 'Todos updated successfully',
+            counts,
+            total: input.todos.length,
+        }));
+    },
+});
+/**
+ * TodoRead tool - Get the current task list
+ */
+export const todoReadTool = defineTool({
+    name: 'todo_read',
+    description: 'Get the current task list. Optionally filter by status.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            status: {
+                type: 'string',
+                enum: ['pending', 'in_progress', 'completed'],
+                description: 'Filter by status (optional)',
+            },
+            includeCompleted: {
+                type: 'boolean',
+                description: 'Include completed tasks (default: true)',
+            },
+        },
+    },
+    execute: (input) => {
+        let todos = defaultStore.getAll();
+        // Filter by status if specified
+        if (input.status) {
+            todos = todos.filter((t) => t.status === input.status);
+        }
+        // Filter out completed if requested
+        if (input.includeCompleted === false) {
+            todos = todos.filter((t) => t.status !== 'completed');
+        }
+        const counts = defaultStore.getCounts();
+        return Promise.resolve(createSuccessResult({
+            todos: todos.map((t) => ({
+                id: t.id,
+                content: t.content,
+                status: t.status,
+                activeForm: t.activeForm,
+                priority: t.priority,
+            })),
+            counts,
+            total: todos.length,
+        }));
+    },
+});
+/**
+ * Factory to create todo tools with a custom store
+ */
+export function createTodoTools(store) {
+    const todoStore = store ?? new TodoStore();
+    const todoWrite = defineTool({
+        name: 'todo_write',
+        description: 'Update the task list. Provide the complete list of todos. ' +
+            'Use this to track progress on multi-step tasks.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                todos: {
+                    type: 'array',
+                    description: 'The complete list of todos',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            content: { type: 'string' },
+                            status: { type: 'string', enum: ['pending', 'in_progress', 'completed'] },
+                            activeForm: { type: 'string' },
+                            priority: { type: 'number' },
+                        },
+                        required: ['content', 'status'],
+                    },
+                },
+            },
+            required: ['todos'],
+        },
+        execute: (input) => {
+            for (const todo of input.todos) {
+                if (!todo.content || todo.content.trim() === '') {
+                    return Promise.resolve(createErrorResult('Todo content cannot be empty'));
+                }
+                if (!['pending', 'in_progress', 'completed'].includes(todo.status)) {
+                    return Promise.resolve(createErrorResult(`Invalid status: ${todo.status}`));
+                }
+            }
+            todoStore.setAll(input.todos);
+            const counts = todoStore.getCounts();
+            return Promise.resolve(createSuccessResult({
+                message: 'Todos updated successfully',
+                counts,
+                total: input.todos.length,
+            }));
+        },
+    });
+    const todoRead = defineTool({
+        name: 'todo_read',
+        description: 'Get the current task list. Optionally filter by status.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                status: {
+                    type: 'string',
+                    enum: ['pending', 'in_progress', 'completed'],
+                },
+                includeCompleted: {
+                    type: 'boolean',
+                },
+            },
+        },
+        execute: (input) => {
+            let todos = todoStore.getAll();
+            if (input.status) {
+                todos = todos.filter((t) => t.status === input.status);
+            }
+            if (input.includeCompleted === false) {
+                todos = todos.filter((t) => t.status !== 'completed');
+            }
+            const counts = todoStore.getCounts();
+            return Promise.resolve(createSuccessResult({
+                todos: todos.map((t) => ({
+                    id: t.id,
+                    content: t.content,
+                    status: t.status,
+                    activeForm: t.activeForm,
+                    priority: t.priority,
+                })),
+                counts,
+                total: todos.length,
+            }));
+        },
+    });
+    return { todoWrite, todoRead, store: todoStore };
+}
+/**
+ * Reset the default store (useful for testing)
+ */
+export function resetDefaultTodoStore() {
+    defaultStore.clear();
+}
+/**
+ * Get the default store (useful for testing or direct access)
+ */
+export function getDefaultTodoStore() {
+    return defaultStore;
+}
+/**
+ * Create a new isolated TodoStore instance.
+ *
+ * Use this when you need state isolation between parallel operations,
+ * such as concurrent sub-agent executions. This prevents state leakage
+ * between parallel runs.
+ *
+ * Inspired by LangGraph issue #6446: Parallel subgraphs with shared
+ * state keys cause InvalidUpdateError.
+ *
+ * @example
+ * ```typescript
+ * // For parallel sub-agents, create isolated stores
+ * const store1 = createIsolatedTodoStore();
+ * const store2 = createIsolatedTodoStore();
+ *
+ * // Each sub-agent uses its own store
+ * await Promise.all([
+ *   runWithStore(store1, task1),
+ *   runWithStore(store2, task2),
+ * ]);
+ * ```
+ */
+export function createIsolatedTodoStore() {
+    return new TodoStore();
+}
+/**
+ * Filter messages to remove redundant todo tool calls.
+ * This helps prevent context bloat from repeated todo_write calls.
+ *
+ * The function keeps only the last N todo_write calls (default: 1),
+ * removing earlier ones to reduce context size.
+ *
+ * @param messages - Array of messages to filter
+ * @param options - Cleanup options
+ * @returns Filtered messages with redundant todo calls removed
+ */
+export function cleanupTodoContextMessages(messages, options) {
+    const { keepLastN = 1, cleanReads = false } = options ?? {};
+    // Find indices of all todo_write tool uses and results
+    const todoWriteIndices = [];
+    const todoReadIndices = [];
+    for (let i = 0; i < messages.length; i++) {
+        const message = messages[i];
+        if (typeof message.content === 'string')
+            continue;
+        const content = message.content;
+        if (!Array.isArray(content))
+            continue;
+        for (const block of content) {
+            if (block.type === 'tool_use' && block.name === 'todo_write') {
+                todoWriteIndices.push(i);
+                break;
+            }
+            if (block.type === 'tool_result') {
+                // Check if this is a result for todo_write
+                // We need to track tool_use IDs to match them, but for simplicity
+                // we'll just mark messages that follow todo_write calls
+            }
+            if (cleanReads && block.type === 'tool_use' && block.name === 'todo_read') {
+                todoReadIndices.push(i);
+                break;
+            }
+        }
+    }
+    // Determine which todo_write indices to remove (keep last N)
+    const indicesToRemove = new Set();
+    if (todoWriteIndices.length > keepLastN) {
+        const toRemove = todoWriteIndices.slice(0, -keepLastN);
+        for (const idx of toRemove) {
+            indicesToRemove.add(idx);
+            // Also remove the following message if it's a tool result
+            if (idx + 1 < messages.length) {
+                const nextMessage = messages[idx + 1];
+                if (nextMessage.role === 'user' && typeof nextMessage.content !== 'string') {
+                    const content = nextMessage.content;
+                    if (Array.isArray(content) && content.some((b) => b.type === 'tool_result')) {
+                        indicesToRemove.add(idx + 1);
+                    }
+                }
+            }
+        }
+    }
+    // Optionally remove old todo_read calls (keep last N)
+    if (cleanReads && todoReadIndices.length > keepLastN) {
+        const toRemove = todoReadIndices.slice(0, -keepLastN);
+        for (const idx of toRemove) {
+            indicesToRemove.add(idx);
+            if (idx + 1 < messages.length) {
+                const nextMessage = messages[idx + 1];
+                if (nextMessage.role === 'user' && typeof nextMessage.content !== 'string') {
+                    const content = nextMessage.content;
+                    if (Array.isArray(content) && content.some((b) => b.type === 'tool_result')) {
+                        indicesToRemove.add(idx + 1);
+                    }
+                }
+            }
+        }
+    }
+    // Filter out removed indices
+    return messages.filter((_, idx) => !indicesToRemove.has(idx));
+}
+/**
+ * Get statistics about todo tool usage in messages
+ */
+export function getTodoContextStats(messages) {
+    let todoWriteCalls = 0;
+    let todoReadCalls = 0;
+    for (const message of messages) {
+        if (typeof message.content === 'string')
+            continue;
+        const content = message.content;
+        if (!Array.isArray(content))
+            continue;
+        for (const block of content) {
+            if (block.type === 'tool_use' && block.name === 'todo_write') {
+                todoWriteCalls++;
+            }
+            if (block.type === 'tool_use' && block.name === 'todo_read') {
+                todoReadCalls++;
+            }
+        }
+    }
+    // Rough estimate: each todo call + result is ~200-500 tokens
+    const avgTokensPerCall = 300;
+    const estimatedTokensSaved = Math.max(0, todoWriteCalls - 1) * avgTokensPerCall;
+    return { todoWriteCalls, todoReadCalls, estimatedTokensSaved };
+}

package/dist/tools/builtin/utils.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Shared utilities for builtin tools
+ */
+/**
+ * Type guard for Node.js errors with code property
+ */
+export declare function isNodeError(error: unknown): error is NodeJS.ErrnoException;
+/**
+ * Get the file extension from a path, including the leading dot.
+ * Returns empty string if no extension found.
+ *
+ * @example
+ * getExtension('/path/to/file.ts') // returns '.ts'
+ * getExtension('/path/to/file') // returns ''
+ * getExtension('/path/to/.gitignore') // returns '' (dotfile, not extension)
+ */
+export declare function getExtension(filePath: string): string;
+/**
+ * Check if a file extension is in the allowed list.
+ * Handles both formats: ['.ts', '.js'] or ['ts', 'js']
+ */
+export declare function isExtensionAllowed(filePath: string, allowedExtensions: string[]): boolean;
+/**
+ * Write a file atomically by writing to a temp file first, then renaming.
+ * This prevents file corruption if the write is interrupted.
+ */
+export declare function atomicWriteFile(filePath: string, content: string, encoding?: BufferEncoding): Promise<void>;