hivecode-mcp 0.11.0 → 0.11.2

package/limits.js

@@ -0,0 +1,346 @@
+// USAGE LIMITS — what stops one misbehaving client from degrading a room for everyone
+// who paid for it.
+//
+// Before this, the only bound anywhere in the relay was `MAX_NAME = 48`. A single agent in a
+// loop could push unbounded messages, grow a document without limit, or open connections
+// until the process died — and the blast radius is not that client, it is every other room
+// on the same relay. That is the difference between "works on my machine" and something you
+// can charge for.
+//
+// Four limits, each chosen because an agent can actually hit it by accident:
+//
+//   MESSAGES   an agent stuck in a write loop. Token bucket, so normal bursty sync (a big
+//              paste, a first-join catch-up) passes and a sustained flood does not.
+//   BYTES      the same loop with big payloads. Rate-limiting messages alone lets 10 msg/s
+//              of 5 MB through, which is the same outage with fewer packets.
+//   DOC SIZE   a file (or a room) that grows without bound. A CRDT never shrinks: every
+//              insert is retained history, so "it will be garbage collected" is not true
+//              here. Past the cap we refuse WRITES and keep serving reads, because dropping
+//              the client would take their unsaved work with it.
+//   CONNS      connection floods, per room and per relay. Separate from the committer/seat
+//              limit: seats are about entitlement, this is about survival.
+//
+// EVERY limit is a REFUSAL WITH A REASON, never a silent drop. An agent that is told
+// `Q4xx over the message rate` can back off; one whose writes vanish will retry forever and
+// look like a broken product. Nothing here throttles reads.
+//
+// Defaults are deliberately generous — roughly 100x what the run2 four-agent session used at
+// peak — so a real team never meets them and a runaway loop meets them in about a second.
+// All of them are env-tunable so a self-hoster can raise them without a code change.
+//
+// ASCII only. Q-codes on refusals.
+
+const num = (name, dflt) => {
+  const v = Number(process.env[name])
+  return Number.isFinite(v) && v > 0 ? v : dflt
+}
+
+// ── TIERS ───────────────────────────────────────────────────────────────────────────────
+// The first version of this file applied ONE set of limits to everybody, which is wrong for
+// a product that charges: a free room got the same 64 MB document ceiling and the same
+// message rate as a room someone is paying $29 a seat for. That is both a giveaway and a
+// support problem -- the paying customer is the one who notices the shared ceiling.
+//
+// So limits scale with the tier the licence actually reports. `plan` comes from the licence
+// record (see license-check.js, which had been dropping it), never from the key string --
+// the whole reason the record is authoritative is that a key told the relay whatever it
+// liked in an earlier version and granted 9,999 seats.
+//
+// The multiplier is per SEAT, deliberately. A 20-seat room legitimately does 10x the traffic
+// of a 2-seat one, and a flat per-room ceiling would punish exactly the customers worth
+// keeping. Free stays generous enough that nobody hits it while evaluating -- the tier is
+// there to bound cost and abuse, not to nag someone into upgrading.
+const TIERS = {
+  free: {
+    // PLANS.free caps at 2 seats (shared/license.js), so this is sized for two agents doing
+    // real work, with headroom. A single evaluator will never see it.
+    msgsPerSec: num('HIVE_FREE_MSGS_PER_SEC', 60),
+    msgBurst: num('HIVE_FREE_MSG_BURST', 600),
+    bytesPerSec: num('HIVE_FREE_BYTES_PER_SEC', 2 * 1024 * 1024),
+    byteBurst: num('HIVE_FREE_BYTE_BURST', 8 * 1024 * 1024),
+    maxDocBytes: num('HIVE_FREE_MAX_DOC_BYTES', 8 * 1024 * 1024),
+    maxConnsPerRoom: num('HIVE_FREE_MAX_CONNS_PER_ROOM', 8),
+  },
+  pro: {
+    // Per seat. A 1-seat Pro room already gets more than the whole free tier.
+    msgsPerSecPerSeat: num('HIVE_PRO_MSGS_PER_SEC_PER_SEAT', 100),
+    msgBurstPerSeat: num('HIVE_PRO_MSG_BURST_PER_SEAT', 1000),
+    bytesPerSecPerSeat: num('HIVE_PRO_BYTES_PER_SEC_PER_SEAT', 4 * 1024 * 1024),
+    byteBurstPerSeat: num('HIVE_PRO_BYTE_BURST_PER_SEAT', 16 * 1024 * 1024),
+    maxDocBytesPerSeat: num('HIVE_PRO_MAX_DOC_BYTES_PER_SEAT', 32 * 1024 * 1024),
+    // Connections, not committers. An agent may hold several file-rooms at once, and a
+    // reader costs a socket without costing a seat.
+    connsPerSeat: num('HIVE_PRO_CONNS_PER_SEAT', 8),
+    // Ceilings so one licence cannot consume the relay no matter how many seats it buys.
+    maxDocBytesCeiling: num('HIVE_PRO_MAX_DOC_BYTES_CEILING', 512 * 1024 * 1024),
+    maxConnsCeiling: num('HIVE_PRO_MAX_CONNS_CEILING', 256),
+  },
+}
+
+/**
+ * The limits that apply to one connection, from the licence verdict.
+ *
+ * Called with the verdict verifyLicense() returned at the handshake. An invalid or absent
+ * licence is the free tier — NOT a refusal: whether an unlicensed client may connect at all
+ * is HIVE_REQUIRE_LICENSE's decision, made before this, and conflating the two would mean a
+ * relay running without licensing enforced silently applied nobody's limits.
+ */
+export function limitsFor(verdict) {
+  const plan = verdict && verdict.valid ? (verdict.plan || 'pro') : 'free'
+  if (plan !== 'pro') {
+    const f = TIERS.free
+    return {
+      tier: 'free', seats: 1,
+      msgsPerSec: f.msgsPerSec, msgBurst: f.msgBurst,
+      bytesPerSec: f.bytesPerSec, byteBurst: f.byteBurst,
+      maxFrameBytes: LIMITS.maxFrameBytes,
+      maxDocBytes: f.maxDocBytes,
+      maxConnsPerRoom: f.maxConnsPerRoom,
+      cooloffMs: LIMITS.cooloffMs,
+    }
+  }
+  const seats = Math.max(1, Number(verdict.seats) || 1)
+  const p = TIERS.pro
+  return {
+    tier: 'pro', seats,
+    msgsPerSec: p.msgsPerSecPerSeat * seats,
+    msgBurst: p.msgBurstPerSeat * seats,
+    bytesPerSec: p.bytesPerSecPerSeat * seats,
+    byteBurst: p.byteBurstPerSeat * seats,
+    maxFrameBytes: LIMITS.maxFrameBytes,
+    maxDocBytes: Math.min(p.maxDocBytesPerSeat * seats, p.maxDocBytesCeiling),
+    maxConnsPerRoom: Math.min(p.connsPerSeat * seats, p.maxConnsCeiling),
+    cooloffMs: LIMITS.cooloffMs,
+  }
+}
+
+export { TIERS }
+
+export const LIMITS = {
+  // Token bucket: sustained rate, with a burst allowance for legitimate spikes.
+  msgsPerSec: num('HIVE_MAX_MSGS_PER_SEC', 200),
+  msgBurst: num('HIVE_MAX_MSG_BURST', 2000),
+  bytesPerSec: num('HIVE_MAX_BYTES_PER_SEC', 8 * 1024 * 1024),
+  byteBurst: num('HIVE_MAX_BYTE_BURST', 32 * 1024 * 1024),
+  // A single frame. y-websocket's first sync step can be large, so this is not tight.
+  maxFrameBytes: num('HIVE_MAX_FRAME_BYTES', 16 * 1024 * 1024),
+  // Retained CRDT size for one doc. A doc is one file in this design.
+  maxDocBytes: num('HIVE_MAX_DOC_BYTES', 64 * 1024 * 1024),
+  maxConnsPerRoom: num('HIVE_MAX_CONNS_PER_ROOM', 64),
+  maxConnsTotal: num('HIVE_MAX_CONNS_TOTAL', 512),
+  // How long a client stays refused after tripping a rate limit. Long enough that a tight
+  // loop actually yields, short enough that a human does not notice a one-off burst.
+  cooloffMs: num('HIVE_RATE_COOLOFF_MS', 5000),
+}
+
+// ── token bucket ────────────────────────────────────────────────────────────────────────
+// Chosen over a fixed window because a fixed window has an edge: 2x the limit can pass
+// across a boundary, which is exactly when a sync storm happens.
+class Bucket {
+  constructor(ratePerSec, capacity) {
+    this.rate = ratePerSec
+    this.cap = capacity
+    this.tokens = capacity
+    this.last = Date.now()
+  }
+  take(n, now = Date.now()) {
+    const elapsed = (now - this.last) / 1000
+    if (elapsed > 0) {
+      this.tokens = Math.min(this.cap, this.tokens + elapsed * this.rate)
+      this.last = now
+    }
+    if (this.tokens >= n) { this.tokens -= n; return true }
+    return false
+  }
+}
+
+// ── per-relay and per-room connection counts ────────────────────────────────────────────
+let totalConns = 0
+const roomConns = new Map() // room -> count
+
+/**
+ * Called at the HTTP upgrade, BEFORE the websocket handshake completes, so a rejected
+ * connection costs one socket and no doc state. Returns null to admit, or {code, reason}.
+ */
+export function admitConnection(room, tier = null) {
+  if (totalConns >= LIMITS.maxConnsTotal) {
+    return { code: 503, reason: `Q430 relay at capacity (${LIMITS.maxConnsTotal} connections)` }
+  }
+  // The per-room ceiling is the TIER's, so a free room cannot hold as many sockets as a
+  // 20-seat Pro room. Falls back to the flat value when no tier is supplied, which is what
+  // happens on a relay running with licensing disabled.
+  const cap = (tier && tier.maxConnsPerRoom) || LIMITS.maxConnsPerRoom
+  const n = roomConns.get(room) || 0
+  if (n >= cap) {
+    const which = tier ? `${tier.tier} tier` : 'this relay'
+    return { code: 429, reason: `Q431 room at capacity (${cap} connections on ${which})` }
+  }
+  return null
+}
+
+export function noteConnectionOpened(room) {
+  totalConns++
+  roomConns.set(room, (roomConns.get(room) || 0) + 1)
+}
+
+export function noteConnectionClosed(room) {
+  totalConns = Math.max(0, totalConns - 1)
+  const n = (roomConns.get(room) || 1) - 1
+  if (n <= 0) roomConns.delete(room) // never leak a zero entry per room
+  else roomConns.set(room, n)
+}
+
+// ── document size ───────────────────────────────────────────────────────────────────────
+// Measured from the encoded update size we have already seen, accumulated per doc. Asking
+// Yjs to encode the whole state on every message would itself be the performance problem.
+const docBytes = new Map() // docName -> approximate retained bytes
+
+export function noteDocBytes(docName, n) {
+  docBytes.set(docName, (docBytes.get(docName) || 0) + n)
+}
+
+export function docOverCap(docName, tier = null) {
+  const cap = (tier && tier.maxDocBytes) || LIMITS.maxDocBytes
+  return (docBytes.get(docName) || 0) >= cap
+}
+
+export function docSize(docName) { return docBytes.get(docName) || 0 }
+
+/** Seed a doc's counter from its real encoded size, e.g. after loading a snapshot. */
+export function setDocBytes(docName, n) { docBytes.set(docName, Math.max(0, Number(n) || 0)) }
+
+export function forgetDoc(docName) { docBytes.delete(docName) }
+
+// ── per-connection rate limiting ────────────────────────────────────────────────────────
+/**
+ * Attach buckets to one connection. Returns a `check(byteLength)` the message handler calls
+ * for every inbound frame: null to allow, or {reason} to refuse.
+ *
+ * State lives on the connection object, so it is freed with the socket and there is no map
+ * to leak or sweep.
+ */
+export function attachRateLimit(conn, tier = null) {
+  const T = tier || LIMITS
+  const msgs = new Bucket(T.msgsPerSec, T.msgBurst)
+  const bytes = new Bucket(T.bytesPerSec, T.byteBurst)
+  const cooloff = T.cooloffMs || LIMITS.cooloffMs
+  const frameCap = T.maxFrameBytes || LIMITS.maxFrameBytes
+  let cooloffUntil = 0
+  let refusedCount = 0
+  // Usage, per connection. This is the raw material for the per-agent visibility below,
+  // and it is counted here because this is the only place every inbound frame passes.
+  let msgCount = 0, byteCount = 0, writeCount = 0, writeBytes = 0
+  const openedAt = Date.now()
+
+  conn._hiveLimit = {
+    tier: T.tier || 'flat',
+    seats: T.seats || null,
+    check(byteLength) {
+      const now = Date.now()
+      if (now < cooloffUntil) {
+        refusedCount++
+        return { reason: `Q432 over the message rate; backing off for ${Math.ceil((cooloffUntil - now) / 1000)}s` }
+      }
+      if (byteLength > frameCap) {
+        // Not a rate problem and no cooloff: one oversized frame is a bug in the client,
+        // and a cooloff would punish its next, valid message.
+        refusedCount++
+        return { reason: `Q433 frame of ${byteLength} bytes exceeds the ${frameCap}-byte limit` }
+      }
+      if (!msgs.take(1, now)) {
+        cooloffUntil = now + cooloff
+        refusedCount++
+        return { reason: `Q432 over the message rate (${T.msgsPerSec}/s sustained, ${T.msgBurst} burst${T.tier ? `, ${T.tier} tier` : ''})` }
+      }
+      if (!bytes.take(byteLength, now)) {
+        cooloffUntil = now + cooloff
+        refusedCount++
+        return { reason: `Q434 over the byte rate (${Math.round(T.bytesPerSec / 1024)} KB/s sustained${T.tier ? `, ${T.tier} tier` : ''})` }
+      }
+      msgCount++; byteCount += byteLength
+      return null
+    },
+    /** Called by the relay once it knows a passing frame was a write, not a read. */
+    noteWrite(byteLength) { writeCount++; writeBytes += byteLength },
+    get refused() { return refusedCount },
+    usage() {
+      return {
+        msgs: msgCount, bytes: byteCount,
+        writes: writeCount, writeBytes,
+        refused: refusedCount,
+        heldMs: Date.now() - openedAt,
+      }
+    },
+  }
+  return conn._hiveLimit
+}
+
+// ── PER-AGENT USAGE ─────────────────────────────────────────────────────────────────────
+// "Cost visibility (per-agent token spend)" is a stated buyer requirement, and it needs one
+// honest correction: THE RELAY CANNOT SEE TOKENS. An agent's LLM calls go to Anthropic or
+// OpenAI directly and never touch this process, so any token number here would be invented.
+//
+// What the relay genuinely knows is ACTIVITY, and it is the more useful half for the problem
+// people actually have: which agent is writing, how much, to which files, and who is sitting
+// on a claim. That answers "why is this room slow", "which agent is hammering routes.js" and
+// "what did each agent actually do" -- none of which a token count answers.
+//
+// Keyed by room+identity and kept in memory only. It is operational telemetry, not billing:
+// billing is seats, which the licence record already decides.
+const usage = new Map() // `${room}${identity}` -> {msgs, bytes, writes, writeBytes, refused, files:Set, sessions, lastAt}
+const UKEY = (room, who) => `${room}${who}`
+
+export function recordUsage(room, who, u, file = null) {
+  if (!room || !who || !u) return
+  const k = UKEY(room, who)
+  let e = usage.get(k)
+  if (!e) { e = { msgs: 0, bytes: 0, writes: 0, writeBytes: 0, refused: 0, files: new Set(), sessions: 0, heldMs: 0, lastAt: 0 }; usage.set(k, e) }
+  e.msgs += u.msgs || 0
+  e.bytes += u.bytes || 0
+  e.writes += u.writes || 0
+  e.writeBytes += u.writeBytes || 0
+  e.refused += u.refused || 0
+  e.heldMs += u.heldMs || 0
+  e.sessions += 1
+  if (file) e.files.add(file)
+  e.lastAt = Date.now()
+}
+
+/** Per-agent activity for one room, or every room when `room` is omitted. */
+export function usageFor(room = null) {
+  const out = []
+  for (const [k, e] of usage) {
+    const [r, who] = k.split('')
+    if (room && r !== room) continue
+    out.push({
+      room: r, agent: who,
+      msgs: e.msgs, bytes: e.bytes,
+      writes: e.writes, writeBytes: e.writeBytes,
+      refused: e.refused,
+      files: e.files.size,
+      sessions: e.sessions,
+      connectedMs: e.heldMs,
+      lastAt: e.lastAt,
+    })
+  }
+  // Busiest writer first — the question this data exists to answer.
+  return out.sort((a, b) => b.writeBytes - a.writeBytes || b.writes - a.writes)
+}
+
+export function stats() {
+  return {
+    connections: totalConns,
+    rooms: roomConns.size,
+    largestDocBytes: docBytes.size ? Math.max(...docBytes.values()) : 0,
+    docsTracked: docBytes.size,
+    limits: LIMITS,
+  }
+}
+
+/** Test-only: reset module state between cases. */
+export function _reset() {
+  totalConns = 0
+  roomConns.clear()
+  docBytes.clear()
+  usage.clear()
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hivecode-mcp",
-  "version": "0.11.0",
-  "description": "MCP server that lets any AI coding agent join a Hivecode room — humans and multiple AI agents edit one live codebase with folder-scoped permissions and approval gates.",
+  "version": "0.11.2",
+  "description": "MCP server that lets any AI coding agent join a Hivecode room \u2014 humans and multiple AI agents edit one live codebase with folder-scoped permissions and approval gates.",
   "type": "module",
   "license": "MIT",
   "homepage": "https://github.com/Ganesh-Kute/HiveCode",
@@ -27,8 +27,11 @@
   },
   "files": [
     "hive-mcp.js",
+    "hive-mailbox.js",
     "sync.js",
     "core.js",
+    "limits.js",
+    "grm-link.cjs",
     "token.js",
     "icr.js",
     "lang-js.js",
@@ -42,7 +45,7 @@
     "hive-coord.js",
     "substrate.js",
     "HIVE_RULES.md",
-    "MCP.md",
+    "docs/MCP.md",
     "README.md",
     "LICENSE"
   ],
