carto-md 2.0.0 → 2.0.1

package/src/acp/agent.js

@@ -0,0 +1,221 @@
+'use strict';
+
+const { Readable, Writable } = require('stream');
+const acp = require('@agentclientprotocol/sdk');
+const { SessionManager } = require('./session');
+const { buildSystemPrompt, buildContextBlock } = require('./prompt');
+const { CARTO_TOOLS, executeTool } = require('./tools');
+const { ProviderRegistry } = require('./providers');
+
+const MAX_ITERATIONS = 25;
+
+class CartoAgent {
+  constructor(connection) {
+    this.connection = connection;
+    this.sessions = new SessionManager();
+    this.providers = new ProviderRegistry();
+  }
+
+  async initialize(_params) {
+    return {
+      protocolVersion: acp.PROTOCOL_VERSION,
+      agentCapabilities: {
+        loadSession: false,
+        promptCapabilities: { image: false, audio: false, embeddedContext: true },
+      },
+      agentInfo: {
+        name: 'carto',
+        title: 'Carto',
+        version: require('../../package.json').version,
+      },
+      authMethods: [],
+    };
+  }
+
+  async authenticate(_params) {
+    return {};
+  }
+
+  async newSession(params) {
+    const session = this.sessions.create(params.cwd || process.cwd());
+    return { sessionId: session.id };
+  }
+
+  async setSessionMode(_params) {
+    return {};
+  }
+
+  async prompt(params) {
+    const session = this.sessions.get(params.sessionId);
+    if (!session) throw new Error(`Session ${params.sessionId} not found`);
+
+    session.abortController?.abort();
+    session.abortController = new AbortController();
+    const signal = session.abortController.signal;
+
+    try {
+      await this._runAgentLoop(params, session, signal);
+    } catch (err) {
+      if (signal.aborted) return { stopReason: 'cancelled' };
+      throw err;
+    }
+
+    session.abortController = null;
+    return { stopReason: 'end_turn' };
+  }
+
+  async cancel(params) {
+    const session = this.sessions.get(params.sessionId);
+    if (session) session.abortController?.abort();
+  }
+
+  // Provider methods
+  async unstable_listProviders(_params) {
+    return { providers: this.providers.list() };
+  }
+
+  async unstable_setProvider(params) {
+    this.providers.set(params);
+    return {};
+  }
+
+  async unstable_disableProvider(_params) {
+    this.providers.disable();
+    return {};
+  }
+
+  // Session list/load stubs
+  async listSessions(_params) { return { sessions: [] }; }
+  async closeSession(_params) { return {}; }
+
+  // ─── Agent Loop ──────────────────────────────────────────────────────────
+
+  async _runAgentLoop(params, session, signal) {
+    // 1. Ensure project is indexed
+    const indexMsg = await session.ensureIndexed();
+    if (indexMsg) {
+      await this.connection.sessionUpdate({
+        sessionId: session.id,
+        update: { sessionUpdate: 'agent_message_chunk', content: { type: 'text', text: indexMsg } },
+      });
+    }
+
+    // 2. Extract user message text
+    const userText = (params.prompt || [])
+      .filter(b => b.type === 'text')
+      .map(b => b.text)
+      .join('\n');
+
+    // 3. Build context from Carto intelligence
+    const contextBlock = buildContextBlock(session.carto, session.workingDir);
+
+    // 4. Build messages array
+    const systemPrompt = buildSystemPrompt(contextBlock);
+    const messages = [
+      { role: 'system', content: systemPrompt },
+      ...session.history,
+      { role: 'user', content: userText },
+    ];
+    session.history.push({ role: 'user', content: userText });
+
+    // 5. Get the active provider
+    const provider = this.providers.getActive();
+    if (!provider) {
+      const msg = 'No LLM provider configured. Please set a provider in your editor settings (API key + model).';
+      await this.connection.sessionUpdate({
+        sessionId: session.id,
+        update: { sessionUpdate: 'agent_message_chunk', content: { type: 'text', text: msg } },
+      });
+      session.history.push({ role: 'assistant', content: msg });
+      return;
+    }
+
+    // 6. Agent loop — iterate until no more tool calls or max iterations
+    let iterations = 0;
+    while (iterations++ < MAX_ITERATIONS) {
+      if (signal.aborted) throw new Error('cancelled');
+
+      const response = await provider.chat(messages, CARTO_TOOLS, signal);
+
+      // Stream text content
+      let assistantText = '';
+      let toolCalls = [];
+
+      for (const block of response.content) {
+        if (block.type === 'text' && block.text) {
+          assistantText += block.text;
+          await this.connection.sessionUpdate({
+            sessionId: session.id,
+            update: { sessionUpdate: 'agent_message_chunk', content: { type: 'text', text: block.text } },
+          });
+        } else if (block.type === 'tool_use') {
+          toolCalls.push(block);
+        }
+      }
+
+      // Add assistant message to history
+      messages.push({ role: 'assistant', content: response.content });
+
+      if (toolCalls.length === 0) {
+        session.history.push({ role: 'assistant', content: assistantText });
+        break;
+      }
+
+      // Execute tool calls
+      const toolResults = [];
+      for (const tc of toolCalls) {
+        // Report tool call to editor
+        await this.connection.sessionUpdate({
+          sessionId: session.id,
+          update: {
+            sessionUpdate: 'tool_call',
+            toolCallId: tc.id,
+            title: tc.name,
+            kind: 'other',
+            status: 'pending',
+            rawInput: tc.input,
+          },
+        });
+
+        // Execute
+        const result = await executeTool(tc.name, tc.input, session);
+
+        // Report completion
+        await this.connection.sessionUpdate({
+          sessionId: session.id,
+          update: {
+            sessionUpdate: 'tool_call_update',
+            toolCallId: tc.id,
+            status: 'completed',
+            content: [{ type: 'content', content: { type: 'text', text: typeof result === 'string' ? result : JSON.stringify(result) } }],
+            rawOutput: result,
+          },
+        });
+
+        toolResults.push({ type: 'tool_result', tool_use_id: tc.id, content: typeof result === 'string' ? result : JSON.stringify(result) });
+      }
+
+      // Add tool results to messages
+      messages.push({ role: 'user', content: toolResults });
+    }
+
+    if (iterations > MAX_ITERATIONS) {
+      await this.connection.sessionUpdate({
+        sessionId: session.id,
+        update: { sessionUpdate: 'agent_message_chunk', content: { type: 'text', text: '\n\n⚠️ Reached maximum iterations (25). Stopping.' } },
+      });
+    }
+  }
+}
+
+/**
+ * startAgent() — Entry point. Connects ACP over stdin/stdout.
+ */
+function startAgent() {
+  const input = Writable.toWeb(process.stdout);
+  const output = Readable.toWeb(process.stdin);
+  const stream = acp.ndJsonStream(input, output);
+  new acp.AgentSideConnection((conn) => new CartoAgent(conn), stream);
+}
+
+module.exports = { startAgent, CartoAgent };

