skyloom 1.14.6 → 1.15.0

package/tests/todo_toolstats.test.ts

@@ -1,94 +1,94 @@
-import { describe, it, expect } from "vitest";
-import { parseTodoItems, renderTodoList, createTodoTool, TODO_WORKING_KEY } from "../src/tools/todo";
-import { clampToolResult } from "../src/core/agent";
-import { ToolRegistry } from "../src/core/tool";
-
-describe("todo_write 任务清单", () => {
-  it("parses a JSON array with status validation and defaults", () => {
-    const { items, error } = parseTodoItems('[{"text":"调研","status":"done"},{"text":"实现","status":"active"},{"text":"测试"}]');
-    expect(error).toBe("");
-    expect(items).toEqual([
-      { text: "调研", status: "done" },
-      { text: "实现", status: "active" },
-      { text: "测试", status: "pending" },
-    ]);
-    // plain string items are accepted as pending
-    expect(parseTodoItems('["a","b"]').items).toEqual([
-      { text: "a", status: "pending" },
-      { text: "b", status: "pending" },
-    ]);
-  });
-
-  it("rejects malformed input", () => {
-    expect(parseTodoItems("not json").items).toBeNull();
-    expect(parseTodoItems('{"text":"x"}').items).toBeNull();
-    expect(parseTodoItems('[{"text":""}]').items).toBeNull();
-    expect(parseTodoItems(JSON.stringify(Array(25).fill({ text: "x" }))).items).toBeNull();
-  });
-
-  it("renderTodoList shows progress and per-item marks", () => {
-    const out = renderTodoList([
-      { text: "调研", status: "done" },
-      { text: "实现", status: "active" },
-      { text: "测试", status: "pending" },
-    ]);
-    expect(out).toContain("任务清单 1/3");
-    expect(out).toContain("✓ 调研");
-    expect(out).toContain("◐ 实现");
-    expect(out).toContain("· 测试");
-  });
-
-  it("the tool stores the list in working memory (survives compaction)", async () => {
-    const working: Record<string, any> = {};
-    const fakeAgent = { memory: { setWorking: (k: string, v: any) => { working[k] = v; } } };
-    const tool = createTodoTool(fakeAgent);
-    const out = String(await tool.handler!({ items: '[{"text":"步骤一","status":"active"}]' }));
-    expect(out).toContain("✓ 任务清单 0/1");
-    expect(working[TODO_WORKING_KEY]).toEqual([{ text: "步骤一", status: "active" }]);
-    expect(String(await tool.handler!({ items: "bad" }))).toContain("✗");
-  });
-});
-
-describe("工具结果上下文保护", () => {
-  it("passes small results through untouched", () => {
-    expect(clampToolResult("short", 100)).toBe("short");
-  });
-
-  it("clamps oversized results keeping head + tail with a hint", () => {
-    const big = "H".repeat(9000) + "M".repeat(9000) + "T".repeat(9000);
-    const out = clampToolResult(big, 12000);
-    expect(out.length).toBeLessThan(13000);
-    expect(out.startsWith("HHHH")).toBe(true);
-    expect(out.endsWith("TTTT")).toBe(true);
-    expect(out).toContain("中间省略");
-    expect(out).toContain("offset");
-  });
-});
-
-describe("ToolRegistry 运行时统计", () => {
-  it("tracks calls / failures / cache hits / avg duration", async () => {
-    const reg = new ToolRegistry();
-    reg.register({
-      name: "ok_tool", description: "test tool", parameters: [], cacheable: true,
-      handler: async () => "fine",
-    });
-    reg.register({
-      name: "bad_tool", description: "failing test tool", parameters: [], maxRetries: 0,
-      handler: async () => { throw new Error("boom"); },
-    });
-
-    await reg.execute("ok_tool", { q: 1 });
-    await reg.execute("ok_tool", { q: 1 }); // cache hit
-    await reg.execute("bad_tool", {});
-
-    const stats = reg.getStats();
-    const ok = stats.find(s => s.name === "ok_tool")!;
-    expect(ok.calls).toBe(1);
-    expect(ok.cacheHits).toBe(1);
-    expect(ok.failures).toBe(0);
-    const bad = stats.find(s => s.name === "bad_tool")!;
-    expect(bad.calls).toBe(1);
-    expect(bad.failures).toBe(1);
-    expect(bad.breaker).toBeDefined();
-  });
-});
+import { describe, it, expect } from "vitest";
+import { parseTodoItems, renderTodoList, createTodoTool, TODO_WORKING_KEY } from "../src/tools/todo";
+import { clampToolResult } from "../src/core/agent";
+import { ToolRegistry } from "../src/core/tool";
+
+describe("todo_write 任务清单", () => {
+  it("parses a JSON array with status validation and defaults", () => {
+    const { items, error } = parseTodoItems('[{"text":"调研","status":"done"},{"text":"实现","status":"active"},{"text":"测试"}]');
+    expect(error).toBe("");
+    expect(items).toEqual([
+      { text: "调研", status: "done" },
+      { text: "实现", status: "active" },
+      { text: "测试", status: "pending" },
+    ]);
+    // plain string items are accepted as pending
+    expect(parseTodoItems('["a","b"]').items).toEqual([
+      { text: "a", status: "pending" },
+      { text: "b", status: "pending" },
+    ]);
+  });
+
+  it("rejects malformed input", () => {
+    expect(parseTodoItems("not json").items).toBeNull();
+    expect(parseTodoItems('{"text":"x"}').items).toBeNull();
+    expect(parseTodoItems('[{"text":""}]').items).toBeNull();
+    expect(parseTodoItems(JSON.stringify(Array(25).fill({ text: "x" }))).items).toBeNull();
+  });
+
+  it("renderTodoList shows progress and per-item marks", () => {
+    const out = renderTodoList([
+      { text: "调研", status: "done" },
+      { text: "实现", status: "active" },
+      { text: "测试", status: "pending" },
+    ]);
+    expect(out).toContain("任务清单 1/3");
+    expect(out).toContain("✓ 调研");
+    expect(out).toContain("◐ 实现");
+    expect(out).toContain("· 测试");
+  });
+
+  it("the tool stores the list in working memory (survives compaction)", async () => {
+    const working: Record<string, any> = {};
+    const fakeAgent = { memory: { setWorking: (k: string, v: any) => { working[k] = v; } } };
+    const tool = createTodoTool(fakeAgent);
+    const out = String(await tool.handler!({ items: '[{"text":"步骤一","status":"active"}]' }));
+    expect(out).toContain("✓ 任务清单 0/1");
+    expect(working[TODO_WORKING_KEY]).toEqual([{ text: "步骤一", status: "active" }]);
+    expect(String(await tool.handler!({ items: "bad" }))).toContain("✗");
+  });
+});
+
+describe("工具结果上下文保护", () => {
+  it("passes small results through untouched", () => {
+    expect(clampToolResult("short", 100)).toBe("short");
+  });
+
+  it("clamps oversized results keeping head + tail with a hint", () => {
+    const big = "H".repeat(9000) + "M".repeat(9000) + "T".repeat(9000);
+    const out = clampToolResult(big, 12000);
+    expect(out.length).toBeLessThan(13000);
+    expect(out.startsWith("HHHH")).toBe(true);
+    expect(out.endsWith("TTTT")).toBe(true);
+    expect(out).toContain("中间省略");
+    expect(out).toContain("offset");
+  });
+});
+
+describe("ToolRegistry 运行时统计", () => {
+  it("tracks calls / failures / cache hits / avg duration", async () => {
+    const reg = new ToolRegistry();
+    reg.register({
+      name: "ok_tool", description: "test tool", parameters: [], cacheable: true,
+      handler: async () => "fine",
+    });
+    reg.register({
+      name: "bad_tool", description: "failing test tool", parameters: [], maxRetries: 0,
+      handler: async () => { throw new Error("boom"); },
+    });
+
+    await reg.execute("ok_tool", { q: 1 });
+    await reg.execute("ok_tool", { q: 1 }); // cache hit
+    await reg.execute("bad_tool", {});
+
+    const stats = reg.getStats();
+    const ok = stats.find(s => s.name === "ok_tool")!;
+    expect(ok.calls).toBe(1);
+    expect(ok.cacheHits).toBe(1);
+    expect(ok.failures).toBe(0);
+    const bad = stats.find(s => s.name === "bad_tool")!;
+    expect(bad.calls).toBe(1);
+    expect(bad.failures).toBe(1);
+    expect(bad.breaker).toBeDefined();
+  });
+});

