@sean.holung/minicode 0.2.3 → 0.3.0

package/dist/tests/serve.integration.test.js

@@ -0,0 +1,759 @@
+import assert from "node:assert/strict";
+import { test, afterEach } from "node:test";
+import { createServer } from "node:http";
+import { mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { createRequestHandler } from "../src/serve/server.js";
+import { AgentBridge } from "../src/serve/agent-bridge.js";
+import { createTestAgentConfig } from "./test-utils.js";
+/**
+ * Lightweight AgentBridge subclass for testing.
+ * Overrides all public methods so no real config/agent/index is needed.
+ */
+class MockBridge extends AgentBridge {
+    _busy = false;
+    turnHistory = [];
+    constructor() {
+        super(() => { }, false);
+    }
+    isBusy() {
+        return this._busy;
+    }
+    getConfig() {
+        return createTestAgentConfig("/tmp/test-workspace");
+    }
+    async runTurn(message) {
+        if (this._busy)
+            throw new Error("busy");
+        this._busy = true;
+        this.turnHistory.push(message);
+        // Simulate streaming by emitting events via the listener system
+        this.emit({ type: "streaming_chunk", content: `Echo: ${message}` });
+        this._busy = false;
+        return {
+            text: `Echo: ${message}`,
+            usage: { inputTokens: 10, outputTokens: 5 },
+        };
+    }
+    /** Expose the private emit for test streaming simulation. */
+    emit(msg) {
+        // Call listeners registered via addListener
+        for (const fn of this.listeners) {
+            fn(msg);
+        }
+    }
+    async listSess() {
+        return [
+            {
+                id: "sess-1",
+                label: "test-session",
+                createdAt: "2026-01-01T00:00:00.000Z",
+                savedAt: "2026-01-01T00:00:00.000Z",
+                messageCount: 3,
+            },
+        ];
+    }
+    async saveSess(label) {
+        return {
+            id: "sess-new",
+            label: label ?? "auto-label",
+            createdAt: "2026-01-01T00:00:00.000Z",
+            savedAt: "2026-01-01T00:00:00.000Z",
+            messageCount: 1,
+        };
+    }
+    async loadSess(label) {
+        if (label === "nonexistent")
+            return null;
+        return { session: {}, label };
+    }
+    setBusy(busy) {
+        this._busy = busy;
+    }
+    hasIndex() {
+        return true;
+    }
+    getSymbols() {
+        return [
+            { name: "foo", qualifiedName: "foo", kind: "function", filePath: "src/foo.ts", startLine: 1, endLine: 5, signature: "function foo(): void", exported: true },
+            { name: "Bar", qualifiedName: "Bar", kind: "class", filePath: "src/bar.ts", startLine: 1, endLine: 20, signature: "class Bar", exported: true },
+            { name: "helper", qualifiedName: "Bar.helper", kind: "method", filePath: "src/bar.ts", startLine: 10, endLine: 15, signature: "helper(): string", exported: false },
+        ];
+    }
+    getSymbol(name) {
+        const syms = this.getSymbols();
+        const match = syms.find((s) => s.qualifiedName === name || s.name === name);
+        if (!match)
+            return undefined;
+        return { ...match, dependencies: [], kind: match.kind };
+    }
+    getDependencies(symbolName) {
+        if (symbolName === "foo") {
+            return [
+                { name: "foo", qualifiedName: "foo", kind: "function", filePath: "src/foo.ts", signature: "function foo(): void" },
+                { name: "Bar", qualifiedName: "Bar", kind: "class", filePath: "src/bar.ts", signature: "class Bar" },
+            ];
+        }
+        return undefined;
+    }
+    getReferences(symbolName) {
+        if (symbolName === "Bar") {
+            return [{ from: "foo", kind: "calls" }];
+        }
+        return undefined;
+    }
+    getCodeMap() {
+        return { text: "## src/foo.ts\n- foo(): void", shownCount: 1, totalCount: 3 };
+    }
+    getGraph() {
+        return {
+            nodes: [
+                { id: "foo", name: "foo", kind: "function", filePath: "src/foo.ts", exported: true },
+                { id: "Bar", name: "Bar", kind: "class", filePath: "src/bar.ts", exported: true },
+            ],
+            edges: [{ from: "foo", to: "Bar", kind: "calls" }],
+        };
+    }
+    getPinnedSymbols() {
+        return [...this._pinned];
+    }
+    _pinned = new Set();
+    pinSymbol(name) {
+        if (name === "nonexistent")
+            return false;
+        this._pinned.add(name);
+        return true;
+    }
+    unpinSymbol(name) {
+        this._pinned.delete(name);
+        return true;
+    }
+    // Annotation state for testing
+    _annotations = new Map();
+    getAnnotations() {
+        return Object.fromEntries(this._annotations);
+    }
+    getAnnotationsForSymbol(name) {
+        // Resolve symbol name to qualifiedName
+        const sym = this.getSymbol(name);
+        const key = sym ? sym.qualifiedName : name;
+        return this._annotations.get(key) ?? [];
+    }
+    addAnnotation(name, text) {
+        const sym = this.getSymbol(name);
+        if (!sym)
+            return false;
+        const trimmed = text.slice(0, 500).trim();
+        if (trimmed.length === 0)
+            return false;
+        const key = sym.qualifiedName;
+        const existing = this._annotations.get(key) ?? [];
+        existing.push(trimmed);
+        this._annotations.set(key, existing);
+        return true;
+    }
+    removeAnnotation(name, index) {
+        const notes = this._annotations.get(name);
+        if (!notes || index < 0 || index >= notes.length)
+            return false;
+        notes.splice(index, 1);
+        if (notes.length === 0)
+            this._annotations.delete(name);
+        return true;
+    }
+    clearAnnotations(name) {
+        this._annotations.delete(name);
+    }
+    async explainSymbol(name, onEvent) {
+        const sym = this.getSymbol(name);
+        if (!sym)
+            throw new Error(`Symbol "${name}" not found`);
+        onEvent({ type: "streaming_chunk", content: `Explaining ${name}...` });
+        return `Explaining ${name}...`;
+    }
+}
+// ── Test harness ──
+let activeServer;
+function startTestServer(bridge) {
+    const handler = createRequestHandler(bridge);
+    const server = createServer(handler);
+    activeServer = server;
+    return new Promise((resolve) => {
+        server.listen(0, "127.0.0.1", () => {
+            const addr = server.address();
+            if (typeof addr === "object" && addr) {
+                resolve(`http://127.0.0.1:${addr.port}`);
+            }
+        });
+    });
+}
+function stopTestServer() {
+    return new Promise((resolve) => {
+        if (activeServer) {
+            activeServer.close(() => resolve());
+            activeServer = undefined;
+        }
+        else {
+            resolve();
+        }
+    });
+}
+afterEach(async () => {
+    await stopTestServer();
+});
+// ── REST API tests ──
+test("GET /api/status returns status and config info", async () => {
+    const bridge = new MockBridge();
+    const base = await startTestServer(bridge);
+    const res = await fetch(`${base}/api/status`);
+    assert.equal(res.status, 200);
+    const body = (await res.json());
+    assert.equal(body.status, "ready");
+    assert.equal(body.workspace, "/tmp/test-workspace");
+    assert.equal(body.model, "test-model");
+    assert.equal(body.provider, "anthropic");
+});
+test("GET /api/status returns busy when agent is busy", async () => {
+    const bridge = new MockBridge();
+    bridge.setBusy(true);
+    const base = await startTestServer(bridge);
+    const res = await fetch(`${base}/api/status`);
+    const body = (await res.json());
+    assert.equal(body.status, "busy");
+});
+test("GET /api/config returns formatted config", async () => {
+    const bridge = new MockBridge();
+    const base = await startTestServer(bridge);
+    const res = await fetch(`${base}/api/config`);
+    assert.equal(res.status, 200);
+    const body = (await res.json());
+    assert.ok(body.config.includes("workspaceRoot"));
+    assert.ok(body.config.includes("test-model"));
+});
+test("GET /api/sessions returns session list", async () => {
+    const bridge = new MockBridge();
+    const base = await startTestServer(bridge);
+    const res = await fetch(`${base}/api/sessions`);
+    assert.equal(res.status, 200);
+    const body = (await res.json());
+    assert.equal(body.sessions.length, 1);
+    assert.equal(body.sessions[0].label, "test-session");
+});
+test("POST /api/sessions/save saves a session", async () => {
+    const bridge = new MockBridge();
+    const base = await startTestServer(bridge);
+    const res = await fetch(`${base}/api/sessions/save`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ label: "my-save" }),
+    });
+    assert.equal(res.status, 200);
+    const body = (await res.json());
+    assert.equal(body.label, "my-save");
+});
+test("POST /api/sessions/load returns 404 for unknown session", async () => {
+    const bridge = new MockBridge();
+    const base = await startTestServer(bridge);
+    const res = await fetch(`${base}/api/sessions/load`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ label: "nonexistent" }),
+    });
+    assert.equal(res.status, 404);
+});
+test("POST /api/sessions/load returns success for known session", async () => {
+    const bridge = new MockBridge();
+    const base = await startTestServer(bridge);
+    const res = await fetch(`${base}/api/sessions/load`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ label: "test-session" }),
+    });
+    assert.equal(res.status, 200);
+    const body = (await res.json());
+    assert.equal(body.label, "test-session");
+});
+test("POST /api/chat returns agent response", async () => {
+    const bridge = new MockBridge();
+    const base = await startTestServer(bridge);
+    const res = await fetch(`${base}/api/chat`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ message: "hello" }),
+    });
+    assert.equal(res.status, 200);
+    const body = (await res.json());
+    assert.equal(body.text, "Echo: hello");
+    assert.equal(body.usage.inputTokens, 10);
+    assert.equal(body.usage.outputTokens, 5);
+});
+test("POST /api/chat returns 400 when message is missing", async () => {
+    const bridge = new MockBridge();
+    const base = await startTestServer(bridge);
+    const res = await fetch(`${base}/api/chat`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({}),
+    });
+    assert.equal(res.status, 400);
+});
+test("POST /api/chat returns 429 when agent is busy", async () => {
+    const bridge = new MockBridge();
+    bridge.setBusy(true);
+    const base = await startTestServer(bridge);
+    const res = await fetch(`${base}/api/chat`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ message: "hello" }),
+    });
+    assert.equal(res.status, 429);
+});
+// ── OpenAI-compatible API tests ──
+test("GET /v1/models returns minicode-agent model", async () => {
+    const bridge = new MockBridge();
+    const base = await startTestServer(bridge);
+    const res = await fetch(`${base}/v1/models`);
+    assert.equal(res.status, 200);
+    const body = (await res.json());
+    assert.equal(body.object, "list");
+    assert.equal(body.data.length, 1);
+    assert.equal(body.data[0].id, "minicode-agent");
+    assert.equal(body.data[0].owned_by, "minicode");
+});
+test("POST /v1/chat/completions non-streaming returns OpenAI-format response", async () => {
+    const bridge = new MockBridge();
+    const base = await startTestServer(bridge);
+    const res = await fetch(`${base}/v1/chat/completions`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            model: "minicode-agent",
+            messages: [{ role: "user", content: "list files" }],
+        }),
+    });
+    assert.equal(res.status, 200);
+    const body = (await res.json());
+    assert.ok(body.id.startsWith("chatcmpl-"));
+    assert.equal(body.object, "chat.completion");
+    assert.equal(body.model, "minicode-agent");
+    assert.equal(body.choices.length, 1);
+    assert.equal(body.choices[0].message.role, "assistant");
+    assert.equal(body.choices[0].message.content, "Echo: list files");
+    assert.equal(body.choices[0].finish_reason, "stop");
+    assert.equal(body.usage.prompt_tokens, 10);
+    assert.equal(body.usage.completion_tokens, 5);
+    assert.equal(body.usage.total_tokens, 15);
+});
+test("POST /v1/chat/completions returns 400 for empty messages", async () => {
+    const bridge = new MockBridge();
+    const base = await startTestServer(bridge);
+    const res = await fetch(`${base}/v1/chat/completions`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ model: "minicode-agent", messages: [] }),
+    });
+    assert.equal(res.status, 400);
+});
+test("POST /v1/chat/completions returns 400 for no user message", async () => {
+    const bridge = new MockBridge();
+    const base = await startTestServer(bridge);
+    const res = await fetch(`${base}/v1/chat/completions`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            model: "minicode-agent",
+            messages: [{ role: "system", content: "You are helpful" }],
+        }),
+    });
+    assert.equal(res.status, 400);
+});
+test("POST /v1/chat/completions returns 429 when busy", async () => {
+    const bridge = new MockBridge();
+    bridge.setBusy(true);
+    const base = await startTestServer(bridge);
+    const res = await fetch(`${base}/v1/chat/completions`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            model: "minicode-agent",
+            messages: [{ role: "user", content: "hello" }],
+        }),
+    });
+    assert.equal(res.status, 429);
+});
+test("POST /v1/chat/completions streaming returns SSE chunks", async () => {
+    const bridge = new MockBridge();
+    const base = await startTestServer(bridge);
+    const res = await fetch(`${base}/v1/chat/completions`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            model: "minicode-agent",
+            messages: [{ role: "user", content: "stream test" }],
+            stream: true,
+        }),
+    });
+    assert.equal(res.status, 200);
+    assert.equal(res.headers.get("content-type"), "text/event-stream");
+    const text = await res.text();
+    const lines = text.split("\n").filter((l) => l.startsWith("data: "));
+    // Should have at least: role chunk, finish chunk, [DONE]
+    assert.ok(lines.length >= 2, `Expected at least 2 data lines, got ${lines.length}`);
+    // First chunk should have role
+    const firstChunk = JSON.parse(lines[0].slice(6));
+    assert.equal(firstChunk.choices[0].delta.role, "assistant");
+    // Last data line before [DONE] should have finish_reason
+    const lastDataLine = lines.filter((l) => l !== "data: [DONE]").pop();
+    const lastChunk = JSON.parse(lastDataLine.slice(6));
+    assert.equal(lastChunk.choices[0].finish_reason, "stop");
+    // Should end with [DONE]
+    assert.ok(text.includes("data: [DONE]"));
+});
+// ── Static file serving tests ──
+test("GET / serves index.html", async () => {
+    const bridge = new MockBridge();
+    const base = await startTestServer(bridge);
+    const res = await fetch(`${base}/`);
+    assert.equal(res.status, 200);
+    assert.equal(res.headers.get("content-type"), "text/html");
+    const html = await res.text();
+    assert.ok(html.includes("minicode"));
+});
+test("GET /style.css serves CSS file", async () => {
+    const bridge = new MockBridge();
+    const base = await startTestServer(bridge);
+    const res = await fetch(`${base}/style.css`);
+    assert.equal(res.status, 200);
+    assert.equal(res.headers.get("content-type"), "text/css");
+});
+test("GET /app.js serves JS file", async () => {
+    const bridge = new MockBridge();
+    const base = await startTestServer(bridge);
+    const res = await fetch(`${base}/app.js`);
+    assert.equal(res.status, 200);
+    assert.equal(res.headers.get("content-type"), "application/javascript");
+});
+test("GET /nonexistent returns 404", async () => {
+    const bridge = new MockBridge();
+    const base = await startTestServer(bridge);
+    const res = await fetch(`${base}/nonexistent.html`);
+    assert.equal(res.status, 404);
+});
+// ── CLI args tests ──
+test("parseCliArgs parses serve subcommand", async () => {
+    const { parseCliArgs } = await import("../src/cli/args.js");
+    const parsed = parseCliArgs(["node", "minicode", "serve"]);
+    assert.equal(parsed.serve, true);
+    assert.equal(parsed.port, 4567);
+});
+test("parseCliArgs parses serve with --port", async () => {
+    const { parseCliArgs } = await import("../src/cli/args.js");
+    const parsed = parseCliArgs(["node", "minicode", "serve", "--port", "8080"]);
+    assert.equal(parsed.serve, true);
+    assert.equal(parsed.port, 8080);
+});
+test("parseCliArgs parses serve with --port=value", async () => {
+    const { parseCliArgs } = await import("../src/cli/args.js");
+    const parsed = parseCliArgs(["node", "minicode", "serve", "--port=9090"]);
+    assert.equal(parsed.serve, true);
+    assert.equal(parsed.port, 9090);
+});
+test("validateCliArgs rejects serve with --oneshot", async () => {
+    const { validateCliArgs, CliUsageError } = await import("../src/cli/args.js");
+    assert.throws(() => validateCliArgs({ verbose: false, oneshot: true, json: false, serve: true, port: 4567, task: "test" }), (err) => err instanceof CliUsageError);
+});
+// ── Graph / Index API tests ──
+test("GET /api/symbols returns all symbols", async () => {
+    const bridge = new MockBridge();
+    const base = await startTestServer(bridge);
+    const res = await fetch(`${base}/api/symbols`);
+    assert.equal(res.status, 200);
+    const body = (await res.json());
+    assert.equal(body.symbols.length, 3);
+    assert.equal(body.symbols[0].name, "foo");
+    assert.equal(body.symbols[1].name, "Bar");
+    assert.equal(body.symbols[2].name, "helper");
+});
+test("GET /api/symbols/:name/dependencies returns dependency cone", async () => {
+    const bridge = new MockBridge();
+    const base = await startTestServer(bridge);
+    const res = await fetch(`${base}/api/symbols/foo/dependencies`);
+    assert.equal(res.status, 200);
+    const body = (await res.json());
+    assert.equal(body.symbol, "foo");
+    assert.equal(body.dependencies.length, 2);
+});
+test("GET /api/symbols/:name/dependencies returns 404 for unknown symbol", async () => {
+    const bridge = new MockBridge();
+    const base = await startTestServer(bridge);
+    const res = await fetch(`${base}/api/symbols/nonexistent/dependencies`);
+    assert.equal(res.status, 404);
+});
+test("GET /api/symbols/:name/references returns references", async () => {
+    const bridge = new MockBridge();
+    const base = await startTestServer(bridge);
+    const res = await fetch(`${base}/api/symbols/Bar/references`);
+    assert.equal(res.status, 200);
+    const body = (await res.json());
+    assert.equal(body.symbol, "Bar");
+    assert.equal(body.references.length, 1);
+    assert.equal(body.references[0].from, "foo");
+});
+test("GET /api/symbols/:name/references returns 404 for unknown symbol", async () => {
+    const bridge = new MockBridge();
+    const base = await startTestServer(bridge);
+    const res = await fetch(`${base}/api/symbols/nonexistent/references`);
+    assert.equal(res.status, 404);
+});
+test("GET /api/code-map returns code map", async () => {
+    const bridge = new MockBridge();
+    const base = await startTestServer(bridge);
+    const res = await fetch(`${base}/api/code-map`);
+    assert.equal(res.status, 200);
+    const body = (await res.json());
+    assert.ok(body.text.includes("foo"));
+    assert.equal(body.shownCount, 1);
+    assert.equal(body.totalCount, 3);
+});
+test("GET /api/graph returns nodes and edges", async () => {
+    const bridge = new MockBridge();
+    const base = await startTestServer(bridge);
+    const res = await fetch(`${base}/api/graph`);
+    assert.equal(res.status, 200);
+    const body = (await res.json());
+    assert.equal(body.nodes.length, 2);
+    assert.equal(body.edges.length, 1);
+    assert.equal(body.edges[0].from, "foo");
+    assert.equal(body.edges[0].to, "Bar");
+    assert.equal(body.edges[0].kind, "calls");
+});
+test("GET /api/focus returns pinned symbols", async () => {
+    const bridge = new MockBridge();
+    const base = await startTestServer(bridge);
+    const res = await fetch(`${base}/api/focus`);
+    assert.equal(res.status, 200);
+    const body = (await res.json());
+    assert.deepEqual(body.pinned, []);
+});
+test("POST /api/focus pins and unpins symbols", async () => {
+    const bridge = new MockBridge();
+    const base = await startTestServer(bridge);
+    // Pin
+    const pinRes = await fetch(`${base}/api/focus`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ action: "pin", symbol: "foo" }),
+    });
+    assert.equal(pinRes.status, 200);
+    const pinBody = (await pinRes.json());
+    assert.ok(pinBody.pinned.includes("foo"));
+    // Unpin
+    const unpinRes = await fetch(`${base}/api/focus`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ action: "unpin", symbol: "foo" }),
+    });
+    assert.equal(unpinRes.status, 200);
+    const unpinBody = (await unpinRes.json());
+    assert.ok(!unpinBody.pinned.includes("foo"));
+});
+test("POST /api/focus returns 404 for unknown symbol", async () => {
+    const bridge = new MockBridge();
+    const base = await startTestServer(bridge);
+    const res = await fetch(`${base}/api/focus`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ action: "pin", symbol: "nonexistent" }),
+    });
+    assert.equal(res.status, 404);
+});
+test("POST /api/focus returns 400 for invalid action", async () => {
+    const bridge = new MockBridge();
+    const base = await startTestServer(bridge);
+    const res = await fetch(`${base}/api/focus`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ action: "toggle", symbol: "foo" }),
+    });
+    assert.equal(res.status, 400);
+});
+// ── Symbol source endpoint tests ──
+test("GET /api/symbols/:name/source returns source code for known symbol", async () => {
+    const bridge = new MockBridge();
+    const base = await startTestServer(bridge);
+    // Create a temp file matching the mock symbol's filePath
+    const wsRoot = "/tmp/test-workspace";
+    mkdirSync(`${wsRoot}/src`, { recursive: true });
+    writeFileSync(`${wsRoot}/src/foo.ts`, "line1\nfunction foo(): void {\n  return;\n}\nline5\n");
+    try {
+        const res = await fetch(`${base}/api/symbols/foo/source`);
+        assert.equal(res.status, 200);
+        const body = (await res.json());
+        assert.equal(body.symbol, "foo");
+        assert.equal(body.filePath, "src/foo.ts");
+        assert.equal(body.startLine, 1);
+        assert.equal(body.endLine, 5);
+        assert.ok(body.source.includes("line1"));
+    }
+    finally {
+        rmSync(wsRoot, { recursive: true, force: true });
+    }
+});
+test("GET /api/symbols/:name/source returns 404 for unknown symbol", async () => {
+    const bridge = new MockBridge();
+    const base = await startTestServer(bridge);
+    const res = await fetch(`${base}/api/symbols/nonexistent/source`);
+    assert.equal(res.status, 404);
+    const body = (await res.json());
+    assert.ok(body.error.includes("nonexistent"));
+});
+test("GET /api/symbols/:name/source returns 500 when file is missing", async () => {
+    const bridge = new MockBridge();
+    const base = await startTestServer(bridge);
+    // Don't create the file — let it fail with a read error
+    const res = await fetch(`${base}/api/symbols/foo/source`);
+    assert.equal(res.status, 500);
+    const body = (await res.json());
+    assert.ok(body.error.includes("src/foo.ts"));
+});
+// ── Annotations API tests ──
+test("GET /api/annotations returns empty annotations initially", async () => {
+    const bridge = new MockBridge();
+    const base = await startTestServer(bridge);
+    const res = await fetch(`${base}/api/annotations`);
+    assert.equal(res.status, 200);
+    const body = (await res.json());
+    assert.deepEqual(body.annotations, {});
+});
+test("POST /api/symbols/:name/annotations adds annotation", async () => {
+    const bridge = new MockBridge();
+    const base = await startTestServer(bridge);
+    const res = await fetch(`${base}/api/symbols/foo/annotations`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ text: "don't modify, stable API" }),
+    });
+    assert.equal(res.status, 200);
+    const body = (await res.json());
+    assert.equal(body.symbol, "foo");
+    assert.equal(body.annotations.length, 1);
+    assert.equal(body.annotations[0], "don't modify, stable API");
+});
+test("GET /api/symbols/:name/annotations returns annotations for symbol", async () => {
+    const bridge = new MockBridge();
+    const base = await startTestServer(bridge);
+    // Add one first
+    await fetch(`${base}/api/symbols/foo/annotations`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ text: "note 1" }),
+    });
+    const res = await fetch(`${base}/api/symbols/foo/annotations`);
+    assert.equal(res.status, 200);
+    const body = (await res.json());
+    assert.equal(body.annotations.length, 1);
+    assert.equal(body.annotations[0], "note 1");
+});
+test("POST /api/symbols/:name/annotations returns 404 for unknown symbol", async () => {
+    const bridge = new MockBridge();
+    const base = await startTestServer(bridge);
+    const res = await fetch(`${base}/api/symbols/nonexistent/annotations`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ text: "hello" }),
+    });
+    assert.equal(res.status, 404);
+});
+test("POST /api/symbols/:name/annotations returns 400 for missing text", async () => {
+    const bridge = new MockBridge();
+    const base = await startTestServer(bridge);
+    const res = await fetch(`${base}/api/symbols/foo/annotations`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({}),
+    });
+    assert.equal(res.status, 400);
+});
+test("DELETE /api/symbols/:name/annotations/:index removes annotation", async () => {
+    const bridge = new MockBridge();
+    const base = await startTestServer(bridge);
+    // Add two annotations
+    await fetch(`${base}/api/symbols/foo/annotations`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ text: "first" }),
+    });
+    await fetch(`${base}/api/symbols/foo/annotations`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ text: "second" }),
+    });
+    // Remove first
+    const res = await fetch(`${base}/api/symbols/foo/annotations/0`, {
+        method: "DELETE",
+    });
+    assert.equal(res.status, 200);
+    const body = (await res.json());
+    assert.equal(body.annotations.length, 1);
+    assert.equal(body.annotations[0], "second");
+});
+test("DELETE /api/symbols/:name/annotations/:index returns 404 for invalid index", async () => {
+    const bridge = new MockBridge();
+    const base = await startTestServer(bridge);
+    const res = await fetch(`${base}/api/symbols/foo/annotations/99`, {
+        method: "DELETE",
+    });
+    assert.equal(res.status, 404);
+});
+test("DELETE /api/symbols/:name/annotations clears all annotations", async () => {
+    const bridge = new MockBridge();
+    const base = await startTestServer(bridge);
+    // Add annotations
+    await fetch(`${base}/api/symbols/foo/annotations`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ text: "note" }),
+    });
+    // Clear all
+    const res = await fetch(`${base}/api/symbols/foo/annotations`, {
+        method: "DELETE",
+    });
+    assert.equal(res.status, 200);
+    const body = (await res.json());
+    assert.deepEqual(body.annotations, []);
+});
+test("GET /api/annotations returns all annotations after adding", async () => {
+    const bridge = new MockBridge();
+    const base = await startTestServer(bridge);
+    await fetch(`${base}/api/symbols/foo/annotations`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ text: "foo note" }),
+    });
+    await fetch(`${base}/api/symbols/Bar/annotations`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ text: "bar note" }),
+    });
+    const res = await fetch(`${base}/api/annotations`);
+    assert.equal(res.status, 200);
+    const body = (await res.json());
+    assert.ok(Object.keys(body.annotations).length >= 2);
+});
+test("GET /api/symbols/:name/explain returns SSE stream", async () => {
+    const bridge = new MockBridge();
+    const base = await startTestServer(bridge);
+    const res = await fetch(`${base}/api/symbols/foo/explain`);
+    assert.equal(res.status, 200);
+    assert.equal(res.headers.get("content-type"), "text/event-stream");
+    const text = await res.text();
+    assert.ok(text.includes("data: "));
+    assert.ok(text.includes("[DONE]"));
+});
+test("GET /api/symbols/:name/explain returns error for unknown symbol", async () => {
+    const bridge = new MockBridge();
+    const base = await startTestServer(bridge);
+    const res = await fetch(`${base}/api/symbols/nonexistent/explain`);
+    assert.equal(res.status, 200); // SSE always starts 200
+    const text = await res.text();
+    assert.ok(text.includes("error"));
+});