package/src/acp/prompt.js

@@ -0,0 +1,69 @@
+'use strict';
+
+const SYSTEM_PROMPT_TEMPLATE = `You are Carto, an AI coding agent with deep architectural awareness.
+
+You understand this project's structure before writing a single line:
+- Every file's blast radius (what breaks if this changes)
+- All API routes and which files define them
+- Domain clusters (AUTH, PAYMENTS, DATABASE, etc.)
+- The full import graph and cross-domain dependencies
+
+RULES:
+1. Always check blast radius before making changes to high-impact files
+2. Reference real file names and routes — never hallucinate paths
+3. Make minimal, focused changes — read first, then write
+4. Warn the user if a change crosses domain boundaries
+5. After changes, confirm what was changed and what it affects
+6. Use existing patterns (check get_similar_patterns before writing new code)
+7. If unsure, read the relevant files — don't guess
+
+You have access to Carto tools that give you structural intelligence about this codebase. Use them proactively.
+
+PROJECT CONTEXT:
+{context}`;
+
+/**
+ * buildContextBlock(carto, workingDir)
+ * Generates a structural context summary from the indexed project.
+ */
+function buildContextBlock(carto, workingDir) {
+  if (!carto) return 'Project not yet indexed.';
+
+  try {
+    const lines = [];
+    const structure = carto.getStructure();
+
+    if (structure.stack && structure.stack.length > 0) {
+      lines.push(`Stack: ${structure.stack.join(', ')}`);
+    }
+
+    if (structure.meta) {
+      const m = structure.meta;
+      lines.push(`Size: ${m.totalFiles || 0} files, ${m.totalRoutes || 0} routes, ${m.totalImportEdges || 0} import edges`);
+    }
+
+    const domains = carto.getDomainsList();
+    if (domains.length > 0) {
+      lines.push(`Domains: ${domains.map(d => `${d.name} (${d.fileCount} files)`).join(', ')}`);
+    }
+
+    const highImpact = carto.getHighImpactFiles(5);
+    if (highImpact && highImpact.length > 0) {
+      lines.push(`High-impact files: ${highImpact.map(f => f.file || f).join(', ')}`);
+    }
+
+    return lines.join('\n') || 'Project indexed but no structural data available.';
+  } catch {
+    return 'Project indexed.';
+  }
+}
+
+/**
+ * buildSystemPrompt(contextBlock)
+ * Assembles the full system prompt with injected context.
+ */
+function buildSystemPrompt(contextBlock) {
+  return SYSTEM_PROMPT_TEMPLATE.replace('{context}', contextBlock);
+}
+
+module.exports = { buildSystemPrompt, buildContextBlock };

