muonroi-cli 1.2.0

package/src/providers/vision-proxy.test.ts

@@ -0,0 +1,167 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { needsVisionProxy, proxyVision } from "./vision-proxy.js";
+
+vi.mock("../models/registry.js", () => ({
+  getModelInfo: (id: string) => {
+    if (id === "deepseek-v4-flash") return { id, supportsVision: false };
+    if (id === "deepseek-v4-pro") return { id, supportsVision: false };
+    if (id === "claude-sonnet-4-6") return { id, supportsVision: true };
+    if (id === "gpt-4o") return { id }; // undefined = defaults to true
+    return null;
+  },
+}));
+
+vi.mock("./keychain.js", () => ({
+  loadKeyForProvider: vi.fn().mockResolvedValue("sk-test-key-12345678901234567890"),
+}));
+
+describe("needsVisionProxy", () => {
+  it("returns true for deepseek models", () => {
+    expect(needsVisionProxy("deepseek-v4-flash")).toBe(true);
+    expect(needsVisionProxy("deepseek-v4-pro")).toBe(true);
+  });
+
+  it("returns false for models with vision support", () => {
+    expect(needsVisionProxy("claude-sonnet-4-6")).toBe(false);
+  });
+
+  it("returns false when supportsVision is undefined (default)", () => {
+    expect(needsVisionProxy("gpt-4o")).toBe(false);
+  });
+
+  it("returns false for unknown models", () => {
+    expect(needsVisionProxy("unknown-model")).toBe(false);
+  });
+});
+
+describe("proxyVision", () => {
+  const fakeBase64 = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk";
+
+  beforeEach(() => {
+    vi.stubGlobal("fetch", vi.fn());
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("passes through when model supports vision", async () => {
+    const messages = [{ role: "user" as const, content: "hello" }];
+    const result = await proxyVision(messages, "claude-sonnet-4-6");
+    expect(result.proxied).toBe(false);
+    expect(result.messages).toBe(messages);
+  });
+
+  it("passes through text-only messages for text-only model", async () => {
+    const messages = [{ role: "user" as const, content: "hello" }];
+    const result = await proxyVision(messages, "deepseek-v4-flash");
+    expect(result.proxied).toBe(false);
+    expect(result.imageCount).toBe(0);
+  });
+
+  it("proxies images through SiliconFlow for text-only model", async () => {
+    const mockFetch = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () =>
+        Promise.resolve({
+          choices: [{ message: { content: "A screenshot showing a login form with email and password fields." } }],
+        }),
+    });
+    vi.stubGlobal("fetch", mockFetch);
+
+    const messages = [
+      {
+        role: "user" as const,
+        content: [
+          { type: "text" as const, text: "describe this screenshot" },
+          { type: "image" as const, image: fakeBase64, mediaType: "image/png" },
+        ],
+      },
+    ];
+
+    const result = await proxyVision(messages, "deepseek-v4-flash");
+    expect(result.proxied).toBe(true);
+    expect(result.imageCount).toBe(1);
+
+    const processed = result.messages[0];
+    expect(processed.role).toBe("user");
+    const content = processed.content as Array<{ type: string; text: string }>;
+    expect(content.every((p) => p.type === "text")).toBe(true);
+    expect(content.some((p) => p.text.includes("Vision Proxy"))).toBe(true);
+    expect(content.some((p) => p.text.includes("login form"))).toBe(true);
+
+    expect(mockFetch).toHaveBeenCalledWith(
+      "https://api.siliconflow.com/v1/chat/completions",
+      expect.objectContaining({
+        method: "POST",
+        headers: expect.objectContaining({ Authorization: "Bearer sk-test-key-12345678901234567890" }),
+      }),
+    );
+
+    const body = JSON.parse(mockFetch.mock.calls[0][1].body);
+    expect(body.model).toBe("Qwen/Qwen2.5-VL-32B-Instruct");
+  });
+
+  it("returns fallback description on API error", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({ ok: false, status: 500, text: () => Promise.resolve("server error") }),
+    );
+
+    const messages = [
+      {
+        role: "user" as const,
+        content: [
+          { type: "text" as const, text: "analyze" },
+          { type: "image" as const, image: fakeBase64, mediaType: "image/png" },
+        ],
+      },
+    ];
+
+    const result = await proxyVision(messages, "deepseek-v4-flash");
+    expect(result.proxied).toBe(true);
+    const content = result.messages[0].content as Array<{ type: string; text: string }>;
+    expect(content.some((p) => p.text.includes("unavailable"))).toBe(true);
+  });
+
+  it("handles multiple images in one message", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: true,
+        json: () =>
+          Promise.resolve({
+            choices: [{ message: { content: "Image 1: header. Image 2: footer." } }],
+          }),
+      }),
+    );
+
+    const messages = [
+      {
+        role: "user" as const,
+        content: [
+          { type: "text" as const, text: "compare these" },
+          { type: "image" as const, image: fakeBase64, mediaType: "image/png" },
+          { type: "image" as const, image: fakeBase64, mediaType: "image/jpeg" },
+        ],
+      },
+    ];
+
+    const result = await proxyVision(messages, "deepseek-v4-flash");
+    expect(result.imageCount).toBe(2);
+    const content = result.messages[0].content as Array<{ type: string; text: string }>;
+    expect(content.some((p) => p.text.includes("2 images analyzed"))).toBe(true);
+  });
+
+  it("preserves non-user messages unchanged", async () => {
+    const messages = [
+      { role: "system" as const, content: "You are helpful." },
+      { role: "assistant" as const, content: "Sure, I can help." },
+      { role: "user" as const, content: "no images here" },
+    ];
+
+    const result = await proxyVision(messages, "deepseek-v4-flash");
+    expect(result.proxied).toBe(false);
+    expect(result.messages).toEqual(messages);
+  });
+});