package/tests/trace.test.ts

@@ -0,0 +1,128 @@
+import { describe, it, expect } from "vitest";
+import { Tracer, traceTotals, renderTrace } from "../src/core/trace";
+
+/** A controllable clock so span timings are deterministic. */
+function clock() {
+  let t = 0;
+  return { now: () => t, advance: (ms: number) => { t += ms; } };
+}
+
+describe("Tracer", () => {
+  it("builds a nested span tree with correct parentage and timing", () => {
+    const c = clock();
+    const tr = new Tracer({ now: c.now });
+    const root = tr.startTrace("fix the bug", "fog");
+    c.advance(10);
+    const llm = tr.startSpan("chat", "llm", { model: "gpt-4o" });
+    c.advance(100);
+    llm.set({ promptTokens: 1200, completionTokens: 300, cost: 0.02 });
+    llm.end("ok");
+    const tool = tr.startSpan("read_file", "tool");
+    c.advance(25);
+    tool.end("ok");
+    root.end("ok");
+    const trace = tr.endTrace()!;
+
+    expect(trace.spans).toHaveLength(3);
+    const rootSpan = trace.spans.find((s) => s.kind === "turn")!;
+    const llmSpan = trace.spans.find((s) => s.kind === "llm")!;
+    const toolSpan = trace.spans.find((s) => s.kind === "tool")!;
+    expect(llmSpan.parentId).toBe(rootSpan.id);
+    expect(toolSpan.parentId).toBe(rootSpan.id); // sibling of llm, both under root
+    expect(llmSpan.endMs! - llmSpan.startMs).toBe(100);
+    expect(toolSpan.endMs! - toolSpan.startMs).toBe(25);
+  });
+
+  it("deeply nests spans by stack order", () => {
+    const c = clock();
+    const tr = new Tracer({ now: c.now });
+    const root = tr.startTrace("t");
+    const a = tr.startSpan("orchestrate", "orchestration");
+    const b = tr.startSpan("subtask", "task");
+    b.end();
+    a.end();
+    root.end();
+    const trace = tr.endTrace()!;
+    const rootSpan = trace.spans[0];
+    const orch = trace.spans.find((s) => s.kind === "orchestration")!;
+    const task = trace.spans.find((s) => s.kind === "task")!;
+    expect(orch.parentId).toBe(rootSpan.id);
+    expect(task.parentId).toBe(orch.id);
+  });
+
+  it("end() is idempotent and endTrace closes dangling spans", () => {
+    const c = clock();
+    const tr = new Tracer({ now: c.now });
+    tr.startTrace("t");
+    const s = tr.startSpan("hang", "tool");
+    c.advance(5);
+    s.end("ok");
+    const firstEnd = s.span!.endMs;
+    c.advance(50);
+    s.end("error"); // second call ignored
+    expect(s.span!.endMs).toBe(firstEnd);
+    expect(s.span!.status).toBe("ok");
+
+    const open = tr.startSpan("never-ended", "tool"); // left open on purpose
+    void open;
+    const trace = tr.endTrace()!;
+    const dangling = trace.spans.find((x) => x.name === "never-ended")!;
+    expect(dangling.endMs).not.toBeNull();
+    expect(dangling.status).toBe("ok");
+  });
+
+  it("aggregates tokens, cost and status counts", () => {
+    const c = clock();
+    const tr = new Tracer({ now: c.now });
+    tr.startTrace("t");
+    tr.startSpan("llm1", "llm", { promptTokens: 100, completionTokens: 50, cost: 0.01 }).end("ok");
+    tr.startSpan("llm2", "llm", { totalTokens: 200, cost: 0.02 }).end("ok");
+    tr.startSpan("tool1", "tool").end("error", { error: "boom" });
+    c.advance(0);
+    const trace = tr.endTrace()!;
+    const tot = traceTotals(trace);
+    expect(tot.llmCalls).toBe(2);
+    expect(tot.toolCalls).toBe(1);
+    expect(tot.errors).toBe(1);
+    expect(tot.totalTokens).toBe(150 + 200);
+    expect(tot.cost).toBeCloseTo(0.03, 6);
+  });
+
+  it("keeps a ring buffer of recent traces", () => {
+    const tr = new Tracer({ maxFinished: 3 });
+    for (let i = 0; i < 5; i++) { tr.startTrace(`t${i}`); tr.endTrace(); }
+    const recent = tr.recent(10);
+    expect(recent).toHaveLength(3);
+    expect(recent.map((t) => t.label)).toEqual(["t2", "t3", "t4"]);
+    expect(tr.last()!.label).toBe("t4");
+  });
+
+  it("a disabled tracer is a no-op and never throws", () => {
+    const tr = new Tracer({ enabled: false });
+    const root = tr.startTrace("t");
+    root.set({ x: 1 }).end();
+    tr.startSpan("s", "tool").end();
+    expect(tr.endTrace()).toBeNull();
+    expect(tr.last()).toBeNull();
+  });
+
+  it("renders a readable tree with totals", () => {
+    const c = clock();
+    const tr = new Tracer({ now: c.now });
+    tr.startTrace("ship feature", "rain");
+    c.advance(5);
+    const llm = tr.startSpan("chat", "llm", { model: "gpt-4o" });
+    c.advance(120);
+    llm.end("ok", { promptTokens: 1000, completionTokens: 200, cost: 0.015 });
+    tr.startSpan("write_file", "tool").end("error", { error: "disk full" });
+    const trace = tr.endTrace()!;
+    const out = renderTrace(trace);
+    expect(out).toContain("ship feature");
+    expect(out).toContain("llm:chat");
+    expect(out).toContain("gpt-4o");
+    expect(out).toContain("tool:write_file");
+    expect(out).toContain("✗");
+    expect(out).toContain("disk full");
+    expect(out).toMatch(/1 llm · 1 tool · 1200 tokens/);
+  });
+});