package/src/acp/providers/anthropic.js

@@ -0,0 +1,125 @@
+'use strict';
+
+const https = require('https');
+const { URL } = require('url');
+
+/**
+ * AnthropicProvider — Handles Anthropic Claude API (Messages API).
+ * Supports tool use and streaming-ready structure.
+ */
+class AnthropicProvider {
+  constructor(apiKey, baseUrl, model) {
+    this.apiKey = apiKey;
+    this.baseUrl = (baseUrl || 'https://api.anthropic.com').replace(/\/$/, '');
+    this.model = model;
+  }
+
+  /**
+   * chat(messages, tools, signal)
+   * Calls the Anthropic Messages API.
+   * Returns { content: [{ type: 'text', text } | { type: 'tool_use', id, name, input }] }
+   */
+  async chat(messages, tools, signal) {
+    // Separate system message from conversation
+    let system = '';
+    const conversationMessages = [];
+
+    for (const msg of messages) {
+      if (msg.role === 'system') {
+        system += (typeof msg.content === 'string' ? msg.content : '') + '\n';
+      } else {
+        conversationMessages.push(this._formatMessage(msg));
+      }
+    }
+
+    const body = {
+      model: this.model,
+      max_tokens: 8192,
+      system: system.trim(),
+      messages: conversationMessages,
+    };
+
+    if (tools && tools.length > 0) {
+      body.tools = tools.map(t => ({
+        name: t.name,
+        description: t.description,
+        input_schema: t.input_schema,
+      }));
+    }
+
+    const data = await this._request('/v1/messages', body, signal);
+    return this._parseResponse(data);
+  }
+
+  _formatMessage(msg) {
+    if (typeof msg.content === 'string') {
+      return { role: msg.role, content: msg.content };
+    }
+
+    if (Array.isArray(msg.content)) {
+      if (msg.role === 'assistant') {
+        // Pass through content blocks (text + tool_use)
+        return { role: 'assistant', content: msg.content };
+      }
+      if (msg.role === 'user') {
+        // Convert tool_result blocks to Anthropic format
+        const blocks = msg.content.map(b => {
+          if (b.type === 'tool_result') {
+            return { type: 'tool_result', tool_use_id: b.tool_use_id, content: b.content };
+          }
+          return b;
+        });
+        return { role: 'user', content: blocks };
+      }
+    }
+
+    return { role: msg.role, content: msg.content };
+  }
+
+  _parseResponse(data) {
+    if (!data.content) return { content: [{ type: 'text', text: 'No response from model.' }] };
+    // Anthropic already returns content in the format we need
+    return { content: data.content };
+  }
+
+  _request(endpoint, body, signal) {
+    return new Promise((resolve, reject) => {
+      const url = new URL(this.baseUrl + endpoint);
+
+      const options = {
+        hostname: url.hostname,
+        port: url.port || 443,
+        path: url.pathname + url.search,
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'x-api-key': this.apiKey,
+          'anthropic-version': '2023-06-01',
+        },
+      };
+
+      const req = https.request(options, (res) => {
+        let data = '';
+        res.on('data', chunk => { data += chunk; });
+        res.on('end', () => {
+          try {
+            const parsed = JSON.parse(data);
+            if (parsed.error) reject(new Error(parsed.error.message || JSON.stringify(parsed.error)));
+            else resolve(parsed);
+          } catch { reject(new Error(`Invalid JSON response: ${data.slice(0, 200)}`)); }
+        });
+      });
+
+      req.on('error', reject);
+
+      if (signal) {
+        signal.addEventListener('abort', () => { req.destroy(); reject(new Error('cancelled')); }, { once: true });
+      }
+
+      req.write(JSON.stringify(body));
+      req.end();
+    });
+  }
+}
+
+module.exports = { AnthropicProvider };