package/src/providers/vision-proxy.ts

@@ -0,0 +1,209 @@
+/**
+ * Vision proxy layer for text-only models (e.g. DeepSeek V4).
+ *
+ * When the active model does not support vision, image parts in the message
+ * are extracted, sent to a cheap vision model on SiliconFlow
+ * (Qwen/Qwen2.5-VL-32B-Instruct @ $0.27/M tokens), and replaced with
+ * structured text descriptions before the message reaches the primary model.
+ */
+
+import type { ModelMessage } from "ai";
+import { getModelInfo } from "../models/registry.js";
+import { loadKeyForProvider } from "./keychain.js";
+
+const VISION_MODELS = [
+  "Qwen/Qwen2.5-VL-32B-Instruct",
+  "Qwen/Qwen3-VL-30B-A3B-Instruct",
+] as const;
+const SILICONFLOW_BASE = "https://api.siliconflow.com/v1";
+const REQUEST_TIMEOUT_MS = 45_000;
+
+interface ImagePart {
+  type: "image";
+  image: string; // base64
+  mediaType: string;
+}
+
+interface TextPart {
+  type: "text";
+  text: string;
+}
+
+type ContentPart = TextPart | ImagePart;
+
+export interface VisionProxyResult {
+  messages: ModelMessage[];
+  proxied: boolean;
+  imageCount: number;
+}
+
+/**
+ * Returns true when the model cannot handle image content natively.
+ */
+export function needsVisionProxy(modelId: string): boolean {
+  const info = getModelInfo(modelId);
+  return info?.supportsVision === false;
+}
+
+/**
+ * Process messages through the vision proxy.
+ * Only messages with image parts are modified; text-only messages pass through.
+ */
+export async function proxyVision(
+  messages: ModelMessage[],
+  modelId: string,
+  signal?: AbortSignal,
+): Promise<VisionProxyResult> {
+  if (!needsVisionProxy(modelId)) {
+    return { messages, proxied: false, imageCount: 0 };
+  }
+
+  let totalImages = 0;
+  const processed: ModelMessage[] = [];
+
+  for (const msg of messages) {
+    if (msg.role !== "user" || typeof msg.content === "string") {
+      processed.push(msg);
+      continue;
+    }
+
+    const parts = msg.content as ContentPart[];
+    const hasImages = parts.some((p) => p.type === "image");
+    if (!hasImages) {
+      processed.push(msg);
+      continue;
+    }
+
+    const imageParts = parts.filter((p): p is ImagePart => p.type === "image");
+    const textParts = parts.filter((p): p is TextPart => p.type === "text");
+    totalImages += imageParts.length;
+
+    const descriptions = await describeImages(imageParts, textParts, signal);
+
+    const newContent = [
+      ...textParts,
+      { type: "text" as const, text: descriptions },
+    ];
+    processed.push({ ...msg, content: newContent });
+  }
+
+  return { messages: processed, proxied: totalImages > 0, imageCount: totalImages };
+}
+
+async function describeImages(
+  images: ImagePart[],
+  contextTexts: TextPart[],
+  signal?: AbortSignal,
+): Promise<string> {
+  let apiKey: string;
+  try {
+    apiKey = await loadKeyForProvider("siliconflow");
+  } catch {
+    return buildFallbackDescription(images);
+  }
+
+  const userContext = contextTexts.map((t) => t.text).join("\n");
+
+  const visionContent: Array<Record<string, unknown>> = [];
+  visionContent.push({
+    type: "text",
+    text: buildAnalysisPrompt(userContext, images.length),
+  });
+
+  for (const img of images) {
+    visionContent.push({
+      type: "image_url",
+      image_url: {
+        url: `data:${img.mediaType};base64,${img.image}`,
+        detail: "high",
+      },
+    });
+  }
+
+  // Try each vision model with fallback
+  for (const model of VISION_MODELS) {
+    try {
+      const result = await callVisionModel(model, visionContent, apiKey, signal);
+      if (result) return formatVisionResult(result, images.length, model);
+    } catch (err) {
+      if (signal?.aborted) throw err;
+      console.warn(`[vision-proxy] ${model} failed, trying next...`);
+    }
+  }
+
+  return buildFallbackDescription(images);
+}
+
+async function callVisionModel(
+  model: string,
+  content: Array<Record<string, unknown>>,
+  apiKey: string,
+  signal?: AbortSignal,
+): Promise<string | null> {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+
+  if (signal) {
+    signal.addEventListener("abort", () => controller.abort(), { once: true });
+  }
+
+  const res = await fetch(`${SILICONFLOW_BASE}/chat/completions`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${apiKey}`,
+    },
+    body: JSON.stringify({
+      model,
+      messages: [{ role: "user", content }],
+      max_tokens: 2048,
+      temperature: 0.1,
+    }),
+    signal: controller.signal,
+  });
+
+  clearTimeout(timeout);
+
+  if (!res.ok) {
+    const errText = await res.text().catch(() => "unknown error");
+    console.warn(`[vision-proxy] ${model} returned ${res.status}: ${errText}`);
+    return null;
+  }
+
+  const data = (await res.json()) as {
+    choices: Array<{ message: { content: string } }>;
+  };
+
+  return data.choices?.[0]?.message?.content ?? null;
+}
+
+function buildAnalysisPrompt(userContext: string, imageCount: number): string {
+  const plural = imageCount > 1 ? `${imageCount} images` : "the image";
+  return [
+    `Analyze ${plural} for a software developer. The developer is working in a coding CLI tool.`,
+    "Focus on:",
+    "- UI layout and component structure (if screenshot)",
+    "- All visible text, labels, buttons, and form elements",
+    "- Colors, spacing, and visual hierarchy",
+    "- Code visible in the image (transcribe exactly)",
+    "- Error messages, console output, or terminal content",
+    "- Any diagram, flowchart, or architectural sketch",
+    "",
+    "Be precise and structured. Use markdown formatting.",
+    userContext ? `\nDeveloper's context: "${userContext}"` : "",
+  ].join("\n");
+}
+
+function formatVisionResult(description: string, imageCount: number, model?: string): string {
+  const usedModel = model ?? VISION_MODELS[0];
+  const header = imageCount > 1
+    ? `[Vision Proxy — ${imageCount} images analyzed via ${usedModel}]`
+    : `[Vision Proxy — image analyzed via ${usedModel}]`;
+  return `\n${header}\n${description}\n[/Vision Proxy]\n`;
+}
+
+function buildFallbackDescription(images: ImagePart[]): string {
+  const count = images.length;
+  const types = [...new Set(images.map((i) => i.mediaType))].join(", ");
+  return `\n[Vision Proxy — unavailable, ${count} image(s) (${types}) could not be analyzed. SILICONFLOW_API_KEY may be missing.]\n`;
+}

