@sleep2agi/commhub-server 0.8.4 → 0.8.5-preview.0

package/README.md

@@ -1,8 +1,13 @@
 # @sleep2agi/commhub-server
 
+[![npm version](https://img.shields.io/npm/v/@sleep2agi/commhub-server.svg)](https://www.npmjs.com/package/@sleep2agi/commhub-server)
+[![npm downloads](https://img.shields.io/npm/dm/@sleep2agi/commhub-server.svg)](https://www.npmjs.com/package/@sleep2agi/commhub-server)
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://github.com/sleep2agi/agent-network/blob/main/LICENSE)
+[![Docs](https://img.shields.io/badge/docs-anet.sh-009e7e.svg)](https://anet.sh)
+
 CommHub: MCP Streamable HTTP + SSE push + REST API for an AI agent network. Single-process Bun server, SQLite-backed, zero config when launched through `anet`.
 
-The supported path is to install the `anet` CLI (`@sleep2agi/agent-network`, currently v2.2.9 at v0.10.10) and run `anet hub start`, which wires up the port, default admin account, recovery admin `utok_`, and local config for you.
+The supported path is to install the `anet` CLI (`@sleep2agi/agent-network`, currently v2.2.10 at v0.10.11) and run `anet hub start`, which wires up the port, default admin account, recovery admin `utok_`, and local config for you.
 
 ## Quick start (verified)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.8.4",
+  "version": "0.8.5-preview.0",
   "description": "CommHub Server — AI Agent communication hub with MCP protocol, multi-network isolation, user auth, and 17 MCP tools.",
   "type": "module",
   "main": "src/index.ts",

package/src/index.ts

@@ -6,6 +6,7 @@ import { db, logTaskEvent, logAudit } from "./db.js";
 import { createSSEStream, pushEvent, getSSEStats } from "./push.js";
 import { register, login, resolveToken, getUserNetworks, getUserAllNetworks, createNetwork, deleteNetwork, renameNetwork, changePassword, issueUserToken, listTokens, createToken, revokeToken, getNetworkMembers, getUserNetworkRole, addNetworkMember, updateMemberRole, removeNetworkMember, createInvite, joinByInvite, createNetworkTokenForNode, type AuthUser } from "./auth.js";
 import { abortRename, cleanupCommittedRenameSessions, commitRename, prepareRename, resolveCanonicalAlias } from "./rename.js";
+import { sharedSendDedup, buildDuplicateSendPayload } from "./send_dedup.js";
 
 const PORT = Number(process.env.PORT) || 9200;
 const HOST = process.env.HOST || "127.0.0.1";
@@ -1202,6 +1203,24 @@ Bun.serve({
       const fromSession = body.from || "api";
       const ttlSeconds = (body as any).ttl_seconds || 3600;
       const metaJson = normalizeMetaJson((body as any).meta);
+
+      // #212 dedup guardrail. Mirrors the MCP `send_task` tool: same
+      // (from_session, target_alias, task) within COMMHUB_SEND_DEDUP_WINDOW_MS
+      // is rejected with a structured `duplicate_send` error so dashboard
+      // dispatch buttons and scripted REST callers get the same guarantee
+      // as agent-driven MCP traffic.
+      const dedup = sharedSendDedup.check(fromSession, targetAlias, body.task);
+      if (dedup.duplicate) {
+        const payload = buildDuplicateSendPayload({
+          from: fromSession,
+          to: targetAlias,
+          ageMs: dedup.ageMs,
+          windowMs: sharedSendDedup.windowMs,
+        });
+        console.log(`[/api/task] ${fromSession} → ${targetAlias}: DROPPED duplicate (age=${dedup.ageMs}ms, window=${sharedSendDedup.windowMs}ms)`);
+        return withCors(req, Response.json(payload, { status: 429 }));
+      }
+
       // Mirror send_task MCP: write inbox + tasks rows in a single
       // transaction so the dispatch is visible to dashboard's Tasks page
       // and the parent_task_id lineage chain. Previously this endpoint
@@ -1237,6 +1256,10 @@ Bun.serve({
       if (taskNetId) { sessionSql += " AND network_id = ?2"; sessionParams.push(taskNetId); }
       const targetSession = db.get<any>(sessionSql, ...sessionParams);
       if (targetSession) pushEvent(targetAlias, { type: "new_task", inbox_count: pending?.cnt ?? 1, priority: body.priority, from: fromSession, ...(canonical.renamed ? { renamed_from: body.alias } : {}) }, taskNetId);
+      // #212 — stamp the dedup index only after the inbox/tasks insert
+      // succeeds. Mirrors the MCP `send_task` path so a failed write
+      // never shadows a legitimate retry.
+      sharedSendDedup.record(fromSession, targetAlias, body.task);
       return withCors(req, Response.json({ ok: true, task_id: id, message_id: id, ...(canonical.renamed ? { renamed_from: body.alias, renamed_to: targetAlias } : {}) }));
     }
 

package/src/send_dedup.test.ts

@@ -0,0 +1,160 @@
+// Unit test for the #212 send_task dedup guardrail.
+//
+// Pure-function module — no DB, no MCP server, just verifies the dedup
+// algebra: same key in window is rejected; different key (cross-from,
+// cross-to, cross-content) is allowed; expired entry restored; disabled
+// window short-circuits everything; structured payload contains both the
+// Chinese hint the LLM is supposed to act on and machine-parseable
+// details.
+import { describe, expect, it } from "bun:test";
+import {
+  SendDedup,
+  buildDuplicateSendPayload,
+  readDedupConfig,
+} from "./send_dedup.js";
+
+describe("readDedupConfig", () => {
+  it("defaults to 300000 ms window and 4096 max keys", () => {
+    const cfg = readDedupConfig({});
+    expect(cfg.windowMs).toBe(300_000);
+    expect(cfg.maxKeys).toBe(4096);
+  });
+
+  it("respects COMMHUB_SEND_DEDUP_WINDOW_MS=0 to disable", () => {
+    const cfg = readDedupConfig({ COMMHUB_SEND_DEDUP_WINDOW_MS: "0" });
+    expect(cfg.windowMs).toBe(0);
+  });
+
+  it("parses custom window and max keys from env", () => {
+    const cfg = readDedupConfig({
+      COMMHUB_SEND_DEDUP_WINDOW_MS: "60000",
+      COMMHUB_SEND_DEDUP_MAX_KEYS: "256",
+    });
+    expect(cfg.windowMs).toBe(60_000);
+    expect(cfg.maxKeys).toBe(256);
+  });
+
+  it("clamps negative window to 0 and small max keys to 64", () => {
+    const cfg = readDedupConfig({
+      COMMHUB_SEND_DEDUP_WINDOW_MS: "-1",
+      COMMHUB_SEND_DEDUP_MAX_KEYS: "1",
+    });
+    expect(cfg.windowMs).toBe(0);
+    expect(cfg.maxKeys).toBe(64);
+  });
+});
+
+describe("SendDedup", () => {
+  it("flags a repeat send within the window", () => {
+    const d = new SendDedup({ windowMs: 60_000, maxKeys: 32 });
+    const t0 = 1_700_000_000_000;
+
+    expect(d.check("alice", "bob", "hello", t0)).toEqual({ duplicate: false });
+    d.record("alice", "bob", "hello", t0);
+
+    const second = d.check("alice", "bob", "hello", t0 + 1000);
+    expect(second.duplicate).toBe(true);
+    if (second.duplicate) {
+      expect(second.lastSentMs).toBe(t0);
+      expect(second.ageMs).toBe(1000);
+    }
+  });
+
+  it("allows the same content after the window elapses", () => {
+    const d = new SendDedup({ windowMs: 60_000, maxKeys: 32 });
+    const t0 = 1_700_000_000_000;
+    d.record("alice", "bob", "hello", t0);
+
+    const stillIn = d.check("alice", "bob", "hello", t0 + 59_000);
+    expect(stillIn.duplicate).toBe(true);
+
+    const past = d.check("alice", "bob", "hello", t0 + 60_001);
+    expect(past).toEqual({ duplicate: false });
+  });
+
+  it("does not conflate different senders, targets, or contents", () => {
+    const d = new SendDedup({ windowMs: 60_000, maxKeys: 32 });
+    const t0 = 1_700_000_000_000;
+    d.record("alice", "bob", "hello", t0);
+
+    // Different sender → allowed.
+    expect(d.check("carol", "bob", "hello", t0 + 1000)).toEqual({ duplicate: false });
+    // Different target → allowed.
+    expect(d.check("alice", "dave", "hello", t0 + 1000)).toEqual({ duplicate: false });
+    // Different content → allowed (even with trailing whitespace tweak).
+    expect(d.check("alice", "bob", "hello ", t0 + 1000)).toEqual({ duplicate: false });
+    // Repeated original → still flagged.
+    expect(d.check("alice", "bob", "hello", t0 + 1000).duplicate).toBe(true);
+  });
+
+  it("treats windowMs=0 as fully disabled", () => {
+    const d = new SendDedup({ windowMs: 0, maxKeys: 32 });
+    expect(d.enabled).toBe(false);
+    d.record("alice", "bob", "hello", 1);
+    expect(d.check("alice", "bob", "hello", 2)).toEqual({ duplicate: false });
+    expect(d.size).toBe(0);
+  });
+
+  it("opportunistically evicts expired entries during check", () => {
+    const d = new SendDedup({ windowMs: 10_000, maxKeys: 32 });
+    d.record("alice", "bob", "hello", 1000);
+    d.record("alice", "bob", "world", 1500);
+    expect(d.size).toBe(2);
+
+    // Far past both entries' window — check should evict both.
+    expect(d.check("alice", "bob", "third", 100_000)).toEqual({ duplicate: false });
+    expect(d.size).toBe(0);
+  });
+
+  it("caps map size by oldest-first eviction when exceeding maxKeys", () => {
+    const d = new SendDedup({ windowMs: 600_000, maxKeys: 64 });
+    for (let i = 0; i < 100; i++) {
+      d.record(`from-${i}`, "bob", `content-${i}`, 1_000 + i);
+    }
+    // Eviction triggers when size > maxKeys; after eviction we keep ~90 %
+    // of maxKeys, so size should land below maxKeys.
+    expect(d.size).toBeLessThanOrEqual(64);
+    expect(d.size).toBeGreaterThan(0);
+  });
+
+  it("hashes content rather than holding the raw bytes", () => {
+    // The key function is the public surface that proves we don't keep
+    // raw content in memory between sends — the map keys themselves are
+    // safe to log/inspect.
+    const key = SendDedup.key("alice", "bob", "secret payload");
+    expect(key.startsWith("alice|bob|")).toBe(true);
+    expect(key).toMatch(/\|[0-9a-f]{64}$/);
+    expect(key).not.toContain("secret");
+  });
+});
+
+describe("buildDuplicateSendPayload", () => {
+  it("contains the Chinese LLM-facing hint with target alias and window minutes", () => {
+    const payload = buildDuplicateSendPayload({
+      from: "A站Grok",
+      to: "A站负责人",
+      ageMs: 12_345,
+      windowMs: 300_000,
+    });
+    expect(payload.ok).toBe(false);
+    expect(payload.error).toBe("duplicate_send");
+    expect(payload.message).toContain("5 分钟内已发给 A站负责人");
+    expect(payload.message).toContain("改写内容或等待");
+    expect(payload.details.age_ms).toBe(12_345);
+    expect(payload.details.window_ms).toBe(300_000);
+    expect(payload.details.from).toBe("A站Grok");
+    expect(payload.details.target).toBe("A站负责人");
+    expect(payload.details.hint_en).toContain("change the content or wait");
+  });
+
+  it("rounds the window display to whole minutes", () => {
+    const payload = buildDuplicateSendPayload({
+      from: "from-x",
+      to: "to-y",
+      ageMs: 0,
+      windowMs: 90_000,
+    });
+    // 90 s rounds to 2 min for the human-readable hint.
+    expect(payload.message).toContain("2 分钟内");
+  });
+});

package/src/send_dedup.ts

@@ -0,0 +1,192 @@
+// #212 — commhub-server send_task dedup guardrail.
+//
+// Vincent's A站Grok ran away on 2026-06-10 and sent the same task to the
+// same target 50+ times within five LLM turns (4692 chunks in a single
+// turn). It ignored three STOP replies — by the time a reply landed back
+// in its inbox the LLM had already decided to dispatch again. The dispatch
+// path was the agent's own commhub_send_task MCP tool call against
+// commhub-server's HTTP MCP transport (#204 preview.6 wiring), so the
+// agent-node runtime never saw the bytes and could not intervene
+// client-side.
+//
+// This module is the server-side guardrail: any `send_task` (whether
+// through MCP `tools/call` or the REST `/api/task` endpoint) is checked
+// against an in-memory dedup index keyed by `(from_session, target_alias,
+// sha256(content))`. A second call to the same key within the configured
+// window is rejected with a structured `duplicate_send` error containing
+// a human-readable hint the LLM can act on ("change the task content or
+// wait").
+//
+// Design notes:
+//   - Keyed by content hash, not the raw content, so we never hold the
+//     task body in memory longer than the request itself.
+//   - In-memory only. Process restart wipes the index, which is the
+//     desired failure mode (servers restart far more rarely than the
+//     5-minute default window, and a fresh window after restart is safer
+//     than rehydrating from disk).
+//   - Opportunistic eviction during every `shouldDedup` call keeps the
+//     map bounded without a separate sweep timer.
+//   - Window = 0 disables the guardrail entirely (escape hatch for the
+//     rare cases where a workflow genuinely needs to fan out the same
+//     task repeatedly — e.g. a batch sweep that produces identical
+//     payloads by design).
+//   - The structured response shape is identical between MCP and REST
+//     callers so the LLM gets the same parseable hint regardless of
+//     transport.
+
+import { createHash } from "crypto";
+
+export type DedupConfig = {
+  /** Window in ms; 0 disables guardrail. Default 300000 (5 min). */
+  windowMs: number;
+  /** Max keys to retain; opportunistically evicted past this. Default 4096. */
+  maxKeys: number;
+};
+
+export function readDedupConfig(env: NodeJS.ProcessEnv = process.env): DedupConfig {
+  const rawWindow = env.COMMHUB_SEND_DEDUP_WINDOW_MS;
+  const windowMs = rawWindow !== undefined ? Math.max(0, Number(rawWindow)) : 300_000;
+  const rawMax = env.COMMHUB_SEND_DEDUP_MAX_KEYS;
+  const maxKeys = rawMax !== undefined ? Math.max(64, Number(rawMax)) : 4096;
+  return {
+    windowMs: Number.isFinite(windowMs) ? windowMs : 300_000,
+    maxKeys: Number.isFinite(maxKeys) ? maxKeys : 4096,
+  };
+}
+
+export type DedupCheck =
+  | { duplicate: false }
+  | { duplicate: true; lastSentMs: number; ageMs: number };
+
+export class SendDedup {
+  private last = new Map<string, number>();
+  private cfg: DedupConfig;
+
+  constructor(cfg: Partial<DedupConfig> = {}) {
+    const fallback = readDedupConfig();
+    this.cfg = { windowMs: cfg.windowMs ?? fallback.windowMs, maxKeys: cfg.maxKeys ?? fallback.maxKeys };
+  }
+
+  /** Whether the dedup guardrail is enabled at all. */
+  get enabled(): boolean {
+    return this.cfg.windowMs > 0;
+  }
+
+  get windowMs(): number {
+    return this.cfg.windowMs;
+  }
+
+  /** Visible for tests only. */
+  get size(): number {
+    return this.last.size;
+  }
+
+  static key(from: string, to: string, content: string): string {
+    const hash = createHash("sha256").update(content).digest("hex");
+    return `${from}|${to}|${hash}`;
+  }
+
+  /**
+   * Check whether (from, to, content) was sent recently. Returns
+   * `{ duplicate: false }` when the call should proceed, or
+   * `{ duplicate: true, lastSentMs, ageMs }` when the caller should be
+   * rejected with a `duplicate_send` error.
+   *
+   * Does NOT record the new send — callers should call `record(...)`
+   * AFTER the underlying side effect (inbox insert + pushEvent) succeeds,
+   * so failed sends don't accidentally block legitimate retries.
+   */
+  check(from: string, to: string, content: string, nowMs: number = Date.now()): DedupCheck {
+    if (!this.enabled) return { duplicate: false };
+    this.evictExpired(nowMs);
+    const k = SendDedup.key(from, to, content);
+    const lastSentMs = this.last.get(k);
+    if (lastSentMs === undefined) return { duplicate: false };
+    const ageMs = nowMs - lastSentMs;
+    if (ageMs >= this.cfg.windowMs) {
+      this.last.delete(k);
+      return { duplicate: false };
+    }
+    return { duplicate: true, lastSentMs, ageMs };
+  }
+
+  /** Record a successful send for future dedup checks. */
+  record(from: string, to: string, content: string, nowMs: number = Date.now()): void {
+    if (!this.enabled) return;
+    const k = SendDedup.key(from, to, content);
+    this.last.set(k, nowMs);
+    if (this.last.size > this.cfg.maxKeys) this.evictOldest();
+  }
+
+  /** Visible for tests. Drops everything. */
+  clear(): void {
+    this.last.clear();
+  }
+
+  private evictExpired(nowMs: number): void {
+    const cutoff = nowMs - this.cfg.windowMs;
+    for (const [k, ts] of this.last) {
+      if (ts < cutoff) this.last.delete(k);
+    }
+  }
+
+  private evictOldest(): void {
+    const target = Math.max(64, Math.floor(this.cfg.maxKeys * 0.9));
+    if (this.last.size <= target) return;
+    const entries = Array.from(this.last.entries()).sort((a, b) => a[1] - b[1]);
+    for (let i = 0; i < this.last.size - target; i++) this.last.delete(entries[i][0]);
+  }
+}
+
+// Process-wide singleton consumed by both the MCP `send_task` tool and
+// the REST `/api/task` endpoint so they share a single dedup index
+// regardless of which transport the agent hits. Tests reach for it via
+// `sharedSendDedup.clear()` to reset between cases.
+export const sharedSendDedup = new SendDedup();
+
+/**
+ * Build the structured `duplicate_send` error payload returned to the
+ * caller (MCP wraps it inside `content[0].text` JSON; REST returns it
+ * directly with HTTP 429). The Chinese hint matches what 通信龙 specified
+ * in the #212 dispatch so the LLM has a consistent piece of text to
+ * reason about and rewrite around.
+ */
+export function buildDuplicateSendPayload(args: {
+  from: string;
+  to: string;
+  ageMs: number;
+  windowMs: number;
+}): {
+  ok: false;
+  error: "duplicate_send";
+  message: string;
+  details: {
+    from: string;
+    target: string;
+    age_ms: number;
+    window_ms: number;
+    hint_zh: string;
+    hint_en: string;
+  };
+} {
+  const windowMin = Math.round(args.windowMs / 60_000);
+  const hintZh =
+    `同内容任务 ${windowMin} 分钟内已发给 ${args.to}, ` +
+    `如确需重发请改写内容或等待。 (Last sent ${args.ageMs}ms ago)`;
+  const hintEn =
+    `Same task content already sent to ${args.to} within the last ` +
+    `${windowMin} min — change the content or wait. (Last sent ${args.ageMs}ms ago)`;
+  return {
+    ok: false,
+    error: "duplicate_send",
+    message: hintZh,
+    details: {
+      from: args.from,
+      target: args.to,
+      age_ms: args.ageMs,
+      window_ms: args.windowMs,
+      hint_zh: hintZh,
+      hint_en: hintEn,
+    },
+  };
+}

package/src/tools.ts

@@ -4,6 +4,7 @@ import { db, uuidv4, logTaskEvent, chainReplyToParent } from "./db.js";
 import { pushEvent } from "./push.js";
 import { getUserNetworkRole } from "./auth.js";
 import { canonicalAliasExists, cleanupRenamedAliasSession, resolveCanonicalAlias } from "./rename.js";
+import { sharedSendDedup, buildDuplicateSendPayload } from "./send_dedup.js";
 
 function ts(): string {
   return new Date().toTimeString().slice(0, 8);
@@ -657,6 +658,27 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
 
       const canonical = resolveCanonicalAlias(effectiveNetId, alias);
       const targetAlias = canonical.alias;
+
+      // #212 dedup guardrail. If this exact (from, to, content) has already
+      // been delivered within COMMHUB_SEND_DEDUP_WINDOW_MS (default 5 min)
+      // we refuse the call and surface a structured `duplicate_send`
+      // error. The LLM receives the Chinese hint inside details.message
+      // and can act on it (rewrite the task or wait). See A站Grok #212
+      // incident: 50+ identical dispatches across 5 LLM turns ignored
+      // three STOP replies — the LLM cannot be trusted to debounce
+      // itself, so the runtime layer must.
+      const dedup = sharedSendDedup.check(from_session, targetAlias, task);
+      if (dedup.duplicate) {
+        const payload = buildDuplicateSendPayload({
+          from: from_session,
+          to: targetAlias,
+          ageMs: dedup.ageMs,
+          windowMs: sharedSendDedup.windowMs,
+        });
+        console.log(`[${ts()}] ${from_session} → send_task → ${targetAlias}: DROPPED duplicate (age=${dedup.ageMs}ms, window=${sharedSendDedup.windowMs}ms)`);
+        return { content: [{ type: "text" as const, text: JSON.stringify(payload) }] };
+      }
+
       console.log(`[${ts()}] ${from_session} → send_task → ${targetAlias}: ${task.slice(0, 60)}${priority === "high" ? " [HIGH]" : ""}${canonical.renamed ? ` [renamed from ${alias}]` : ""}`);
       const id = uuidv4();
       // 事务：inbox + tasks 双写 + 触碰目标 session 的 task/updated_at（让
@@ -680,6 +702,10 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
         db.run(touchSql, touchParams);
       });
       logTaskEvent(id, null, "delivered", from_session, parentTaskId ? `→ ${targetAlias} (parent=${parentTaskId.slice(0,8)})` : `→ ${targetAlias}`);
+      // Only stamp the dedup index after the inbox/tasks transaction
+      // succeeds, so a failed insert never silently shadows a legitimate
+      // retry.
+      sharedSendDedup.record(from_session, targetAlias, task);
 
       const session = scopedSessionStatus(targetAlias, effectiveNetId);