@b1anyu/arena 0.1.0 → 0.2.0

package/src/room.mjs

@@ -10,6 +10,51 @@ export const DEBOUNCE_MS = 1500;
 export const IDLE_END_MS = 10000;
 export const INTERRUPTED_KEEP_MS = 4000;
 
+/**
+ * Room settings the host can change from the control page while the debate is
+ * running. Everything that used to be a hardcoded constant lives here so a
+ * rule change does not need a restart or a code edit.
+ */
+export const DEFAULT_SETTINGS = Object.freeze({
+  mp: DEFAULT_MP, // energy per agent
+  idleEndMs: IDLE_END_MS, // silence before the referee calls time (0 = never)
+  allowGuestFinish: false, // may a participant end the room?
+  requireEvidenceForRefund: true, // evidence refunds 1 MP only when true
+  maxMessageChars: 2000, // hard cap, protects the stream from a wall of text
+  debounceMs: DEBOUNCE_MS,
+  openObserver: true, // /state readable without a token (the spectator page)
+  tokenJoinLimit: 0, // joins allowed per invite token; 0 = unlimited
+  // How long without any request before a member is reported stale. An agent
+  // that crashes or closes its terminal never calls /leave, so silence is the
+  // only signal. Guests default to two listen windows (~2 min).
+  staleAfterMs: 150_000,
+  sceneEnabled: true, // guests may read the scene at all
+  sceneAllow: null, // optional list of path prefixes inside the scene
+  sceneDeny: [], // path prefixes to hide even if allowed
+});
+
+export function coerceSettings(input, base = DEFAULT_SETTINGS) {
+  const out = { ...base };
+  if (!input || typeof input !== 'object') return out;
+  const num = (v, lo, hi) => (Number.isFinite(Number(v)) ? Math.max(lo, Math.min(hi, Number(v))) : undefined);
+  const set = (k, v) => {
+    if (v !== undefined) out[k] = v;
+  };
+  set('mp', num(input.mp, 1, 99));
+  set('idleEndMs', num(input.idleEndMs, 0, 3_600_000));
+  set('maxMessageChars', num(input.maxMessageChars, 50, 20_000));
+  set('debounceMs', num(input.debounceMs, 0, 10_000));
+  set('tokenJoinLimit', num(input.tokenJoinLimit, 0, 1000));
+  set('staleAfterMs', num(input.staleAfterMs, 10_000, 3_600_000));
+  for (const k of ['allowGuestFinish', 'requireEvidenceForRefund', 'openObserver', 'sceneEnabled']) {
+    if (typeof input[k] === 'boolean') out[k] = input[k];
+  }
+  if (Array.isArray(input.sceneAllow)) out.sceneAllow = input.sceneAllow.map(String).slice(0, 50);
+  else if (input.sceneAllow === null) out.sceneAllow = null;
+  if (Array.isArray(input.sceneDeny)) out.sceneDeny = input.sceneDeny.map(String).slice(0, 50);
+  return out;
+}
+
 const now = () => Date.now();
 const rand = (n) => Math.floor(Math.random() * n);
 