package/src/router/classifier/grammars.ts

@@ -0,0 +1,17 @@
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+
+export type GrammarId = "typescript" | "python";
+
+export const GRAMMARS: Record<GrammarId, string> = {
+  typescript: "tree-sitter-typescript/tree-sitter-typescript.wasm",
+  python: "tree-sitter-python/tree-sitter-python.wasm",
+};
+
+export async function loadGrammarBytes(id: GrammarId): Promise<Uint8Array> {
+  const rel = GRAMMARS[id];
+  // Resolve under node_modules -- works under Bun + Node
+  const p = path.join(process.cwd(), "node_modules", rel);
+  const buf = await fs.readFile(p);
+  return new Uint8Array(buf);
+}

package/src/router/classifier/index.test.ts

@@ -0,0 +1,33 @@
+import { beforeAll, describe, expect, it } from "vitest";
+import { classify, warm } from "./index.js";
+
+describe("classify orchestrator", () => {
+  beforeAll(async () => {
+    await warm();
+  }, 30_000);
+
+  it("returns hot for generic greeting (short message fast path)", () => {
+    const result = classify("hi");
+    expect(result.tier).toBe("hot");
+    expect(result.confidence).toBe(0.6);
+    expect(result.reason).toBe("regex:short-message");
+  });
+
+  it("returns hot for regex-matchable prompts", () => {
+    const result = classify("create a file called hello.ts");
+    expect(result.tier).toBe("hot");
+    expect(result.confidence).toBeGreaterThanOrEqual(0.55);
+  });
+
+  it("threshold gating: prompt scoring 0.6 returns abstain when threshold is 0.8", () => {
+    // "explain something" matches regex with ~0.70 confidence
+    const result = classify("explain what this does", 0.8);
+    expect(result.tier).toBe("abstain");
+  });
+
+  it("returns hot for tree-sitter-detectable code prompts", () => {
+    const result = classify("```ts\nconst x: number = 1;\n```");
+    expect(result.tier).toBe("hot");
+    expect(result.confidence).toBeGreaterThanOrEqual(0.55);
+  });
+});

