@travisennis/acai 0.0.4 → 0.0.6

package/README.md

@@ -14,7 +14,7 @@ Acai is a powerful **AI-driven command-line interface (CLI) tool** designed to a
 *   **Codebase Interaction:** Read, edit, and navigate files; search code; and understand project structure.
 *   **Git Integration:** Generate conventional commits, review pull requests, and manage local changes.
 *   **Extensible Tooling:** Utilizes a suite of internal tools (e.g., `bash`, `codeInterpreter`, `webSearch`) to perform actions.
-*   **Multi-Model Support:** Seamlessly switch between various AI providers (e.g., OpenAI, Google, Anthropic, DeepSeek, OpenRouter).
+*   **Multi-Model Support:** Seamlessly switch between various AI providers (e.g., OpenAI, Google, Anthropic, DeepSeek, Groq, OpenRouter).
 *   **Context Management:** Automatically incorporates relevant file content, clipboard data, and conversation history into AI prompts.
 *   **Configurable & Learnable:** Customize behavior through project-specific rules and learn from user corrections.
 
@@ -30,6 +30,7 @@ Acai is a powerful **AI-driven command-line interface (CLI) tool** designed to a
 *   **Token Usage Tracking:** Monitor AI token consumption.
 *   **Configurable AI Models:** Easily switch between different LLM providers and models.
 *   **Shell Integration:** Execute shell commands inline using `!`command`` syntax.
+*   **Dynamic Tools:** Create and load custom tools from JavaScript files in your project or user directory.
 
 ## 🛠️ Technologies Used
 
@@ -37,12 +38,8 @@ Acai is built primarily with **TypeScript** and runs on **Node.js**. Key technol
 
 *   **TypeScript:** For type-safe and scalable code.
 *   **Node.js:** The JavaScript runtime environment.
-*   **AI SDK (`@ai-sdk/*`):** For integrating with various Large Language Models (LLMs) like OpenAI, Google Gemini, Anthropic, DeepSeek, and OpenRouter.
-*   **Tree-sitter:** For robust and efficient code parsing and syntax analysis across multiple programming languages (TypeScript, JavaScript, Java, Python).
-*   **`chalk`, `ora`, `log-update`:** For rich and interactive terminal output.
-*   **`@inquirer/prompts`:** For interactive prompts; CLI args parsed with Node's `util.parseArgs`.
+*   **AI SDK (`@ai-sdk/*`):** For integrating with various Large Language Models (LLMs) like OpenAI, Google Gemini, Anthropic, DeepSeek, Groq, and OpenRouter.
 *   **`ripgrep` (via `grep.ts` tool):** For fast file content searching.
-*   **`marked`:** For rendering Markdown in the terminal.
 *   **`pino`:** For structured logging.
 *   **`zod`:** For schema validation.
 *   **`biomejs/biome`:** For code formatting and linting.
@@ -122,6 +119,9 @@ GOOGLE_GENERATIVE_AI_API_KEY=your_google_api_key_here
 # DeepSeek
 DEEPSEEK_API_KEY=your_deepseek_api_key_here
 
+# Groq (Kimi models)
+GROQ_API_KEY=your_groq_api_key_here
+
 # X.AI (Grok models)
 X_AI_API_KEY=your_xai_api_key_here
 # Alternative name also supported:
@@ -159,6 +159,7 @@ ANTHROPIC_API_KEY=sk-ant-...
 
 # Optional: Additional providers
 GOOGLE_GENERATIVE_AI_API_KEY=...
+GROQ_API_KEY=...
 OPENROUTER_API_KEY=sk-or-...
 
 # Optional: Web services (fallbacks available if not provided)
@@ -181,8 +182,8 @@ acai
 # Specify a model
 acai --model anthropic:sonnet
 
-# One-shot mode
-acai -p "What files contain the term 'toolCallRepair'?" -o
+# CLI mode (one-shot execution)
+acai -p "What files contain the term 'toolCallRepair'?"
 
 # Pipe input
 echo "How many TypeScript files are in this project?" | acai
@@ -215,6 +216,8 @@ You can reference files and directories directly in your prompts:
 - `@http://example.com` - Fetch and include web content
 - ``!`command` `` - Execute shell command and include output
 
+**Note:** Using `-p/--prompt` runs in CLI mode (one-shot execution), while running without a prompt starts interactive REPL mode.
+
 For a list of available commands, type `/help` within the REPL.
 
 ## Interactive CLI Commands
@@ -238,12 +241,230 @@ For a list of available commands, type `/help` within the REPL.
 - `/generateRules` - Analyze the current conversation and suggest project rules
 - `/edit <path> "<change description>"` - Edit a file with AI assistance
 - `/copy` - Copy the last assistant response to the system clipboard
+- `/list-tools` or `/lt` - List all available static and dynamic tools
 
 Clipboard notes:
 - macOS: uses `pbcopy`
 - Windows: uses `clip`
 - Linux: tries `xclip`, falls back to `xsel`
 
