@joystack/cli 0.1.55 → 0.1.56

package/lib/relay/relay.mjs

@@ -1,300 +1,310 @@
-// The relay's hub, inside the dev server: events from a page the server
-// serves, or from the agent, passed on to every other place something
-// listens. The browser half is shared/ui/relay/relay.js (its README is the
-// contract both halves keep).
+// The relay's dev server end: `joystack dev` as the other end of a host's
+// `server()` connection (shared/ui/relay/server.js, whose README is the
+// manual). A host page asks; the dev server answers what it was asked, and
+// announces a fact to the creator's own pages. It never asks a page
+// anything, and never passes one page's message to another.
 //
-//   POST /__joystack/relay                  publish { id?, name, data, image?, client? }
-//   GET  /__joystack/relay/stream?listen=…  SSE: `hello` (this client's id, what the
-//                                           other places listen for, the agent), then
-//                                           `listens`, `agent` and `event` frames
-//   GET  /__joystack/relay/status           { agent }, for `joystack assets`' warning
+//   POST /__joystack/relay  { name, data }   answered in a 200 with
+//                                            { ok: true, value } or
+//                                            { ok: false, reason, message }
+//   announcements           on the page's reload stream, as SSE events named
+//                           `relay`, `{ name, data }`, only down a stream a
+//                           creator's page opened (static-server.mjs)
 //
-// Who may do what: a page this server served may publish (same origin), and
-// the creator's own pages (this machine, or the owner's live link in the
-// maker: `fromCreator`) may also listen; a phone on the wifi or a --share
-// tester publishes with `from.creator` false and a picture refused, and
-// cannot listen. The agent speaks with the bearer token the server writes to
-// .joystack/relay/.connection-<port> (connection.mjs), from loopback and never
-// from a browser, and is stamped `from.agent`. `from` is stamped here and
-// never taken from the sender.
+// The names a page may ask:
+//   server.agent          who would be woken (a name), or null
+//   server.picks          whether this server takes picks: true where its
+//                         feed for Claude Code is on (a laptop), false where
+//                         it is off (the maker's machine, whose page takes
+//                         them)
+//   note.reply { id }     the agent's reply to that note, { text, at }, or
+//                         null; a reply is kept for a day
+//   each name on the engine's agent feed (shared/ui/relay/agent-feed.json):
+//                         its line in the dev server's log, which Claude Code
+//                         reads in .joystack/dev/last.log, and the agent woken
+//                         for an entry with `wakes_up_agent`. `note.sent`
+//                         files the note and answers { id, agent }; the
+//                         others answer { agent }.
+// The name the agent asks, with the token only it can read
+// (`joystack relay reply`):
+//   agent.reply { to, text }  kept by the note's id, and `note.replied { id }`
+//                             announced
+// The dev server's other announcement: `server.agent { agent }` when the
+// agent comes or goes.
 //
