carto-md 2.0.9 → 2.1.0

package/docs/quickstart.md

@@ -0,0 +1,95 @@
+# Quickstart — 10 minutes from install to first MCP query
+
+Get carto wired into your AI tool and answering questions about your codebase in under ten minutes.
+
+## 1. Install (30 seconds)
+
+```bash
+npm install -g carto-md
+```
+
+Carto ships prebuilt native binaries for macOS arm64/x64, Linux x64 (glibc + musl), and Windows x64. If you're on a platform without prebuilds you'll fall back to compiling from source — see [troubleshooting.md](./troubleshooting.md#native-build-fails) if that breaks.
+
+Verify the install:
+
+```bash
+carto --version
+```
+
+## 2. Index your project (1 minute)
+
+```bash
+cd ~/your-project
+carto init
+```
+
+You'll see something like:
+
+```
+[CARTO] Detecting project...
+[CARTO] Detected: nextjs (typescript)
+[CARTO] Found 847 JS/TS files (847 total)
+[CARTO] Discovered 847 source files
+[CARTO] Computing reverse dependencies...
+[CARTO] Indexed 847 files in 1.8s
+[CARTO] MCP auto-wired into: Cursor, Claude Code, Kiro
+[CARTO] AGENTS.md generated.
+
+┌─ Carto · indexed ─────────────────────────────────────────
+│  847 files · 5 domains · 23 routes · 1,204 import edges
+│
+│  Top domains:
+│    CORE          (677 files)
+│    AUTH          (42 files)
+│    PAYMENTS      (38 files)
+│    DATABASE      (67 files)
+│
+│  💡 Highest-risk file: src/lib/db.ts
+│     (34 files depend on it — try `carto why src/lib/db.ts`)
+└───────────────────────────────────────────────────────────
+```
+
+What just happened:
+
+- Carto walked the project, parsed every source file with tree-sitter
+- Built an import graph, clustered files into domains (Leiden+CPM), extracted routes + models
+- Wrote `.carto/` containing the SQLite index, the bitmap sidecar, the per-domain context files
+- Wrote `AGENTS.md` at the project root
+- Installed 4 git hooks so the index re-syncs on commit/checkout/merge/rebase
+- Detected your installed AI tools and wrote MCP config files for each
+
+## 3. Restart your AI tool
+
+The MCP wiring lands when the AI tool starts fresh. Kill it and reopen, then verify carto loaded — most tools log MCP server connections.
+
+## 4. Ask your first question
+
+Open any prompt your AI tool exposes and try one of:
+
+> *"What's the blast radius of `src/lib/db.ts`?"*
+
+> *"Show me the architecture overview."*
+
+> *"What files would I need to change to add rate limiting to /api/users?"*
+
+The AI calls Carto's MCP tools (`get_blast_radius`, `get_architecture`, `get_change_plan`) and answers with structural facts instead of grepping.
+
+## 5. Try the CLI too
+
+While you're here:
+
+```bash
+carto status                              # one-screen health view
+carto why src/lib/db.ts                   # 3-line summary of a file
+carto explain "add rate limiting"         # natural-language → plan
+carto check                               # cross-domain violations
+carto doctor                              # diagnose any setup issues
+```
+
+## What's next
+
+- [`docs/concepts/blast-radius.md`](./concepts/blast-radius.md) — what "blast radius" means and how it's computed
+- [`docs/concepts/domains.md`](./concepts/domains.md) — how the Leiden clusterer infers AUTH/PAYMENTS/etc. without config
+- [`docs/concepts/mcp-integration.md`](./concepts/mcp-integration.md) — every MCP tool with an example call
+- [`docs/guides/adding-feature-safely.md`](./guides/adding-feature-safely.md) — the workflow this whole thing enables
+- [`docs/guides/ci-integration.md`](./guides/ci-integration.md) — drop the GitHub Action onto every PR

package/docs/scale.md

@@ -8,8 +8,8 @@ The bitmap-backed graph engine is designed to handle 100K-1M files cleanly. This
 
 For each run we capture:
 
-- **Init time** — full `runSyncV2` from a wiped `.carto/` directory.
-- **Sync time** — second `runSyncV2` immediately after, no files changed (mtime+hash skip path).
+- **Init time** — full `runSync` from a wiped `.carto/` directory.
+- **Sync time** — second `runSync` immediately after, no files changed (mtime+hash skip path).
 - **DB size** — `.carto/carto.db` bytes on disk.
 - **bitmap.bin size** — the sidecar bytes on disk.
 - **Sidecar (RAM)** — sum of all bitmap word-array byte lengths held in memory.

package/docs/troubleshooting.md

@@ -0,0 +1,180 @@
+# Troubleshooting
+
+> Real failure modes, with fixes.
+
+## Install / native modules
+
+### `node-gyp rebuild` fails on install
+
+Symptom: `npm install -g carto-md` exits with C++ errors mentioning `tree-sitter` or `better-sqlite3`.
+
+Why: no prebuilt binary for your platform → falling back to compile-from-source → no C++ toolchain present.
+
+Fix: install build tools, then retry.
+
+| OS | Command |
+|---|---|
+| macOS | `xcode-select --install` |
+| Ubuntu / Debian | `sudo apt-get install build-essential python3` |
+| RHEL / Fedora | `sudo dnf groupinstall "Development Tools"` |
+| Windows | `npm install --global windows-build-tools` (run from elevated PowerShell) |
+| Alpine | `apk add --no-cache python3 make g++` |
+
+If you're on a supported platform (macOS arm64/x64, Linux x64 glibc + musl, Windows x64), you *shouldn't* be hitting this. Run `carto doctor` — the output will tell you which native module is the problem.
+
+### Node version refused at install time
+
+```
+[CARTO] Node v16.x.x is too old. carto-md requires Node ≥ v18.
+```
+
+Upgrade Node. https://nodejs.org/ — even-numbered LTS releases (18, 20, 22) are best.
+
+### Missing optional grammars
+
+```
+⚠ Tree-sitter grammars (2 of 8 missing: tree-sitter-rust, tree-sitter-java)
+```
+
+The optional language grammars failed to prebuild on your platform. Files in those languages still get indexed — Carto falls back to regex extraction (less accurate but functional).
+
+To force a grammar to install:
+
+```bash
+npm install -g tree-sitter-rust
+```
+
+If that fails too, the platform doesn't have a prebuild and won't compile. That's fine — regex fallback works.
+
+## Index / sync
+
+### `carto sync` says "0 files re-parsed" but I changed files
+
+Cache hit. Carto stats each file's mtime+size and skips ones that haven't changed. If you genuinely changed a file but mtime didn't move (rare — usually copying a same-content file), force a re-parse:
+
+```bash
+touch src/the/file.ts
+carto sync
+```
+
+For a full rebuild from scratch:
+
+```bash
+carto remove
+carto init
+```
+
+### `carto check` claims unstable clustering
+
+```
+[CARTO] Warning: 8.2% of files changed domain since last sync — clustering unstable.
+```
+
+The Leiden+CPM clusterer can be sensitive when the codebase is borderline between two stable partitions. If this happens repeatedly:
+
+1. Pin the important files with `anchor` in `carto.config.json`. See [`docs/concepts/domains.md`](./concepts/domains.md).
+2. If a domain is genuinely splitting (a refactor in progress), this is informational — accept the drift.
+3. If you don't care about exact domain names but want stability, set keyword hints in `carto.config.json` so the names are forced.
+
+### Index is huge
+
+A 100K-file repo produces a 160 MB `carto.db` and 20 MB `bitmap.bin`. Larger than expected? Most likely you're indexing `node_modules/`, a `vendor/` dir, or a generated `dist/`. Run:
+
+```bash
+carto inspect | head -20
+```
+
+That shows the file count. If it's way bigger than your source tree, edit `.cartoignore` to exclude the offender:
+
+```
+node_modules/
+vendor/
+**/__generated__/
+build/
+dist/
+out/
+```
+
+## MCP / AI tool integration
+
+### AI tool doesn't see Carto's tools
+
+1. Restart the AI tool (it loads MCP config at startup).
+2. Run `carto doctor` — it surfaces whether config files exist for the tools you have installed.
+3. If `doctor` says "MCP configuration: no MCP config files found", re-run `carto init` (it auto-wires).
+4. If `init` doesn't detect your tool, see the README's manual config snippets in the [Manual MCP wiring](../README.md) section (collapsed `<details>` block right after the install snippet).
+
+### MCP server crashes
+
+Pre-2.0.7 the MCP server could crash on tool errors and the AI tool would see `-32000 Failed to reconnect`. Fixed in 2.0.7. If you're seeing it on a newer version, set `CARTO_DEBUG=1` before launching the AI tool to capture stderr.
+
+### "Lazy re-parse" doesn't fire on stale files
+
+The MCP server stats the file on every file-aware query and re-parses if mtime is newer than the DB row. If a query returns stale data:
+
+1. Check the file's mtime: `stat src/the/file.ts`
+2. Compare against the DB row: `carto inspect | grep "last full sync"`
+3. If mtime is older, sync was after edit and the data isn't stale.
+4. If mtime is newer but the data is stale, file a bug — that's the regression test target.
+
+## Validation API / PR Action
+
+### `carto pr-impact` says "No carto index"
+
+The action's cache restored an empty `.carto/`. Either:
+
+- Cache key isn't invalidating. Check `hashFiles` glob in the workflow.
+- First run on this branch — let it run `carto init` cold once.
+- Index was removed; run `carto init` manually inside the workflow before pr-impact.
+
+### Sticky comment isn't sticky
+
+The action looks for the `<!-- carto-impact-report -->` marker in existing PR comments and updates the first match. If multiple comments have the marker (somehow), the action updates the first. If you see duplicate comments, check that the workflow isn't running twice (e.g. matrix builds, multiple triggers).
+
+### `--fail-on HIGH` trips too often
+
+Lower the threshold to `MEDIUM` for a softer gate, or use `--fail-on` only on `main`-bound PRs and not feature-branch PRs. Or accept that HIGH-risk PRs deserve careful review and let the gate work as intended.
+
+## SWE-bench harness
+
+### `bench/swe-bench/run.sh --task-set verified` says "dataset not found"
+
+Download the SWE-bench-Verified dataset from Hugging Face:
+
+```bash
+pip install huggingface_hub
+huggingface-cli download princeton-nlp/SWE-bench_Verified \
+  --repo-type dataset --local-dir ~/swe-bench-verified
+```
+
+Or set `CARTO_SWE_VERIFIED_PATH=/path/to/test.jsonl`.
+
+### AnthropicAgent throws on `--arm carto`
+
+You ran `--task-set verified` without `ANTHROPIC_API_KEY`. Set the key, or stick to `--task-set sample` which uses the deterministic StubAgent.
+
+### Cost runaway during a real-API run
+
+Set an Anthropic spend limit on your account dashboard *before* a long run. The harness emits per-task token counts to the JSONL output — tail it during the run to spot anomalies early:
+
+```bash
+tail -f bench/swe-bench/results/<run-id>.jsonl | jq .tokensInput
+```
+
+## General
+
+### `carto doctor` is the right starting point
+
+For any "something is broken" report, run `carto doctor` first. It checks Node, native modules, the index, git hooks, MCP config, .cartoignore. The output points at the broken component with a `Fix:` line.
+
+### Found a real bug
+
+Open an issue with:
+
+- `node --version`
+- `carto --version`
+- Output of `carto doctor`
+- Output of `carto inspect | head -30`
+- Steps to reproduce
+
+The maintainer triage is fast on real bugs with reproducible info. The triage is slow on vague "carto doesn't work" reports.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "carto-md",
-  "version": "2.0.9",
-  "description": "Structural intelligence layer for AI coding tools. Indexes your codebase into SQLite — routes, models, import graph, blast radius, domains — and exposes 22 MCP tools for Kiro, Cursor, and Claude.",
+  "version": "2.1.0",
+  "description": "Structural intelligence + episodic memory for AI coding tools. Indexes your codebase into SQLite — routes, models, import graph, blast radius, domains — and exposes ~75 MCP tools (validate_diff, get_change_plan, did_we_discuss_this, get_predictive_risk, …) for Cursor, Claude Code, Codex, Kiro, and any other MCP client.",
   "bin": {
     "carto": "src/cli/index.js"
   },
@@ -39,7 +39,7 @@
   "author": {
     "name": "Ansh Sonkar",
     "url": "https://github.com/theanshsonkar",
-    "twitter": "https://x.com/theanshsonkar"
+    "linkedin": "https://www.linkedin.com/in/theanshsonkar"
   },
   "license": "MIT",
   "keywords": [
@@ -59,8 +59,14 @@
     "sqlite",
     "blast-radius",
     "import-graph",
+    "episodic-memory",
+    "validate-diff",
     "kiro",
     "claude",
-    "zed"
+    "claude-code",
+    "codex",
+    "windsurf",
+    "zed",
+    "anci"
   ]
 }