+## Custom Tools
+
+Acai supports dynamic custom tools that users can define as executable Node.js scripts. These tools extend the core functionality without modifying the source code.
+
+### Directories
+
+- **Project tools**: `./.acai/tools/*.(m)js` (project-specific, override global tools with the same name).
+- **User tools**: `~/.acai/tools/*.(m)js` (global, available across all projects).
+
+### Format Specification
+
+Custom tools are Node.js scripts that respond to environment variables:
+
+- **Describe mode**: Set `TOOL_ACTION=describe` to output YAML metadata to stdout.
+
+Example output:
+
+```
+name: run-tests
+description: Run tests in a project workspace with proper output formatting
+parameters:
+  - name: dir
+    type: string
+    description: the workspace directory to run tests in
+    required: false
+    default: "."
+```
+
+- **Execute mode**: Set `TOOL_ACTION=execute` and read JSON parameters from stdin (array of `{name: string, value: any}`), perform the action, and output results to stdout (JSON or text). Exit with 0 on success, non-zero on error.
+
+Scripts should include `#!/usr/bin/env node` shebang for executability.
+
+### Security Notes
+
+- Dynamic tools run in sandboxed child processes with limited permissions (no network access beyond what's allowed, timeout of 30s, isolated environment).
+- Scripts have access to the project directory but cannot access Acai internals.
+- Validate inputs and handle errors gracefully.
+- Malicious scripts could perform unintended actions; review tools before use.
+- Future enhancements may include script signing or allowlisting.
+
+### Example Script
+
+Create `./.acai/tools/run-tests.js`:
+
+```javascript
+#!/usr/bin/env node
+
+const { spawn } = require('node:child_process');
+
+if (process.env.TOOL_ACTION === 'describe') {
+  console.log(JSON.stringify({
+    name: 'run-tests',
+    description: 'Run tests in the specified directory',
+    parameters: [
+      {
+        name: 'dir',
+        type: 'string',
+        description: 'Directory to run tests in (default: current directory)',
+        required: false,
+        default: '.'
+      }
+    ]
+  }, null, 2));
+  process.exit(0);
+}
+
+if (process.env.TOOL_ACTION === 'execute') {
+  let params = [];
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('readable', () => {
+    let chunk;
+    while (null !== (chunk = process.stdin.read())) {
+      params = JSON.parse(chunk);
+    }
+  });
+
+  process.stdin.on('end', () => {
+    const dir = params.find(p => p.name === 'dir')?.value || '.';
+    const child = spawn('npm', ['test'], { cwd: dir, stdio: 'pipe' });
+    let output = '';
+    child.stdout.on('data', (data) => output += data);
+    child.on('close', (code) => {
+      console.log(output);
+      process.exit(code);
+    });
+  });
+}
+```
+
+### Loading Tools
+
+Dynamic tools are loaded automatically on each user input.
+
+For more details, see the implementation in `source/tools/dynamic-tool-loader.ts`.
+
+## Dynamic Tools
+
+Acai supports dynamic tools - custom tools that you can create and load from JavaScript files. This allows you to extend Acai's functionality with your own specialized tools.
+
+### Creating Dynamic Tools
+
+Dynamic tools are JavaScript files that follow a specific structure. Here's a simple example:
+
+```javascript
+#!/usr/bin/env node
+
+if (process.env.TOOL_ACTION === 'describe') {
+  console.log(JSON.stringify({
+    name: 'my-custom-tool',
+    description: 'A custom tool that does something useful',
+    parameters: [
+      {
+        name: 'input',
+        type: 'string',
+        description: 'Input to process',
+        required: true
+      }
+    ]
+  }, null, 2));
+  process.exit(0);
+}
+
+if (process.env.TOOL_ACTION === 'execute') {
+  let params = [];
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('readable', () => {
+    let chunk;
+    while (null !== (chunk = process.stdin.read())) {
+      params = JSON.parse(chunk);
+    }
+  });
+
+  process.stdin.on('end', () => {
+    const input = params.find(p => p.name === 'input')?.value;
+    // Your tool logic here
+    const result = `Processed: ${input}`;
+    console.log(result);
+    process.exit(0);
+  });
+}
+```
+
+### Tool Structure
+
+- **Describe Phase**: When `TOOL_ACTION=describe`, the tool must output JSON metadata
+  - `name`: Tool name (will be prefixed with `dynamic:`)
+  - `description`: Human-readable description
+  - `parameters`: Array of parameter definitions
+- **Execute Phase**: When `TOOL_ACTION=execute`, the tool reads parameters from stdin and outputs results
+
+### Parameter Definition
+
+Each parameter can have:
+- `name`: Parameter name
+- `type`: "string", "number", or "boolean"
+- `description`: Human-readable description
+- `required`: Boolean (default: false)
+- `default`: Default value for optional parameters
+
+### Tool Locations
+
+Dynamic tools are loaded from two locations:
+1. **Project tools**: `.acai/tools/` in your project directory
+2. **User tools**: `~/.acai/tools/` in your home directory
+
+Project tools override user tools with the same name.
+
+### Configuration
+
+Dynamic tools are configured in your `.acai.json` file:
+
+```json
+{
+  "tools": {
+    "dynamicTools": {
+      "enabled": true,
+      "maxTools": 50
+    }
+  }
+}
+```
+
+- `enabled`: Enable/disable dynamic tools (default: true)
+- `maxTools`: Maximum number of tools to load (default: 50)
+
+### Security Considerations
+
+Dynamic tools run with the same privileges as Acai itself. Keep these security points in mind:
+
+- **Input Validation**: Always validate and sanitize input parameters
+- **Path Safety**: Be careful with file paths to prevent directory traversal
+- **Resource Limits**: Tools are automatically killed after 30 seconds
+- **No Shell Access**: Tools run directly with Node.js, not through a shell
+
+### Example Tools
+
+See the included `run-tests.js` tool in `.acai/tools/` for a complete example.
+
+### Listing Tools
+
+Use the `/list-tools` command to see all available tools, including dynamic tools:
+
+```
+> /list-tools
+Available tools:
+  Static tools:
+    bash
+    readFile
+    editFile
+    ...
+  Dynamic tools:
+    dynamic:run-tests
+    dynamic:my-custom-tool
+
+  Total: 14 static, 2 dynamic
+```
+
 ## Configuration
 
 ### Project Configuration

package/dist/agent/index.d.ts

@@ -0,0 +1,119 @@
+import type { LanguageModelUsage, ToolExecuteFunction } from "ai";
+import { type ToolCallRepairFunction } from "ai";
+import type { MessageHistory } from "../messages.ts";
+import type { ModelManager } from "../models/manager.ts";
+import type { ModelMetadata } from "../models/providers.ts";
+import type { TokenTracker } from "../tokens/tracker.ts";
+import type { CompleteToolSet } from "../tools/index.ts";
+type AgentOptions = {
+    modelManager: ModelManager;
+    tokenTracker: TokenTracker;
+    messageHistory: MessageHistory;
+    maxIterations?: number;
+    maxRetries?: number;
+    toolCallRepair?: ToolCallRepairFunction<CompleteToolSet>;
+};
+type RunOptions = {
+    systemPrompt: string;
+    input: string;
+    toolDefs: CompleteToolSet;
+    executors: Map<keyof CompleteToolSet, ToolExecuteFunction<unknown, string>>;
+    abortSignal?: AbortSignal;
+};
+export type ToolEvent = {
+    type: "tool-call-start";
+    name: string;
+    toolCallId: string;
+    msg: string;
+    args: unknown;
+} | {
+    type: "tool-call-update";
+    name: string;
+    toolCallId: string;
+    msg: string;
+    args: unknown;
+} | {
+    type: "tool-call-end";
+    name: string;
+    toolCallId: string;
+    msg: string;
+    args: unknown;
+} | {
+    type: "tool-call-error";
+    name: string;
+    toolCallId: string;
+    msg: string;
+    args: unknown;
+};
+export type AgentEvent = {
+    type: "agent-start";
+} | {
+    type: "agent-stop";
+} | {
+    type: "agent-error";
+    message: string;
+} | {
+    type: "step-start";
+} | {
+    type: "step-stop";
+} | {
+    type: "thinking-start";
+    content: string;
+} | {
+    type: "thinking";
+    content: string;
+} | {
+    type: "thinking-end";
+    content: string;
+} | {
+    type: "message";
+    role: "user";
+    content: string;
+} | {
+    type: "message-start";
+    role: "assistant";
+    content: string;
+} | {
+    type: "message";
+    role: "assistant";
+    content: string;
+} | {
+    type: "message-end";
+    role: "assistant";
+    content: string;
+} | ToolEvent;
+export type AgentState = {
+    modelId: string;
+    modelConfig: ModelMetadata;
+    steps: {
+        toolResults: Array<{
+            toolName: string;
+        }>;
+        toolCalls: Array<{
+            toolName: string;
+        }>;
+    }[];
+    usage: {
+        [K in keyof LanguageModelUsage]-?: number;
+    };
+    totalUsage: {
+        [K in keyof LanguageModelUsage]-?: number;
+    };
+    timestamps: {
+        start: number;
+        stop: number;
+    };
+};
+export declare class Agent {
+    private opts;
+    private _state;
+    private abortController;
+    constructor(opts: AgentOptions);
+    get state(): AgentState;
+    get abortSignal(): AbortSignal;
+    run(args: RunOptions): AsyncGenerator<AgentEvent>;
+    abort(): void;
+    resetState(): AgentState;
+}
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/agent/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../source/agent/index.ts"],"names":[],"mappings":"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"}