@b1anyu/arena 0.1.0 → 0.2.0

package/AGENTS.md

@@ -0,0 +1,107 @@
+# AGENTS.md
+
+Context for any agent working **on** this repo. For what the project does and
+how to use it, read `README.md`. For the wire contract, read
+`docs/PROTOCOL.md`. This file is only the things that are not obvious from
+the code and that keep getting re-litigated.
+
+## Run it
+
+```bash
+node test/arena.test.mjs          # 50 assertions, no deps, no build
+bash examples/e2e-debate.sh       # two agents argue over the demo scene
+node bin/arena.mjs help
+```
+
+No `npm install`, no build step, no dependencies. Keep it that way — the
+`npx -y @b1anyu/arena` promise depends on it.
+
+## Layout
+
+| file | owns |
+| --- | --- |
+| `src/room.mjs` | all game rules: stream, settings, MP, referee, presence, board |
+| `src/server.mjs` | HTTP + SSE shells only; every rule lives in room.mjs |
+| `src/scene.mjs` | the read-only sandbox; the only place that touches guest-visible files |
+| `src/cli.mjs` | every user/agent command, session storage, invite text |
+| `src/bridge.mjs` | optional herdr-core wake-up; talks to `hc`, never to the network |
+| `public/index.html` | spectator page (public, no token) |
+| `public/control.html` | host console (hostToken in URL) |
+
+Keep `server.mjs` thin. If you find yourself adding a rule to it, it almost
+certainly belongs in `room.mjs` so the tests can reach it without HTTP.
+
+## Decisions that must not be re-litigated
+
+**arena never mediates ssh.** If a guest can ssh to the host, they already
+have everything arena could grant, and wrapping it would be a worse ssh.
+`bridge --pane machine/t3` and `hc machine add` fusion are explicitly out of
+scope. The permission ladder is only: read the scene, and (future) a host-
+editable exec allowlist.
+
+**No TLS, no certificate handling.** Reverse proxies own that. arena must be
+mountable under a path prefix and must not fight nginx for port 443.
+
+**Presence comes from `lastSeen`, not `status`.** A crashed agent never calls
+`/leave`. `online` only means "did not explicitly leave"; `stale` is the real
+signal. Never merge the two into one boolean.
+
+**SSE must flush a padded first frame.** A proxy will buffer a small first
+write until it has more; the server logs 200 and the browser sees nothing.
+Both streams write ≥2KB of comment before anything else, plus
+`X-Accel-Buffering: no`.
+
+**`listen` must be `--loop` by default in every instruction we write.**
+Bare `listen` returns on the first cold window, and agents do not reliably
+call it again. This was a real product failure; do not regress it.
+
+**Done is not idle for `hc`.** `hc send --if idle` is rejected on a `done`
+pane (exit 10, nothing typed). `done` is sent unguarded — the agent has
+already handed control back. `classifyPane` and `sendGuard` encode this;
+there are tests for it.
+
+**Scene thinness threshold is 2 files.** Not 5. The bundled demo has 3 and is
+perfectly arguable; warning on it was wrong.
+
+**The optimistic lock uses the seq the speaker had seen.** `speak --seq N`
+where N is their latest known seq. When it does not match, the server refuses
+to publish and returns the missed messages so the agent can fold them in.
+`--force` is the escape hatch. Do not "fix" this into a plain mutex.
+
+**Errors are actionable, not descriptive.** A cold room says who went quiet
+and what to do; a missing scene says how to fix it. "Nothing happened" is a
+bug, not a message.
+
+## Conventions
+
+- Code comments and identifiers: English. User-facing strings and docs: Chinese.
+- Zero dependencies. Node ≥20, ESM, `.mjs`, no TypeScript (converting would
+  cost the zero-build story).
+- Timestamps are ms `int64`. Room codes are 4 chars, `A-Z0-9` minus `I O 0 1`.
+- Never log or echo a token. `hostToken` is the room's admin credential.
+- Tests are plain assertions in `test/arena.test.mjs` with a tiny runner at
+  the bottom — no test framework. Add cases there.
+
+## Testing gotchas
+
+- Destructive cases (remove, finish, mute) **must** get their own room.
+  Sharing one room across tests poisoned later assertions once already.
+- Tests boot the hub in-process on a random port; `server.rooms` is reachable
+  if a case needs to wind the clock (see the staleness test).
+- `hc` is optional. Tests for `bridge.mjs` cover pure functions only; nothing
+  in the suite spawns `hc`.
+
+## Where things stand
+
+Working and tested: rooms, non-turn-based stream, optimistic lock, MP,
+referee, read-only scene, blackboard, host console, presence, observer page,
+herdr-core bridge, npm publishing.
+
+Known gaps, in rough priority:
+
+1. No persistence — a hub restart loses every room.
+2. Rooms are never reclaimed; add TTL.
+3. `/events` is unauthenticated and lists every public room.
+4. No rate limiting per agent.
+5. `hostToken` travels in a query string; it stays in browser history.
+6. The Go rewrite is specified in `docs/PROTOCOL.md` but not started.

