carto-md 2.0.0 → 2.0.1

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/acp-strategy.md

@@ -0,0 +1,480 @@
+# Carto ACP Agent — Strategy & Implementation Plan
+
+> Build the brain, not the editor. Ship to every IDE in weeks.
+
+---
+
+## What is ACP?
+
+**Agent Client Protocol (ACP)** is an open standard created by Zed Industries that lets any AI coding agent work inside any compatible editor — without custom integrations.
+
+- **LSP** = one standard so any editor supports any programming language
+- **ACP** = one standard so any editor supports any AI coding agent
+
+**Transport:** JSON-RPC 2.0 over stdin/stdout (local) or HTTP/WebSocket (remote)  
+**Editors:** Zed, JetBrains (IntelliJ, WebStorm, etc.), VS Code (in progress)  
+**SDK:** `@agentclientprotocol/sdk` (TypeScript/JS, Python, Rust, Kotlin, Java)
+
+---
+
+## The Core Idea
+
+Instead of building a standalone editor, build Carto as an **ACP agent** that plugs into existing editors. Carto already has the structural intelligence — ACP gives it hands.
+
+```
+┌─────────────────────────────────────────┐
+│  Zed / JetBrains / VS Code             │
+│  ┌───────────────────────────────────┐  │
+│  │  Agent Panel → "Carto" thread     │  │
+│  │                                   │  │
+│  │  User: "Add rate limiting to      │  │
+│  │         /api/users"               │  │
+│  │                                   │  │
+│  │  Carto: I see AUTH domain has     │  │
+│  │  12 files, 3 routes. Highest      │  │
+│  │  impact: auth/session.ts          │  │
+│  │  (8 dependents). Here's my plan:  │  │
+│  │  [shows file diffs inline]        │  │
+│  └───────────────────────────────────┘  │
+└─────────────────────────────────────────┘
+         ↕ ACP (stdin/stdout)
+┌─────────────────────────────────────────┐
+│  carto agent (Node.js process)          │
+│  ├── Carto structural intelligence      │
+│  ├── LLM calls (user's own API key)    │
+│  └── File edits streamed back           │
+└─────────────────────────────────────────┘
+```
+
+---
+
+## How Data Flows (MCP vs ACP)
+
+### Current: MCP (passive tool server)
+
+```
+External AI (Claude/Cursor) decides to call a tool
+    ↓
+get_blast_radius("auth.service.ts")
+    ↓
+Carto returns a SUMMARY → "3 files affected, risk HIGH"
+    ↓
+AI uses summary to answer (may miss context, can't read files through Carto)
+```
+
+**Problem:** LLM gets summaries, not full context. It has to guess which tools to call. It can't read actual file contents through Carto.
+
+### New: ACP (active intelligent agent)
+
+```
+User asks: "Add rate limiting to /api/users"
+    ↓
+Carto agent receives message
+    ↓
+Carto INTERNALLY queries its own SQLite:
+  - Blast radius of relevant files
+  - Domain context (AUTH)
+  - Similar patterns in codebase
+  - Import graph neighbors
+    ↓
+Carto reads ACTUAL file contents via ACP fileSystem
+    ↓
+Carto builds a RICH prompt with all context + file contents
+    ↓
+Sends to LLM (user's API key) → gets response
+    ↓
+Streams answer + file diffs back to editor
+```
+
+**Key difference:** Carto controls the LLM call. It proactively provides the right context instead of waiting for the LLM to ask.
+
+### What the LLM receives (built by Carto):
+
+| Data | How it gets to the LLM |
+|------|----------------------|
+| Structural facts (blast radius, domains, routes) | Carto queries SQLite internally → injects into system prompt |
+| Relevant file contents (actual code) | Carto reads via ACP fileSystem → includes in prompt |
+| Domain context (`.carto/context/AUTH.md` etc.) | Carto reads internally → includes relevant domain |
+| Import graph | Carto summarizes relevant portion → injects |
+| Similar patterns | Carto finds matching files → includes as examples |
+
+Carto acts as a **smart filter** — only sends what's relevant. No token waste.
+
+---
+
+## Auto-Index on First Session
+
+When a user opens a Carto agent thread in any project:
+
+```
+User opens Carto agent thread in Zed
+    ↓
+Carto checks: does .carto/carto.db exist?
+    ↓
+NO → automatically runs full indexing
+    ↓
+  • Discovers all source files
+  • tree-sitter parse → imports + symbols (0.05–0.2ms/file)
+  • Babel deep parse → routes + models (API files only)
+  • Leiden+CPM graph clustering → domain detection
+  • Computes reverse deps → blast radius
+  • Writes .carto/carto.db + context/*.md
+    ↓
+Takes 1-10 seconds depending on repo size:
+  • Prisma (3,303 files): 1.6s
+  • Supabase (6,818 files): 4.9s
+  • VS Code (10,565 files): 9.7s
+    ↓
+Agent responds: "Indexed! Found X files, Y routes, Z domains. How can I help?"
+    ↓
+YES → opens SQLite instantly (<10ms), ready to go
+```
+
+**On subsequent sessions:** No re-indexing. SQLite opens in <10ms.
+
+**On file changes:** If `carto watch` is running, DB stays live. If not, agent can do a quick mtime check on session start (178ms–1.2s for unchanged repos).
+
+### What gets created on disk:
+
+```
+project/
+├── .carto/
+│   ├── carto.db              ← SQLite (import graph, routes, models, domains, blast radius)
+│   ├── config.json           ← project settings
+│   └── context/
+│       ├── AUTH.md           ← domain context (auto-generated)
+│       ├── CORE.md
+│       ├── DATABASE.md
+│       └── PAYMENTS.md
+├── AGENTS.md                 ← still generated (useful for other MCP tools)
+└── src/...
+```
+
+Same as today. ACP doesn't change what Carto creates — just who reads it.
+
+---
+
+## Supported LLM Providers (BYOK)
+
+Carto currently has **zero LLM integration** — it's purely structural intelligence. The ACP agent adds LLM calls. We support any provider the user brings:
+
+### Tier 1 — Full support (streaming, tool use, all models)
+
+| Provider | Protocol | Models |
+|----------|----------|--------|
+| **OpenAI** | `openai` | GPT-4o, GPT-4o-mini, o1, o3 |
+| **Anthropic** | `anthropic` | Claude Sonnet 4, Claude Haiku |
+| **Google Gemini** | `openai` (compatible) | Gemini 2.5 Pro, 2.5 Flash |
+
+### Tier 2 — Works via OpenAI-compatible API
+
+| Provider | Protocol | Notes |
+|----------|----------|-------|
+| **Azure OpenAI** | `azure` | Enterprise deployments |
+| **AWS Bedrock** | `bedrock` | Claude/Titan via AWS |
+| **Ollama** | `openai` | Local models (Llama, Mistral, Qwen, DeepSeek) |
+| **OpenRouter** | `openai` | Any model via single API |
+| **Together AI** | `openai` | Open-source models hosted |
+| **Groq** | `openai` | Ultra-fast inference |
+| **LM Studio** | `openai` | Local GUI + API |
+| **vLLM** | `openai` | Self-hosted inference |
+
+### How BYOK works in ACP:
+
+```
+1. User installs Carto agent in Zed/JetBrains
+2. Editor calls providers/list → Carto returns supported providers
+3. User configures their key in editor settings:
+   - API key (stored securely by editor)
+   - Base URL (for self-hosted/proxy)
+   - Model name
+4. Editor calls providers/set → Carto stores config
+5. All LLM calls use user's key — zero cost to us
+```
+
+### Provider config stored in:
+
+```json
+// .carto/agent-config.json (gitignored)
+{
+  "provider": {
+    "apiType": "anthropic",
+    "baseUrl": "https://api.anthropic.com",
+    "model": "claude-sonnet-4-20250514"
+  }
+}
+```
+
+API keys are NEVER stored by Carto — they're passed via ACP `providers/set` headers at runtime and held in memory only.
+
+### Cost to user:
+
+| Usage Level | Tokens/day | Claude Sonnet | Gemini Flash (free) | Ollama (local) |
+|-------------|-----------|---------------|--------------------|----|
+| Light (5 tasks) | ~50K | ~$0.15 | $0.00 | $0.00 |
+| Medium (15 tasks) | ~150K | ~$0.50 | $0.00 | $0.00 |
+| Heavy (30+ tasks) | ~400K | ~$1.20 | $0.00 (rate limits) | $0.00 |
+| Power user | ~1M | ~$3.00 | Needs paid tier | $0.00 |
+
+---
+
+## What ACP Gives You For Free
+
+Everything the editor handles natively — zero code from us:
+
+| Feature | ACP / Editor Handles It |
+|---------|------------------------|
+| Chat panel UI | ✅ Zed/JetBrains Agent Panel |
+| Multiple chats / threads | ✅ Built-in threads sidebar |
+| Conversation persistence & resume | ✅ Editor manages sessions |
+| Stop / Interrupt button | ✅ Native editor stop |
+| Inline diffs with Accept / Reject | ✅ ACP native diff content type |
+| "Open in Editor" for large diffs | ✅ Native editor behavior |
+| Tool call visibility (collapsed) | ✅ Editor renders agent plan |
+| File read / write / create / delete | ✅ ACP `fileSystem` capability |
+| Terminal / command execution | ✅ ACP `terminals` capability |
+| Streaming token responses | ✅ ACP streams natively |
+| BYOK (Bring Your Own Key) | ✅ ACP `providers/set` |
+| Session list / resume old chats | ✅ ACP `session/list`, `session/resume` |
+| Redirect mid-task | ✅ Editor supports new message while agent runs |
+| Keyboard shortcuts | ✅ Editor-native |
+
+**~75-80% of the chat.md spec is free from ACP.**
+
+---
+
+## What We Build (The Actual Product)
+
+### 1. Auto-Context Injection
+
+Every user message gets enriched with structural context before hitting the LLM:
+
+```javascript
+// What we inject into the system prompt (user doesn't see this)
+const context = carto.getContextForFile(session.currentFile);
+
+// Becomes:
+`Current file: src/auth/auth.service.ts
+Domain: AUTH
+Blast radius: 3 routes, 2 services affected
+  - Directly affected: auth.routes.ts, auth.controller.ts, auth.middleware.ts
+  - Routes impacted: POST /auth/login, GET /auth/me, POST /auth/register
+Import graph: session.service.ts, user.repository.ts
+Imported by: auth.routes.ts, auth.middleware.ts`
+```
+
+### 2. Carto Intelligence as Internal Tools
+
+The LLM can call these during reasoning (Carto handles them internally):
+
+```
+get_blast_radius(file)     → full impact analysis
+get_structure()            → project architecture
+get_domain(name)           → domain routes, models, files
+get_routes()               → all API endpoints
+get_change_plan(intent)    → files to touch, similar patterns
+get_context(file)          → everything about a file
+get_similar_patterns(file) → conventions to follow
+```
+
+### 3. The Agent Loop
+
+```javascript
+async function handlePrompt(userMessage, session) {
+  // 1. Auto-index if needed
+  if (!dbExists(session.workingDir)) {
+    await indexProject(session.workingDir);
+    stream("Indexed! Found X files, Y routes, Z domains.\n\n");
+  }
+
+  // 2. Get structural context for current file
+  const context = carto.getContextForFile(session.currentFile);
+
+  // 3. Build messages with rich context
+  const messages = [
+    { role: "system", content: buildSystemPrompt(context) },
+    ...session.history,
+    { role: "user", content: userMessage }
+  ];
+
+  // 4. Agent loop
+  let iterations = 0;
+  while (iterations++ < 25) {
+    const response = await callLLM(messages, {
+      provider: session.provider,
+      tools: [...CARTO_TOOLS, ...FILE_TOOLS],
+      stream: true
+    });
+
+    for (const block of response) {
+      if (block.type === "text") stream(block.text);
+      if (block.type === "tool_use") {
+        const result = await executeTool(block, session);
+        messages.push(toolResult(block.id, result));
+      }
+    }
+
+    if (noMoreToolCalls(response)) break;
+  }
+}
+```
+
+### 4. System Prompt
+
+```
+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
+
+CONTEXT (auto-provided every message):
+Current file: {filePath}
+Domain: {domain}
+Blast radius: {blastRadius}
+Imports: {imports}
+Imported by: {importedBy}
+```
+
+---
+
+## What You Lose vs Standalone Editor
+
+| Spec Feature | Reality with ACP |
+|---|---|
+| Custom UI layout (exact mockup) | ❌ Editor's standard agent panel |
+| `📖 🎯 ⚡` icons per tool type | ❌ Editor decides tool call rendering |
+| Auto-context badge visible to user | ❌ Context is invisible (sent to LLM only) |
+| Custom storage format | ❌ Editor manages persistence |
+| Custom keyboard shortcuts | ❌ Editor controls shortcuts |
+
+**All cosmetic.** The intelligence differentiators are fully preserved.
+
+---
+
+## ACP vs Building Standalone
+
+| | Standalone Editor | ACP Agent |
+|---|---|---|
+| Time to ship V1 | 6-12 months | 4-6 weeks |
+| UI control | Full | Limited (editor's panel) |
+| Editor reach | Only ours | Zed + JetBrains + VS Code |
+| Core intelligence | ✅ | ✅ (same) |
+| Blast radius / domain awareness | ✅ | ✅ (same) |
+| BYOK | Build it | Free from ACP |
+| Diff viewer | Build it | Free from ACP |
+| Terminal integration | Build it | Free from ACP |
+| Session persistence | Build it | Free from ACP |
+| LLM provider switching | Build it | Free from ACP |
+
+---
+
+## Implementation Plan
+
+### Phase 1 — Core Agent (Week 1-2)
+
+- [ ] Add `carto agent` CLI command (starts ACP mode via stdin/stdout)
+- [ ] Implement `AgentSideConnection` with capabilities: `fileSystem`, `terminals`
+- [ ] Auto-index on first session (detect missing `.carto/carto.db` → run sync)
+- [ ] Wire Carto tools as internal agent tools
+- [ ] Build agent loop (context injection → LLM call → tool routing → stream back)
+- [ ] Write system prompt with auto-context
+
+### Phase 2 — LLM Providers / BYOK (Week 2-3)
+
+- [ ] Implement `providers/list` — advertise supported providers
+- [ ] Implement `providers/set` — accept API key + base URL + model
+- [ ] OpenAI provider (GPT-4o, GPT-4o-mini)
+- [ ] Anthropic provider (Claude Sonnet, Haiku)
+- [ ] Gemini provider (via OpenAI-compatible endpoint)
+- [ ] Generic OpenAI-compatible provider (Ollama, OpenRouter, Together, Groq, LM Studio, vLLM)
+- [ ] Azure OpenAI provider
+- [ ] Store model config in `.carto/agent-config.json` (gitignored, no secrets)
+
+### Phase 3 — Polish (Week 3-4)
+
+- [ ] 25-iteration safety cap with pause + user prompt
+- [ ] Context overflow handling (auto-summarize old messages)
+- [ ] Blast radius check before AND after file writes
+- [ ] Cross-domain change warnings
+- [ ] Register in ACP Registry (discoverable from Zed/JetBrains)
+
+### Phase 4 — Advanced (Week 5+)
+
+- [ ] Parallel agent support (multiple Carto threads on different tasks)
+- [ ] Slash commands (`/blast`, `/domain`, `/routes`)
+- [ ] Agent plan display (show what Carto intends to do before doing it)
+- [ ] If traction warrants: standalone editor with full UI control
+
+---
+
+## Technical Setup
+
+```bash
+# Install ACP SDK
+npm install @agentclientprotocol/sdk
+
+# CLI commands
+carto serve    # existing — MCP mode (passive tools, keep as-is)
+carto agent    # new — ACP mode (active agent, stdin/stdout)
+```
+
+### File structure (new code):
+
+```
+src/
+├── acp/
+│   ├── agent.js           ← ACP AgentSideConnection setup
+│   ├── session.js         ← Session management + auto-index
+│   ├── prompt.js          ← System prompt builder + context injection
+│   ├── tools.js           ← Carto tools exposed to LLM
+│   └── providers/
+│       ├── index.js       ← Provider registry + BYOK logic
+│       ├── openai.js      ← OpenAI/compatible provider
+│       ├── anthropic.js   ← Anthropic provider
+│       └── types.js       ← Shared types
+├── cli/
+│   ├── index.js           ← add "agent" command
+│   └── agent.js           ← new: starts ACP mode
+├── mcp/                   ← existing MCP server (unchanged)
+└── ...                    ← existing Carto intelligence (unchanged)
+```
+
+---
+
+## References
+
+- **ACP TypeScript SDK:** `@agentclientprotocol/sdk` ([npm](https://www.npmjs.com/package/@agentclientprotocol/sdk))
+- **ACP Spec:** https://agentclientprotocol.com
+- **Reference impl:** [Gemini CLI ACP](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/zed-integration/zedIntegration.ts)
+- **ACP Registry:** https://zed.dev/blog/acp-registry
+- **Configurable LLM Providers RFD:** https://agentclientprotocol.com/rfds/custom-llm-endpoint
+
+---
+
+## Why This Makes Sense
+
+Carto already has the hard part — understanding codebases at scale:
+- 10,565 files indexed in <10 seconds
+- Blast radius computed in <5ms
+- Domain detection via graph clustering
+- Route/model extraction across 8 languages
+
+What it's missing: the ability to **act** on that knowledge. ACP gives it hands (file edits, terminal) and a voice (LLM reasoning). The combination — structural intelligence + LLM + editor integration — is what makes this better than every other AI coding agent.
+
+Other agents are smart but blind. Carto sees the architecture. ACP lets it act on what it sees.
+
+---
+
+*Decision: Go ACP. Auto-index on first session. Support all major LLM providers via BYOK. Ship to Zed + JetBrains in 4-6 weeks.*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "carto-md",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "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"
   ]
 }