-// An event goes only where something listens. Each stream names what its
-// page listens for; the hub keeps the union of what the OTHER places listen
-// for per client and streams it, so a window posts only what would reach
-// someone. The hub's own listeners (the laptop conversation, conversation.mjs,
-// when an agent session started the server; a `joystack relay tail`) are in
-// that union like any page.
-import { randomBytes, timingSafeEqual } from 'node:crypto';
-import { sessionAlive } from '../agent-session.mjs';
-import { removeConnection, writeConnection } from './connection.mjs';
-import { createConversation, newToken } from './conversation.mjs';
+// Who may ask: only the creator's own pages (this machine, or the owner's
+// live link in the maker: `fromCreator`), from a page this server served. A
+// hostile website in the creator's browser can fire a POST at localhost,
+// and what is posted here reaches an AI agent; a phone on the wifi or a
+// --share tester is someone else.
+import { randomBytes } from 'node:crypto';
+import { mkdirSync, readdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { postToSession, sessionAlive } from '../agent-session.mjs';
+import { relayDir, removeConnection, writeConnection } from './connection.mjs';
+import { createConversation, newToken, TEXT_MAX_CHARS } from './conversation.mjs';
+import { relayFiles } from './engine.mjs';
+import { bearer, json, parse, readBody, text, MAX_BYTES } from './http.mjs';
 
 export const RELAY_PATH = '/__joystack/relay';
-// What one publish may weigh: a picture rides only from the creator's
-// browser, so its cap is larger; anyone else sends small JSON only.
-export const MAX_BYTES = 2 * 1024 * 1024;
-export const LOCAL_MAX_BYTES = 8 * 1024 * 1024;
-const MAX_LISTENS = 32;
 const AGENT_POLL_MS = 3000;
-const NAME_RE = /^[a-z0-9][a-z0-9-]*(\.[a-z0-9][a-z0-9-]*)+$/;
-const PATTERN_RE = /^[a-z0-9*][a-z0-9*-]*(\.[a-z0-9*][a-z0-9*-]*)*$/;
-const ID_RE = /^[a-z0-9][a-z0-9-]{0,31}$/;
-const PNG_PREFIX = 'data:image/png;base64,';
-const LOOPBACK = new Set(['127.0.0.1', '::1', '::ffff:127.0.0.1']);
+// A note's id, as the dev server makes it when the note is sent.
+const NOTE_ID_RE = /^[a-f0-9]{12}$/;
+// A name, as the relay's connection checks it (shared/ui/relay/connection.js):
+// it is written into the log the agent reads, so nothing else gets that far.
+const NAME_RE = /^[a-z][a-z0-9-]*(\.[a-z0-9-]+)+$/;
+const NAME_MAX_CHARS = 100;
+// How long a reply is kept for the page that waits for it: past the note's
+// own thirty-minute wait, with room for a page reopened later that day.
+const REPLY_KEEP_MS = 24 * 60 * 60 * 1000;
 
-// A pattern compiled once, when a listen is registered: the hub tests every
-// listen of every client against every event, so each pattern is a RegExp
-// held with its listen rather than split again per event. `*` stands for one
-// segment; alone it matches every name.
-export function matcher(pattern) {
-  if (pattern === '*') return /^[a-z0-9.-]+$/;
-  const segs = String(pattern).split('.').map((seg) => (seg === '*' ? '[a-z0-9-]+' : seg.replace(/[.*+?^${}()|[\]\\-]/g, '\\$&')));
-  return new RegExp(`^${segs.join('\\.')}$`);
-}
-const withMatcher = (listen) => ({ ...listen, re: matcher(listen.pattern) });
-
-const json = (res, status, body, extra = {}) => {
-  const buf = Buffer.from(JSON.stringify(body));
-  res.writeHead(status, { 'Content-Type': 'application/json', 'Content-Length': buf.length, 'Cache-Control': 'no-store', ...extra });
-  res.end(buf);
-};
-const text = (res, status, body, extra = {}) => {
-  res.writeHead(status, { 'Content-Type': 'text/plain', ...extra });
-  res.end(body);
-};
-
-// The listen list a stream asked for: `[[pattern, image], …]` as JSON.
-function parseListens(raw) {
-  let list;
-  try { list = JSON.parse(raw ?? '[]'); } catch { return null; }
-  if (!Array.isArray(list) || list.length > MAX_LISTENS) return null;
-  const out = [];
-  for (const item of list) {
-    const [pattern, image] = Array.isArray(item) ? item : [item, false];
-    if (typeof pattern !== 'string' || !PATTERN_RE.test(pattern)) return null;
-    out.push(withMatcher({ pattern, image: image === true }));
-  }
-  return out;
-}
-
-// The agent's credential: a bearer token from a process on this machine,
-// never a browser (which always sends Origin on a cross-origin request and
-// cannot set this header from a page the server did not serve). 'agent'
-// when it is the server's token, 'refused' when a bearer was offered and is
-// not, null when none was offered.
-function bearer(req, token) {
-  const header = String(req.headers.authorization ?? '');
-  if (!header.startsWith('Bearer ')) return null;
-  const supplied = Buffer.from(header.slice(7));
-  const expected = Buffer.from(token);
-  const ok = LOOPBACK.has(req.socket.remoteAddress) && !req.headers.origin
-    && supplied.length === expected.length && timingSafeEqual(supplied, expected);
-  return ok ? 'agent' : 'refused';
-}
-
-// The path of the page that published, from the request's Referer; null
-// for the agent, or when the browser sent none.
-function pageOf(req) {
-  try {
-    const u = new URL(String(req.headers.referer ?? ''));
-    return u.pathname;
-  } catch { return null; }
-}
-
-function readBody(req, res, maxBytes) {
-  return new Promise((resolve) => {
-    const chunks = [];
-    let size = 0;
-    let overflowed = false;
-    req.on('data', (chunk) => {
-      if (overflowed) return; // draining the rest so the client can read the 413
-      size += chunk.length;
-      if (size > maxBytes) {
-        overflowed = true;
-        chunks.length = 0;
-        text(res, 413, `event too large (max ${maxBytes} bytes)`, { Connection: 'close' });
-        return;
-      }
-      chunks.push(chunk);
-    });
-    req.on('end', () => resolve(overflowed ? null : Buffer.concat(chunks).toString('utf8')));
-  });
-}
+const answer = (value) => ({ ok: true, value: value ?? null });
+const refuse = (reason, message) => ({ ok: false, reason, message });
 
-// What a publish asked for, checked: `{ error }` with the words for a 400,
-// or `{ name, data, image, id, skip }`. A picture is a PNG data URL and only
-// from the creator's browser; an id the sender chose is kept when it is one
-// the hub would have made.
-function parseEvent(raw, creator) {
-  let body;
-  try { body = JSON.parse(raw); } catch { return { error: 'body must be JSON' }; }
-  const name = body?.name;
-  if (typeof name !== 'string' || !NAME_RE.test(name)) return { error: 'an event is named <publisher>.<what>' };
-  const { image } = body;
-  if (image !== undefined && (typeof image !== 'string' || !image.startsWith(PNG_PREFIX))) return { error: 'image must be a PNG data URL' };
-  if (image !== undefined && !creator) return { error: 'only the creator\'s own browser can attach a picture' };
+// The agent coming and going is a session file appearing or vanishing,
+// which nothing announces, so it is looked at every few seconds while a
+// creator's page is open (`start` to `stop`), and `changed(agent)` told. A
+// page asks `server.agent` when its stream opens, so a change while none was
+// open is not lost.
+function watchAgent(agentNow, changed) {
+  let timer = null;
   return {
-    name,
-    data: body.data === undefined ? null : body.data,
-    image,
-    id: typeof body.id === 'string' && ID_RE.test(body.id) ? body.id : randomBytes(4).toString('hex'),
-    skip: typeof body.client === 'string' ? body.client : null,
+    start() {
+      if (timer) return;
+      let last = agentNow();
+      timer = setInterval(() => {
+        const now = agentNow();
+        if (now === last) return;
+        last = now;
+        changed(now);
+      }, AGENT_POLL_MS);
+      timer.unref();
+    },
+    stop() {
+      if (timer) clearInterval(timer);
+      timer = null;
+    },
   };
 }
 
-export function createRelay({
-  projectDir, agentSession = null, log = () => {}, cliBin = 'joystack',
-  // The dev server's own trust checks (static-server.mjs): whether a request
-  // came from a page this server served, and from the creator's own browser.
-  sameOrigin = () => true, fromCreator = () => true,
-}) {
+export function createRelay(options) {
+  const {
+    projectDir, agentSession = null, log = () => {}, cliBin = 'joystack',
+    // The dev server's own trust checks (static-server.mjs): whether a request
+    // came from a page this server served (`{ requireOrigin }` refusing one
+    // that names no origin), and from the creator's own browser.
+    sameOrigin = () => true, fromCreator = () => true,
+    // The engine's shared/ folder, asked when the feed is first needed.
+    sharedDir = () => null,
+    // Whether Claude Code's feed is told anything: off on the maker's game
+    // machine, whose agent is the maker's.
+    feed: feedOn = true,
+  } = options;
   const token = newToken();
-  const clients = new Set();   // { id, res, listens, agent }
-  const own = [];              // the hub's own listeners: { pattern, image, deliver }
-  if (agentSession) own.push(withMatcher(createConversation({ projectDir, agentSession, log, cliBin })));
+  // One conversation for both ends, so the agent's wake limit covers both.
+  const conversation = agentSession ? createConversation({ projectDir, agentSession, log, cliBin }) : null;
   let port = null;
-  let agentTimer = null;
-  let lastAgent = null;
+  const replies = replyStore(projectDir);
+  // The creator's pages' reload streams, each a `send(name, data)`.
+  const streams = new Set();
+  let feedLoading = null;
 
   const agentNow = () => (sessionAlive(agentSession) ? agentSession.agent : null);
-  const send = (client, frame) => { try { client.res.write(`data: ${JSON.stringify(frame)}\n\n`); } catch { /* gone */ } };
 
-  // What everyone but `client` listens for, one entry per pattern, `image`
-  // when any of them asked for the picture.
-  function othersFor(client) {
-    const union = new Map();
-    const add = ({ pattern, image }) => { union.set(pattern, { pattern, image: image || union.get(pattern)?.image || false }); };
-    for (const c of clients) if (c !== client) c.listens.forEach(add);
-    own.forEach(add);
-    return [...union.values()];
+  function announce(name, data) {
+    for (const send of streams) {
+      try { send(name, data); } catch { /* that stream is closing */ }
+    }
+  }
+
+  const watcher = agentSession ? watchAgent(agentNow, (agent) => announce('server.agent', { agent })) : { start() {}, stop() {} };
+
+  // The engine's feed: its list and the code that words it, from the game's
+  // own engine, loaded on first use. Null when there is none, or the feed is
+  // off; a feed that did not load is looked for again next time, so an
+  // engine updated under a running server is found.
+  const warned = { older: false, broken: false };
+  function feed() {
+    feedLoading ??= (async () => {
+      if (!feedOn) return null;
+      const dir = relayFiles(sharedDir(), ['feed.js', 'agent-feed.json']);
+      if (!dir) {
+        if (!warned.older) log('relay: your game\'s engine is older than this `joystack dev`: run `npx joystack update` in the game\'s folder, so that its dev tools reach your agent');
+        warned.older = true;
+        return null;
+      }
+      const lib = await import(pathToFileURL(join(dir, 'feed.js')).href);
+      let list = [];
+      try { list = JSON.parse(readFileSync(join(dir, 'agent-feed.json'), 'utf8')); } catch { /* no list */ }
+      return { lib, entries: lib.checkFeed(list) };
+    })().catch((err) => {
+      if (!warned.broken) log(`relay: the engine's feed did not load (${err?.message ?? err})`);
+      warned.broken = true;
+      return null;
+    });
+    const loading = feedLoading;
+    loading.then((f) => { if (!f && feedOn && feedLoading === loading) feedLoading = null; });
+    return loading;
   }
-  const broadcastListens = () => { for (const c of clients) send(c, { type: 'listens', others: othersFor(c) }); };
 
-  // The agent coming and going is a session file appearing or vanishing,
-  // which no event announces, so it is looked at every few seconds while a
-  // page is listening, and told only when it changes.
-  function watchAgent() {
-    if (agentTimer || !agentSession) return;
-    lastAgent = agentNow();
-    agentTimer = setInterval(() => {
-      if (!clients.size) { clearInterval(agentTimer); agentTimer = null; return; }
-      const now = agentNow();
-      if (now === lastAgent) return;
-      lastAgent = now;
-      for (const c of clients) send(c, { type: 'agent', agent: now });
-    }, AGENT_POLL_MS);
-    agentTimer.unref();
+  async function sendNote(data) {
+    const id = randomBytes(6).toString('hex');
+    if (!conversation) return { id, agent: false };
+    const { image, ...rest } = data && typeof data === 'object' ? data : {};
+    const { agent } = await conversation.deliver({ id, data: rest, from: { creator: true, agent: false } }, { image });
+    return { id, agent };
   }
 
-  // Deliver a stamped event: to every client (but the one that published it)
-  // whose listens match, with the picture only to one that asked; and to the
-  // hub's own listeners. Resolves { delivered, agent }.
-  async function deliver(event, image, skip) {
-    let delivered = 0;
-    for (const c of clients) {
-      if (skip && c.id === skip) continue;
-      const hits = c.listens.filter((l) => l.re.test(event.name));
-      if (!hits.length) continue;
-      const wantsImage = hits.some((l) => l.image) && image !== undefined;
-      send(c, { type: 'event', event: wantsImage ? { ...event, image } : event });
-      delivered += 1;
+  // A name on the engine's feed: its line in the log, and the agent woken
+  // when its entry says so. Null when the name is not on the list.
+  async function feedLine(name, data) {
+    const f = await feed();
+    const entry = f && f.lib.feedEntry(f.entries, name);
+    if (!entry) return null;
+    const line = f.lib.feedLine(name, f.lib.fill(entry.say, data));
+    log(line);
+    return { entry, line };
+  }
+  async function told(name, data) {
+    const fed = await feedLine(name, data);
+    if (!fed) return null;
+    const { entry, line } = fed;
+    if (!entry.wakes_up_agent || !sessionAlive(agentSession)) return { agent: false };
+    try {
+      await postToSession(agentSession, `[Joystack dev tools] ${line}`);
+      return { agent: true };
+    } catch (err) {
+      log(`relay: could not wake the agent session (${err.message})`);
+      return { agent: false };
     }
-    let agent = false;
-    for (const l of own) {
-      if (!l.re.test(event.name)) continue;
-      try {
-        const out = await l.deliver(event, { image: l.image ? image : undefined });
-        if (out?.agent) agent = true;
-      } catch (err) {
-        log(`relay: a listener for ${l.pattern} failed (${err?.message ?? err})`);
-      }
+  }
+
+  function keepReply(data) {
+    const out = replies.keep(data);
+    if (out.ok) {
+      announce('note.replied', { id: data.to });
+      out.value = { shown: streams.size > 0 };
     }
-    return { delivered, agent };
+    return out;
   }
 
-  async function handlePublish(req, res) {
-    if (req.method !== 'POST') return text(res, 405, 'POST only', { Allow: 'POST' });
-    const auth = bearer(req, token);
-    if (auth === 'refused') return json(res, 403, { error: 'only `joystack relay` on this machine may publish as the agent' });
-    const agent = auth === 'agent';
-    // Only a page this server itself served may publish: a hostile website
-    // in the creator's browser can fire a no-preflight POST at localhost, and
-    // what is published here reaches an AI agent as data from the game.
-    if (!agent && !sameOrigin(req)) return text(res, 403, 'cross-origin post rejected');
-    const creator = agent || fromCreator(req);
-    const raw = await readBody(req, res, creator ? LOCAL_MAX_BYTES : MAX_BYTES);
-    if (raw === null) return undefined;
-    const asked = parseEvent(raw, creator);
-    if (asked.error) return text(res, 400, asked.error);
-    const { name, data, image, id, skip } = asked;
-    const event = { id, name, at: new Date().toISOString(), from: { page: agent ? null : pageOf(req), creator, agent }, data };
-    const out = await deliver(event, image, skip);
-    const label = typeof data?.label === 'string' ? ` ${JSON.stringify(data.label.slice(0, 80))}` : '';
-    log(`relay: ${name}${label} → ${out.delivered} listener${out.delivered === 1 ? '' : 's'}${out.agent ? ', the agent woken' : ''}`);
-    return json(res, 200, { ok: true, id, delivered: out.delivered, agent: out.agent });
+  async function fromPage({ name, data }) {
+    if (name === 'server.agent') return answer(agentNow());
+    if (name === 'server.picks') return answer(feedOn);
+    if (name === 'note.reply') return replies.read(data?.id);
+    // A note is filed and sent whatever the feed says; its line in the log
+    // is the feed's.
+    if (name === 'note.sent') {
+      await feedLine(name, data);
+      return answer(await sendNote(data));
+    }
+    const out = await told(name, data);
+    return out ? answer(out) : refuse('unknown', `joystack dev does not handle ${name}`);
   }
 
-  function handleStream(req, res, query) {
-    if (req.method !== 'GET') return text(res, 405, 'GET only', { Allow: 'GET' });
-    const auth = bearer(req, token);
-    if (auth === 'refused') return json(res, 403, { error: 'only `joystack relay` on this machine may listen as the agent' });
-    const agent = auth === 'agent';
-    // The stream carries what the creator's tools say and show, so only the
-    // creator's own pages may open one. A browser names where a request came
-    // from; a page from another site is refused even where CORS would stop
-    // it from reading the answer.
-    const site = req.headers['sec-fetch-site'];
-    const siteOk = site === undefined || site === 'same-origin' || site === 'none';
-    if (!agent && !(fromCreator(req) && sameOrigin(req) && siteOk)) return text(res, 403, 'the relay is the creator\'s own');
-    const listens = agent && !query.has('listen') ? [withMatcher({ pattern: '*', image: false })] : parseListens(query.get('listen'));
-    if (!listens) return text(res, 400, 'listen must be a JSON list of [pattern, image] pairs');
-    res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', Connection: 'keep-alive' });
-    res.write(':connected\n\n');
-    const client = { id: randomBytes(4).toString('hex'), res, listens, agent };
-    clients.add(client);
-    send(client, { type: 'hello', client: client.id, others: othersFor(client), agent: agentNow() });
-    broadcastListens();
-    watchAgent();
-    const keepalive = setInterval(() => res.write(':keepalive\n\n'), 10_000);
-    keepalive.unref();
-    res.on('close', () => {
-      clearInterval(keepalive);
-      clients.delete(client);
-      broadcastListens();
-    });
-    return undefined;
+  function fromAgent({ name, data }) {
+    if (name === 'agent.reply') return keepReply(data);
+    return refuse('unknown', `joystack dev takes only agent.reply from the agent, not ${name}`);
   }
 
-  // Whether an agent session is connected. Only the creator may read it, as
-  // for the stream; the custom header forces a CORS preflight the server never
-  // grants, so no foreign page can read it.
-  function handleStatus(req, res) {
-    if (!fromCreator(req) || !sameOrigin(req) || req.headers['x-joystack-agent-ui'] !== '1') return text(res, 403, 'dev tools only');
-    return json(res, 200, { agent: agentNow() });
+  async function handleRequest(req, res) {
+    if (req.method !== 'POST') return text(res, 405, 'POST only', { Allow: 'POST' });
+    const auth = bearer(req, token);
+    if (auth === 'refused') return text(res, 403, 'only `joystack relay` on this machine may speak as the agent');
+    if (auth !== 'agent') {
+      // A browser always names the origin of a POST and where it came from,
+      // and a page on another site cannot pass these. A program on this
+      // machine can write any header it likes, and so can pass them as the
+      // creator's page; that is accepted (only the agent's token, which
+      // needs read access to the game folder, speaks as the agent).
+      const site = req.headers['sec-fetch-site'];
+      if (!sameOrigin(req, { requireOrigin: true }) || !(site === undefined || site === 'same-origin')) return text(res, 403, 'cross-origin request rejected');
+      if (!fromCreator(req)) return text(res, 403, 'only the creator\'s own browser reaches joystack dev\'s relay');
+    }
+    const raw = await readBody(req, res, MAX_BYTES);
+    if (raw === null) return undefined;
+    const body = parse(raw);
+    if (!body || typeof body.name !== 'string' || body.name.length > NAME_MAX_CHARS || !NAME_RE.test(body.name)) return text(res, 400, 'expected { name, data }, the name <owner>.<what>');
+    return json(res, 200, await (auth === 'agent' ? fromAgent(body) : fromPage(body)));
   }
 
   return {
-    // Answers a request under RELAY_PATH; anything else is not the relay's.
-    handle(req, res, urlPath, query = new URLSearchParams()) {
-      if (urlPath === RELAY_PATH) return handlePublish(req, res).catch((err) => { log(`relay: ${err?.message ?? err}`); if (!res.headersSent) text(res, 500, '500'); });
-      if (urlPath === `${RELAY_PATH}/stream`) return handleStream(req, res, query);
-      if (urlPath === `${RELAY_PATH}/status`) return handleStatus(req, res);
-      return text(res, 404, 'not found');
+    // Answers a request under RELAY_PATH; anything else there is not found.
+    handle(req, res, urlPath) {
+      if (urlPath !== RELAY_PATH) return text(res, 404, 'not found');
+      return handleRequest(req, res).catch((err) => {
+        log(`relay: ${err?.message ?? err}`);
+        if (!res.headersSent) json(res, 200, refuse('error', 'joystack dev failed to answer; its terminal says why'));
+      });
+    },
+    // A creator's page's reload stream, which hears every announcement as
+    // `send(name, data)`. Returns the function that stops it.
+    listen(send) {
+      streams.add(send);
+      watcher.start();
+      return () => {
+        streams.delete(send);
+        if (!streams.size) watcher.stop();
+      };
     },
     // The server is listening on `port`: write the agent's credential.
     attach(listeningPort) {
       port = listeningPort;
-      try { writeConnection(projectDir, port, token); } catch (err) { log(`relay: the agent cannot publish (${err?.message ?? err})`); }
+      try { writeConnection(projectDir, port, token); } catch (err) { log(`relay: the agent cannot reply to notes (${err?.message ?? err})`); }
     },
     agent: agentNow,
-    // For a test: what every other place listens for, as a fresh stream would be told.
-    others: () => othersFor(null),
     close() {
-      if (agentTimer) clearInterval(agentTimer);
-      agentTimer = null;
-      for (const c of clients) { try { c.res.end(); } catch { /* gone */ } }
-      clients.clear();
+      watcher.stop();
+      streams.clear();
       if (port !== null) removeConnection(projectDir, port, token);
     },
   };
 }
+
+// The agent's replies, one file per note under .joystack/relay/replies/,
+// shared by every dev server running for the game folder.
+function replyStore(projectDir) {
+  const repliesDir = join(relayDir(projectDir), 'replies');
+  const replyFile = (id) => join(repliesDir, `${id}.json`);
+  // Whether a note with this id was filed in this game folder.
+  const noteFiled = (id) => {
+    try { return readdirSync(relayDir(projectDir)).some((f) => f.endsWith(`-${id}.json`)); } catch { return false; }
+  };
+
+  // Replies past REPLY_KEEP_MS, removed when another is kept.
+  function prune() {
+    let names = [];
+    try { names = readdirSync(repliesDir); } catch { return; }
+    for (const n of names) {
+      const file = join(repliesDir, n);
+      try { if (Date.now() - statSync(file).mtimeMs > REPLY_KEEP_MS) unlinkSync(file); } catch { /* gone already */ }
+    }
+  }
+
+  return {
+    read(id) {
+      if (!NOTE_ID_RE.test(String(id))) return refuse('error', 'a note id is 12 hex digits');
+      let reply;
+      try {
+        if (Date.now() - statSync(replyFile(id)).mtimeMs > REPLY_KEEP_MS) return answer(null);
+        reply = JSON.parse(readFileSync(replyFile(id), 'utf8'));
+      } catch { return answer(null); }
+      return answer({ text: String(reply.text ?? ''), at: String(reply.at ?? '') });
+    },
+    // Kept until REPLY_KEEP_MS has passed rather than handed out once, so a
+    // page that reloads while it asks, or a second tab waiting on the same
+    // note, still finds it. Written fresh: an existing file is removed
+    // rather than written through, so a planted link is never followed.
+    keep({ to, text: said } = {}) {
+      if (!NOTE_ID_RE.test(String(to)) || !noteFiled(to)) return refuse('error', `no note ${to} was sent from this game`);
+      const words = typeof said === 'string' ? said.trim().slice(0, TEXT_MAX_CHARS) : '';
+      if (!words) return refuse('error', 'a reply needs its text');
+      mkdirSync(repliesDir, { recursive: true });
+      prune();
+      try { unlinkSync(replyFile(to)); } catch (err) { if (err.code !== 'ENOENT') throw err; }
+      writeFileSync(replyFile(to), JSON.stringify({ text: words, at: new Date().toISOString() }), { flag: 'wx' });
+      return answer(null);
+    },
+  };
+}

package/lib/reload-client.mjs

@@ -0,0 +1,58 @@
+// The page's half of /__reload, under `joystack dev` (live-versions.mjs). Every
+// page the server serves belongs to one version of the game, and leaves when
+// that version stops being the one served:
+//
+//   game    a game page. It reloads as soon as an update starts, so no game
+//           runs while files are replaced; the server answers it with the
+//           "Updating…" page, then the game.
+//   status  the "Updating…" or error page. It reloads when a version is ready.
+//   other   any other page (the Assets page). It reloads once the new version
+//           is served.
+//
+// The stream sends `reload` after every switch, and the status (JSON) on
+// connecting and whenever it changes. A page whose version is not the one in
+// the status reloads at once: it was served just before a switch.
+export const reloadClient = (kind, version, token) => `<script>
+(() => {
+  const kind = ${JSON.stringify(kind)};
+  const version = ${JSON.stringify(version)};
+  let alive = false;
+  let opened = false;
+  let leaving = false;
+  // Loaded again by a navigation to its own address: Safari makes a reload
+  // without its cache, every module downloaded again however long it may be
+  // kept. An address with a #fragment would only move to it, so that one reloads.
+  const leave = () => { if (!leaving) { leaving = true; if (location.hash) location.reload(); else location.replace(location.href); } };
+  function connect() {
+    const es = new EventSource('/__reload?page=' + kind + '&token=${token}');
+    // The relay's announcements to this page (relay/relay.mjs), sent only
+    // down a stream the creator's own page opened, handed to the page's
+    // server() (shared/ui/relay/server.js) as window events; and the stream
+    // coming back after it was lost, when that server() asks again for what
+    // may have changed.
+    es.onopen = () => {
+      if (opened) window.dispatchEvent(new Event('joystack:relay-open'));
+      opened = alive = true;
+    };
+    es.addEventListener('relay', (e) => {
+      let m;
+      try { m = JSON.parse(e.data); } catch { return; }
+      window.dispatchEvent(new CustomEvent('joystack:relay', { detail: m }));
+    });
+    es.onmessage = (e) => {
+      if (e.data === 'reload') return leave();
+      let s;
+      try { s = JSON.parse(e.data); } catch { return; }
+      if (kind === 'game' && (s.state !== 'ready' || s.version !== version)) return leave();
+      if (kind === 'status' && s.state === 'ready') return leave();
+      if (kind === 'status') window.dispatchEvent(new CustomEvent('joystack-status', { detail: s }));
+    };
+    es.onerror = () => {
+      es.close();
+      setTimeout(connect, alive ? 200 : 1000);
+      alive = false;
+    };
+  }
+  connect();
+})();
+</script>`;