@compilr-dev/agents 0.1.0 → 0.2.0

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

@@ -1,6 +1,8 @@
 /**
  * Built-in tools for common operations
  */
+export { TOOL_NAMES, TOOL_SETS } from './tool-names.js';
+export type { ToolName } from './tool-names.js';
 export { readFileTool, createReadFileTool } from './read-file.js';
 export type { ReadFileInput } from './read-file.js';
 export { writeFileTool, createWriteFileTool } from './write-file.js';
@@ -25,6 +27,8 @@ export { createTaskTool, defaultAgentTypes } from './task.js';
 export type { TaskInput, TaskResult, AgentTypeConfig, TaskToolOptions, ContextMode, ThoroughnessLevel, SubAgentEventInfo, } from './task.js';
 export { webFetchTool, createWebFetchTool } from './web-fetch.js';
 export type { WebFetchInput, WebFetchResult, WebFetchOptions } from './web-fetch.js';
+export { suggestTool, createSuggestTool } from './suggest.js';
+export type { SuggestInput, SuggestToolOptions } from './suggest.js';
 export declare const builtinTools: {
     readonly readFile: import("../types.js").Tool<import("./read-file.js").ReadFileInput>;
     readonly writeFile: import("../types.js").Tool<import("./write-file.js").WriteFileInput>;
@@ -37,8 +41,9 @@ export declare const builtinTools: {
     readonly todoWrite: import("../types.js").Tool<import("./todo.js").TodoWriteInput>;
     readonly todoRead: import("../types.js").Tool<import("./todo.js").TodoReadInput>;
     readonly webFetch: import("../types.js").Tool<import("./web-fetch.js").WebFetchInput>;
+    readonly suggest: import("../types.js").Tool<import("./suggest.js").SuggestInput>;
 };
 /**
  * Array of all built-in tools
  */
-export declare const allBuiltinTools: readonly [import("../types.js").Tool<import("./read-file.js").ReadFileInput>, import("../types.js").Tool<import("./write-file.js").WriteFileInput>, import("../types.js").Tool<import("./bash.js").BashInput>, import("../types.js").Tool<import("./bash-output.js").BashOutputInput>, import("../types.js").Tool<import("./kill-shell.js").KillShellInput>, import("../types.js").Tool<import("./grep.js").GrepInput>, import("../types.js").Tool<import("./glob.js").GlobInput>, import("../types.js").Tool<import("./edit.js").EditInput>, import("../types.js").Tool<import("./todo.js").TodoWriteInput>, import("../types.js").Tool<import("./todo.js").TodoReadInput>, import("../types.js").Tool<import("./web-fetch.js").WebFetchInput>];
+export declare const allBuiltinTools: readonly [import("../types.js").Tool<import("./read-file.js").ReadFileInput>, import("../types.js").Tool<import("./write-file.js").WriteFileInput>, import("../types.js").Tool<import("./bash.js").BashInput>, import("../types.js").Tool<import("./bash-output.js").BashOutputInput>, import("../types.js").Tool<import("./kill-shell.js").KillShellInput>, import("../types.js").Tool<import("./grep.js").GrepInput>, import("../types.js").Tool<import("./glob.js").GlobInput>, import("../types.js").Tool<import("./edit.js").EditInput>, import("../types.js").Tool<import("./todo.js").TodoWriteInput>, import("../types.js").Tool<import("./todo.js").TodoReadInput>, import("../types.js").Tool<import("./web-fetch.js").WebFetchInput>, import("../types.js").Tool<import("./suggest.js").SuggestInput>];

package/dist/tools/builtin/index.js

@@ -1,6 +1,8 @@
 /**
  * Built-in tools for common operations
  */
+// Tool names - single source of truth
+export { TOOL_NAMES, TOOL_SETS } from './tool-names.js';
 // Read file tool
 export { readFileTool, createReadFileTool } from './read-file.js';
 // Write file tool
@@ -25,6 +27,8 @@ export { todoWriteTool, todoReadTool, createTodoTools, TodoStore, resetDefaultTo
 export { createTaskTool, defaultAgentTypes } from './task.js';
 // WebFetch tool
 export { webFetchTool, createWebFetchTool } from './web-fetch.js';
+// Suggest tool (next action suggestions)
+export { suggestTool, createSuggestTool } from './suggest.js';
 /**
  * Collection of all built-in tools for easy registration
  */
@@ -38,6 +42,7 @@ import { globTool } from './glob.js';
 import { editTool } from './edit.js';
 import { todoWriteTool, todoReadTool } from './todo.js';
 import { webFetchTool } from './web-fetch.js';
+import { suggestTool } from './suggest.js';
 export const builtinTools = {
     readFile: readFileTool,
     writeFile: writeFileTool,
@@ -50,6 +55,7 @@ export const builtinTools = {
     todoWrite: todoWriteTool,
     todoRead: todoReadTool,
     webFetch: webFetchTool,
+    suggest: suggestTool,
 };
 /**
  * Array of all built-in tools
@@ -66,4 +72,5 @@ export const allBuiltinTools = [
     todoWriteTool,
     todoReadTool,
     webFetchTool,
+    suggestTool,
 ];

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

@@ -0,0 +1,57 @@
+/**
+ * Suggest Tool - Suggest next action to the user
+ *
+ * This tool allows the agent to suggest a logical next action for the user.
+ * The suggestion appears as "ghost text" in the CLI input prompt.
+ *
+ * Features:
+ * - Silent tool (produces no visible output in conversation)
+ * - Emits 'suggest' event for CLI to handle
+ * - Only the last suggestion per response is kept
+ */
+import type { Tool } from '../types.js';
+import type { AgentEvent } from '../../agent.js';
+/**
+ * Input parameters for suggest tool
+ */
+export interface SuggestInput {
+    /**
+     * The suggested action or command for the user to take next
+     */
+    action: string;
+    /**
+     * Brief explanation of why this action is suggested (optional)
+     */
+    reason?: string;
+}
+/**
+ * Options for creating the suggest tool
+ */
+export interface SuggestToolOptions {
+    /**
+     * Callback to emit suggest event
+     * The CLI captures this to display the suggestion
+     */
+    onSuggest?: (event: Extract<AgentEvent, {
+        type: 'suggest';
+    }>) => void;
+}
+/**
+ * Default suggest tool (no-op, for testing or when suggestions are disabled)
+ */
+export declare const suggestTool: Tool<SuggestInput>;
+/**
+ * Create a suggest tool with event emission
+ *
+ * @example
+ * ```typescript
+ * const suggestTool = createSuggestTool({
+ *   onSuggest: (event) => {
+ *     // Handle the suggestion (e.g., pass to CLI input prompt)
+ *     console.log('Suggested action:', event.action);
+ *   }
+ * });
+ * agent.registerTool(suggestTool);
+ * ```
+ */
+export declare function createSuggestTool(options?: SuggestToolOptions): Tool<SuggestInput>;

package/dist/tools/builtin/suggest.js

@@ -0,0 +1,99 @@
+/**
+ * Suggest Tool - Suggest next action to the user
+ *
+ * This tool allows the agent to suggest a logical next action for the user.
+ * The suggestion appears as "ghost text" in the CLI input prompt.
+ *
+ * Features:
+ * - Silent tool (produces no visible output in conversation)
+ * - Emits 'suggest' event for CLI to handle
+ * - Only the last suggestion per response is kept
+ */
+import { defineTool, createSuccessResult } from '../define.js';
+/**
+ * Default suggest tool (no-op, for testing or when suggestions are disabled)
+ */
+export const suggestTool = defineTool({
+    name: 'suggest',
+    description: 'Suggest a next action for the user. The suggestion appears as ghost text in the input prompt. ' +
+        'Use this after completing a task to guide the user toward a logical next step. ' +
+        'Good suggestions are actionable, specific, and follow naturally from what you just did. ' +
+        'Examples: "run npm test to verify the fix", "review the changes in src/index.ts", ' +
+        '"commit the changes with git commit". Only suggest when there is a clear, helpful next step.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            action: {
+                type: 'string',
+                description: 'The suggested action or command for the user to take next',
+            },
+            reason: {
+                type: 'string',
+                description: 'Brief explanation of why this action is suggested (optional)',
+            },
+        },
+        required: ['action'],
+    },
+    execute: (_input) => {
+        // Default implementation - silent, no-op
+        // Real implementation uses createSuggestTool with onSuggest callback
+        return Promise.resolve(createSuccessResult({
+            suggested: true,
+            message: 'Suggestion noted (no handler configured)',
+        }));
+    },
+});
+/**
+ * Create a suggest tool with event emission
+ *
+ * @example
+ * ```typescript
+ * const suggestTool = createSuggestTool({
+ *   onSuggest: (event) => {
+ *     // Handle the suggestion (e.g., pass to CLI input prompt)
+ *     console.log('Suggested action:', event.action);
+ *   }
+ * });
+ * agent.registerTool(suggestTool);
+ * ```
+ */
+export function createSuggestTool(options = {}) {
+    const { onSuggest } = options;
+    return defineTool({
+        name: 'suggest',
+        description: 'Suggest a next action for the user. The suggestion appears as ghost text in the input prompt. ' +
+            'Use this after completing a task to guide the user toward a logical next step. ' +
+            'Good suggestions are actionable, specific, and follow naturally from what you just did. ' +
+            'Examples: "run npm test to verify the fix", "review the changes in src/index.ts", ' +
+            '"commit the changes with git commit". Only suggest when there is a clear, helpful next step.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    description: 'The suggested action or command for the user to take next',
+                },
+                reason: {
+                    type: 'string',
+                    description: 'Brief explanation of why this action is suggested (optional)',
+                },
+            },
+            required: ['action'],
+        },
+        execute: (input) => {
+            // Emit the suggest event if handler is configured
+            if (onSuggest) {
+                onSuggest({
+                    type: 'suggest',
+                    action: input.action,
+                    reason: input.reason,
+                });
+            }
+            // Silent result - no visible output in conversation
+            return Promise.resolve(createSuccessResult({
+                suggested: true,
+                action: input.action,
+            }));
+        },
+    });
+}