@@ -34,13 +79,12 @@ export function agentId(name) {
  * sees the whole exchange instead of four half-sentencess.
  */
 export class Room {
-  constructor({ code, topic, scene = null, mp = DEFAULT_MP, idleEndMs = IDLE_END_MS }) {
+  constructor({ code, topic, scene = null, settings = {} }) {
     this.code = code;
     this.topic = topic;
     this.scene = scene;
     this.hostAgentId = null;
-    this.mp = mp;
-    this.idleEndMs = idleEndMs;
+    this.settings = coerceSettings(settings);
     this.createdAt = now();
     this.closedAt = null;
     this.onEvent = null;
@@ -53,6 +97,46 @@ export class Room {
     this.batch = null; // {fromSeq, toSeq, timer}
     this.conclusion = null;
     this._waiters = new Set();
+    this.jobs = new Map(); // agentId -> {disabled, note} host-controlled
+    this.joinCounts = new Map(); // invite token -> joins so far
+  }
+
+  /** Host-side control. Returns what changed, for the audit trail. */
+  updateSettings(patch) {
+    const before = { ...this.settings };
+    this.settings = coerceSettings(patch, this.settings);
+    // MP ceiling shrank: clamp everyone rather than leaving them above cap.
+    for (const m of this.members.values()) {
+      if (!m.isHost) m.mp = Math.min(m.mp, this.settings.mp);
+    }
+    const changed = Object.keys(this.settings).filter((k) => JSON.stringify(before[k]) !== JSON.stringify(this.settings[k]));
+    if (changed.length) {
+      this._event('settings', `房主调整规则：${changed.join(', ')}`);
+      this._maybeFinishIdle();
+    }
+    return { changed, settings: this.settings };
+  }
+
+  setMemberControl(id, { disabled, note }) {
+    const m = this.members.get(id);
+    if (!m) return { ok: false, error: `unknown agent ${id}` };
+    if (m.isHost) return { ok: false, error: 'cannot control the host' };
+    const job = this.jobs.get(id) || {};
+    if (typeof disabled === 'boolean') job.disabled = disabled;
+    if (typeof note === 'string') job.note = note.slice(0, 280);
+    this.jobs.set(id, job);
+    this._event('control', `${m.name}：${disabled === true ? '已禁言' : disabled === false ? '解除禁言' : ''}${note ? ' ' + job.note : ''}`.trim());
+    return { ok: true, member: { ...m, disabled: Boolean(job.disabled) } };
+  }
+
+  removeMember(id) {
+    const m = this.members.get(id);
+    if (!m) return { ok: false, error: `unknown agent ${id}` };
+    if (m.isHost) return { ok: false, error: 'cannot remove the host' };
+    m.status = 'offline';
+    m.removed = true;
+    this._event('leave', `${m.name} 被房主移出`);
+    return { ok: true };
   }
 
   _add({ name, role, owner, isHost = false, mp }) {
@@ -63,7 +147,9 @@ export class Room {
       role: role || 'guest',
       owner: owner || 'anon',
       isHost,
-      mp: mp ?? this.mp,
+      // A participant who joins after the host raised MP starts full, not
+      // stuck at the old ceiling.
+      mp: mp ?? this.settings.mp,
       status: 'idle', // idle | working | waiting | offline
       note: null,
       joinedAt: now(),
@@ -83,11 +169,29 @@ export class Room {
     return e;
   }
 
-  join({ name, role, owner, mp, isHost = false }) {
+  join({ name, role, owner, mp, isHost = false, token }) {
+    // Host-side join budget: one leaked invite promptly becoming twenty agents
+    // is what let a single person drown a room.
+    const limit = this.settings.tokenJoinLimit;
+    if (limit > 0 && token) {
+      const used = this.joinCounts.get(token) || 0;
+      if (used >= limit) return { refused: 'join_limit', limit };
+      this.joinCounts.set(token, used + 1);
+    }
     // Re-entry with the same name is allowed; ids are unique per join.
     return this._add({ name, role, owner, isHost, mp });
   }
 
+  /** Whether a member may act at all (removed / muted). */
+  canAct(id) {
+    const m = this.members.get(id);
+    if (!m) return { ok: false, error: `unknown agent ${id}` };
+    if (m.removed) return { ok: false, removed: true, hint: '你已被房主移出房间。' };
+    const job = this.jobs.get(id);
+    if (job?.disabled) return { ok: false, muted: true, hint: '你已被房主禁言。' };
+    return { ok: true };
+  }
+
   leave(id) {
     const m = this.members.get(id);
     if (!m) return false;
@@ -138,6 +242,7 @@ export class Room {
    */
   speak({ from, text, basedOnSeq, force = false, evidence = null, kind = 'text' }) {
     const m = this.members.get(from);
+    const job = this.jobs.get(from) || {};
     if (!m) return { ok: false, error: `unknown agent ${from}` };
     if (this.closedAt) return { ok: false, error: 'room is closed' };
     const body = String(text || '').trim();
@@ -155,6 +260,14 @@ export class Room {
       };
     }
 
+    const cap = this.settings.maxMessageChars;
+    if (body.length > cap) {
+      return { ok: false, tooLong: true, limit: cap, hint: `消息 ${body.length} 字，超过上限 ${cap}。精简后重发。` };
+    }
+    if (job.disabled) {
+      return { ok: false, muted: true, hint: '你已被房主禁言。可以继续 pass 或取证，不能发言。' };
+    }
+
     // Energy: plain opinion costs 1 MP; evidence counters do not.
     const hasEvidence = Boolean(evidence && String(evidence).trim());
     if (!hasEvidence) {
@@ -166,8 +279,8 @@ export class Room {
         };
       }
       m.mp -= 1;
-    } else {
-      m.mp = Math.min(this.mp, m.mp + 1); // evidence refunds at most 1
+    } else if (this.settings.requireEvidenceForRefund) {
+      m.mp = Math.min(this.settings.mp, m.mp + 1); // evidence refunds at most 1
     }
 
     this.seq += 1;
@@ -269,16 +382,16 @@ export class Room {
 
   _scheduleBatch(msg) {
     if (!this.batch) {
-      this.batch = { fromSeq: msg.seq, toSeq: msg.seq, endsAt: now() + DEBOUNCE_MS };
+      this.batch = { fromSeq: msg.seq, toSeq: msg.seq, endsAt: now() + this.settings.debounceMs };
       setTimeout(() => {
         const b = this.batch;
         this.batch = null;
         for (const w of this._waiters) w.check();
         if (b) this._maybeFinishIdle();
-      }, DEBOUNCE_MS);
+      }, this.settings.debounceMs);
     } else {
       this.batch.toSeq = msg.seq;
-      this.batch.endsAt = now() + DEBOUNCE_MS;
+      this.batch.endsAt = now() + this.settings.debounceMs;
     }
     this._maybeFinishIdle();
   }
@@ -290,11 +403,13 @@ export class Room {
   _maybeFinishIdle() {
     if (this.closedAt) return;
     clearTimeout(this._idleTimer);
+    // 0 disables the referee entirely: the host decides when it ends.
+    if (this.settings.idleEndMs === 0) return;
     if (this.messages.length === 0) return;
     const busy = [...this.members.values()].some((m) => m.status === 'working');
     if (busy) return;
     const sinceLast = now() - (this.messages[this.messages.length - 1]?.ts || 0);
-    const wait = Math.max(0, this.idleEndMs - sinceLast);
+    const wait = Math.max(0, this.settings.idleEndMs - sinceLast);
     this._idleTimer = setTimeout(() => {
       if (this.closedAt) return;
       const stillBusy = [...this.members.values()].some((m) => m.status === 'working');
@@ -313,13 +428,26 @@ export class Room {
     return this.conclusion;
   }
 
+  /**
+   * An agent that crashed never calls /leave, so `status` cannot be trusted
+   * on its own. Anything not heard from for this long is reported as stale
+   * separately from online/offline: "idle" and "silently dead" look identical
+   * otherwise, and the CLI tells users to do different things about them.
+   */
+  isStale(m, now_ms = now()) {
+    if (m.removed || m.status === 'offline') return false;
+    return now_ms - m.lastSeen > this.settings.staleAfterMs;
+  }
+
   state() {
+    const t = now();
     return {
       code: this.code,
       topic: this.topic,
       scene: this.scene,
       seq: this.seq,
       closed: Boolean(this.closedAt),
+      settings: this.settings,
       members: [...this.members.values()].map((m) => ({
         id: m.id,
         name: m.name,
@@ -328,8 +456,12 @@ export class Room {
         isHost: m.isHost,
         mp: m.mp,
         status: m.status,
-        note: m.note,
+        note: this.jobs.get(m.id)?.note || m.note,
         online: m.status !== 'offline',
+        stale: this.isStale(m, t),
+        lastSeenAgoMs: m.status === 'offline' ? null : t - m.lastSeen,
+        removed: Boolean(m.removed),
+        muted: Boolean(this.jobs.get(m.id)?.disabled),
       })),
     };
   }

package/src/scene.mjs

@@ -44,6 +44,27 @@ export class Scene {
     return Boolean(this.root);
   }
 
+  /**
+   * Host-controlled exposure, applied before the path sandbox. `sceneAllow`
+   * is an opt-in list of path prefixes; `sceneDeny` always wins.
+   */
+  checkPolicy(settings, p) {
+    if (!settings) return { ok: true };
+    const rel = String(p || '.').replace(/^\.\//, '').replace(/^\/+/, '');
+    const deny = settings.sceneDeny || [];
+    const hitDeny = deny.find((d) => d && (rel === d.replace(/\/$/, '') || rel.startsWith(`${d.replace(/\/$/, '')}/`)));
+    if (hitDeny) return { ok: false, error: `房主隐藏了这个位置：${hitDeny}` };
+    const allow = settings.sceneAllow;
+    if (Array.isArray(allow) && allow.length) {
+      const inAllow = rel === '.' || allow.some((a) => {
+        const pre = String(a).replace(/^\.\//, '').replace(/\/$/, '');
+        return !pre || rel === pre || rel.startsWith(`${pre}/`);
+      });
+      if (!inAllow) return { ok: false, error: `房主只开放了这些位置：${allow.join(', ')}` };
+    }
+    return { ok: true };
+  }
+
   /** Resolve a caller-supplied path and refuse anything outside the root. */
   async resolve(p, { allowRoot = true } = {}) {
     if (!this.enabled) throw new Error('this room has no scene');

package/src/server.mjs

@@ -18,6 +18,21 @@ const json = (res, code, body, extra = {}) => {
   res.end(data);
 };
 
+/**
+ * Headers that keep an SSE response un-buffered through a reverse proxy.
+ * `X-Accel-Buffering` is honoured by nginx; `no-transform` stops intermediaries
+ * from re-encoding the stream; `Connection: keep-alive` keeps the socket open.
+ */
+function sseHeaders(res) {
+  res.writeHead(200, {
+    'content-type': 'text/event-stream; charset=utf-8',
+    'cache-control': 'no-cache, no-transform',
+    connection: 'keep-alive',
+    'x-accel-buffering': 'no',
+    'access-control-allow-origin': '*',
+  });
+}
+
 async function body(req, limit = 1_000_000) {
   return new Promise((resolve, reject) => {
     let n = 0;
@@ -70,15 +85,14 @@ export function createServer({ pageHtml = null } = {}) {
     }
   };
 
-  const createRoom = ({ topic, scene, name, mp, idleEndMs }) => {
+  const createRoom = ({ topic, scene, name, mp, idleEndMs, settings: s }) => {
     let code;
     do code = roomCode(); while (rooms.has(code));
     const room = new Room({
       code,
       topic: topic || '（未命名议题）',
       scene: scene ? { root: scene } : null,
-      mp,
-      idleEndMs,
+      settings: { mp, idleEndMs, ...(s || {}) },
     });
     room.sceneObj = new Scene(scene);
     room.token = crypto.randomBytes(18).toString('base64url');
@@ -116,19 +130,19 @@ export function createServer({ pageHtml = null } = {}) {
       if (p === '/health') return json(res, 200, { ok: true, rooms: rooms.size, version: '0.1.0' });
 
       if (p === '/' && req.method === 'GET') {
-        if (!pageHtml) return json(res, 200, { ok: true, hint: 'GET /r/<CODE>/state' });
+        const page = pageHtml?.index || (typeof pageHtml === 'string' ? pageHtml : null);
+        if (!page) return json(res, 200, { ok: true, hint: 'GET /r/<CODE>/state' });
         res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
-        return res.end(pageHtml);
+        return res.end(page);
       }
 
       // Observer SSE (no token: read-only public view of a room)
       if (p === '/events' && req.method === 'GET') {
-        res.writeHead(200, {
-          'content-type': 'text/event-stream',
-          'cache-control': 'no-cache',
-          connection: 'keep-alive',
-          'access-control-allow-origin': '*',
-        });
+        sseHeaders(res);
+        // A proxy will happily buffer a small first frame until it has more
+        // (cloudflared did exactly this). A padded comment forces the first
+        // flush out immediately, before the hello event matters.
+        res.write(`: ${' '.repeat(2048)}\n\n`);
         const send = (s) => res.write(`data: ${s}\n\n`);
         observers.add(send);
         res.write(`data: ${JSON.stringify({ hello: true, rooms: [...rooms.keys()] })}\n\n`);
@@ -140,9 +154,12 @@ export function createServer({ pageHtml = null } = {}) {
         return;
       }
 
-      // List rooms (observer)
+      // List rooms (observer). Only the room's shape, not the spectator
+      // controls — /rooms must not leak a closed room's contents.
       if (p === '/rooms' && req.method === 'GET') {
-        return json(res, 200, [...rooms.values()].map((r) => ({ ...r.state(), createdAt: r.createdAt })));
+        return json(res, 200, [...rooms.values()]
+          .filter((r) => r.settings.openObserver)
+          .map((r) => ({ ...r.state(), createdAt: r.createdAt })));
       }
 
       // Open a room. Any client that can reach the hub may do this; that is
@@ -167,8 +184,21 @@ export function createServer({ pageHtml = null } = {}) {
       const sub = m[2] || '/';
       const tok = url.searchParams.get('token') || req.headers['x-arena-token'];
 
-      // Public read-only views
+      // Host console. The page itself is static; every action it takes is
+      // host-token-gated on the server, so serving it here leaks nothing.
+      // The token arrives in the fragment-friendly `?host=` query string.
+      if (sub === '/control' && req.method === 'GET') {
+        const page = pageHtml?.control || null;
+        if (!page) return json(res, 404, { error: 'control page missing' });
+        res.writeHead(200, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' });
+        return res.end(page);
+      }
+
+      // Public read-only views, unless the host closed them.
       if (sub === '/state' || sub === '/') {
+        if (!room.settings.openObserver && !auth(room, req, url)) {
+          return json(res, 401, { error: '这个房间的实况仅对参与者开放' });
+        }
         const b = await (req.method === 'POST' ? body(req) : {});
         return json(res, 200, {
           ...room.state(),
@@ -187,7 +217,13 @@ export function createServer({ pageHtml = null } = {}) {
           owner: b.owner || b.ownerName || 'anon',
           isHost: Boolean(b.isHost) && !room.hostAgentId,
           mp: Number.isFinite(b.mp) ? b.mp : undefined,
+          token: tok,
         });
+        if (member.refused === 'join_limit') {
+          return json(res, 403, {
+            error: `这个邀请最多允许 ${member.limit} 个 Agent 进场，已满。找房主要新邀请。`,
+          });
+        }
         return json(res, 200, {
           agentId: member.id,
           you: member,
@@ -212,9 +248,15 @@ export function createServer({ pageHtml = null } = {}) {
         return json(res, 200, { ...out, state: room.state(), board: room.list().map((x) => ({ key: x.key, version: x.version, from: x.from })) });
       }
 
-      if (req.method === 'POST' && ['/speak', '/pass', '/status', '/idle', '/leave', '/board', '/scene', '/finish'].includes(sub)) {
+      if (req.method === 'POST' && ['/speak', '/pass', '/status', '/idle', '/leave', '/board', '/scene', '/finish', '/control', '/member'].includes(sub)) {
         if (!authed) return json(res, 401, { error: 'bad or missing token' });
         const b = await body(req);
+        // Removal and muting are enforced here, not just hidden in the UI.
+        // Host control routes are keyed by the target id, not the caller.
+        if (!['/leave', '/control', '/member'].includes(sub)) {
+          const gate = room.canAct(b.agent);
+          if (!gate.ok && sub !== '/pass') return json(res, 403, gate);
+        }
         switch (sub) {
           case '/speak': {
             const out = room.speak({
@@ -252,6 +294,11 @@ export function createServer({ pageHtml = null } = {}) {
           case '/scene': {
             const sc = room.sceneObj;
             if (!sc || !sc.enabled) return json(res, 400, { error: 'this room has no scene' });
+            if (!room.settings.sceneEnabled && !isHost(room, req, url)) {
+              return json(res, 403, { error: '房主关闭了现场取证' });
+            }
+            const gate = sc.checkPolicy(room.settings, b.path || '.');
+            if (!gate.ok) return json(res, 403, gate);
             const agentName = room.members.get(b.agent)?.name || 'agent';
             const op = b.op || 'list';
             let out;
@@ -264,9 +311,30 @@ export function createServer({ pageHtml = null } = {}) {
             room._event('scene', `${agentName} 正在现场取证：${op}`, { from: b.agent });
             return json(res, 200, out);
           }
+          case '/control': {
+            if (!isHost(room, req, url)) return json(res, 403, { error: '只有房主能改规则' });
+            const out = room.updateSettings(b.settings || {});
+            room.notify({ type: 'settings', settings: room.settings, changed: out.changed });
+            return json(res, 200, { ok: true, ...out });
+          }
+          case '/member': {
+            if (!isHost(room, req, url)) return json(res, 403, { error: '只有房主能管理选手' });
+            if (b.op === 'remove') {
+              const out = room.removeMember(b.id);
+              if (out.ok) room.notify({ type: 'members' });
+              return json(res, out.ok ? 200 : 400, out);
+            }
+            const out = room.setMemberControl(b.id, { disabled: b.disabled, note: b.note });
+            if (out.ok) room.notify({ type: 'members' });
+            return json(res, out.ok ? 200 : 400, out);
+          }
           case '/finish': {
-            if (!isHost(room, req, url) && !b.force) {
-              return json(res, 403, { error: 'only the host can call time (or pass force:true)' });
+            const host = isHost(room, req, url);
+            if (!host && !b.force && !room.settings.allowGuestFinish) {
+              return json(res, 403, { error: '只有房主能吹哨（当前设置不允许参赛者收官）' });
+            }
+            if (!host && !room.settings.allowGuestFinish && b.force) {
+              return json(res, 403, { error: '房主已关闭参赛者收官，force 不再有效' });
             }
             room.finish(b.reason || 'host called time', b.conclusion || null);
             room.notify({ type: 'finish', reason: b.reason });
@@ -283,11 +351,10 @@ export function createServer({ pageHtml = null } = {}) {
           res.end();
         };
         const send = (s) => res.write(`data: ${s}\n\n`);
-        res.writeHead(200, {
-          'content-type': 'text/event-stream',
-          'cache-control': 'no-cache',
-          connection: 'keep-alive',
-        });
+        sseHeaders(res);
+        // Same first-flush trick as /events: the bridge can sit silent for
+        // minutes and must not be held hostage by a proxy's buffer.
+        res.write(`: ${' '.repeat(2048)}\n\n`);
         for (const msg of room.messages.filter((x) => x.seq > since)) res.write(`data: ${JSON.stringify({ type: 'message', message: msg })}\n\n`);
         if (!roomStreams.has(room.code)) roomStreams.set(room.code, new Set());
         roomStreams.get(room.code).add(send);