After a revision upgrade, a lite runner from an old checkout fails login
with an opaque "Client out of date" and its scripts only report "No game
client is attached".
- Engine: on a revision mismatch, read the username from the login block
(laid out the same across revisions) and record it for 30 minutes; a
correct-revision login clears it. The management port serves it at
/outdated-client.
- Gateway: when an SDK connects to a bot with no live client, ask the
engine and answer sdk_error with the update steps. Old SDK checkouts
print gateway errors, so this reaches people who haven't pulled yet.
- Public /api/version. The lite runner checks it before loading the
cache and fails with OutdatedClientError (a LoginError, code 6) naming
the fix; the runner and swarm exit 3 instead of retrying.
- CLAUDE.md troubleshooting entry for the message.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Following the README, `bun bots/<name>/script.ts` with no browser tab or lite
runner attached printed "Connected", ran every action against nothing, and
exited 0. runScript never launches a client (autoLaunchBrowser: false), and
the README said the SDK would.
There are two ways that happened:
- No client ever attached: the gateway has no state, connect() times out its
ready wait and then "continues anyway".
- A client attached earlier but has gone: the gateway replays the state it
cached, so the ready check passes on a snapshot minutes old.
runScript now waits up to 10s for `tick` to advance after connecting. It
compares ticks, not getStateAge(), because that mixes gateway and local
clocks; a live run measured -343ms. If no tick arrives it throws an error
that names both ways to start a client, and a failed connect now sets
exitCode 1.
The README Getting Started and CLAUDE.md now include the lite runner step,
the README no longer claims scripts launch a client, and the CLAUDE.md
troubleshooting entry no longer points at an option runScript doesn't expose.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The engine already supported MESSAGE_PRIVATE end-to-end; this adds the
send path and tooling:
- sendPrivateMessage on browser Client + LiteClient (userhash + WordPack
payload, local type-6 echo), new 'privateMessage' bot action
- sdk.sendPrivateMessage(name, msg) + sdk.dm(name, text) (chunked like say)
- gateway: observe mode whitelists privateMessage alongside say; new
POST /dm/:username endpoint - a separate path from /say on purpose, so
old gateways' non-JSON banner makes the CLI fall back to the WS path
(cleanly rejected) instead of leaking a DM as public chat
- chat CLI: bun sdk/chat.ts <bot> --to <player> "msg"
- engine: FriendServer PM handler logs private_chat best-effort instead of
letting a missing account row (local easy-startup) kill the relay
PMs deliver to any online player - no friends list needed. One social
packet (say or PM) per tick; dm() paces its chunks. Delivery requires
FRIEND_SERVER=true (prod fly.toml already sets it; local quickstart
defaults off and drops PMs silently).
Verified E2E on the local stack: both directions, 3-chunk long message,
observe-mode WS path, non-chat actions still rejected in observe mode.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- Gateway: observe-mode sessions may send 'say' (and nothing else), so
chat tools can talk through a bot without pre-empting its controller
- sdk/chat.ts: send / read / --watch chat over an observe connection
- maxMessageLength default 80 -> 400; engine WordPack caps follow the
config instead of hardcoding 80
- 240-byte packed budget in both WordPack copies + byte-aware SDK
chunking: all chat frames carry a 1-byte length and digit/punctuation
chars pack at ~1 byte each, so long non-prose text would wrap the
length byte and corrupt the stream
- chat handlers use Packet.alloc(1): the 100-byte alloc(0) tier threw
RangeError on >~200-char messages and kicked the player with no log
- say() paces multi-chunk sends with wall-clock sleep in observe mode
(a 'wait' action is rejected there and would occupy the bot executor)
- lite runner: GATEWAY_URL override (SERVER doubles as game origin and
gateway address, which broke for localhost:8888)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Two silent failure modes cost bots a 10s timeout each and were
indistinguishable from "the action ran and did nothing".
Op rejections. When the server refuses an op (stunned, mid-action, target
out of view, modal open underneath) every Op*Handler answers with
UNSET_MAP_FLAG and nothing else - no message, no error. Client.ts and the
lite client now both count those packets, StateCollector turns unsets
that arrive while the player is standing still into
state.opFeedback.opRejectedCount, and ActionHelpers exposes the
snapshot/compare pair. interactNpc and pickpocketNpc use it to bail with
reason 'rejected' instead of waiting out the timeout. opFeedback is
optional throughout - an older connected client just goes quiet, and the
helpers report "no rejection".
Pickpocket acking. "You attempt to pick..." is printed by ~pick_pocket
before its first p_delay, so it is the earliest evidence the op actually
ran - an attempt earlier than xp or a stun. Without it, a lost op looked
identical to a slow one. Attempts that neither ack nor reject within 3
idle ticks (measured from the last step, since the client walks before
writing OPNPC) now return reason 'not_started'. Also fixes "you fail to
pick" being read as a timeout rather than a stun, and checks xp before
messages so a successful pick is never misreported.
find* reachability. All four find* lookups take {reachable: true}, which
returns null rather than a target the client cannot route to - the case
where the client silently writes no packet at all. Default behaviour is
unchanged: an unreachable match still wins if it is the only one.
PATCHES.md gains entries for the lite client, the ClientStream.isClosed
getter, the LoopCycle split, and the mapFlagUnsetCount counter, which is
now duplicated in both clients and would go quiet without a loud failure
if a sync reverted it. bun run test covers src/lite too.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Agents hit SDK papercuts constantly - a method returns success:true and
nothing happened, a dialog option isn't where the docs say it is - and
there was nowhere to put that. Filing one is now a single command:
bun sdk/bug-report.ts "walkTo returns success at closed gates"
The SDK's git commit is stamped on every report, so a report points at the
code that produced it.
Server side, POST /bug-report appends JSONL to the mounted volume
(BUG_REPORTS_FILE in fly.toml, so reports survive deploys). The endpoint is
deliberately write-only: nothing is served back over HTTP, and reports are
read off the machine with
fly ssh console -C "cat /opt/server/data/bug-reports.jsonl"
Reports always go to rs-sdk-demo.fly.dev, never to whatever SERVER a bot is
playing on - a bug found against a local server is still a bug in the SDK.
Telemetry is on by default; TELEMETRY=false in bot.env or the environment
turns it off.
Also renames claude.md -> CLAUDE.md and agents.md -> AGENTS.md. Those names
only resolved on macOS: the filesystem is case-insensitive here, so git had
recorded lowercase names that no tool would find on a case-sensitive
checkout. Verified on a case-sensitive volume - before the rename, lookups
for CLAUDE.md and AGENTS.md both missed; after, all three resolve to the one
real file.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
