@sleep2agi/commhub-server 0.9.0-preview.96 → 0.9.0-preview.98

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.9.0-preview.96",
+  "version": "0.9.0-preview.98",
   "description": "CommHub Server — AI Agent communication hub with MCP protocol, multi-network isolation, user auth, and MCP tools (17 collaboration-core + node/provider ops tools; authoritative list: docs-site/docs/api/mcp-tools.md).",
   "type": "module",
   "main": "src/index.ts",

package/src/requirements-errors.ts

@@ -106,6 +106,7 @@ const ENTRIES: Record<string, Entry> = {
   client_id_taken: { field: 'client_id', message: 'That client_id was already used for another task.', hint: 'Generate a new client_id for each new task.' },
   // ── 列表 / 事件 ──
   invalid_view: { field: 'view', message: 'view must be full or summary.' },
+  invalid_last_event: { field: 'last_event', message: 'last_event must be 1 or 0 (REST). On MCP use include_last_event: true / false.' },
   invalid_overdue: { field: 'overdue', message: 'overdue must be true or false (REST: 1 / 0 / true / false).' },
   invalid_due_within_days: { field: 'due_within_days', message: 'due_within_days must be an integer from 0 to 365 (0 = due later today).' },
   invalid_limit: { field: 'limit', message: 'limit is out of range.' },

package/src/requirements-http.test.ts

@@ -373,7 +373,7 @@ describe("requirements stay on the hub", () => {
     expect((await api(ownerToken, path, { method: "PATCH", body: JSON.stringify({ due: "" }) })).body.requirement.due).toBe("");
     const listed = await api(ownerToken, "/api/requirements");
     expect(listed.body.capabilities).toContain("due_datetime");
-    expect(listed.body.capabilities).toEqual(["agent_owner", "description", "checklist", "projects", "due_datetime", "external_ref", "archived", "agent_api", "sub_requirements", "tags", "priority_lowest", "start_date", "requirement_seq", "search", "paging", "completed_at", "stats", "tag_ops", "list_summary", "changes", "events"]);
+    expect(listed.body.capabilities).toEqual(["agent_owner", "description", "checklist", "projects", "due_datetime", "external_ref", "archived", "agent_api", "sub_requirements", "tags", "priority_lowest", "start_date", "requirement_seq", "search", "paging", "completed_at", "stats", "tag_ops", "list_summary", "changes", "events", "last_event"]);
   });
 
   test("sub-requirements: parent_id in the same network, no cycles, ≤ 5 levels, child counts, filters, delete detaches children", async () => {

package/src/requirements-last-event-http.test.ts

@@ -0,0 +1,344 @@
+// #506 —— GET /api/requirements 每行带 last_event:这张卡最新的一条动态(requirement_events,评论也算)。
+// HTTP 集成测试(真实 Bun.serve,临时库;PG 梯子上用 COMMHUB_TEST_PG_URL 原样再跑一遍)。钉住:
+//   - 形状:{ type, field, actor: { id, kind, display_name } | null, at, summary? };没有流水的卡 = null(字段总在);
+//   - 评论(不改卡的任何一列)成为 last_event,summary 是正文摘要;
+//   - 节点(节点令牌)改状态 → actor.kind = "node",display_name = 节点名,summary「pool → doing」;
+//   - ETag:没变时 304,加一条评论之后同一个 If-None-Match 不再命中(列表缓存也作废);
+//   - 可见范围同行:受限成员看不见的节点 actor = null;scoped 成员看不见的卡根本不在列表里;
+//   - view=summary 同样带 last_event;REST last_event=0 不带(其他值 400 invalid_last_event);
+//   - MCP requirements_list 默认不带(守住 #471 的上下文预算),include_last_event=true 才带,参数严格(非布尔 → 报错)。
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const DIR = mkdtempSync(join(tmpdir(), "anet-req-last-event-"));
+process.env.COMMHUB_DB ||= join(DIR, "hub.db");
+process.env.COMMHUB_UPLOADS_DIR = join(DIR, "uploads");
+
+const PW = "LastEventPassw0rd!x";
+let BASE = "";
+let hub: any = null;
+let NET = "";
+let db: any = null;
+let admin = { token: "", id: "" };
+let member = { token: "", id: "" };
+let scoped = { token: "", id: "" };
+let restricted = { token: "", id: "" };
+let nodeToken = "";
+let NODE = "";
+
+type R = { status: number; body: any; etag: string | null };
+async function send(token: string, method: string, path: string, payload?: unknown, headers: Record<string, string> = {}): Promise<R> {
+  const res = await fetch(`${BASE}${path}`, {
+    method,
+    headers: { ...(token ? { Authorization: `Bearer ${token}` } : {}), "Content-Type": "application/json", ...headers },
+    body: payload === undefined ? undefined : JSON.stringify(payload),
+  });
+  const text = await res.text();
+  let body: any = null;
+  try { body = JSON.parse(text); } catch {}
+  return { status: res.status, body, etag: res.headers.get("etag") };
+}
+const create = async (t: string, card: Record<string, unknown>) => {
+  const r = await send(t, "POST", "/api/requirements", { network_id: NET, ...card });
+  expect(r.status).toBe(201);
+  return r.body.requirement as { id: string; seq: number };
+};
+const list = (t: string, qs = "", headers: Record<string, string> = {}) => send(t, "GET", `/api/requirements?network_id=${NET}${qs}`, undefined, headers);
+const rowOf = (r: R, id: string) => (r.body.requirements as any[]).find(x => x.id === id);
+async function mcp(token: string, name: string, args: Record<string, unknown>): Promise<{ data: any; text: string; isError: boolean }> {
+  const res = await fetch(`${BASE}/mcp`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", Accept: "application/json, text/event-stream", "MCP-Protocol-Version": "2025-03-26" },
+    body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name, arguments: args } }),
+  });
+  const raw = await res.text();
+  const lines = raw.split("\n").filter(x => x.startsWith("data:"));
+  const out = lines.length ? JSON.parse(lines.at(-1)!.slice(5).trim()) : JSON.parse(raw);
+  const text = out.result?.content?.[0]?.text ?? out.error?.message ?? "";
+  let data: any = null;
+  try { data = JSON.parse(text); } catch {}
+  return { data, text, isError: !!out.error || !!out.result?.isError };
+}
+const comment = (t: string, id: string, text: string) => send(t, "POST", `/api/requirements/${id}/comments?network_id=${NET}`, { text });
+
+beforeAll(async () => {
+  process.env.HOST = "127.0.0.1";
+  const { register, createNetworkTokenForNode } = await import("./auth.js");
+  db = (await import("./db.js")).db;
+  const a = register(`le_admin_${Date.now()}`, PW, undefined, "示例管理员");
+  expect(a.ok).toBe(true);
+  admin = { token: a.token!, id: a.user!.user_id };
+  NET = a.network_id!;
+  db.run("UPDATE users SET role = 'admin' WHERE user_id = ?1", [admin.id]);
+  const mod: any = await import("./server.js");
+  hub = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  BASE = `http://127.0.0.1:${hub.port}`;
+  const mk = async (username: string) => {
+    const r = await send(admin.token, "POST", "/api/admin/users", { username, password: PW, network_id: NET, role: "member" });
+    expect(r.status).toBe(200);
+    const login = await send("", "POST", "/api/auth/login", { username, password: PW });
+    expect(login.status).toBe(200);
+    return { token: login.body.token as string, id: login.body.user.user_id as string };
+  };
+  const stamp = Date.now();
+  member = await mk(`le_member_${stamp}`);
+  scoped = await mk(`le_scoped_${stamp}`);
+  restricted = await mk(`le_restricted_${stamp}`);
+  db.run("UPDATE users SET display_name = ?1 WHERE user_id = ?2", ["示例成员", member.id]);
+  db.run("UPDATE network_members SET task_access = 'all', agent_access = 'all' WHERE network_id = ?1 AND user_id = ?2", [NET, member.id]);
+  db.run("UPDATE network_members SET task_access = 'scoped' WHERE network_id = ?1 AND user_id = ?2", [NET, scoped.id]);
+  // 看全部任务,但一个 Agent 都没授权:所有节点对他隐去
+  db.run("UPDATE network_members SET task_access = 'all', agent_access = 'granted' WHERE network_id = ?1 AND user_id = ?2", [NET, restricted.id]);
+  NODE = `n_le_${stamp}`;
+  db.run("INSERT INTO nodes (node_id, node_name, alias, network_id) VALUES (?1, ?2, ?3, ?4)", [NODE, "le-node", "le-node", NET]);
+  const ntok = createNetworkTokenForNode(admin.id, NET, "le-node");
+  expect(ntok.ok).toBe(true);
+  nodeToken = ntok.token!;
+}, 30_000);
+
+afterAll(() => {
+  try { hub?.stop?.(true); } catch {}
+  try { rmSync(DIR, { recursive: true, force: true }); } catch {}
+});
+
+describe("#506 GET /api/requirements last_event", () => {
+  test("capability `last_event` is advertised; a fresh card's last_event is its `created` event", async () => {
+    const card = await create(member.token, { name: "最新动态示例一" });
+    const r = await list(admin.token);
+    expect(r.status).toBe(200);
+    expect(r.body.capabilities).toContain("last_event");
+    const row = rowOf(r, card.id);
+    expect(row.last_event).toEqual({ type: "created", field: null, actor: { id: member.id, kind: "user", display_name: "示例成员" }, at: row.last_event.at });
+    expect(Date.parse(row.last_event.at)).toBeGreaterThan(0);
+  });
+
+  test("rows with no events → last_event null (field present)", async () => {
+    const card = await create(admin.token, { name: "没有流水的旧卡" });
+    // 动态上线前建的卡 / 过了 180 天保留期的卡:流水里没有它
+    db.run("DELETE FROM requirement_events WHERE requirement_id = ?1", [card.id]);
+    const row = rowOf(await list(admin.token), card.id);
+    expect("last_event" in row).toBe(true);
+    expect(row.last_event).toBeNull();
+  });
+
+  test("a comment becomes last_event (type comment, summary = text), though it changes no column", async () => {
+    const card = await create(admin.token, { name: "评论示例" });
+    const before = rowOf(await list(admin.token), card.id);
+    expect((await comment(member.token, card.id, "第一条进展:\n已经复现,  正在修。")).status).toBe(201);
+    const row = rowOf(await list(admin.token), card.id);
+    expect(row.updatedAt).toBe(before.updatedAt); // 评论不改卡
+    expect(row.last_event).toMatchObject({ type: "comment", field: null, actor: { id: member.id, kind: "user", display_name: "示例成员" }, summary: "第一条进展: 已经复现, 正在修。" });
+    // 很长的评论:摘要截断到 120 字
+    await comment(admin.token, card.id, "长".repeat(500));
+    const long = rowOf(await list(admin.token), card.id).last_event;
+    expect(long.actor).toEqual({ id: admin.id, kind: "user", display_name: "示例管理员" });
+    expect(long.summary.length).toBe(120);
+    expect(long.summary.endsWith("…")).toBe(true);
+  });
+
+  test("a status change by a node shows kind=node with the node's name and `pool → doing`", async () => {
+    const card = await create(admin.token, { name: "节点改状态示例" });
+    const p = await send(nodeToken, "PATCH", `/api/requirements/${card.id}?network_id=${NET}`, { column: "doing" });
+    expect(p.status).toBe(200);
+    const row = rowOf(await list(admin.token), card.id);
+    expect(row.last_event).toMatchObject({ type: "changed", field: "column", actor: { id: NODE, kind: "node", display_name: "le-node" }, summary: "pool → doing" });
+    // 节点自己读列表(MCP requirements_list 走同一条路,默认 view=summary)也带着
+    const viaNode = rowOf(await list(nodeToken, "&view=summary"), card.id);
+    expect(viaNode.last_event).toEqual(row.last_event);
+  });
+
+  test("ETag: 304 while nothing changed; adding a comment changes the ETag (cache invalidated)", async () => {
+    const card = await create(admin.token, { name: "ETag 示例" });
+    const first = await list(admin.token);
+    expect(first.etag).toBeTruthy();
+    const again = await list(admin.token, "", { "If-None-Match": first.etag! });
+    expect(again.status).toBe(304);
+    expect((await comment(admin.token, card.id, "加一条评论")).status).toBe(201);
+    const after = await list(admin.token, "", { "If-None-Match": first.etag! });
+    expect(after.status).toBe(200);
+    expect(after.etag).not.toBe(first.etag);
+    expect(rowOf(after, card.id).last_event).toMatchObject({ type: "comment", summary: "加一条评论" });
+    // summary 视图的缓存键不同,同样作废
+    const s1 = await list(admin.token, "&view=summary");
+    await comment(admin.token, card.id, "再加一条");
+    const s2 = await list(admin.token, "&view=summary", { "If-None-Match": s1.etag! });
+    expect(s2.status).toBe(200);
+    expect(rowOf(s2, card.id).last_event.summary).toBe("再加一条");
+  });
+
+  test("visibility: a restricted member sees the node actor masked; a scoped member does not get the row at all", async () => {
+    const card = await create(admin.token, { name: "可见范围示例" });
+    expect((await send(nodeToken, "PATCH", `/api/requirements/${card.id}?network_id=${NET}`, { priority: "high" })).status).toBe(200);
+    const seen = rowOf(await list(restricted.token), card.id);
+    expect(seen.last_event).toMatchObject({ type: "changed", field: "priority", actor: null, summary: "normal → high" });
+    expect(JSON.stringify(seen.last_event)).not.toContain(NODE);
+    expect(JSON.stringify(seen.last_event)).not.toContain("le-node");
+    // 只看相关任务的成员:这张卡与他无关 → 不在列表里,last_event 也就无从谈起
+    const s = await list(scoped.token);
+    expect(s.status).toBe(200);
+    expect(rowOf(s, card.id)).toBeUndefined();
+    expect(JSON.stringify(s.body)).not.toContain(NODE);
+  });
+
+  test("restricted member: an agent_owner change between hidden nodes degrades to a bare `changed` (no field / summary)", async () => {
+    const other = `n_le_other_${Date.now()}`;
+    db.run("INSERT INTO nodes (node_id, node_name, alias, network_id) VALUES (?1, ?2, ?3, ?4)", [other, "le-other", "le-other", NET]);
+    const card = await create(admin.token, { name: "隐去示例", agent_owner: { kind: "node", id: NODE } });
+    expect((await send(admin.token, "PATCH", `/api/requirements/${card.id}?network_id=${NET}`, { agent_owner: { kind: "node", id: other } })).status).toBe(200);
+    expect(rowOf(await list(admin.token), card.id).last_event).toMatchObject({ type: "changed", field: "agent_owner", actor: { id: admin.id, kind: "user" } });
+    const seen = rowOf(await list(restricted.token), card.id).last_event;
+    expect(seen).toEqual({ type: "changed", field: null, actor: { id: admin.id, kind: "user", display_name: "示例管理员" }, at: seen.at });
+  });
+
+  test("REST last_event=0 drops the field; any other value is 400 invalid_last_event with field", async () => {
+    const card = await create(admin.token, { name: "REST 开关示例" });
+    const off = await list(admin.token, "&last_event=0");
+    expect(off.status).toBe(200);
+    expect("last_event" in rowOf(off, card.id)).toBe(false);
+    expect(off.body.requirements.some((r: any) => "last_event" in r)).toBe(false);
+    expect(rowOf(await list(admin.token, "&last_event=1"), card.id).last_event).toMatchObject({ type: "created" });
+    const bad = await list(admin.token, "&last_event=yes");
+    expect(bad.status).toBe(400);
+    expect(bad.body).toMatchObject({ ok: false, error: "invalid_last_event", field: "last_event" });
+  });
+
+  test("MCP requirements_list: no last_event by default; include_last_event=true adds it; non-boolean rejected", async () => {
+    const card = await create(admin.token, { name: "MCP 开关示例" });
+    await comment(admin.token, card.id, "MCP 能看到的评论");
+    const def = await mcp(nodeToken, "requirements_list", {});
+    expect(def.isError).toBe(false);
+    expect(def.data.requirements.length).toBeGreaterThan(0);
+    expect(def.data.requirements.some((r: any) => "last_event" in r)).toBe(false);
+    expect(def.text).not.toContain(`"last_event":`); // (capabilities still lists "last_event" — the Hub supports it)
+    const off = await mcp(nodeToken, "requirements_list", { include_last_event: false });
+    expect(off.data.requirements.some((r: any) => "last_event" in r)).toBe(false);
+    const on = await mcp(nodeToken, "requirements_list", { include_last_event: true });
+    expect(on.isError).toBe(false);
+    expect(on.data.requirements.every((r: any) => "last_event" in r)).toBe(true);
+    expect(on.data.requirements.find((r: any) => r.id === card.id).last_event).toMatchObject({ type: "comment", actor: { id: admin.id, kind: "user" }, summary: "MCP 能看到的评论" });
+    const bad = await mcp(nodeToken, "requirements_list", { include_last_event: "yes" });
+    expect(bad.isError).toBe(true);
+    expect(bad.text).toContain("include_last_event");
+  });
+
+  test("one page of many cards: every row gets its own latest event", async () => {
+    const ids: string[] = [];
+    for (let i = 0; i < 12; i++) ids.push((await create(admin.token, { name: `批量 ${i}` })).id);
+    for (let i = 0; i < ids.length; i += 2) await comment(member.token, ids[i], `评论 ${i}`);
+    const r = await list(admin.token, "&limit=50");
+    for (let i = 0; i < ids.length; i++) {
+      const ev = rowOf(r, ids[i]).last_event;
+      if (i % 2 === 0) expect(ev).toMatchObject({ type: "comment", summary: `评论 ${i}` });
+      else expect(ev).toMatchObject({ type: "created", actor: { id: admin.id } });
+    }
+  });
+});
+
+// #506 跟进 —— 评论不动 updated_at,所以增量读(changes=1 + updated_since)过去看不见它:「评论了」要等下次整读。
+// 现在 changes=1(且带 last_event)时,游标之后有新流水的卡也回。updated_at 语义不变(评论不改卡)。
+describe("#506 changes=1 returns cards whose newest event is after the cursor", () => {
+  const tick = () => new Promise(r => setTimeout(r, 5));
+  const changes = (t: string, since: string, extra = "", headers: Record<string, string> = {}) =>
+    list(t, `&changes=1&updated_since=${encodeURIComponent(since)}${extra}`, headers);
+  const cursorNow = async (t: string) => {
+    const base = await changes(t, new Date().toISOString());
+    expect(base.status).toBe(200);
+    await tick();
+    return base.body.server_time as string;
+  };
+
+  test("a comment after the cursor → that row comes back with the new last_event; untouched rows do not", async () => {
+    const a = await create(admin.token, { name: "增量评论 A" });
+    const b = await create(admin.token, { name: "增量评论 B" });
+    const before = rowOf(await list(admin.token), a.id);
+    await tick();
+    const since = await cursorNow(admin.token);
+    expect((await comment(member.token, a.id, "增量里看得到这条")).status).toBe(201);
+    const r = await changes(admin.token, since);
+    expect(r.status).toBe(200);
+    const ids = (r.body.requirements as any[]).map(x => x.id);
+    expect(ids).toEqual([a.id]);
+    expect(ids).not.toContain(b.id);
+    const row = rowOf(r, a.id);
+    expect(row.updatedAt).toBe(before.updatedAt); // updated_at 语义不变:评论不改卡
+    expect(row.last_event).toMatchObject({ type: "comment", actor: { id: member.id, kind: "user" }, summary: "增量里看得到这条" });
+    expect(r.body.deleted).toEqual([]);
+    // summary 视图同样回
+    const s = await changes(admin.token, since, "&view=summary");
+    expect((s.body.requirements as any[]).map(x => x.id)).toEqual([a.id]);
+    expect(rowOf(s, a.id).last_event.summary).toBe("增量里看得到这条");
+  });
+
+  test("no event and no update after the cursor → nothing returned; a comment then changes the result and its ETag", async () => {
+    const a = await create(admin.token, { name: "增量空" });
+    await tick();
+    const since = await cursorNow(admin.token);
+    const empty = await changes(admin.token, since);
+    expect(empty.status).toBe(200);
+    expect(empty.body.requirements).toEqual([]);
+    expect(empty.body.deleted).toEqual([]);
+    expect(empty.etag).toBeTruthy();
+    expect((await comment(admin.token, a.id, "空之后的评论")).status).toBe(201);
+    const after = await changes(admin.token, since, "", { "If-None-Match": empty.etag! });
+    expect(after.status).toBe(200);
+    expect(after.etag).not.toBe(empty.etag);
+    expect((after.body.requirements as any[]).map(x => x.id)).toEqual([a.id]);
+  });
+
+  test("full-list ETag changes on a comment (list cache invalidated by the write)", async () => {
+    const a = await create(admin.token, { name: "整表 ETag" });
+    const first = await list(admin.token);
+    expect((await list(admin.token, "", { "If-None-Match": first.etag! })).status).toBe(304);
+    expect((await comment(admin.token, a.id, "整表也变")).status).toBe(201);
+    const after = await list(admin.token, "", { "If-None-Match": first.etag! });
+    expect(after.status).toBe(200);
+    expect(after.etag).not.toBe(first.etag);
+  });
+
+  test("unchanged contracts: last_event=0 (MCP default) and plain updated_since (no changes=1) still filter by updated_at only", async () => {
+    const a = await create(admin.token, { name: "旧语义" });
+    await tick();
+    const since = await cursorNow(admin.token);
+    expect((await comment(admin.token, a.id, "只是一条评论")).status).toBe(201);
+    expect((await changes(admin.token, since, "&last_event=0")).body.requirements).toEqual([]);
+    const plain = await list(admin.token, `&updated_since=${encodeURIComponent(since)}`);
+    expect(plain.status).toBe(200);
+    expect(rowOf(plain, a.id)).toBeUndefined();
+    // MCP changes=true 默认不带 last_event → 同样不回;include_last_event=true → 回
+    const mDef = await mcp(nodeToken, "requirements_list", { changes: true, updated_since: since });
+    expect(mDef.isError).toBe(false);
+    expect(mDef.data.requirements.map((r: any) => r.id)).not.toContain(a.id);
+    const mOn = await mcp(nodeToken, "requirements_list", { changes: true, updated_since: since, include_last_event: true });
+    expect(mOn.isError).toBe(false);
+    expect(mOn.data.requirements.find((r: any) => r.id === a.id)?.last_event).toMatchObject({ type: "comment", summary: "只是一条评论" });
+  });
+
+  test("a real update after the cursor still comes back (updated_at path); a delete is reported in `deleted`, not as a row", async () => {
+    const a = await create(admin.token, { name: "增量改动" });
+    const d = await create(admin.token, { name: "增量删除" });
+    await comment(admin.token, d.id, "删之前的评论");
+    await tick();
+    const since = await cursorNow(admin.token);
+    expect((await send(admin.token, "PATCH", `/api/requirements/${a.id}?network_id=${NET}`, { priority: "high" })).status).toBe(200);
+    expect((await send(admin.token, "DELETE", `/api/requirements/${d.id}?network_id=${NET}`)).status).toBe(200);
+    const r = await changes(admin.token, since);
+    expect((r.body.requirements as any[]).map(x => x.id)).toEqual([a.id]);
+    expect(rowOf(r, a.id).last_event).toMatchObject({ type: "changed", field: "priority" });
+    expect(r.body.deleted).toEqual([d.id]);
+  });
+
+  test("visibility: a scoped member does not get a card it cannot see, even when it was commented on", async () => {
+    const hidden = await create(admin.token, { name: "scoped 看不见" });
+    const mine = await create(admin.token, { name: "scoped 看得见", owner: { kind: "user", id: scoped.id } });
+    await tick();
+    const since = await cursorNow(scoped.token);
+    expect((await comment(admin.token, hidden.id, "别人的卡上的评论")).status).toBe(201);
+    expect((await comment(admin.token, mine.id, "他的卡上的评论")).status).toBe(201);
+    const r = await changes(scoped.token, since);
+    expect(r.status).toBe(200);
+    expect((r.body.requirements as any[]).map(x => x.id)).toEqual([mine.id]);
+    expect(JSON.stringify(r.body)).not.toContain(hidden.id);
+  });
+});

