carto-md 2.0.0 → 2.0.2

package/BENCHMARK_RESULTS.md

@@ -0,0 +1,34 @@
+# Carto V2 Benchmark Results
+
+Generated: 2026-05-28T17:58:28.019Z
+Platform: Node v20.20.1 · 8 CPUs · 8192.0 MB RAM · darwin arm64
+
+| Repo | Source Files | Indexed | First Run | Second Run | DB Size | Routes | Import Edges |
+|------|-------------|---------|-----------|------------|---------|--------|--------------|
+| prisma | 3303 | 3303 | 1.6s | 178ms | 2.2 MB | 10 | 3590 |
+| supabase | 6818 | 6746 | 4.9s | 725ms | 4.3 MB | 90 | 5754 |
+| vscode | 10565 | 10565 | 9.7s | 1.2s | 10.6 MB | 11 | 19769 |
+| zed | 1837 | 1837 | 2.7s | 83ms | 4.7 MB | 12 | 2176 |
+
+## Domains Detected
+
+**prisma:** DATABASE(1044) · CORE(752) · EVENTS(36) · AUTH(8)
+**supabase:** CORE(4243) · AUTH(412) · DATABASE(387) · PAYMENTS(51) · EVENTS(17) · NOTIFICATIONS(12) · TRPC(3)
+**vscode:** CORE(5330) · AUTH(850) · EVENTS(446) · DATABASE(419) · NOTIFICATIONS(5)
+**zed:** CORE(1424) · DATABASE(110) · AUTH(75) · EVENTS(55) · PAYMENTS(53) · NOTIFICATIONS(10) · TRPC(2)
+
+## MCP Query Latency
+
+| Repo | get_structure | get_routes | get_domains_list |
+|------|--------------|------------|-----------------|
+| prisma | 0ms | 0ms | 1ms |
+| supabase | 1ms | 0ms | 3ms |
+| vscode | 1ms | 0ms | 3ms |
+| zed | 0ms | 0ms | 1ms |
+
+## Target Assessment
+
+- **prisma**: ✅ All targets met
+- **supabase**: ✅ All targets met
+- **vscode**: ✅ All targets met
+- **zed**: ✅ All targets met

package/CONTRIBUTING.md

@@ -215,7 +215,7 @@ cd carto
 npm install
 node src/cli/index.js init   # test in any project
 node src/cli/index.js serve  # test MCP server