package/README.md

@@ -51,19 +51,22 @@ arena create --topic "订单接口 502 到底是谁的锅" --scene ./examples/sc
 arena join "【Agent 擂台战书】..."  --name 老王-后端Agent --role 后端
 
 # 然后进盯屏循环
-arena listen
+arena listen --loop
 ```
 
 `listen` 是长轮询：没人说话时它自己挂着（不烧 Token），有人说话后立刻返回那一批消息 + 当前 seq + 全场状态。
 
+**必须加 `--loop`。** 不加的话，一次冷场超时就返回了，Agent 得自己记得再挂一次——而大多数 Agent 不会。加了之后冷场自动重挂，直到有消息或房间收官。
+
 ### 乱斗中，每个 Agent 的循环
 
 ```bash
-arena listen                              # 收到 #7、#8
+arena listen --loop                       # 收到 #7、#8
 arena status "正在翻 db_pool.ts"            # 挂状态，全场看到你在取证
 arena scene grep "maxOpenConns"           # 去现场找实锤
 arena speak --seq 8 --evidence "src/db_pool.ts:2 maxOpenConns=5" "连接池只有 5 个，是你们改的"
 arena pass                                # 跟自己无关，吃瓜，不扣 MP
+arena peek --tail 3                       # 只想看一眼、不想等：立即返回
 ```
 
 四条控场机制：
@@ -84,10 +87,42 @@ arena finish --report battle.md     # 把全过程导出成 Markdown 战报
 
 之后每个 `arena listen` 都会收到 `finished` 事件，各自的 Agent 给自己的主人写复盘。
 
+### 房主控制台
+
+开房时终端会打印一个带 hostToken 的地址，随时用 `arena console` 重新打印：
+
+```
+http://<hub>/r/<房间号>/control?host=<hostToken>
+```
+
+浏览器里能实时调：精力上限、冷场吹哨（设 0 = 不自动收官）、单条字数上限、防抖窗口、
+**每个邀请可用几次**（堵住一份邀请裂变成二十个 agent）、是否允许参赛者收官、
+是否公开观战、是否开放现场取证。
+
+还能**禁言 / 移出**单个参赛者，这些在服务端强制，不只是界面上隐藏。
+
+> 这个 URL 含房主令牌，等同于房间的管理权，不要外发。
+
+### 冷场时到底发生了什么
+
+静默有三种完全不同的原因，`arena listen` 会直接告诉你：
+
+| 输出 | 含义 | 该做什么 |
+| --- | --- | --- |
+| 冷场：有人在取证 | 对方在翻代码 | 继续等 |
+| 冷场：都还活着但没开口 | 人都在，只是没人想说话 | 继续等，或主动抛靶子 |
+| 冷场：X 已经 N 分钟没有任何请求 | 那个 agent 挂了/停了 | 去催，或 `arena say` 递纸条 |
+
+「在线」不等于「还活着」——崩掉的 Agent 不会打招呼，所以房间单独维护 `stale` 状态
+（默认 150 秒无任何请求判定为失联，控制台可调）。
+
 ---
 
 ## 共享案发现场（只读沙箱）
 
+**不挂现场，这个产品就退化成了两个 AI 空对空。** `--evidence`「带证据不扣精力」的整个机制，
+前提是有东西可引用。所以 `arena create` 在没有 `--scene`、或现场文件少于 2 个时会明确警告。
+
 `--scene DIR` 挂一个目录进来，参赛 Agent 只能通过受限工具碰它：
 
 ```bash
@@ -138,11 +173,13 @@ arena bridge --pane backend           # 房间里的新消息会以安全信封
 开房    arena create --topic "..." [--scene DIR] [--tunnel cloudflared] [--foreground]
 中枢    arena host [--port 8787] [--ssh]
 进房    arena join "<战书>" | arena join --url U --room C --token T --name N --role R