package/src/acp/providers/index.js

@@ -0,0 +1,83 @@
+'use strict';
+
+const { OpenAIProvider } = require('./openai');
+const { AnthropicProvider } = require('./anthropic');
+
+const SUPPORTED_PROVIDERS = [
+  { id: 'anthropic', name: 'Anthropic', defaultModel: 'claude-sonnet-4-20250514', models: ['claude-sonnet-4-20250514', 'claude-haiku-3-20250414'] },
+  { id: 'openai', name: 'OpenAI', defaultModel: 'gpt-4o', models: ['gpt-4o', 'gpt-4o-mini', 'o1', 'o3'] },
+  { id: 'gemini', name: 'Google Gemini', defaultModel: 'gemini-2.5-flash', models: ['gemini-2.5-pro', 'gemini-2.5-flash'] },
+  { id: 'ollama', name: 'Ollama (local)', defaultModel: 'llama3.1', models: [] },
+  { id: 'openrouter', name: 'OpenRouter', defaultModel: 'anthropic/claude-sonnet-4', models: [] },
+  { id: 'azure', name: 'Azure OpenAI', defaultModel: 'gpt-4o', models: [] },
+  { id: 'groq', name: 'Groq', defaultModel: 'llama-3.3-70b-versatile', models: [] },
+  { id: 'together', name: 'Together AI', defaultModel: 'meta-llama/Llama-3-70b-chat-hf', models: [] },
+];
+
+const DEFAULT_BASE_URLS = {
+  anthropic: 'https://api.anthropic.com',
+  openai: 'https://api.openai.com/v1',
+  gemini: 'https://generativelanguage.googleapis.com/v1beta/openai',
+  ollama: 'http://localhost:11434/v1',
+  openrouter: 'https://openrouter.ai/api/v1',
+  groq: 'https://api.groq.com/openai/v1',
+  together: 'https://api.together.xyz/v1',
+};
+
+class ProviderRegistry {
+  constructor() {
+    this._active = null;
+    this._config = null;
+  }
+
+  /**
+   * list() — Returns supported providers for ACP providers/list.
+   */
+  list() {
+    return SUPPORTED_PROVIDERS.map(p => ({
+      id: p.id,
+      name: p.name,
+      defaultModel: p.defaultModel,
+      models: p.models,
+    }));
+  }
+
+  /**
+   * set(params) — Configures the active provider from ACP providers/set.
+   * params: { providerId, apiKey, baseUrl?, model? }
+   */
+  set(params) {
+    const { providerId, apiKey, baseUrl, model } = params;
+    const providerDef = SUPPORTED_PROVIDERS.find(p => p.id === providerId);
+    if (!providerDef) throw new Error(`Unknown provider: ${providerId}`);
+
+    const resolvedModel = model || providerDef.defaultModel;
+    const resolvedUrl = baseUrl || DEFAULT_BASE_URLS[providerId] || '';
+
+    this._config = { providerId, apiKey, baseUrl: resolvedUrl, model: resolvedModel };
+
+    if (providerId === 'anthropic') {
+      this._active = new AnthropicProvider(apiKey, resolvedUrl, resolvedModel);
+    } else {
+      // All others use OpenAI-compatible API
+      this._active = new OpenAIProvider(apiKey, resolvedUrl, resolvedModel);
+    }
+  }
+
+  /**
+   * disable() — Clears the active provider.
+   */
+  disable() {
+    this._active = null;
+    this._config = null;
+  }
+
+  /**
+   * getActive() — Returns the active provider instance or null.
+   */
+  getActive() {
+    return this._active;
+  }
+}
+
+module.exports = { ProviderRegistry, SUPPORTED_PROVIDERS };

package/src/acp/providers/openai.js