package/dist/tools/builtin/task.js

@@ -13,6 +13,7 @@
  * - Extended built-in agent types
  */
 import { defineTool, createSuccessResult, createErrorResult } from '../define.js';
+import { TOOL_NAMES, TOOL_SETS } from './tool-names.js';
 /**
  * Map our context mode to agent's context mode
  */
@@ -123,6 +124,7 @@ export function createTaskTool(options) {
             const agentConfig = agentTypes[subagent_type];
             // Check concurrent limit
             if (activeCount >= maxConcurrent) {
+                console.error(`[task-tool] BLOCKED: activeCount=${String(activeCount)}, maxConcurrent=${String(maxConcurrent)}`);
                 return createErrorResult(`Maximum concurrent sub-agents (${String(maxConcurrent)}) reached. ` +
                     `Wait for existing tasks to complete.`);
             }
@@ -131,6 +133,7 @@ export function createTaskTool(options) {
                 onSpawn(subagent_type, description);
             }
             activeCount++;
+            console.error(`[task-tool] SPAWN: ${subagent_type}, activeCount=${String(activeCount)}`);
             try {
                 // Note: Sub-agents currently use the parent's provider
                 // Future enhancement: support model switching via providerFactory
@@ -198,10 +201,12 @@ export function createTaskTool(options) {
                 return createSuccessResult(taskResult);
             }
             catch (error) {
+                console.error(`[task-tool] ERROR: ${subagent_type}, error=${error instanceof Error ? error.message : String(error)}`);
                 return createErrorResult(`Sub-agent failed: ${error instanceof Error ? error.message : String(error)}`);
             }
             finally {
                 activeCount--;
+                console.error(`[task-tool] DONE: ${subagent_type}, activeCount=${String(activeCount)}`);
             }
         },
     });