@@ -55,11 +58,12 @@
     "relay": "node server.js",
     "sync:engine": "node sync-engine.mjs",
     "check:engine": "node sync-engine.mjs --check",
-    "pretest": "node scripts/sync-engine.mjs --check",
+    "pretest": "node scripts/sync-engine.mjs --check && node scripts/check-files.mjs",
     "test": "node tests/test.js",
+    "test:identity": "node tests/identity-audit-test.mjs",
     "test:billing": "node tests/billing-test.mjs",
     "test:license": "node tests/hive-license-test.js",
-    "test:money": "node tests/billing-test.mjs && node tests/hive-license-test.js && node tests/recover-test.mjs",
+    "test:money": "node tests/payment-e2e-test.mjs && node tests/subscribe-test.mjs && node tests/lifecycle-test.mjs && node tests/billing-test.mjs && node tests/hive-license-test.js && node tests/recover-test.mjs",
     "check:web": "tsc --noEmit",
     "build:web": "esbuild web/src/main.ts --bundle --minify --format=iife --target=es2019 --outfile=public/app.js",
     "test:substrate": "node substrate-test.js",
@@ -68,7 +72,23 @@
     "test:substrate:authority": "node substrate-authority-test.js",
     "test:substrate:all": "node substrate-test.js && node substrate-live-test.js && node substrate-enforce-test.js && node substrate-authority-test.js",
     "test:recover": "node tests/recover-test.mjs",