package/scripts/gen-api-docs.js

@@ -0,0 +1,170 @@
+'use strict';
+
+/**
+ * scripts/gen-api-docs.js — generate `docs/api/<tool>.md` for every MCP
+ * tool registered in `src/mcp/server.js`. Re-run after adding a new tool.
+ *
+ * Usage:
+ *   node scripts/gen-api-docs.js              # writes docs/api/
+ *   node scripts/gen-api-docs.js --dry-run    # print to stdout, no writes
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const projectRoot = path.join(__dirname, '..');
+const docsDir = path.join(projectRoot, 'docs', 'api');
+
+function loadTools() {
+  // Cheap eval — extract the TOOLS array literal from server.js so we
+  // don't have to wire MCP server startup just to read tool definitions.
+  // We require() the module and read the captured TOOLS via a re-export.
+  const serverPath = path.join(projectRoot, 'src', 'mcp', 'server.js');
+  const src = fs.readFileSync(serverPath, 'utf-8');
+  // Find the `const TOOLS = [` block.
+  const startIdx = src.indexOf('const TOOLS = [');
+  if (startIdx === -1) throw new Error('TOOLS array not found in server.js');
+  // Walk forward, balancing brackets.
+  let depth = 0, i = startIdx;
+  for (; i < src.length; i++) {
+    if (src[i] === '[') depth++;
+    else if (src[i] === ']') { depth--; if (depth === 0) { i++; break; } }
+  }
+  const arrayLiteral = src.slice(startIdx + 'const TOOLS = '.length, i);
+  // eslint-disable-next-line no-eval
+  const TOOLS = (new Function(`return ${arrayLiteral}`))();
+  return TOOLS;
+}
+
+function indexMarkdown(tools) {
+  const groups = groupByPrefix(tools);
+  const lines = [
+    '# Carto MCP Tools — API Reference',
+    '',
+    'Auto-generated from `src/mcp/server.js`. Re-run `node scripts/gen-api-docs.js` after adding tools.',
+    '',
+    `**${tools.length} tools** across ${groups.size} categories.`,
+    '',
+    '## Categories',
+    '',
+  ];
+  for (const [groupName, names] of groups) {
+    lines.push(`### ${groupName} (${names.length})`);
+    for (const n of names) {
+      lines.push(`- [\`${n}\`](./${n}.md)`);
+    }
+    lines.push('');
+  }
+  return lines.join('\n');
+}
+
+function groupByPrefix(tools) {
+  // Group by the first prefix segment of the tool name.
+  const groups = new Map();
+  for (const t of tools) {
+    let group = 'Other';
+    if (t.name.startsWith('get_arch') || t.name.startsWith('get_domain_evolution') || t.name.startsWith('get_hotspot') ||
+        t.name.startsWith('get_complexity') || t.name.startsWith('get_churn') || t.name.startsWith('get_domain_health') ||
+        t.name.startsWith('get_temporal') || t.name === 'get_architectural_drift') group = 'Temporal';
+    else if (t.name === 'get_invariants' || t.name === 'get_canonical_pattern' || t.name === 'get_conventions' ||
+             t.name === 'get_action_patterns' || t.name === 'scaffold_for_intent' || t.name === 'get_working_memory' ||
+             t.name === 'get_pending_decisions' || t.name === 'get_active_drift' || t.name === 'get_active_suggestions' ||
+             t.name === 'dismiss_suggestion') group = 'Brain';
+    else if (t.name === 'get_minimal_context_for_intent' || t.name === 'get_progressive_disclosure_tree' ||
+             t.name === 'get_token_budget_report' || t.name === 'get_decision_log' || t.name === 'get_evolution_delta' ||
+             t.name === 'get_change_velocity' || t.name === 'get_test_coverage_map' || t.name === 'get_safety_checklist' ||
+             t.name === 'get_data_flow' || t.name === 'get_interface_contract' || t.name === 'explain_change_in_natural_language' ||
+             t.name === 'get_stale_docs' || t.name === 'get_dependency_surface' || t.name === 'get_upgrade_risk') group = 'AI-native';
+    else if (t.name.startsWith('get_cross_language') || t.name === 'get_iac_resources' ||
+             t.name === 'ingest_otlp_traces' || t.name === 'get_risk_weighted_blast_radius' ||
+             t.name === 'get_dead_code_with_confidence' || t.name === 'get_hot_in_prod_no_tests' ||
+             t.name === 'get_semantic_diff' || t.name === 'get_llm_enrichment') group = 'Adjacent';
+    else if (t.name === 'get_predictive_risk' || t.name === 'get_microservice_cut_points' || t.name === 'validate_change' ||
+             t.name === 'get_file_ownership' || t.name === 'get_cross_team_coupling' || t.name === 'get_drift_digest' ||
+             t.name === 'get_ai_cost_attribution') group = 'Predictive';
+    else if (t.name === 'get_org_architecture' || t.name === 'get_service_dependency_graph' ||
+             t.name === 'get_cross_repo_blast_radius' || t.name === 'find_consumers_of_api' ||
+             t.name === 'get_org_domain_mapping' || t.name === 'get_service_boundary_violations' ||
+             t.name === 'get_microservices_migration_cut_points') group = 'Org-wide';
+    else if (t.name === 'validate_diff' || t.name === 'get_recent_decisions' || t.name === 'get_session_context' ||
+             t.name === 'did_we_discuss_this' || t.name === 'get_intervention_history') group = 'Episodic Memory';
+    else group = 'Core graph';
+    if (!groups.has(group)) groups.set(group, []);
+    groups.get(group).push(t.name);
+  }
+  const order = ['Core graph', 'Episodic Memory', 'Temporal', 'Brain', 'AI-native', 'Adjacent', 'Predictive', 'Org-wide', 'Other'];
+  const sorted = new Map();
+  for (const g of order) if (groups.has(g)) sorted.set(g, groups.get(g));
+  return sorted;
+}
+
+function toolMarkdown(t) {
+  const lines = [
+    `# \`${t.name}\``,
+    '',
+    t.description || '_(no description)_',
+    '',
+    '## Input schema',
+    '',
+    '```json',
+    JSON.stringify(t.inputSchema || { type: 'object' }, null, 2),
+    '```',
+    '',
+    '## Required arguments',
+    '',
+  ];
+  const required = (t.inputSchema && t.inputSchema.required) || [];
+  if (required.length === 0) lines.push('_None._');
+  else for (const r of required) lines.push(`- \`${r}\``);
+  lines.push('');
+  lines.push('## Properties');
+  lines.push('');
+  const props = (t.inputSchema && t.inputSchema.properties) || {};
+  if (Object.keys(props).length === 0) lines.push('_None._');
+  else {
+    lines.push('| Name | Type | Description |');
+    lines.push('|------|------|-------------|');
+    for (const [name, schema] of Object.entries(props)) {
+      const type = schema.type || (schema.items ? `array<${schema.items.type || 'string'}>` : 'any');
+      const desc = (schema.description || '').replace(/\|/g, '\\|');
+      lines.push(`| \`${name}\` | ${type} | ${desc} |`);
+    }
+  }
+  lines.push('');
+  lines.push('## See also');
+  lines.push('');
+  lines.push('- [Index of all MCP tools](./README.md)');
+  return lines.join('\n');
+}
+
+function main() {
+  const dry = process.argv.includes('--dry-run');
+  const tools = loadTools();
+  if (!dry) {
+    fs.mkdirSync(docsDir, { recursive: true });
+  }
+  let written = 0;
+  for (const t of tools) {
+    const p = path.join(docsDir, `${t.name}.md`);
+    const md = toolMarkdown(t);
+    if (dry) {
+      console.log(`\n=== ${p} ===\n${md}\n`);
+    } else {
+      fs.writeFileSync(p, md, 'utf-8');
+      written++;
+    }
+  }
+  const indexPath = path.join(docsDir, 'README.md');
+  const indexMd = indexMarkdown(tools);
+  if (!dry) fs.writeFileSync(indexPath, indexMd, 'utf-8');
+
+  if (dry) console.log(`\n[dry-run] would write ${tools.length + 1} files.`);
+  else console.log(`[CARTO] Generated ${written} per-tool docs + 1 index → docs/api/`);
+  return tools.length;
+}
+
+if (require.main === module) {
+  try { main(); } catch (err) { console.error(err.message); process.exit(1); }
+}
+
+module.exports = { loadTools, toolMarkdown, indexMarkdown, main };

package/src/acp/agent.js

@@ -6,6 +6,7 @@ const { SessionManager } = require('./session');
 const { buildSystemPrompt, buildContextBlock } = require('./prompt');
 const { CARTO_TOOLS, executeTool } = require('./tools');
 const { ProviderRegistry } = require('./providers');
+const { loadAgentConfig, saveAgentConfig } = require('./config');
 
 const MAX_ITERATIONS = 25;
 
@@ -14,13 +15,17 @@ class CartoAgent {
     this.connection = connection;
     this.sessions = new SessionManager();
     this.providers = new ProviderRegistry();
+    // Rehydrate last-used provider config (no API key — that still comes
+    // from the environment or IDE settings). Done lazily so a fresh repo
+    // without `.carto/agent-config.json` doesn't pay any cost.
+    this._lastProviderConfig = null;
   }
 
   async initialize(_params) {
     return {
       protocolVersion: acp.PROTOCOL_VERSION,
       agentCapabilities: {
-        loadSession: false,
+        loadSession: true,
         promptCapabilities: { image: false, audio: false, embeddedContext: true },
       },
       agentInfo: {
@@ -37,7 +42,12 @@ class CartoAgent {
   }
 
   async newSession(params) {
-    const session = this.sessions.create(params.cwd || process.cwd());
+    const cwd = params.cwd || process.cwd();
+    const session = this.sessions.create(cwd);
+    // Lazy-load any persisted provider config for this project.
+    if (!this._lastProviderConfig) {
+      this._lastProviderConfig = loadAgentConfig(cwd);
+    }
     return { sessionId: session.id };
   }
 
@@ -61,6 +71,10 @@ class CartoAgent {
     }
 
     session.abortController = null;
+    // Persist after every successful prompt so an editor crash never
+    // loses session history. Best-effort; failures don't surface to the
+    // client (we'd rather complete the turn than block on disk).
+    try { this.sessions.persist(session); } catch {}
     return { stopReason: 'end_turn' };
   }
 
@@ -77,9 +91,38 @@ class CartoAgent {
   // editor settings; ProviderRegistry remains as the internal
   // configuration carrier.
 
-  // Session list/load stubs
-  async listSessions(_params) { return { sessions: [] }; }
-  async closeSession(_params) { return {}; }
+  // Session list/load — persisted ACP sessions.
+  // Sessions are persisted to `.carto/acp-sessions.db` after every
+  // prompt completion. `listSessions` returns persisted sessions for the
+  // working directory; `loadSession` rehydrates one into memory.
+  async listSessions(params) {
+    const cwd = (params && params.cwd) || process.cwd();
+    const rows = this.sessions.list(cwd);
+    return {
+      sessions: rows.map(r => ({
+        sessionId: r.id,
+        cwd: r.working_dir,
+        createdAt: r.created_at,
+        updatedAt: r.updated_at,
+        messageCount: r.msg_count || 0,
+      })),
+    };
+  }
+  async loadSession(params) {
+    if (!params || !params.sessionId || !params.cwd) return { sessionId: null };
+    const session = this.sessions.resume(params.sessionId, params.cwd);
+    return { sessionId: session ? session.id : null };
+  }
+  async closeSession(params) {
+    if (params && params.sessionId) {
+      const session = this.sessions.get(params.sessionId);
+      if (session) {
+        try { this.sessions.persist(session); } catch {}
+      }
+      this.sessions.delete(params.sessionId);
+    }
+    return {};
+  }
 
   // ─── Agent Loop ──────────────────────────────────────────────────────────
 
@@ -128,19 +171,48 @@ class CartoAgent {
     while (iterations++ < MAX_ITERATIONS) {
       if (signal.aborted) throw new Error('cancelled');
 
-      const response = await provider.chat(messages, CARTO_TOOLS, signal);
+      // True LLM token streaming.
+      //
+      // The provider streams text deltas via `onTextChunk`. We forward
+      // each chunk to the editor as it arrives so the UI feels alive
+      // instead of stalling for the duration of the request. The
+      // *aggregated* assistant text is captured here so we can store
+      // it on `session.history` once the turn ends — the provider
+      // still returns the full `{ content: [...] }` object so tool_use
+      // blocks survive.
+      let streamedText = '';
+      const onTextChunk = (delta) => {
+        if (!delta) return;
+        streamedText += delta;
+        // Fire-and-forget — sessionUpdate returns a Promise but the SDK
+        // tolerates concurrent calls and we don't want each delta to
+        // block the next one.
+        this.connection.sessionUpdate({
+          sessionId: session.id,
+          update: { sessionUpdate: 'agent_message_chunk', content: { type: 'text', text: delta } },
+        }).catch(() => { /* connection errors surface elsewhere */ });
+      };
+
+      const response = await provider.chat(messages, CARTO_TOOLS, signal, onTextChunk);
 
-      // Stream text content
+      // After the stream completes, classify content blocks. Text was
+      // already forwarded chunk-by-chunk; here we only need to collect
+      // tool_use blocks and reconcile assistantText for history.
       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 } },
-          });
+          // If the provider didn't actually stream (e.g. test stub or
+          // a non-streaming compatible API), forward the text once here
+          // so the editor still sees it.
+          if (!streamedText) {
+            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);
         }