package/src/router/classifier/index.ts

@@ -0,0 +1,21 @@
+// FORBIDDEN imports (enforced by tests/arch/no-network-in-classifier.test.ts):
+//   node:net | node:http(s) | undici | axios | ../ee/* | global-fetch
+import type { ClassifierResult } from "../types.js";
+import { matchRegex } from "./regex.js";
+import { initTreeSitter, lazyTreeSitter } from "./tree-sitter.js";
+
+export function classify(prompt: string, threshold = 0.55): ClassifierResult {
+  const r = matchRegex(prompt);
+  if (r.confidence >= threshold) return r;
+  const t = lazyTreeSitter(prompt);
+  if (t.confidence >= threshold) return t;
+  return {
+    tier: "abstain",
+    confidence: Math.max(r.confidence, t.confidence),
+    reason: "low-confidence",
+  };
+}
+
+export async function warm(): Promise<void> {
+  await initTreeSitter(["typescript", "python"]);
+}

package/src/router/classifier/regex.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from "vitest";
+import { matchRegex } from "./regex.js";
+
+describe("matchRegex", () => {
+  it('classifies "create file foo.ts with hello world" with confidence >= 0.55', () => {
+    const result = matchRegex("create file foo.ts with hello world");
+    expect(result.confidence).toBeGreaterThanOrEqual(0.55);
+    expect(result.reason).toMatch(/^regex:/);
+  });
+
+  it('classifies "hi how are you" as short message with moderate confidence', () => {
+    const result = matchRegex("hi how are you");
+    expect(result.confidence).toBe(0.6);
+    expect(result.reason).toBe("regex:short-message");
+    expect(result.tierHint).toBe("fast");
+  });
+
+  describe("seed intents (>= 7 patterns at >= 0.55 confidence)", () => {
+    const seeds = [
+      { prompt: "create a file called app.ts", intent: "create-file" },
+      { prompt: "edit the main.ts file to fix the bug", intent: "edit" },
+      { prompt: "run the test command", intent: "run-command" },
+      { prompt: "explain what this code does", intent: "explain" },
+      { prompt: "refactor the auth module", intent: "refactor" },
+      { prompt: "search for the function declaration", intent: "search" },
+      { prompt: "install package express", intent: "install" },
+    ];
+
+    for (const { prompt, intent } of seeds) {
+      it(`matches "${prompt}" as regex:${intent} with >= 0.55`, () => {
+        const result = matchRegex(prompt);
+        expect(result.confidence).toBeGreaterThanOrEqual(0.55);
+        expect(result.reason).toBe(`regex:${intent}`);
+      });
+    }
+  });
+
+  it('returns tier "hot" for high confidence matches', () => {
+    const result = matchRegex("create a file called foo.ts");
+    expect(result.tier).toBe("hot");
+  });
+
+  it('returns tier "abstain" for long complex input', () => {
+    const result = matchRegex("I need you to analyze the distributed system architecture across all microservices and identify race conditions in the payment processing pipeline");
+    expect(result.tier).toBe("abstain");
+  });
+});

package/src/router/classifier/regex.ts