package/tests/tui.test.ts

@@ -1,67 +1,67 @@
-import { describe, it, expect } from "vitest";
-import { charWidth, visualWidth, padVisual, StreamRenderer } from "../src/cli/tui";
-
-describe("CJK-aware width", () => {
-  it("counts ascii as 1, CJK as 2", () => {
-    expect(charWidth("a".codePointAt(0)!)).toBe(1);
-    expect(charWidth("雾".codePointAt(0)!)).toBe(2);
-    expect(charWidth("，".codePointAt(0)!)).toBe(2); // fullwidth comma
-  });
-
-  it("treats control chars as width 0", () => {
-    expect(charWidth("\r".codePointAt(0)!)).toBe(0);
-    expect(charWidth("\n".codePointAt(0)!)).toBe(0);
-  });
-
-  it("visualWidth sums correctly and ignores ANSI", () => {
-    expect(visualWidth("abc")).toBe(3);
-    expect(visualWidth("雾雨")).toBe(4);
-    expect(visualWidth("a雾b")).toBe(4);
-    expect(visualWidth("\x1b[36m雾\x1b[39m")).toBe(2); // color codes don't count
-  });
-
-  it("padVisual pads to a visual column count", () => {
-    expect(visualWidth(padVisual("雾", 6))).toBe(6);
-    expect(padVisual("abc", 2)).toBe("abc"); // never truncates
-  });
-});
-
-/** Capture writes from a StreamRenderer into a string. */
-function render(text: string, columns = 40, chunk = 3): string {
-  let buf = "";
-  const fakeOut = { columns, write: (s: string) => { buf += s; return true; } } as any;
-  const r = new StreamRenderer(fakeOut, { gutter: "  " });
-  for (let i = 0; i < text.length; i += chunk) r.write(text.slice(i, i + chunk));
-  r.flush();
-  return buf;
-}
-
-describe("StreamRenderer", () => {
-  it("prefixes every line with the gutter", () => {
-    const out = render("hello world", 80);
-    expect(out.startsWith("  ")).toBe(true);
-  });
-
-  it("never exceeds the content width per visual line", () => {
-    const out = render("天空织机是一个本地优先的多智能体终端框架用于验证换行宽度限制是否生效啊", 40);
-    const maxContent = Math.min(40 - 2 - 1, 96);
-    for (const line of out.split("\n")) {
-      expect(visualWidth(line)).toBeLessThanOrEqual(2 + maxContent); // gutter + content
-    }
-  });
-
-  it("strips stray carriage returns (CRLF from providers)", () => {
-    const out = render("line one\r\nline two", 80);
-    expect(out.includes("\r")).toBe(false);
-    expect(out).toContain("line one");
-    expect(out).toContain("line two");
-  });
-
-  it("wraps English on word boundaries without splitting short words", () => {
-    // maxCols floors at 32, so use text long enough to exceed it.
-    const out = render("alpha beta gamma delta epsilon zeta eta theta iota kappa", 40);
-    expect(out.split("\n").length).toBeGreaterThan(1);
-    // no whole word should be broken across a wrap (each appears intact)
-    for (const w of ["alpha", "epsilon", "kappa"]) expect(out).toContain(w);
-  });
-});
+import { describe, it, expect } from "vitest";
+import { charWidth, visualWidth, padVisual, StreamRenderer } from "../src/cli/tui";
+
+describe("CJK-aware width", () => {
+  it("counts ascii as 1, CJK as 2", () => {
+    expect(charWidth("a".codePointAt(0)!)).toBe(1);
+    expect(charWidth("雾".codePointAt(0)!)).toBe(2);
+    expect(charWidth("，".codePointAt(0)!)).toBe(2); // fullwidth comma
+  });
+
+  it("treats control chars as width 0", () => {
+    expect(charWidth("\r".codePointAt(0)!)).toBe(0);
+    expect(charWidth("\n".codePointAt(0)!)).toBe(0);
+  });
+
+  it("visualWidth sums correctly and ignores ANSI", () => {
+    expect(visualWidth("abc")).toBe(3);
+    expect(visualWidth("雾雨")).toBe(4);
+    expect(visualWidth("a雾b")).toBe(4);
+    expect(visualWidth("\x1b[36m雾\x1b[39m")).toBe(2); // color codes don't count
+  });
+
+  it("padVisual pads to a visual column count", () => {
+    expect(visualWidth(padVisual("雾", 6))).toBe(6);
+    expect(padVisual("abc", 2)).toBe("abc"); // never truncates
+  });
+});
+
+/** Capture writes from a StreamRenderer into a string. */
+function render(text: string, columns = 40, chunk = 3): string {
+  let buf = "";
+  const fakeOut = { columns, write: (s: string) => { buf += s; return true; } } as any;
+  const r = new StreamRenderer(fakeOut, { gutter: "  " });
+  for (let i = 0; i < text.length; i += chunk) r.write(text.slice(i, i + chunk));
+  r.flush();
+  return buf;
+}
+
+describe("StreamRenderer", () => {
+  it("prefixes every line with the gutter", () => {
+    const out = render("hello world", 80);
+    expect(out.startsWith("  ")).toBe(true);
+  });
+
+  it("never exceeds the content width per visual line", () => {
+    const out = render("天空织机是一个本地优先的多智能体终端框架用于验证换行宽度限制是否生效啊", 40);
+    const maxContent = Math.min(40 - 2 - 1, 96);
+    for (const line of out.split("\n")) {
+      expect(visualWidth(line)).toBeLessThanOrEqual(2 + maxContent); // gutter + content
+    }
+  });
+
+  it("strips stray carriage returns (CRLF from providers)", () => {
+    const out = render("line one\r\nline two", 80);
+    expect(out.includes("\r")).toBe(false);
+    expect(out).toContain("line one");
+    expect(out).toContain("line two");
+  });
+
+  it("wraps English on word boundaries without splitting short words", () => {
+    // maxCols floors at 32, so use text long enough to exceed it.
+    const out = render("alpha beta gamma delta epsilon zeta eta theta iota kappa", 40);
+    expect(out.split("\n").length).toBeGreaterThan(1);
+    // no whole word should be broken across a wrap (each appears intact)
+    for (const w of ["alpha", "epsilon", "kappa"]) expect(out).toContain(w);
+  });
+});