-npm test                     # run test suite (30 tests)
+npm test                     # run test suite (35 tests)
 node test/correctness.js     # run correctness tests (31 tests)
 node test/benchmark.js       # run benchmarks against real repos
 ```
@@ -232,7 +232,7 @@ node test/benchmark.js       # run benchmarks against real repos
 - [ ] Extension added to `CODE_EXTS` and `detectLanguage()` in `sync-v2.js`
 - [ ] No changes to merger logic (unless explicitly fixing a merger bug)
 - [ ] No network calls added
-- [ ] `npm test` passes (30/30)
+- [ ] `npm test` passes (35/35)
 - [ ] `node test/correctness.js` passes (31/31)
 
 ---

package/README.md

@@ -162,12 +162,70 @@ Custom domains via `carto.config.json`:
 | `carto sync` | Full re-index (skips unchanged files via mtime+size cache) |
 | `carto watch` | Incremental live re-index on every file save (<50ms) |
 | `carto serve` | Start MCP server for Kiro / Cursor / Claude |
+| `carto agent` | Start ACP agent mode (for Zed / JetBrains / VS Code) |
 | `carto impact <file>` | Blast radius: risk level, affected files, routes at risk |
 | `carto check` | Cross-domain violations, high-risk uncommitted changes, domain health |
 | `carto remove` | Remove AGENTS.md and .carto/ from project |
 
 ---
 
+## ACP Agent (Zed / JetBrains / VS Code)
+
+Carto works as a full **ACP agent** — not just a passive tool server, but an active coding agent with architectural awareness.
+
+```
+User: "Add rate limiting to /api/users"
+  ↓
+Carto auto-queries its own SQLite:
+  - Blast radius of relevant files
+  - Domain context (AUTH)
+  - Similar patterns in codebase
+  ↓
+Builds rich prompt with structural context
+  ↓
+Sends to LLM (your API key) → streams answer + diffs back to editor
+```
+
+### Setup in Zed
+
+Add to `~/.config/zed/settings.json`:
+
+```json
+{
+  "agent_servers": {
+    "Carto": {
+      "command": "carto",
+      "args": ["agent"]
+    }
+  }
+}
+```
+
+### BYOK (Bring Your Own Key)
+
+Carto supports any LLM provider — configure in your editor:
+
+| Provider | Models |
+|----------|--------|
+| Anthropic | Claude Sonnet 4, Haiku |
+| OpenAI | GPT-4o, GPT-4o-mini, o1, o3 |
+| Google Gemini | Gemini 2.5 Pro, 2.5 Flash |
+| Ollama | Any local model (free) |
+| OpenRouter | Any model via single API |
+| Groq | Ultra-fast inference |
+| Together AI | Open-source models |
+| Azure OpenAI | Enterprise deployments |
+
+### What makes it different
+
+Other agents are smart but blind. Carto sees the architecture:
+- Auto-indexes your project on first session (1-10s depending on size)
+- Injects structural context into every LLM call (blast radius, domains, routes)
+- 12 internal tools the LLM can call during reasoning
+- Zero cost to you beyond your own API key
+
+---
+
 ## V1 → V2 migration
 
 Run `carto sync` — it auto-migrates your existing `graph-cache.json` and `map.json` into SQLite and renames them to `.bak`. No manual steps.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "carto-md",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "Structural intelligence layer for AI coding tools. Indexes your codebase into SQLite — routes, models, import graph, blast radius, domains — and exposes 16 MCP tools for Kiro, Cursor, and Claude.",
   "bin": {
     "carto": "src/cli/index.js"
@@ -12,6 +12,7 @@
     "test:benchmark": "node test/benchmark.js"
   },
   "dependencies": {
+    "@agentclientprotocol/sdk": "^0.22.1",
     "@babel/parser": "^7.29.3",
     "@modelcontextprotocol/sdk": "^1.0.0",
     "better-sqlite3": "11.7.0",
@@ -39,6 +40,8 @@
     "agents",
     "AGENTS.md",
     "AI",
+    "acp",
+    "agent-client-protocol",
     "context",
     "codebase",
     "developer-tools",
@@ -51,6 +54,7 @@
     "blast-radius",
     "import-graph",
     "kiro",
-    "claude"
+    "claude",
+    "zed"
   ]
 }

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 };

package/src/acp/session.js

@@ -0,0 +1,71 @@
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const { Carto } = require('../engine/carto');
+
+class Session {
+  constructor(id, workingDir) {
+    this.id = id;
+    this.workingDir = workingDir;
+    this.history = [];
+    this.abortController = null;
+    this.carto = null;
+    this._indexed = false;
+  }
+
+  /**
+   * ensureIndexed() — Auto-indexes the project if .carto/carto.db is missing.
+   * Returns a status message if indexing was performed, null otherwise.
+   */
+  async ensureIndexed() {
+    if (this._indexed) return null;
+
+    const dbPath = path.join(this.workingDir, '.carto', 'carto.db');
+    this.carto = new Carto();
+
+    if (fs.existsSync(dbPath)) {
+      // DB exists — just load the index (fast path, <10ms)
+      await this.carto.index(this.workingDir);
+      this._indexed = true;
+      return null;
+    }
+
+    // No DB — run full indexing
+    const start = Date.now();
+    await this.carto.index(this.workingDir, { useWorkers: true });
+    this._indexed = true;
+
+    const meta = this.carto.getMeta();
+    const duration = ((Date.now() - start) / 1000).toFixed(1);
+    const domains = this.carto.getDomainsList();
+    const routes = this.carto.getRoutes();
+
+    return `✓ Indexed project in ${duration}s — ${meta.totalFiles || 0} files, ${routes.length} routes, ${domains.length} domains detected.\n\n`;
+  }
+}
+
+class SessionManager {
+  constructor() {
+    this._sessions = new Map();
+  }
+
+  create(workingDir) {
+    const id = crypto.randomBytes(16).toString('hex');
+    const dir = workingDir || process.cwd();
+    const session = new Session(id, dir);
+    this._sessions.set(id, session);
+    return session;
+  }
+
+  get(id) {
+    return this._sessions.get(id) || null;
+  }
+
+  delete(id) {
+    this._sessions.delete(id);
+  }
+}
+
+module.exports = { Session, SessionManager };

package/src/acp/tools.js

@@ -0,0 +1,150 @@
+'use strict';
+
+/**
+ * Carto tools exposed to the LLM during the agent loop.
+ * These wrap the Carto engine's query methods as tool definitions
+ * compatible with OpenAI/Anthropic function calling format.
+ */
+
+const CARTO_TOOLS = [
+  {
+    name: 'get_blast_radius',
+    description: 'Get all files, routes, and domains affected by changing a specific file. Use before making changes to understand impact.',
+    input_schema: { type: 'object', properties: { file: { type: 'string', description: 'Relative file path from project root' } }, required: ['file'] },
+  },
+  {
+    name: 'get_context',
+    description: 'Get full structural context for a file: domain, blast radius, import neighbors, routes, models, env vars, and cross-domain dependencies.',
+    input_schema: { type: 'object', properties: { file: { type: 'string', description: 'Relative file path from project root' } }, required: ['file'] },
+  },
+  {
+    name: 'get_structure',
+    description: 'Get project structure: import graph summary, entry points, high impact files, tech stack, and domains.',
+    input_schema: { type: 'object', properties: {}, required: [] },
+  },
+  {
+    name: 'get_domain',
+    description: 'Get all routes, models, functions, and context for a specific domain (e.g. AUTH, PAYMENTS, DATABASE, CORE).',
+    input_schema: { type: 'object', properties: { domain: { type: 'string', description: 'Domain name e.g. AUTH, PAYMENTS' } }, required: ['domain'] },
+  },
+  {
+    name: 'get_routes',
+    description: 'Get all API routes in this project including REST, tRPC, and webhooks.',
+    input_schema: { type: 'object', properties: {}, required: [] },
+  },
+  {
+    name: 'get_change_plan',
+    description: 'Given a natural-language intent, returns files to touch, domains affected, blast radius, and similar patterns.',
+    input_schema: { type: 'object', properties: { intent: { type: 'string', description: 'What you want to change, e.g. "add rate limiting to /api/users"' } }, required: ['intent'] },
+  },
+  {
+    name: 'get_similar_patterns',
+    description: 'Find structurally similar files — same domain, same route shape, or shared dependencies. Use to find conventions before writing new code.',
+    input_schema: { type: 'object', properties: { file: { type: 'string', description: 'Relative file path' }, limit: { type: 'number', description: 'Max results (default 5)' } }, required: ['file'] },
+  },
+  {
+    name: 'get_neighbors',
+    description: 'Get import graph neighbors of a file — files it imports and files that import it.',
+    input_schema: { type: 'object', properties: { file: { type: 'string', description: 'Relative file path' }, hops: { type: 'number', description: 'Hops to traverse (default 1, max 3)' } }, required: ['file'] },
+  },
+  {
+    name: 'get_cross_domain',
+    description: 'Get all import edges that cross domain boundaries. Use to detect unexpected coupling.',
+    input_schema: { type: 'object', properties: {}, required: [] },
+  },
+  {
+    name: 'get_high_impact_files',
+    description: 'Get the files with the highest blast radius — most other files depend on them.',
+    input_schema: { type: 'object', properties: { limit: { type: 'number', description: 'Number of files (default 10)' } }, required: [] },
+  },
+  {
+    name: 'search_routes',
+    description: 'Search API routes by path or method. Case-insensitive.',
+    input_schema: { type: 'object', properties: { query: { type: 'string', description: 'Search query e.g. "auth", "POST"' } }, required: ['query'] },
+  },
+  {
+    name: 'get_models',
+    description: 'Get all data models (Prisma, Zod, TypeScript interfaces, etc.), optionally filtered by domain.',
+    input_schema: { type: 'object', properties: { domain: { type: 'string', description: 'Optional domain filter' } }, required: [] },
+  },
+];
+
+/**
+ * executeTool(name, input, session)
+ * Executes a Carto tool and returns the result as a string.
+ */
+function executeTool(name, input, session) {
+  const carto = session.carto;
+  if (!carto) return 'Project not indexed. Cannot execute tool.';
+
+  try {
+    switch (name) {
+      case 'get_blast_radius': {
+        const result = carto.getBlastRadius(input.file);
+        if (!result) return `File not found: ${input.file}`;
+        return JSON.stringify(result, null, 2);
+      }
+      case 'get_context': {
+        const result = carto.getContextForFile(input.file);
+        if (!result) return `File not found: ${input.file}`;
+        return JSON.stringify(result, null, 2);
+      }
+      case 'get_structure': {
+        const s = carto.getStructure();
+        return JSON.stringify({
+          stack: s.stack,
+          domains: s.domains,
+          entryPoints: s.entryPoints,
+          highImpact: (s.highImpact || []).slice(0, 10),
+          meta: s.meta,
+        }, null, 2);
+      }
+      case 'get_domain': {
+        const result = carto.getDomain(input.domain);
+        if (!result) return `Domain not found: ${input.domain}`;
+        return JSON.stringify(result, null, 2);
+      }
+      case 'get_routes': {
+        return JSON.stringify(carto.getRoutes(), null, 2);
+      }
+      case 'get_change_plan': {
+        // Synthesize a change plan from structural data
+        const routes = carto.searchRoutes(input.intent);
+        const structure = carto.getStructure();
+        const domains = carto.getDomainsList();
+        return JSON.stringify({ matchingRoutes: routes, domains, highImpact: (structure.highImpact || []).slice(0, 5) }, null, 2);
+      }
+      case 'get_similar_patterns': {
+        // Find files in same domain with similar structure
+        const ctx = carto.getContextForFile(input.file);
+        if (!ctx) return `File not found: ${input.file}`;
+        const domain = carto.getDomain(ctx.domain);
+        const limit = input.limit || 5;
+        const similar = (domain && domain.files || []).filter(f => f !== input.file).slice(0, limit);
+        return JSON.stringify({ domain: ctx.domain, similarFiles: similar }, null, 2);
+      }
+      case 'get_neighbors': {
+        const result = carto.getNeighbors(input.file, input.hops || 1);
+        return JSON.stringify(result, null, 2);
+      }
+      case 'get_cross_domain': {
+        return JSON.stringify(carto.getCrossDomainDeps().slice(0, 50), null, 2);
+      }
+      case 'get_high_impact_files': {
+        return JSON.stringify(carto.getHighImpactFiles(input.limit || 10), null, 2);
+      }
+      case 'search_routes': {
+        return JSON.stringify(carto.searchRoutes(input.query), null, 2);
+      }
+      case 'get_models': {
+        return JSON.stringify(carto.getModels(input.domain), null, 2);
+      }
+      default:
+        return `Unknown tool: ${name}`;
+    }
+  } catch (err) {
+    return `Tool error (${name}): ${err.message}`;
+  }
+}
+
+module.exports = { CARTO_TOOLS, executeTool };

package/src/agents/formatter.js

@@ -16,6 +16,9 @@ function formatSections({ routes, models, frontend, structure, warnings, fileMap
       sections.push(`- ${icon} ${entry.name}${suffix}`);
     }
   } else {
+    if (process.env.CARTO_DEBUG) {
+      console.warn('[CARTO] Warning: structure data was empty when formatting AGENTS.md');
+    }
     sections.push('_No structure data available._');
   }
 

package/src/agents/scan-structure.js

@@ -0,0 +1,69 @@
+'use strict';
+
+const fs = require('fs');
+
+/**
+ * IGNORE_DIRS — names skipped at the top level when listing project structure.
+ *
+ * This is intentionally a *small* set tuned for the "Project Structure (auto)"
+ * block in AGENTS.md. It is NOT the same as the recursive file-discovery
+ * ignore lists (e.g. JS_IGNORE / PYTHON_IGNORE in src/detector/files.js or
+ * IGNORE_DIRS in src/store/sync-v2.js) — those filter what gets indexed.
+ *
+ * Top-level structure should still surface things like `dist/`, `build/`,
+ * `coverage/` (so users see what their project actually contains), but it
+ * should hide noise (`node_modules`, `.git`, `.carto`, etc.) and the file
+ * the structure block is about to be merged into (`AGENTS.md`).
+ *
+ * Anchored on the original V1 set in src/sync.js so existing AGENTS.md
+ * outputs do not drift after the V1 → V2 cleanup.
+ */
+const IGNORE_DIRS = new Set([
+  'node_modules',
+  '.git',
+  '__pycache__',
+  '.venv',
+  'venv',
+  '.idea',
+  '.vscode',
+  '.carto',
+  'AGENTS.md'
+]);
+
+/**
+ * scanStructure(basePath) → Array<{ name: string, type: 'dir' | 'file' }>
+ *
+ * Lists the immediate children of `basePath` (one level deep, no recursion).
+ * Filters out IGNORE_DIRS. Sorts: directories before files; alphabetical
+ * within each group.
+ *
+ * Symlinks are reported by Dirent as neither dir nor file → treated as 'file'.
+ * Failures (missing dir, EACCES, etc.) return an empty array silently — the
+ * formatter handles the empty case.
+ */
+async function scanStructure(basePath) {
+  const entries = [];
+  let items;
+  try {
+    items = await fs.promises.readdir(basePath, { withFileTypes: true });
+  } catch {
+    return entries;
+  }
+
+  for (const item of items) {
+    if (IGNORE_DIRS.has(item.name)) continue;
+    entries.push({
+      name: item.name,
+      type: item.isDirectory() ? 'dir' : 'file'
+    });
+  }
+
+  entries.sort((a, b) => {
+    if (a.type !== b.type) return a.type === 'dir' ? -1 : 1;
+    return a.name.localeCompare(b.name);
+  });
+
+  return entries;
+}
+
+module.exports = { scanStructure, IGNORE_DIRS };

package/src/cli/agent.js

@@ -0,0 +1,13 @@
+'use strict';
+
+const { startAgent } = require('../acp/agent');
+
+/**
+ * `carto agent` — Starts Carto in ACP mode (stdin/stdout).
+ * Editors like Zed and JetBrains spawn this as a subprocess.
+ */
+function run() {
+  startAgent();
+}
+
+module.exports = { run };

package/src/cli/index.js

@@ -15,6 +15,7 @@ Commands:
   check         Report cross-domain deps, high-risk uncommitted changes, domain health
   remove        Remove AGENTS.md and .carto/ from this project
   serve         Start MCP server for AI tool integration
+  agent         Start ACP agent mode (for Zed, JetBrains, VS Code)
 
 Options:
   --help, -h   Show this help message
@@ -58,6 +59,8 @@ if (command === 'init') {
   require('./remove').run(process.cwd());
 } else if (command === 'serve') {
   require('./serve').run(process.cwd());
+} else if (command === 'agent') {
+  require('./agent').run();
 } else {
   console.error(`[CARTO] Unknown command: ${command}`);
   printUsage();

package/src/store/sync-v2.js

@@ -13,6 +13,7 @@ const { clusterByDomain } = require('../agents/domains');
 const { clusterByGraph } = require('../agents/leiden');
 const { formatSections, formatDomainFile } = require('../agents/formatter');
 const { mergeIntoAgentsMd } = require('../agents/merger');
+const { scanStructure } = require('../agents/scan-structure');
 const { WorkerPool, POOL_SIZE } = require('../engine/worker-pool');
 const { parseCartoIgnore } = require('../security/ignore');
 
@@ -420,7 +421,7 @@ async function runSyncV2(config) {
 
   // 8. Generate outputs (only if files changed)
   if (toProcess.length > 0) {
-    generateOutputs(store, config, projectRoot, store.getImportGraph());
+    await generateOutputs(store, config, projectRoot, store.getImportGraph());
   }
 
   console.log(`[CARTO] Indexed ${toProcess.length} files (${cached} cached) in ${elapsed}ms`);
@@ -461,12 +462,13 @@ function buildFileDataFromStore(store) {
 /**
  * Generate backward-compatible outputs (AGENTS.md, context files, map.json)
  */
-function generateOutputs(store, config, projectRoot, importGraph) {
+async function generateOutputs(store, config, projectRoot, importGraph) {
   const structure = store.getStructure();
   const routes = store.getRoutes();
   const models = store.getModels();
   const envVars = store.getEnvVars();
   const domains = store.getDomainsList();
+  const topLevelStructure = await scanStructure(projectRoot);
 
   // Write domain context files — lazy: only write if stale or missing
   const contextDir = path.join(projectRoot, '.carto', 'context');
@@ -518,7 +520,7 @@ function generateOutputs(store, config, projectRoot, importGraph) {
       routes,
       models,
       frontend: { fetches: [], storageKeys: [] },
-      structure: [],
+      structure: topLevelStructure,
       warnings: [],
       fileMap: [],
       functions: {},

package/src/sync.js

@@ -13,8 +13,7 @@ const { buildStackLine } = require('./extractors/stack');
 const { loadHashes, saveHashes, computeChangedFiles } = require('./cache/file-hash');
 const { loadGraphCache, saveGraphCache, buildEmptyCache } = require('./cache/graph-cache');
 const { applyIncrementalUpdate, recomputeGraphMetrics } = require('./engine/incremental');
-
-const IGNORE_DIRS = new Set(['node_modules', '.git', '__pycache__', '.venv', 'venv', '.idea', '.vscode', '.carto', 'AGENTS.md']);
+const { scanStructure } = require('./agents/scan-structure');
 
 // Load plugins once at module load
 const plugins = loadLanguagePlugins();
@@ -29,22 +28,6 @@ async function safeReadFile(filePath, warnings) {
   }
 }
 
-async function scanStructure(basePath) {
-  const entries = [];
-  try {
-    const items = await fs.promises.readdir(basePath, { withFileTypes: true });
-    for (const item of items) {
-      if (IGNORE_DIRS.has(item.name)) continue;
-      entries.push({ name: item.name, type: item.isDirectory() ? 'dir' : 'file' });
-    }
-    entries.sort((a, b) => {
-      if (a.type !== b.type) return a.type === 'dir' ? -1 : 1;
-      return a.name.localeCompare(b.name);
-    });
-  } catch {}
-  return entries;
-}
-
 /**
  * runFullSync(config)
  *