@@ -0,0 +1,54 @@
+import type { ClassifierResult } from "../types.js";
+
+const PATTERNS: Array<{
+  re: RegExp;
+  intent: string;
+  confidence: number;
+  tierHint: "fast" | "balanced" | "premium";
+}> = [
+  // English patterns
+  { re: /\b(create|new|make|generate)\s+(a\s+)?(file|component|module|class|function)\b/i, intent: "create-file", confidence: 0.85, tierHint: "fast" },
+  { re: /\b(edit|modify|update|change|fix|patch)\s+(the\s+)?\S+/i, intent: "edit", confidence: 0.8, tierHint: "fast" },
+  { re: /\b(run|execute|exec)\s+(the\s+)?(command|script|npm|bun|tsc|test|build)\b/i, intent: "run-command", confidence: 0.85, tierHint: "fast" },
+  { re: /\b(explain|what\s+does|describe|how\s+does)\b/i, intent: "explain", confidence: 0.7, tierHint: "fast" },
+  { re: /\b(search|find|grep|look\s+for)\b/i, intent: "search", confidence: 0.8, tierHint: "fast" },
+  { re: /\b(install|add)\s+(package|dep|dependency|module)\b/i, intent: "install", confidence: 0.85, tierHint: "fast" },
+  { re: /\b(list|show|ls|cat|read|head|tail)\b/i, intent: "read", confidence: 0.8, tierHint: "fast" },
+  { re: /\bgit\s+(status|log|diff|add|commit|push|pull|branch|checkout)\b/i, intent: "git", confidence: 0.85, tierHint: "fast" },
+  { re: /\brefactor\b/i, intent: "refactor", confidence: 0.75, tierHint: "balanced" },
+  { re: /\b(architect|design|plan|strategy)\b/i, intent: "design", confidence: 0.7, tierHint: "premium" },
+  // Vietnamese patterns — higher tiers first to avoid premature fast-match
+  { re: /(thiết kế|kiến trúc|\barchitect\b|\bdesign\b|xây dựng hệ thống|chiến lược)/i, intent: "design", confidence: 0.7, tierHint: "premium" },
+  { re: /(tái cấu trúc|refactor|cấu trúc lại|tổ chức lại)/i, intent: "refactor", confidence: 0.75, tierHint: "balanced" },
+  { re: /(thêm tính năng|thêm chức năng|bổ sung|implement)/i, intent: "add-feature", confidence: 0.75, tierHint: "balanced" },
+  { re: /(tạo|tạo mới|sinh|generate)\s+.*(file|component|module|class|hàm|function)/i, intent: "create-file", confidence: 0.85, tierHint: "fast" },
+  { re: /(sửa|fix|chỉnh|update|cập nhật|patch|sửa lỗi)\s+\S+/i, intent: "edit", confidence: 0.8, tierHint: "fast" },
+  { re: /(chạy|run|thực thi)\s+(lệnh|command|script|test|build)/i, intent: "run-command", confidence: 0.85, tierHint: "fast" },
+  { re: /(giải thích|explain|mô tả|describe)\s+/i, intent: "explain", confidence: 0.7, tierHint: "fast" },
+  { re: /(tìm|tìm kiếm|search|grep)\s+/i, intent: "search", confidence: 0.8, tierHint: "fast" },
+  { re: /(cài|cài đặt|install|thêm)\s+(package|gói|thư viện|dep)/i, intent: "install", confidence: 0.85, tierHint: "fast" },
+  { re: /(liệt kê|hiển thị|show|đọc|xem)\s+(file|thư mục|danh sách)/i, intent: "read", confidence: 0.8, tierHint: "fast" },
+];
+
+export function matchRegex(prompt: string): ClassifierResult {
+  // Hot-path: catch obvious English CLI commands without brain call
+  for (const p of PATTERNS) {
+    if (p.re.test(prompt)) {
+      return {
+        tier: "hot",
+        confidence: p.confidence,
+        reason: `regex:${p.intent}`,
+        tierHint: p.tierHint,
+      };
+    }
+  }
+
+  // Short messages in any language — delegate tier choice to brain via warm path
+  // but mark as "hot" so we skip the cold path (expensive LLM)
+  const trimmed = prompt.trim();
+  if (trimmed.length <= 80 && trimmed.split(/\s+/).length <= 10) {
+    return { tier: "hot", confidence: 0.6, reason: "regex:short-message", tierHint: "fast" };
+  }
+
+  return { tier: "abstain", confidence: 0.0, reason: "regex:no-match" };
+}

package/src/router/classifier/tree-sitter.test.ts