package/tests/web.test.ts

@@ -0,0 +1,169 @@
+import { describe, it, expect, afterAll } from "vitest";
+import { escapeHtml, highlightCode, mdInline, mdToHtml } from "../src/web/markdown";
+import { renderInkWashUI, AGENTS_META } from "../src/web/ui";
+
+/* ════════ markdown renderer (isomorphic, injected into the page) ════════ */
+
+describe("web · markdown renderer", () => {
+  it("escapes HTML in all text paths (no XSS through content)", () => {
+    expect(escapeHtml('<img src=x onerror=alert(1)>')).not.toContain("<img");
+    expect(mdToHtml('hello <script>alert(1)</script>')).not.toContain("<script");
+    expect(mdToHtml('`<b>code</b>`')).toContain("&lt;b&gt;");
+    expect(mdToHtml('# <svg/onload=x>')).not.toContain("<svg");
+    // link text + URL are escaped; javascript: URLs are never linkified
+    expect(mdToHtml('[x](javascript:alert(1))')).not.toContain("<a");
+    expect(mdToHtml('["><img>](https://e.com)')).not.toContain("<img");
+  });
+
+  it("renders inline markdown: bold, italic, code, strikethrough, links", () => {
+    const h = mdInline("**粗** *斜* `code` ~~删~~ [链接](https://example.com)");
+    expect(h).toContain("<strong>粗</strong>");
+    expect(h).toContain("<em>斜</em>");
+    expect(h).toContain("<code>code</code>");
+    expect(h).toContain("<del>删</del>");
+    expect(h).toContain('href="https://example.com"');
+    expect(h).toContain('rel="noopener noreferrer"');
+  });
+
+  it("renders block markdown: headings, lists, quote, hr, table", () => {
+    const h = mdToHtml("# 标题\n\n- 甲\n- 乙\n\n1. 一\n2. 二\n\n> 引用\n\n---\n\n| A | B |\n|---|---|\n| 1 | 2 |");
+    expect(h).toContain('class="md-h md-h1"');
+    expect(h).toContain("<ul><li>甲</li><li>乙</li></ul>");
+    expect(h).toContain("<ol><li>一</li><li>二</li></ol>");
+    expect(h).toContain("<blockquote>引用</blockquote>");
+    expect(h).toContain("<hr>");
+    expect(h).toContain("<th>A</th>");
+    expect(h).toContain("<td>2</td>");
+  });
+
+  it("renders fenced code blocks with language tag, copy button, and highlighting", () => {
+    const h = mdToHtml("```ts\nconst x = 'hi' // note\n```");
+    expect(h).toContain('class="cb-lang">ts<');
+    expect(h).toContain('class="cb-copy"');
+    expect(h).toContain('<span class="tk-k">const</span>');
+    expect(h).toContain(`<span class="tk-s">'hi'</span>`);
+    expect(h).toContain('tk-c'); // comment token
+  });
+
+  it("tolerates an unclosed fence (mid-stream rendering)", () => {
+    const h = mdToHtml("说明\n```py\nprint(1)");
+    expect(h).toContain("<p>说明</p>");
+    expect(h).toContain("print");
+    expect(h).toContain("codeblock");
+  });
+
+  it("uses #-comments for python/shell and //-comments for C-likes", () => {
+    expect(highlightCode("# note", "py")).toContain("tk-c");
+    expect(highlightCode("// note", "ts")).toContain("tk-c");
+    expect(highlightCode("# not a comment", "ts")).not.toContain("tk-c");
+  });
+
+  it("escapes content inside code blocks", () => {
+    const h = mdToHtml("```html\n<div onclick=x>\n```");
+    expect(h).not.toContain("<div onclick");
+    expect(h).toContain("&lt;div");
+  });
+});
+
+/* ════════ page integrity ════════ */
+
+describe("web · page", () => {
+  const html = renderInkWashUI();
+  const script = (html.match(/<script>([\s\S]*?)<\/script>/) || [])[1] || "";
+
+  it("injected client script is valid standalone JS with no module artifacts", () => {
+    expect(script.length).toBeGreaterThan(1000);
+    expect(() => new Function(script)).not.toThrow();
+    for (const bad of ["exports.", "require(", "Object.defineProperty(exports"]) {
+      expect(script, `leaked module artifact: ${bad}`).not.toContain(bad);
+    }
+    for (const fn of ["function escapeHtml", "function highlightCode", "function mdInline", "function mdToHtml", "function clientMain"]) {
+      expect(script).toContain(fn);
+    }
+  });
+
+  it("ships the enterprise interaction surface", () => {
+    // stop-generation, theme toggle, export/clear, shortcuts, scroll pill, toasts
+    for (const marker of ["send-btn", "theme-btn", "export-btn", "clear-btn", "keys-modal", "scroll-pill", "toasts", "AbortController", "localStorage"]) {
+      expect(html, `missing: ${marker}`).toContain(marker);
+    }
+    // tool timeline + reasoning + markdown body classes exist in CSS
+    for (const cls of [".tool-row", ".think", ".codeblock", ".md-table", ".caret", ".welcome"]) {
+      expect(html, `missing css: ${cls}`).toContain(cls);
+    }
+    // dark mode tokens
+    expect(html).toContain("[data-theme=dark]");
+    expect(html).toContain("prefers-reduced-motion");
+  });
+
+  it("shortcut labels are OS-aware, not hardcoded to macOS", () => {
+    // no ⌘ baked into the static HTML/hint — labels are filled at boot
+    const staticHtml = html.replace(/<script>[\s\S]*?<\/script>/, "");
+    expect(staticHtml).not.toContain("⌘");
+    // the client detects Apple platforms and picks per-platform modifiers:
+    // ⌘ on Apple; Alt+digit (Ctrl+digit is browser-reserved) and Ctrl+K elsewhere
+    expect(script).toContain("isApple");
+    expect(script).toMatch(/isApple \? .⌘. : .Alt\+./);
+    expect(script).toMatch(/isApple \? .⌘. : .Ctrl\+./);
+    expect(script).toContain("localizeShortcuts");
+    // physical-key matching so macOS Option+digit (¡™£…) still works
+    expect(script).toContain("Digit[1-6]");
+    expect(script).toContain("e.altKey");
+  });
+
+  it("includes all six agents with light+dark pigments and suggestions", () => {
+    expect(AGENTS_META).toHaveLength(6);
+    for (const a of AGENTS_META) {
+      expect(a.light).toMatch(/^#[0-9a-f]{6}$/i);
+      expect(a.dark).toMatch(/^#[0-9a-f]{6}$/i);
+      expect(a.tips.length).toBeGreaterThanOrEqual(3);
+      expect(html).toContain(a.kanji);
+    }
+  });
+});
+
+/* ════════ live server integration ════════ */
+
+describe("web · server", () => {
+  let close: (() => void) | null = null;
+  afterAll(() => { if (close) close(); });
+
+  it("serves the UI and the JSON API; rejects bad requests", async () => {
+    const { startWebServer } = await import("../src/web/server");
+    const port = 3789 + Math.floor(Math.random() * 1000);
+    await startWebServer(port);
+
+    const page = await fetch(`http://127.0.0.1:${port}/`);
+    expect(page.status).toBe(200);
+    const body = await page.text();
+    expect(body).toContain("水墨气象台");
+    expect(body).toContain("clientMain()");
+
+    const agents = await fetch(`http://127.0.0.1:${port}/api/agents`);
+    expect(agents.status).toBe(200);
+    const aj: any = await agents.json();
+    // agent construction is environment-dependent (needs provider config);
+    // the contract here is the response shape, not the roster
+    expect(Array.isArray(aj.agents)).toBe(true);
+
+    const status = await fetch(`http://127.0.0.1:${port}/api/status`);
+    expect(status.status).toBe(200);
+
+    const bad = await fetch(`http://127.0.0.1:${port}/api/chat`, {
+      method: "POST", headers: { "Content-Type": "application/json" }, body: "{}",
+    });
+    expect(bad.status).toBe(400);
+
+    // Host-header guard: a rebound/evil Host is refused on loopback binding.
+    // (fetch/undici silently drops a Host override, so use raw http.)
+    const http = await import("http");
+    const evilStatus = await new Promise<number>((resolve, reject) => {
+      const r = http.request(
+        { host: "127.0.0.1", port, path: "/api/agents", headers: { Host: "evil.example.com" } },
+        (resp) => { resp.resume(); resolve(resp.statusCode || 0); });
+      r.on("error", reject);
+      r.end();
+    });
+    expect(evilStatus).toBe(403);
+  }, 15000);
+});