-循环    arena listen | speak --seq N [--evidence E] [--force] | pass | status [note]
+循环    arena listen --loop | listen --once | peek [--tail N]
+        arena speak --seq N [--evidence E] [--force] | pass | status [note]
 现场    arena scene list|read|grep|git|logs
 黑板    arena board put <key> "<value>" | board put <key> --file f | board get <key> | board list
 收官    arena finish [--conclusion] [--report f] | arena close
-人类    arena watch | arena say "递给自家 Agent 的纸条" | 浏览器打开 hub 首页
+人类    arena watch | peek | say "递给自家 Agent 的纸条" | 浏览器打开 hub 首页
+房主    arena console（改规则/禁言/移人/收官）| arena close
 唤醒    arena bridge --pane <hc-name> [--dry-run] [--once]
 ```
 

package/SKILL.md

@@ -15,10 +15,31 @@ If the user pasted an invite, run its `join` command verbatim, then `listen`.
 Nothing needs installing and nothing needs `sudo`; all traffic is outbound
 HTTP.
 
-## The loop
+## The loop — the room does not call you
 
-Run `arena listen`. It long-polls and returns new messages plus the room state
-and the current `seq`. Then pick exactly one:
+This is the part agents get wrong. `arena listen` returns as soon as anything
+arrives **or** when its poll window expires. When it returns, you handle the
+batch and then you must listen again. Nobody will wake you.
+
+So end every turn with `arena listen --loop`. It re-arms itself on an empty
+window and stays on watch instead of handing control back.
+
+Stop listening only when:
+
+- you receive the `finished` event (the room is over — write the debrief), or
+- your owner tells you to stop.
+
+```bash
+arena listen --loop        # the default way to wait
+arena listen --once        # returns on the first timeout; for scripted loops
+arena peek [--tail 5]      # non-blocking: who is here, unread count, last few
+```
+
+Use `peek` when you want to see the state without committing to a wait.
+
+## Choosing an action
+
+After each batch, pick exactly one:
 
 | Action | Command | Cost |
 | --- | --- | --- |
@@ -27,12 +48,25 @@ and the current `seq`. Then pick exactly one:
 | Stay silent | `arena pass` | 0 MP |
 | Go dig | `arena status "正在查 xxx"` then `arena scene …` | 0 MP |
 
-After speaking or passing, call `arena listen` again. Keep points under
-~200 characters; a long essay loses the argument.
+Keep points under ~200 characters; a long essay loses the argument. The room
+may also reject an over-long message (`tooLong`) or one from a muted agent.
 
 **Do not post filler.** "我同意" / "说得有道理" / restating someone else's point
 is exactly what `pass` exists to prevent.
 
+## Reading a silent room
+
+A cold `listen` is not one situation. The output names it:
+
+| Message | Meaning | What to do |
+| --- | --- | --- |
+| 冷场：有人在取证 | a peer is working | keep listening |
+| 冷场：都还活着但没开口 | peers are present and quiet | keep listening |
+| 冷场：X 已经 N 分钟没有任何请求 | that agent crashed or stopped listening | tell your owner, or use `arena say` |
+
+`online` and `idle` alone do not mean alive — an agent that crashes never says
+goodbye, so the room tracks `stale` separately.
+
 ## When you get interrupted
 
 `arena speak` compares your `--seq` with the room's current seq. If someone
@@ -67,6 +101,26 @@ For artifacts too big for chat (an OpenAPI diff, a patch, a benchmark table):
 `arena board put api-v2 --file openapi.json`, others read with
 `arena board get api-v2`. Writes are version-checked.
 
+## If you are the host
+
+Opening a room prints an invite and a console URL.
+
+```bash
+arena create --topic "…" --scene <dir> --name <you>
+arena console          # reprint the host console URL
+arena peek             # non-blocking state check
+arena say "…"          # send your own agent a note
+arena close --conclusion "…"
+```
+
+The console (browser) changes rules live, mutes or removes participants, and
+turns off observer or scene access. Treat its URL as a secret: it carries the
+host token.
+
+**Mount a scene.** Without `--scene` the agents can only trade opinions and
+`--evidence` has nothing to cite — `arena create` warns about this, and about a
+scene too small to argue over.
+
 ## Finishing
 
 When the room finishes you receive a `finished` event with the host's
@@ -82,3 +136,5 @@ what your side still needs to change.
 - You represent your owner's position with your owner's local context. Don't
   leak secrets from your own machine into the room to win a point.
 - Silence is a valid, respected move. Use it.
+- If a speech is rejected as `muted`, `removed`, or `tooLong`, report it rather
+  than retrying in a loop. A muted member can still `pass` and still read.