@@ -0,0 +1,26 @@
+import { beforeAll, describe, expect, it } from "vitest";
+import { initTreeSitter, lazyTreeSitter } from "./tree-sitter.js";
+
+describe("tree-sitter classifier", () => {
+  beforeAll(async () => {
+    await initTreeSitter(["typescript", "python"]);
+  }, 30_000);
+
+  it("parses TypeScript fenced code with confidence >= 0.55", () => {
+    const result = lazyTreeSitter("```ts\nconst x: number = 1\n```");
+    expect(result.confidence).toBeGreaterThanOrEqual(0.55);
+    expect(result.reason).toMatch(/^tree-sitter:typescript/);
+  });
+
+  it("parses Python fenced code with confidence >= 0.55", () => {
+    const result = lazyTreeSitter("```python\ndef f(x): return x\n```");
+    expect(result.confidence).toBeGreaterThanOrEqual(0.55);
+    expect(result.reason).toMatch(/^tree-sitter:python/);
+  });
+
+  it("returns abstain for prompts without fenced code", () => {
+    const result = lazyTreeSitter("hello world no code here");
+    expect(result.tier).toBe("abstain");
+    expect(result.reason).toBe("tree-sitter:no-fenced-code");
+  });
+});

package/src/router/classifier/tree-sitter.ts

@@ -0,0 +1,87 @@
+import type { ClassifierResult } from "../types.js";
+import { type GrammarId, loadGrammarBytes } from "./grammars.js";
+
+type ParserHandle = { parser: any; lang: any };
+const cache = new Map<GrammarId, ParserHandle>();
+let initOnce: Promise<void> | null = null;
+
+// Resolve web-tree-sitter classes from dynamic import (CJS/ESM compat)
+function resolveModule(mod: any): { Parser: any; Language: any } {
+  // Named exports take priority, then nested under default
+  const Parser = mod.Parser ?? mod.default?.Parser;
+  const Language = mod.Language ?? mod.default?.Language;
+  return { Parser, Language };
+}
+
+async function initParser(): Promise<void> {
+  if (initOnce) return initOnce;
+  initOnce = (async () => {
+    const ts = await import("web-tree-sitter");
+    const { Parser } = resolveModule(ts);
+    await Parser.init();
+  })();
+  return initOnce;
+}
+
+export async function initTreeSitter(grammars: GrammarId[] = ["typescript", "python"]): Promise<void> {
+  await initParser();
+  const ts = await import("web-tree-sitter");
+  const { Parser, Language } = resolveModule(ts);
+  for (const id of grammars) {
+    if (cache.has(id)) continue;
+    const bytes = await loadGrammarBytes(id);
+    const lang = await Language.load(bytes);
+    const parser = new Parser();
+    parser.setLanguage(lang);
+    cache.set(id, { parser, lang });
+  }
+}
+
+// Fire-and-forget warm at boot
+export function warmTreeSitter(): void {
+  void initTreeSitter();
+}
+
+function detectLang(prompt: string): GrammarId | null {
+  if (/```(ts|tsx|typescript)\b/i.test(prompt)) return "typescript";
+  if (/```(py|python)\b/i.test(prompt)) return "python";
+  return null;
+}
+
+export function lazyTreeSitter(prompt: string): ClassifierResult {
+  const id = detectLang(prompt);
+  if (!id) {
+    return {
+      tier: "abstain",
+      confidence: 0.0,
+      reason: "tree-sitter:no-fenced-code",
+    };
+  }
+  const handle = cache.get(id);
+  if (!handle) {
+    return { tier: "abstain", confidence: 0.3, reason: "tree-sitter:cold" };
+  }
+  // Extract fenced code body (best-effort)
+  const m = prompt.match(/```\w+\n([\s\S]*?)```/);
+  const body = m ? m[1] : prompt;
+  try {
+    const tree = handle.parser.parse(body);
+    // Confidence based on syntactically meaningful node count
+    const root = tree.rootNode;
+    const named = root.namedChildCount;
+    const errs = root.hasError ? 1 : 0;
+    const conf = named >= 1 && !errs ? 0.8 : named >= 1 ? 0.55 : 0.3;
+    return {
+      tier: conf >= 0.55 ? "hot" : "abstain",
+      confidence: conf,
+      reason: `tree-sitter:${id}`,
+      tierHint: "balanced",
+    };
+  } catch {
+    return {
+      tier: "abstain",
+      confidence: 0.0,
+      reason: `tree-sitter:${id}-parse-error`,
+    };
+  }
+}