-    "test:mailbox": "node tests/mailbox-test.mjs && node tests/mcp-wait-test.mjs"
+    "test:mailbox": "node tests/mailbox-test.mjs && node tests/mcp-wait-test.mjs",
+    "test:limits": "node tests/limits-test.mjs",
+    "test:rejoin": "node tests/rejoin-clobber-test.mjs",
+    "test:prod": "node tests/test.js && node tests/firstrun-test.mjs && node tests/credential-split-test.mjs && node tests/limits-test.mjs && node tests/usage-meter-test.mjs && node tests/rejoin-clobber-test.mjs && node tests/durability-test.mjs && node tests/payment-e2e-test.mjs && node tests/subscribe-test.mjs && node tests/lifecycle-test.mjs && node tests/billing-test.mjs && node tests/hive-license-test.js && node tests/recover-test.mjs && node demo/wrap-test.mjs",
+    "test:meter": "node tests/usage-meter-test.mjs",
+    "test:subscribe": "node tests/subscribe-test.mjs",
+    "test:cred": "node tests/credential-split-test.mjs",
+    "test:firstrun": "node tests/firstrun-test.mjs",
+    "test:lifecycle": "node tests/lifecycle-test.mjs",
+    "test:payment": "node tests/payment-e2e-test.mjs",
+    "scorecard": "node scorecard.mjs",
+    "demo:video": "node demo/record.mjs",
+    "test:wrap": "node demo/wrap-test.mjs",
+    "demo:panel": "node demo/record-panel.mjs",
+    "demo:all": "node demo/record.mjs && node demo/record-panel.mjs",
+    "check:files": "node scripts/check-files.mjs",
+    "prepublishOnly": "node scripts/check-files.mjs"
   },
   "engines": {
     "node": ">=18"
@@ -94,4 +114,4 @@
     "test": "tests"
   },
   "author": "Ganesh Shivlal Kute <support@getgrm.tech>"
-}
+}