protoagent 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Thomas Gauvin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,39 @@
+# ProtoAgent
+
+🤖 **Interactive AI coding agent that can read, write, and execute files in your terminal.**
+
+## Get Started
+
+```bash
+npm install -g protoagent
+protoagent
+```
+
+That's it! ProtoAgent will guide you through setup and start helping with your coding tasks.
+
+## What it does
+
+- **File Operations** - Read, write, edit, and search files
+- **Shell Commands** - Execute terminal commands safely
+- **Code Analysis** - Understand and analyze your codebase
+- **Project Generation** - Create files, folders, and entire project structures
+- **Interactive Chat** - Natural language interface for all coding tasks
+
+## Example Usage
+
+```
+protoagent> Create a React component called Button.tsx
+protoagent> Find all TODO comments in my project
+protoagent> Set up a Node.js Express server with TypeScript
+protoagent> Debug this error in my package.json
+protoagent> Show me the structure of my src folder
+```
+
+## Requirements
+
+- Node.js 16+
+- OpenAI API key (you'll be prompted to set this up on first run)
+
+## License
+
+MIT

package/dist/agentic-loop.js

@@ -0,0 +1,277 @@
+import { tools, handleToolCall } from './tools/index.js';
+import { createChatCompletion } from './config/client.js';
+import { generateSystemPrompt } from './config/system-prompt.js';
+import { getModelConfig } from './config/providers.js';
+import { estimateTokens, createUsageInfo, logUsageInfo, getContextInfo } from './utils/cost-tracker.js';
+import { checkAndCompactIfNeeded } from './utils/conversation-compactor.js';
+// Create system message for ProtoAgent dynamically
+async function createSystemMessage() {
+    const systemPrompt = await generateSystemPrompt();
+    return {
+        role: 'system',
+        content: systemPrompt
+    };
+}
+export class AgenticLoop {
+    constructor(openaiClient, config, options = {}) {
+        this.systemMessage = null;
+        this.openaiClient = openaiClient;
+        this.config = config;
+        this.options = {
+            maxIterations: options.maxIterations || 100,
+            streamOutput: options.streamOutput !== false, // Default to true
+        };
+        this.messages = []; // Will be initialized with system message in initialize()
+    }
+    /**
+     * Initialize the agentic loop with dynamic system message
+     */
+    async initialize() {
+        this.systemMessage = await createSystemMessage();
+        this.messages = [this.systemMessage];
+    }
+    /**
+     * Get the current conversation history
+     */
+    getMessages() {
+        return [...this.messages];
+    }
+    /**
+     * Clear the conversation history (keeps system message)
+     */
+    clearHistory() {
+        this.messages = this.systemMessage ? [this.systemMessage] : [];
+    }
+    /**
+     * Add a message to the conversation history
+     */
+    addMessage(message) {
+        this.messages.push(message);
+    }
+    /**
+     * Process a user input and run the agentic loop
+     */
+    async processUserInput(userInput) {
+        try {
+            // Add user message to conversation history
+            this.addMessage({
+                role: 'user',
+                content: userInput
+            });
+            console.log('🤔 Thinking...');
+            // Start the agentic loop
+            let continueProcessing = true;
+            let iterationCount = 0;
+            while (continueProcessing && iterationCount < this.options.maxIterations) {
+                iterationCount++;
+                try {
+                    // Check if conversation needs compaction before making API call
+                    const modelConfig = getModelConfig(this.config.provider, this.config.model);
+                    if (modelConfig) {
+                        const contextInfo = getContextInfo(this.messages, modelConfig);
+                        if (contextInfo.needsCompaction) {
+                            console.log('\n🗜️  Context window approaching limit, compacting conversation...');
+                            this.messages = await checkAndCompactIfNeeded(this.openaiClient, this.config.model, this.messages, modelConfig.contextWindow, contextInfo.currentTokens);
+                        }
+                    }
+                    // Create completion using OpenAI with built-in retry logic and cost tracking
+                    const { stream, estimatedInputTokens } = await createChatCompletion(this.openaiClient, {
+                        model: this.config.model,
+                        messages: this.messages,
+                        tools: tools,
+                        tool_choice: 'auto',
+                        stream: true
+                    }, this.config, this.messages);
+                    // Collect the streamed response
+                    let assistantMessage = {
+                        role: 'assistant',
+                        content: '',
+                        tool_calls: []
+                    };
+                    let streamedContent = '';
+                    let hasToolCalls = false;
+                    let actualUsage = undefined;
+                    for await (const chunk of stream) {
+                        const delta = chunk.choices[0]?.delta;
+                        if (chunk.usage) {
+                            actualUsage = chunk.usage;
+                        }
+                        if (delta?.content) {
+                            streamedContent += delta.content;
+                            assistantMessage.content = streamedContent;
+                            // Stream content to user in real-time if no tool calls are being made
+                            if (this.options.streamOutput && !hasToolCalls && !delta.tool_calls) {
+                                if (streamedContent === delta.content) {
+                                    // First content chunk
+                                    process.stdout.write('\\n🤖 ProtoAgent: ');
+                                }
+                                process.stdout.write(delta.content);
+                            }
+                        }
+                        if (delta?.tool_calls) {
+                            hasToolCalls = true;
+                            // Initialize tool_calls array if not exists
+                            if (!assistantMessage.tool_calls) {
+                                assistantMessage.tool_calls = [];
+                            }
+                            // Handle tool calls in streaming
+                            for (const toolCallDelta of delta.tool_calls) {
+                                const index = toolCallDelta.index || 0;
+                                // Ensure we have an entry at this index
+                                if (!assistantMessage.tool_calls[index]) {
+                                    assistantMessage.tool_calls[index] = {
+                                        id: '',
+                                        type: 'function',
+                                        function: { name: '', arguments: '' }
+                                    };
+                                }
+                                if (toolCallDelta.id) {
+                                    assistantMessage.tool_calls[index].id = toolCallDelta.id;
+                                }
+                                if (toolCallDelta.function?.name) {
+                                    assistantMessage.tool_calls[index].function.name += toolCallDelta.function.name;
+                                }
+                                if (toolCallDelta.function?.arguments) {
+                                    assistantMessage.tool_calls[index].function.arguments += toolCallDelta.function.arguments;
+                                }
+                            }
+                        }
+                    }
+                    const message = assistantMessage;
+                    // Calculate and log cost information
+                    if (modelConfig) {
+                        const finalInputTokens = actualUsage?.prompt_tokens ?? estimatedInputTokens;
+                        const finalOutputTokens = actualUsage?.completion_tokens ?? estimateTokens(message.content || '');
+                        const usageInfo = createUsageInfo(finalInputTokens, finalOutputTokens, modelConfig);
+                        const contextInfo = getContextInfo(this.messages, modelConfig);
+                        logUsageInfo(usageInfo, contextInfo, modelConfig);
+                    }
+                    // Check if AI wants to use tools
+                    if (message.tool_calls && message.tool_calls.length > 0) {
+                        // Add the AI's message (with tool calls) to conversation
+                        this.addMessage(message);
+                        console.log(`🔧 Using ${message.tool_calls.length} tool(s)...`);
+                        // Execute each tool call
+                        for (const toolCall of message.tool_calls) {
+                            const { name, arguments: args } = toolCall.function;
+                            console.log(`🛠️  ${name}`);
+                            try {
+                                const toolArgs = JSON.parse(args);
+                                const result = await handleToolCall(name, toolArgs);
+                                // Add tool result to conversation
+                                this.addMessage({
+                                    role: 'tool',
+                                    tool_call_id: toolCall.id,
+                                    content: result
+                                });
+                                // Show abbreviated result to user
+                                const lines = result.split('\\n');
+                                if (lines.length > 10) {
+                                    console.log(`   ✅ ${lines.slice(0, 3).join('\\n   ')}\\n   ... (${lines.length - 6} more lines) ...\\n   ${lines.slice(-3).join('\\n   ')}`);
+                                }
+                                else {
+                                    console.log(`   ✅ ${result.slice(0, 200)}${result.length > 200 ? '...' : ''}`);
+                                }
+                            }
+                            catch (error) {
+                                const errorMessage = error instanceof Error ? error.message : String(error);
+                                console.log(`   ❌ Error: ${errorMessage}`);
+                                // Add error result to conversation
+                                this.addMessage({
+                                    role: 'tool',
+                                    tool_call_id: toolCall.id,
+                                    content: `Error: ${errorMessage}`
+                                });
+                            }
+                        }
+                        // Continue the loop to let AI process tool results
+                        continue;
+                    }
+                    else {
+                        // AI provided a regular response
+                        if (message.content && !hasToolCalls) {
+                            // Content was already streamed to user during the loop above
+                            if (this.options.streamOutput) {
+                                console.log('\\n'); // Add newline after streaming is complete
+                            }
+                            else {
+                                console.log(`\\n🤖 ProtoAgent: ${message.content}\\n`);
+                            }
+                            // Add AI response to conversation history
+                            this.addMessage({
+                                role: 'assistant',
+                                content: message.content
+                            });
+                        }
+                        else if (message.content && hasToolCalls) {
+                            // AI provided content along with tool calls (rare case)
+                            if (this.options.streamOutput) {
+                                process.stdout.write('\\n🤖 ProtoAgent: ');
+                                process.stdout.write(message.content);
+                                console.log('\\n');
+                            }
+                            else {
+                                console.log(`\\n🤖 ProtoAgent: ${message.content}\\n`);
+                            }
+                            // Add AI response to conversation history
+                            this.addMessage({
+                                role: 'assistant',
+                                content: message.content
+                            });
+                        }
+                        continueProcessing = false;
+                    }
+                }
+                catch (apiError) {
+                    // Handle API errors that weren't caught by the retry logic
+                    console.error('\\n❌ API Error:', apiError?.message || 'Unknown API error');
+                    // Check for specific error types and provide helpful messages
+                    if (apiError?.status === 401) {
+                        console.log('💡 Authentication failed. Your API key may be invalid or expired.');
+                        console.log('   Run: protoagent config --update-key');
+                    }
+                    else if (apiError?.status === 403) {
+                        console.log('💡 Access forbidden. Check your API key permissions or billing status.');
+                    }
+                    else if (apiError?.status === 400) {
+                        console.log('💡 Bad request. There may be an issue with the request format.');
+                        console.log('   This could be a bug in ProtoAgent. Please check for updates.');
+                    }
+                    else {
+                        console.log('💡 An unexpected API error occurred. Please try again.');
+                    }
+                    // Exit the processing loop for API errors
+                    break;
+                }
+            }
+            if (iterationCount >= this.options.maxIterations) {
+                console.log('\\n⚠️  Maximum iteration limit reached. Task may be incomplete.');
+            }
+        }
+        catch (error) {
+            // Handle general processing errors
+            console.error('\\n❌ Error during processing:', error?.message || 'Unknown error');
+            // Provide helpful error messages for common issues
+            if (error?.message?.includes('API key')) {
+                console.log('💡 There seems to be an issue with your API key configuration.');
+                console.log('   Run: protoagent config --show');
+            }
+            else if (error?.message?.includes('model')) {
+                console.log('💡 There seems to be an issue with the selected model.');
+                console.log('   Run: protoagent config --update-model');
+            }
+            else {
+                console.log('💡 An unexpected error occurred. Please check your configuration and try again.');
+            }
+            console.log('\\n🤖 ProtoAgent: I encountered an error and cannot continue processing this request.\\n');
+        }
+    }
+}
+/**
+ * Create a new agentic loop instance
+ */
+export async function createAgenticLoop(openaiClient, config, options) {
+    const loop = new AgenticLoop(openaiClient, config, options);
+    await loop.initialize();
+    return loop;
+}

package/dist/config/client.js

@@ -0,0 +1,166 @@
+/**
+ * OpenAI client manager for ProtoAgent
+ */
+import OpenAI from 'openai';
+import { geminiProvider, cerebrasProvider, getModelConfig } from './providers.js';
+import { estimateTokens, getContextInfo } from '../utils/cost-tracker.js';
+/**
+ * Create OpenAI client from configuration
+ */
+export function createOpenAIClient(config) {
+    if (config.provider === 'openai') {
+        return new OpenAI({
+            apiKey: config.credentials.OPENAI_API_KEY
+        });
+    }
+    if (config.provider === 'gemini') {
+        return new OpenAI({
+            apiKey: config.credentials.GEMINI_API_KEY,
+            baseURL: geminiProvider.baseURL
+        });
+    }
+    if (config.provider === 'cerebras') {
+        return new OpenAI({
+            apiKey: config.credentials.CEREBRAS_API_KEY,
+            baseURL: cerebrasProvider.baseURL
+        });
+    }
+    throw new Error(`Unsupported provider: ${config.provider}`);
+}
+/**
+ * Sleep for a given number of milliseconds
+ */
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+/**
+ * Check if an error is retryable
+ */
+function isRetryableError(error) {
+    // Check for rate limiting (429)
+    if (error?.status === 429) {
+        return true;
+    }
+    // Check for server errors (5xx)
+    if (error?.status >= 500 && error?.status < 600) {
+        return true;
+    }
+    // Check for network/connection errors
+    if (error?.code === 'ECONNRESET' ||
+        error?.code === 'ENOTFOUND' ||
+        error?.code === 'ECONNREFUSED' ||
+        error?.message?.includes('network') ||
+        error?.message?.includes('timeout')) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Get appropriate delay for rate limiting based on error
+ */
+function getRateLimitDelay(error, attempt) {
+    // Check for Retry-After header (OpenAI provides this for rate limits)
+    if (error?.headers?.['retry-after']) {
+        const retryAfter = parseInt(error.headers['retry-after'], 10);
+        if (!isNaN(retryAfter)) {
+            return retryAfter * 1000; // Convert to milliseconds
+        }
+    }
+    // Default exponential backoff for rate limits: 2^attempt seconds (min 2s, max 60s)
+    const baseDelay = Math.min(Math.pow(2, attempt) * 1000, 60000);
+    const jitter = Math.random() * 1000; // Add jitter to prevent thundering herd
+    return Math.max(baseDelay + jitter, 2000); // Minimum 2 seconds
+}
+/**
+ * Get delay for general retryable errors
+ */
+function getRetryDelay(attempt) {
+    // Exponential backoff: 1, 2, 4 seconds with jitter
+    const baseDelay = Math.pow(2, attempt - 1) * 1000;
+    const jitter = Math.random() * 500;
+    return Math.min(baseDelay + jitter, 4000); // Max 4 seconds
+}
+/**
+ * Create chat completion with OpenAI with retry logic and cost tracking
+ */
+export async function createChatCompletion(client, params, config, messages) {
+    const maxRetries = 3;
+    let lastError;
+    // Get model configuration for cost tracking
+    const modelConfig = getModelConfig(config.provider, config.model);
+    // Estimate input tokens for cost calculation
+    const estimatedInputTokens = messages.reduce((total, msg) => {
+        if ('content' in msg && msg.content && typeof msg.content === 'string') {
+            return total + estimateTokens(msg.content);
+        }
+        return total;
+    }, 0);
+    // Log context information before making the request
+    if (modelConfig) {
+        const contextInfo = getContextInfo(messages, modelConfig);
+        console.log(`📊 Context: ${contextInfo.currentTokens}/${contextInfo.maxTokens} tokens (${contextInfo.utilizationPercentage.toFixed(1)}%)`);
+        if (contextInfo.needsCompaction) {
+            console.log(`⚠️  Context approaching limit - automatic compaction will trigger soon`);
+        }
+    }
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+        try {
+            const stream = await client.chat.completions.create({
+                ...params,
+                stream: true,
+                stream_options: { include_usage: true }
+            });
+            return { stream, estimatedInputTokens };
+        }
+        catch (error) {
+            lastError = error;
+            // Handle rate limiting (429) specially
+            if (error?.status === 429) {
+                const delay = getRateLimitDelay(error, attempt);
+                const seconds = Math.round(delay / 1000);
+                if (attempt < maxRetries) {
+                    console.log(`\n⏳ Rate limited by API. Waiting ${seconds} seconds before retry (attempt ${attempt}/${maxRetries})...`);
+                    await sleep(delay);
+                    continue;
+                }
+                else {
+                    console.error('\n❌ Rate limit exceeded. Maximum retries reached.');
+                    console.log('💡 Tip: Consider upgrading your API plan or waiting before making more requests.');
+                    break;
+                }
+            }
+            // Handle other retryable errors
+            if (isRetryableError(error) && attempt < maxRetries) {
+                const delay = getRetryDelay(attempt);
+                const seconds = Math.round(delay / 1000);
+                console.log(`\n⚠️  API error (${error?.status || error?.code || 'unknown'}). Retrying in ${seconds} seconds (attempt ${attempt}/${maxRetries})...`);
+                await sleep(delay);
+                continue;
+            }
+            // For non-retryable errors or max retries reached, break immediately
+            break;
+        }
+    }
+    // If we get here, all retries failed
+    console.error('\n❌ API request failed after all retry attempts.');
+    // Provide user-friendly error messages
+    if (lastError?.status === 401) {
+        console.log('💡 This looks like an authentication error. Check your API key configuration.');
+        console.log('   Run: protoagent config --update-key');
+    }
+    else if (lastError?.status === 429) {
+        console.log('💡 Rate limit exceeded. Try again later or upgrade your API plan.');
+    }
+    else if (lastError?.status === 403) {
+        console.log('💡 Access forbidden. Check your API key permissions and billing status.');
+    }
+    else if (lastError?.status >= 500) {
+        console.log('💡 Server error. The API service may be temporarily unavailable.');
+    }
+    else if (lastError?.code === 'ENOTFOUND' || lastError?.message?.includes('network')) {
+        console.log('💡 Network connection error. Check your internet connection.');
+    }
+    // Suggest graceful shutdown
+    console.log('\n🚪 ProtoAgent will now exit. Please resolve the issue and try again.');
+    process.exit(1);
+}