@@ -222,7 +227,7 @@ export const defaultAgentTypes = {
         contextMode: 'inherit-summary',
         supportsThoroughness: true,
         toolInheritance: 'filter',
-        allowedTools: ['glob', 'grep', 'read'],
+        allowedTools: [...TOOL_SETS.READ_ONLY],
     },
     'code-review': {
         description: 'Agent specialized for reviewing code changes. Use after writing ' +
@@ -238,7 +243,7 @@ export const defaultAgentTypes = {
         contextMode: 'inherit-summary',
         supportsThoroughness: false,
         toolInheritance: 'filter',
-        allowedTools: ['glob', 'grep', 'read'],
+        allowedTools: [...TOOL_SETS.READ_ONLY],
     },
     general: {
         description: 'General-purpose agent for complex multi-step tasks. Use when ' +
@@ -262,7 +267,7 @@ export const defaultAgentTypes = {
         contextMode: 'inherit-summary',
         supportsThoroughness: false,
         toolInheritance: 'filter',
-        allowedTools: ['glob', 'grep', 'read'],
+        allowedTools: [...TOOL_SETS.READ_ONLY],
     },
     'test-runner': {
         description: 'Agent for running and analyzing tests. Use to run test suites, ' +
@@ -278,7 +283,7 @@ export const defaultAgentTypes = {
         contextMode: 'inherit-summary',
         supportsThoroughness: true,
         toolInheritance: 'filter',
-        allowedTools: ['bash', 'glob', 'grep', 'read'],
+        allowedTools: [...TOOL_SETS.READ_ONLY_WITH_BASH],
     },
     'doc-lookup': {
         description: 'Agent for searching documentation and APIs. Use to find ' +
@@ -294,7 +299,7 @@ export const defaultAgentTypes = {
         contextMode: 'isolated',
         supportsThoroughness: true,
         toolInheritance: 'filter',
-        allowedTools: ['webFetch', 'glob', 'grep', 'read'],
+        allowedTools: [...TOOL_SETS.READ_ONLY_WITH_WEB],
     },
     refactor: {
         description: 'Agent for refactoring code safely. Use for renaming, extracting, ' +
@@ -310,8 +315,8 @@ export const defaultAgentTypes = {
         contextMode: 'inherit-summary',
         supportsThoroughness: false,
         toolInheritance: 'filter',
-        allowedTools: ['glob', 'grep', 'read', 'edit', 'write'],
-        deniedTools: ['bash'],
+        allowedTools: [...TOOL_SETS.REFACTOR],
+        deniedTools: [TOOL_NAMES.BASH],
     },
     'security-audit': {
         description: 'Agent for security auditing code. Use to scan for vulnerabilities, ' +
@@ -329,7 +334,7 @@ export const defaultAgentTypes = {
         contextMode: 'isolated',
         supportsThoroughness: true,
         toolInheritance: 'filter',
-        allowedTools: ['glob', 'grep', 'read', 'bash'],
+        allowedTools: [...TOOL_SETS.SECURITY_AUDIT],
     },
     debug: {
         description: 'Agent for debugging issues. Use to investigate bugs, analyze ' +

package/dist/tools/builtin/tool-names.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Tool Names - Single Source of Truth
+ *
+ * All tool names are defined here to avoid hardcoding them in multiple places.
+ * Import these constants wherever you need to reference tool names.
+ */
+/**
+ * Built-in tool names as constants
+ */
+export declare const TOOL_NAMES: {
+    readonly READ_FILE: "read_file";
+    readonly WRITE_FILE: "write_file";
+    readonly BASH: "bash";
+    readonly BASH_OUTPUT: "bash_output";
+    readonly KILL_SHELL: "kill_shell";
+    readonly GREP: "grep";
+    readonly GLOB: "glob";
+    readonly EDIT: "edit";
+    readonly TODO_WRITE: "todo_write";
+    readonly TODO_READ: "todo_read";
+    readonly WEB_FETCH: "web_fetch";
+    readonly TASK: "task";
+    readonly SUGGEST: "suggest";
+};
+/**
+ * Type for tool name values
+ */
+export type ToolName = (typeof TOOL_NAMES)[keyof typeof TOOL_NAMES];
+/**
+ * Common tool sets for agent types
+ * Use these instead of hardcoding tool arrays
+ */
+export declare const TOOL_SETS: {
+    /** Read-only tools for exploration and code review */
+    readonly READ_ONLY: readonly ["glob", "grep", "read_file"];
+    /** Read-only tools plus bash for running commands */
+    readonly READ_ONLY_WITH_BASH: readonly ["bash", "glob", "grep", "read_file"];
+    /** Read-only tools plus web fetch for documentation lookup */
+    readonly READ_ONLY_WITH_WEB: readonly ["web_fetch", "glob", "grep", "read_file"];
+    /** Tools for refactoring (read + edit + write, no bash) */
+    readonly REFACTOR: readonly ["glob", "grep", "read_file", "edit", "write_file"];
+    /** Tools for security auditing (read + bash for dependency checks) */
+    readonly SECURITY_AUDIT: readonly ["glob", "grep", "read_file", "bash"];
+};

package/dist/tools/builtin/tool-names.js

@@ -0,0 +1,51 @@
+/**
+ * Tool Names - Single Source of Truth
+ *
+ * All tool names are defined here to avoid hardcoding them in multiple places.
+ * Import these constants wherever you need to reference tool names.
+ */
+/**
+ * Built-in tool names as constants
+ */
+export const TOOL_NAMES = {
+    READ_FILE: 'read_file',
+    WRITE_FILE: 'write_file',
+    BASH: 'bash',
+    BASH_OUTPUT: 'bash_output',
+    KILL_SHELL: 'kill_shell',
+    GREP: 'grep',
+    GLOB: 'glob',
+    EDIT: 'edit',
+    TODO_WRITE: 'todo_write',
+    TODO_READ: 'todo_read',
+    WEB_FETCH: 'web_fetch',
+    TASK: 'task',
+    SUGGEST: 'suggest',
+};
+/**
+ * Common tool sets for agent types
+ * Use these instead of hardcoding tool arrays
+ */
+export const TOOL_SETS = {
+    /** Read-only tools for exploration and code review */
+    READ_ONLY: [TOOL_NAMES.GLOB, TOOL_NAMES.GREP, TOOL_NAMES.READ_FILE],
+    /** Read-only tools plus bash for running commands */
+    READ_ONLY_WITH_BASH: [TOOL_NAMES.BASH, TOOL_NAMES.GLOB, TOOL_NAMES.GREP, TOOL_NAMES.READ_FILE],
+    /** Read-only tools plus web fetch for documentation lookup */
+    READ_ONLY_WITH_WEB: [
+        TOOL_NAMES.WEB_FETCH,
+        TOOL_NAMES.GLOB,
+        TOOL_NAMES.GREP,
+        TOOL_NAMES.READ_FILE,
+    ],
+    /** Tools for refactoring (read + edit + write, no bash) */
+    REFACTOR: [
+        TOOL_NAMES.GLOB,
+        TOOL_NAMES.GREP,
+        TOOL_NAMES.READ_FILE,
+        TOOL_NAMES.EDIT,
+        TOOL_NAMES.WRITE_FILE,
+    ],
+    /** Tools for security auditing (read + bash for dependency checks) */
+    SECURITY_AUDIT: [TOOL_NAMES.GLOB, TOOL_NAMES.GREP, TOOL_NAMES.READ_FILE, TOOL_NAMES.BASH],
+};

package/dist/tools/index.d.ts

@@ -6,5 +6,5 @@ export { defineTool, createSuccessResult, createErrorResult, wrapToolExecute } f
 export type { DefineToolOptions } from './define.js';
 export { DefaultToolRegistry, createToolRegistry } from './registry.js';
 export type { ToolRegistryOptions } from './registry.js';
-export { readFileTool, createReadFileTool, writeFileTool, createWriteFileTool, bashTool, createBashTool, execStream, detectFifoUsage, bashOutputTool, createBashOutputTool, killShellTool, createKillShellTool, ShellManager, getDefaultShellManager, setDefaultShellManager, grepTool, createGrepTool, globTool, createGlobTool, editTool, createEditTool, todoWriteTool, todoReadTool, createTodoTools, TodoStore, resetDefaultTodoStore, getDefaultTodoStore, createIsolatedTodoStore, cleanupTodoContextMessages, getTodoContextStats, webFetchTool, createWebFetchTool, createTaskTool, defaultAgentTypes, builtinTools, allBuiltinTools, } from './builtin/index.js';
-export type { ReadFileInput, WriteFileInput, BashInput, BashResult, FifoDetectionResult, BashOutputInput, BashOutputResult, KillShellInput, KillShellResult, ShellStatus, BackgroundShell, ShellOutput, ShellManagerOptions, GrepInput, GlobInput, EditInput, TodoWriteInput, TodoReadInput, TodoItem, TodoStatus, TodoContextCleanupOptions, WebFetchInput, WebFetchResult, WebFetchOptions, TaskInput, TaskResult, AgentTypeConfig, TaskToolOptions, ContextMode, ThoroughnessLevel, SubAgentEventInfo, } from './builtin/index.js';
+export { readFileTool, createReadFileTool, writeFileTool, createWriteFileTool, bashTool, createBashTool, execStream, detectFifoUsage, bashOutputTool, createBashOutputTool, killShellTool, createKillShellTool, ShellManager, getDefaultShellManager, setDefaultShellManager, grepTool, createGrepTool, globTool, createGlobTool, editTool, createEditTool, todoWriteTool, todoReadTool, createTodoTools, TodoStore, resetDefaultTodoStore, getDefaultTodoStore, createIsolatedTodoStore, cleanupTodoContextMessages, getTodoContextStats, webFetchTool, createWebFetchTool, createTaskTool, defaultAgentTypes, suggestTool, createSuggestTool, builtinTools, allBuiltinTools, TOOL_NAMES, TOOL_SETS, } from './builtin/index.js';
+export type { ReadFileInput, WriteFileInput, BashInput, BashResult, FifoDetectionResult, BashOutputInput, BashOutputResult, KillShellInput, KillShellResult, ShellStatus, BackgroundShell, ShellOutput, ShellManagerOptions, GrepInput, GlobInput, EditInput, TodoWriteInput, TodoReadInput, TodoItem, TodoStatus, TodoContextCleanupOptions, WebFetchInput, WebFetchResult, WebFetchOptions, TaskInput, TaskResult, AgentTypeConfig, TaskToolOptions, ContextMode, ThoroughnessLevel, SubAgentEventInfo, SuggestInput, SuggestToolOptions, } from './builtin/index.js';

package/dist/tools/index.js

@@ -33,5 +33,9 @@ todoWriteTool, todoReadTool, createTodoTools, TodoStore, resetDefaultTodoStore,
 webFetchTool, createWebFetchTool, 
 // Task (sub-agent spawning)
 createTaskTool, defaultAgentTypes, 
+// Suggest (next action suggestions)
+suggestTool, createSuggestTool, 
 // Collections
-builtinTools, allBuiltinTools, } from './builtin/index.js';
+builtinTools, allBuiltinTools, 
+// Tool names - single source of truth
+TOOL_NAMES, TOOL_SETS, } from './builtin/index.js';

package/dist/tools/registry.d.ts

@@ -72,6 +72,10 @@ export declare class DefaultToolRegistry implements IToolRegistry {
      * Clear all registered tools
      */
     clear(): void;
+    /**
+     * Get the registry options (for inheritance by sub-agents)
+     */
+    getOptions(): ToolRegistryOptions;
 }
 /**
  * Create a new ToolRegistry with optional initial tools and options

package/dist/tools/registry.js

@@ -138,6 +138,15 @@ export class DefaultToolRegistry {
     clear() {
         this.tools.clear();
     }
+    /**
+     * Get the registry options (for inheritance by sub-agents)
+     */
+    getOptions() {
+        return {
+            defaultTimeoutMs: this.defaultTimeoutMs,
+            toolTimeouts: { ...this.toolTimeouts },
+        };
+    }
 }
 /**
  * Create a new ToolRegistry with optional initial tools and options

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/agents",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Lightweight multi-LLM agent library for building CLI AI assistants",
   "type": "module",
   "main": "dist/index.js",