@@ -0,0 +1,137 @@
+'use strict';
+
+const https = require('https');
+const http = require('http');
+const { URL } = require('url');
+
+/**
+ * OpenAIProvider — Handles OpenAI and all OpenAI-compatible APIs.
+ * Works with: OpenAI, Gemini, Ollama, OpenRouter, Together, Groq, Azure, LM Studio, vLLM.
+ */
+class OpenAIProvider {
+  constructor(apiKey, baseUrl, model) {
+    this.apiKey = apiKey;
+    this.baseUrl = baseUrl.replace(/\/$/, '');
+    this.model = model;
+  }
+
+  /**
+   * chat(messages, tools, signal)
+   * Calls the OpenAI-compatible /chat/completions endpoint.
+   * Returns { content: [{ type: 'text', text } | { type: 'tool_use', id, name, input }] }
+   */
+  async chat(messages, tools, signal) {
+    const body = {
+      model: this.model,
+      messages: this._formatMessages(messages),
+      stream: false,
+    };
+
+    if (tools && tools.length > 0) {
+      body.tools = tools.map(t => ({
+        type: 'function',
+        function: { name: t.name, description: t.description, parameters: t.input_schema },
+      }));
+    }
+
+    const data = await this._request('/chat/completions', body, signal);
+    return this._parseResponse(data);
+  }
+
+  _formatMessages(messages) {
+    const formatted = [];
+    for (const msg of messages) {
+      if (typeof msg.content === 'string') {
+        formatted.push({ role: msg.role, content: msg.content });
+      } else if (Array.isArray(msg.content)) {
+        // Handle tool_use blocks (assistant) and tool_result blocks (user)
+        if (msg.role === 'assistant') {
+          const text = msg.content.filter(b => b.type === 'text').map(b => b.text).join('');
+          const toolCalls = msg.content.filter(b => b.type === 'tool_use').map(b => ({
+            id: b.id,
+            type: 'function',
+            function: { name: b.name, arguments: JSON.stringify(b.input) },
+          }));
+          const entry = { role: 'assistant' };
+          if (text) entry.content = text;
+          if (toolCalls.length > 0) entry.tool_calls = toolCalls;
+          formatted.push(entry);
+        } else if (msg.role === 'user') {
+          // Tool results
+          for (const block of msg.content) {
+            if (block.type === 'tool_result') {
+              formatted.push({ role: 'tool', tool_call_id: block.tool_use_id, content: block.content });
+            } else if (block.type === 'text') {
+              formatted.push({ role: 'user', content: block.text });
+            }
+          }
+        }
+      }
+    }
+    return formatted;
+  }
+
+  _parseResponse(data) {
+    const choice = data.choices && data.choices[0];
+    if (!choice) return { content: [{ type: 'text', text: 'No response from model.' }] };
+
+    const msg = choice.message;
+    const content = [];
+
+    if (msg.content) {
+      content.push({ type: 'text', text: msg.content });
+    }
+
+    if (msg.tool_calls) {
+      for (const tc of msg.tool_calls) {
+        let input = {};
+        try { input = JSON.parse(tc.function.arguments); } catch {}
+        content.push({ type: 'tool_use', id: tc.id, name: tc.function.name, input });
+      }
+    }
+
+    return { content };
+  }
+
+  _request(endpoint, body, signal) {
+    return new Promise((resolve, reject) => {
+      const url = new URL(this.baseUrl + endpoint);
+      const isHttps = url.protocol === 'https:';
+      const mod = isHttps ? https : http;
+
+      const options = {
+        hostname: url.hostname,
+        port: url.port || (isHttps ? 443 : 80),
+        path: url.pathname + url.search,
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Authorization': `Bearer ${this.apiKey}`,
+        },
+      };
+
+      const req = mod.request(options, (res) => {
+        let data = '';
+        res.on('data', chunk => { data += chunk; });
+        res.on('end', () => {
+          try {
+            const parsed = JSON.parse(data);
+            if (parsed.error) reject(new Error(parsed.error.message || JSON.stringify(parsed.error)));
+            else resolve(parsed);
+          } catch { reject(new Error(`Invalid JSON response: ${data.slice(0, 200)}`)); }
+        });
+      });
+
+      req.on('error', reject);
+
+      if (signal) {
+        signal.addEventListener('abort', () => { req.destroy(); reject(new Error('cancelled')); }, { once: true });
+      }
+
+      req.write(JSON.stringify(body));
+      req.end();
+    });
+  }
+}
+
+module.exports = { OpenAIProvider };