package/src/requirements-list-slim-http.test.ts

@@ -124,7 +124,11 @@ describe("view=summary", () => {
     expect(summary.body.requirements.map((r: any) => r.id)).toEqual(full.body.requirements.map((r: any) => r.id));
     const one = await send(admin.token, "GET", `/api/requirements/${card.id}?network_id=${NET}`);
     expect(one.body.requirement.description).toBe(f.description);
-    expect(summary.text.length).toBeLessThan(full.text.length / 2);
+    // 比的是 summary 省掉的那部分(正文 / 子任务):两边一样多的 last_event(#506,每行约 150 B)不算,
+    // 否则这张只有几行的小表上,固定开销会把比例拉过一半。
+    const bare = (body: any) => JSON.stringify({ ...body, requirements: body.requirements.map(({ last_event: _l, ...r }: any) => r) }).length;
+    expect(summary.body.requirements.every((r: any) => "last_event" in r)).toBe(true);
+    expect(bare(summary.body)).toBeLessThan(bare(full.body) / 2);
   });
 
   test("view=full is the plain list; an unknown view is a 400", async () => {

package/src/requirements.ts

@@ -729,7 +729,7 @@ function ifNoneMatchHits(header: string | null, etag: string): boolean {
 // list_summary:GET 认 view=summary(不带描述正文与子任务条目,见 toSummary);changes:GET 认 changes=1 + updated_since
 // (改过的卡含归档的,加上 deleted 墓碑与 server_time,见 listChanges)。
 // events:GET /api/requirements/events —— 字段级的改动流水(谁、何时、旧值 → 新值,requirement-events.ts)。
-export const REQUIREMENT_CAPABILITIES = ["agent_owner", "description", "checklist", "projects", "due_datetime", "external_ref", "archived", "agent_api", "sub_requirements", "tags", "priority_lowest", "start_date", "requirement_seq", "search", "paging", "completed_at", "stats", "tag_ops", "list_summary", "changes", "events"] as const;
+export const REQUIREMENT_CAPABILITIES = ["agent_owner", "description", "checklist", "projects", "due_datetime", "external_ref", "archived", "agent_api", "sub_requirements", "tags", "priority_lowest", "start_date", "requirement_seq", "search", "paging", "completed_at", "stats", "tag_ops", "list_summary", "changes", "events", "last_event"] as const;
 
 // ── 子需求 ──
 // parent_id:同一网络里的另一张卡;不能成环;最多 5 层(顶层是第 1 层)。删父卡 = 子卡保留、parent_id 置空。
@@ -1105,7 +1105,16 @@ function listFilters(url: URL, sql: string, params: unknown[], ctx?: Requirement
   if (since !== null) {
     const ms = Date.parse(since);
     if (!Number.isFinite(ms)) return jsonError("invalid_updated_since", 400);
-    sql += ` AND updated_at >= ?${params.push(new Date(ms).toISOString())}`;
+    const n = params.push(new Date(ms).toISOString());
+    // #506 —— 增量(changes=1)且带 last_event 时,「之后有新流水」的卡也算改过:评论只追加 requirement_events、
+    // 不动 updated_at(updatedAt 是「卡本身最后一次被改」,评论不算 —— 见 last_event 测试),不这样评论要等下次整读才出现。
+    // 同一个占位符用两次(SQLite / PostgreSQL 都认,没有绑了不用的参数);子查询走 idx_requirement_events_created,
+    // 只扫游标之后的流水。不带 changes 的 updated_since 照旧只按 updated_at 过滤(同步方 / MCP 筛选语义不变);
+    // last_event=0(MCP 默认)行上没有动态可看,也照旧。
+    const eventsToo = q.get("changes") === "1" && q.get("last_event") !== "0";
+    sql += eventsToo
+      ? ` AND (updated_at >= ?${n} OR requirement_id IN (SELECT requirement_id FROM requirement_events WHERE created_at >= ?${n}))`
+      : ` AND updated_at >= ?${n}`;
   }
   const seq = q.get("seq");
   if (seq !== null) {
@@ -1260,6 +1269,95 @@ function deletedSince(ctx: RequirementsRequestContext, sinceIso: string): string
   return db.all<TombstoneRow>(sql, ...params).filter(row => canSeeTask(caller, row)).map(row => row.requirement_id);
 }
 
+// ── 列表每行的「最新动态」(#506)──
+// 卡片上一行「谁 · 刚刚 · 干了什么」。以前 App 只能拿 updatedAt / updated_by 拼,评论不改卡、所以不算;也说不出改了什么。
+// 这里从 requirement_events(评论也在里面,kind=comment)取每张卡最新的一条:一页只一次查询
+// (MAX(id) GROUP BY,走 idx_requirement_events_card;SQLite / PostgreSQL 同一句),再按出现的人一次查名字。
+// 只算这一页的卡(已经按调用者可见范围筛过);受限成员看不见的节点:actor 隐去,
+// 人员字段(owner / agent_owner / participants)的改动隐去之后前后一样的,只剩「改过」(field / summary 都不给)——
+// 与 updatedAt 透露的信息相同,不多泄一个字。180 天保留期外 / 没有流水的卡 = null。
+export type LastEvent = {
+  type: string;
+  field: string | null;
+  actor: { id: string; kind: "user" | "node"; display_name: string | null } | null;
+  at: string;
+  summary?: string;
+};
+const LAST_EVENT_SUMMARY_MAX = 120;
+const clip = (s: string) => (s.length > LAST_EVENT_SUMMARY_MAX ? `${s.slice(0, LAST_EVENT_SUMMARY_MAX - 1)}…` : s);
+const isRef = (v: unknown): v is { kind: string; id: string } => !!v && typeof v === "object" && typeof (v as { id?: unknown }).id === "string" && ((v as { kind?: unknown }).kind === "user" || (v as { kind?: unknown }).kind === "node");
+
+/** 一条流水 → 一句话(人员字段不给:名字另有 actor 显示,引用里的 id 对卡片没用)。 */
+function lastEventSummary(ev: ReturnType<typeof eventPublic>): string | undefined {
+  const text = (v: unknown) => (v === null || v === undefined || v === "" ? "—" : String(v));
+  if (ev.kind === "comment") {
+    const t = (ev.new as { text?: unknown } | null)?.text;
+    return typeof t === "string" ? clip(t.replace(/\s+/g, " ").trim()) : undefined;
+  }
+  if (ev.kind !== "changed") return undefined;
+  switch (ev.field) {
+    case "column": case "priority": case "due": case "start": case "archived": case "project": case "parent":
+      return clip(`${text(ev.old)} → ${text(ev.new)}`);
+    case "title": return typeof ev.new === "string" ? clip(ev.new) : undefined;
+    case "checklist_item": {
+      const item = ev.new as { text?: unknown; done?: unknown } | null;
+      return item && typeof item.text === "string" ? clip(`${item.done ? "[x]" : "[ ]"} ${item.text}`) : undefined;
+    }
+    case "checklist": {
+      const c = ev.new as { total?: unknown; done?: unknown } | null;
+      return c ? `${Number(c.done ?? 0)}/${Number(c.total ?? 0)}` : undefined;
+    }
+    case "tags": return Array.isArray(ev.new) ? clip(ev.new.join(", ")) : undefined;
+    default: return undefined;
+  }
+}
+
+function lastEventsFor(ctx: RequirementsRequestContext, rows: readonly Row[]): Map<string, LastEvent> {
+  const out = new Map<string, LastEvent>();
+  if (!rows.length) return out;
+  const ids = rows.map(r => r.requirement_id);
+  const marks = ids.map((_, i) => `?${i + 1}`).join(",");
+  const events = db.all<EventRow>(
+    `SELECT id, network_id, requirement_id, seq, title, actor_json, kind, field, old_json, new_json, created_at FROM requirement_events
+     WHERE id IN (SELECT MAX(id) FROM requirement_events WHERE requirement_id IN (${marks}) GROUP BY requirement_id)`,
+    ...ids,
+  );
+  if (!events.length) return out;
+  const pubs = events.map(eventPublic);
+  const userIds = new Set<string>(), nodeIds = new Set<string>();
+  for (const ev of pubs) if (isRef(ev.actor)) (ev.actor.kind === "user" ? userIds : nodeIds).add(ev.actor.id);
+  // 名字规则同 GET /api/requirements/people 的 name(没设显示名 → 用户名 / alias / node_name)。
+  const names = new Map<string, string>();
+  if (userIds.size) {
+    const u = [...userIds];
+    for (const r of db.all<{ id: string; name: string }>(`SELECT user_id AS id, COALESCE(NULLIF(display_name,''), username) AS name FROM users WHERE user_id IN (${u.map((_, i) => `?${i + 1}`).join(",")})`, ...u)) names.set(`user:${r.id}`, r.name);
+  }
+  if (nodeIds.size) {
+    const n = [...nodeIds];
+    for (const r of db.all<{ id: string; name: string }>(`SELECT node_id AS id, COALESCE(NULLIF(display_name,''), NULLIF(alias,''), node_name) AS name FROM nodes WHERE node_id IN (${n.map((_, i) => `?${i + 1}`).join(",")})`, ...n)) names.set(`node:${r.id}`, r.name);
+  }
+  const networkOf = new Map(rows.map(r => [r.requirement_id, r.network_id] as const));
+  const hiddenBy = new Map<string, HiddenNode>();
+  for (const ev of pubs) {
+    const networkId = networkOf.get(ev.requirement_id)!;
+    if (!hiddenBy.has(networkId)) hiddenBy.set(networkId, hiddenNodeFilter(ctx, networkId));
+    const hidden = hiddenBy.get(networkId)!;
+    const actor = isRef(ev.actor) && !isHiddenRef(ev.actor, hidden)
+      ? { id: ev.actor.id, kind: ev.actor.kind as "user" | "node", display_name: names.get(`${ev.actor.kind}:${ev.actor.id}`) ?? null }
+      : null;
+    let field = ev.field;
+    let summary = lastEventSummary(ev);
+    if (hidden && (field === "owner" || field === "agent_owner" || field === "participants")) {
+      const strip = (v: unknown) => (Array.isArray(v) ? v.filter(ref => !isHiddenRef(ref, hidden)) : isHiddenRef(v, hidden) ? null : v);
+      if (JSON.stringify(strip(ev.old)) === JSON.stringify(strip(ev.new))) { field = null; summary = undefined; }
+    }
+    const last: LastEvent = { type: ev.kind, field, actor, at: ev.at };
+    if (summary !== undefined) last.summary = summary;
+    out.set(ev.requirement_id, last);
+  }
+  return out;
+}
+
 // ── 任务动态(requirement-events.ts)──
 // GET /api/requirements/events?network_id&since&limit&cursor&requirement_id:一个网络的改动流水,按 id 从新到旧。
 // 可见范围与列表相同:卡还在 → 按当前这张卡判断调用者看不看得见;删掉了 → 按墓碑(过了墓碑保留期的删除,
@@ -1491,6 +1589,10 @@ async function handleRequirementsRequestInner(ctx: RequirementsRequestContext):
     if (view !== null && view !== "full" && view !== "summary") return jsonError("invalid_view", 400);
     const changes = url.searchParams.get("changes") === "1";
     if (changes && url.searchParams.get("updated_since") === null) return jsonError("updated_since_required", 400);
+    // last_event=0:不带每行的 last_event(MCP requirements_list 默认这么调,保住 #471 的 Agent 上下文预算)。不带 / =1 = 带。
+    const lastEventParam = url.searchParams.get("last_event");
+    if (lastEventParam !== null && lastEventParam !== "0" && lastEventParam !== "1") return jsonError("invalid_last_event", 400);
+    const withLastEvent = lastEventParam !== "0";
     // changes 模式:server_time 取在读表之前,下次拿它当 updated_since,读表期间的写入不会漏(>= 会重复回一次,客户端按 id 覆盖)。
     const serverTime = new Date().toISOString();
     nodeReadNote(ctx, "GET /api/requirements", null);
@@ -1505,7 +1607,9 @@ async function handleRequirementsRequestInner(ctx: RequirementsRequestContext):
       return conditionalBody(ctx.req, cached.body, cached.etag);
     }
     const page = listPage(ctx, filtered, params, lq);
-    const rows = page.rows.map(row => toPublicFor(ctx, row));
+    // last_event(#506):每行最新一条动态(含评论),没有 = null。旧 App 不认识,忽略即可。
+    const lastEvents = withLastEvent ? lastEventsFor(ctx, page.rows) : null;
+    const rows = lastEvents ? page.rows.map(row => ({ ...toPublicFor(ctx, row), last_event: lastEvents.get(row.requirement_id) ?? null })) : page.rows.map(row => toPublicFor(ctx, row));
     // capabilities:客户端按这个决定显示哪些功能(预计完成能不能带时刻、有没有项目…),不用靠猜字段。
     // has_more / next_cursor:后面还有没有(带 cursor=next_cursor 再读一页)。旧客户端不认识,忽略即可。
     const payload: Record<string, unknown> = { ok: true, requirements: view === "summary" ? rows.map(toSummary) : rows, capabilities: REQUIREMENT_CAPABILITIES, has_more: page.hasMore, next_cursor: page.nextCursor };

package/src/tools.ts

@@ -5977,13 +5977,14 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
     limit: z.number().int().min(1).max(1000).optional().describe(`page size, default ${REQ_LIST_MCP_DEFAULT_LIMIT}`),
     cursor: z.string().max(600).optional().describe("next_cursor from the previous page"),
     view: z.enum(["full", "summary"]).optional().describe("default summary (no description / checklist bodies; has_description, checklist_count instead); full = everything"),
-    changes: z.boolean().optional().describe("with updated_since: only tasks changed since then (archived included) + deleted ids + server_time"),
+    changes: z.boolean().optional().describe("with updated_since: only tasks changed since then (archived included; with include_last_event also ones with a newer event, e.g. a comment) + deleted ids + server_time"),
+    include_last_event: z.boolean().optional().describe("default false; true adds last_event per row (newest event incl. comments: type, field, actor, at, summary; null if none), ~150 B/row"),
   };
   const reqListKeys = Object.keys(reqListShape);
   server.registerTool(
     "requirements_list",
     {
-      description: `List requirement tasks in your network, newest first. Defaults (MCP): view='summary' (no description / checklist bodies; has_description, checklist_count instead; ~0.5 KB per task) and ${REQ_LIST_MCP_DEFAULT_LIMIT} per page; has_more + next_cursor → pass cursor. Full text: requirements_get, or view='full' with a small limit (≤ 1000). Filters: seq (#N), status, project_id ('none'), owner / agent_owner ('user:<id>' / 'node:<id>' / 'none'), tag (exact), updated_since (ISO), overdue / due_within_days (open tasks only), external_ref, parent_id / top_level, department_id (owner in it or below), include_archived; q searches title / description / people / project / tags (terms ANDed). Rows carry children {total, done}. changes=true (with updated_since) returns only tasks changed since then, archived included, plus deleted ids and server_time for the next updated_since. Unknown parameters are rejected (-32602).`,
+      description: `List requirement tasks in your network, newest first. Defaults (MCP): view='summary' (no description / checklist bodies; has_description, checklist_count instead; ~0.5 KB per task) and ${REQ_LIST_MCP_DEFAULT_LIMIT} per page; has_more + next_cursor → pass cursor. Full text: requirements_get, or view='full' with a small limit (≤ 1000). Filters: seq (#N), status, project_id ('none'), owner / agent_owner ('user:<id>' / 'node:<id>' / 'none'), tag (exact), updated_since (ISO), overdue / due_within_days (open tasks only), external_ref, parent_id / top_level, department_id (owner in it or below), include_archived; q searches title / description / people / project / tags (terms ANDed). Rows carry children {total, done}; include_last_event=true adds last_event (newest event incl. comments). changes=true (with updated_since) returns only tasks changed since then, archived included, plus deleted ids and server_time for the next updated_since. Unknown parameters are rejected (-32602).`,
       // Strict: registerTool honours a constructed object's unknownKeys (server.tool() would strip them silently).
       inputSchema: z.strictObject(reqListShape, {
         error: (iss: any) => iss.code === "unrecognized_keys"
@@ -5999,6 +6000,8 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       if (args.include_archived) q.set("include_archived", "1");
       if (args.top_level) q.set("top_level", "1");
       if (args.changes) q.set("changes", "1");
+      // #506 —— REST 每行默认带 last_event(App 用);MCP 默认不带,守住 #471 的上下文预算。
+      if (!args.include_last_event) q.set("last_event", "0");
       if (args.overdue !== undefined) q.set("overdue", args.overdue ? "1" : "0");
       if (args.due_within_days !== undefined) q.set("due_within_days", String(args.due_within_days));
       return requirementsCall("GET", `/api/requirements?${q}`, args.network_id);