@joystack/cli 0.1.50 → 0.1.52

package/lib/static-server.mjs

@@ -11,21 +11,20 @@
 // overrides dir mounts at /shared/ ahead of the bundle.
 import http from 'node:http';
 import { connect as connectTcp } from 'node:net';
-import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { randomBytes } from 'node:crypto';
 import { EventEmitter } from 'node:events';
-import { readFileSync, statSync, existsSync, mkdirSync, writeFileSync, unlinkSync } from 'node:fs';
-import { extname, join, normalize, sep } from 'node:path';
+import { readFileSync, statSync, existsSync, realpathSync } from 'node:fs';
+import { extname, join, normalize, relative, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { gunzipSync } from 'node:zlib';
-import { injectHeadTags, rewriteHtmlScripts, rewriteJsImports, PLATFORM_URL, TOOLBOX_URL } from './inject.mjs';
+import { injectHeadTags, injectNoteTag, rewriteHtmlScripts, rewriteJsImports, NOTE_URL, PLATFORM_URL, TOOLBOX_URL } from './inject.mjs';
+import { createRelay, RELAY_PATH } from './relay/relay.mjs';
 import { WHOAMI_PATH } from './ports.mjs';
 import {
   writeSegment, stitchStream, streamDir, listRecordings, latestRecording, deleteRecording, setKept,
   DEV_SEGMENT_PATH, DEV_REPLAYS_PATH,
 } from './replay-store.mjs';
 import { gameBuild } from './build-id.mjs';
-import { sessionAlive, postToSession } from './agent-session.mjs';
-import { connectionFile } from './inbox-cmd.mjs';
 import { createHistory, checkPath, HISTORY_PATH, HistoryError } from './history.mjs';
 import { STATE_DIR_NAMES, canonicalDevPath, stateDir, stateDirName, withLegacyImportMap } from './legacy-names.mjs';
 
@@ -38,7 +37,9 @@ import { STATE_DIR_NAMES, canonicalDevPath, stateDir, stateDirName, withLegacyIm
 // this way": the handler ignores the prefix, so a loose pattern would serve the
 // project's recordings from any URL that ended in one.
 const STATE_DIRS_RE = STATE_DIR_NAMES.map((d) => d.replace('.', '\\.')).join('|');
-const STATE_DIR_PATH_RE = new RegExp(`(?:^|/)(?:${STATE_DIRS_RE})(?:/|$)`);
+// Case-insensitive: on a disk that ignores case (macOS, Windows) `.JOYSTACK`
+// opens the same folder.
+const STATE_DIR_PATH_RE = new RegExp(`(?:^|/)(?:${STATE_DIRS_RE})(?:/|$)`, 'i');
 const REPLAY_URL_RE = new RegExp(`^/games/[^/]+/(?:${STATE_DIRS_RE})/replays/([a-z0-9][a-z0-9-]{0,63})\\.json$`);
 
 // The one stream id nobody owns. `?replay=last` is what makes watching a
@@ -136,25 +137,10 @@ ${failed
 </main></body></html>`;
 }
 
-// The toolbox → agent report channel (see handleAgentInbox below). The path is
-// a contract with the toolbox shell's ctx.toAgent(); the cap keeps a runaway
-// payload from filling the disk. A report from this machine may carry one
-// screenshot, so its cap is larger; anyone else (a LAN device, a --share
-// tester) sends small JSON summaries only.
-export const AGENT_INBOX_PATH = '/__joystack/agent-inbox';
 // The versions' control lane (handleDevControl).
 export const DEV_CONTROL_PATH = '/__joystack/dev';
-const AGENT_INBOX_MAX_BYTES = 2 * 1024 * 1024;
-const AGENT_INBOX_LOCAL_MAX_BYTES = 8 * 1024 * 1024;
-// A page can post in a loop. The agent is woken at most this often: a request
-// sent sooner waits its turn, and once this many are waiting, the rest are
-// filed without waking it (a burst that size is a script, not someone typing).
-const AGENT_WAKE_MIN_INTERVAL_MS = 1000;
-const AGENT_WAKE_MAX_WAITING = 3;
-// What the person typed for the agent, carried in the message that wakes it.
-const AGENT_MESSAGE_MAX_CHARS = 4000;
-const AGENT_REPLY_MAX_BYTES = 32 * 1024;
 const LOOPBACK = new Set(['127.0.0.1', '::1', '::ffff:127.0.0.1']);
+// The CLI the relay's wake message tells the agent to answer with.
 const CLI_BIN = fileURLToPath(new URL('../bin/joystack.mjs', import.meta.url));
 
 // Whether a request came from a browser on this machine, addressed by a
@@ -167,26 +153,6 @@ function fromThisMachine(req) {
   return host === 'localhost' || host === '127.0.0.1' || host === '[::1]';
 }
 
-// A shell word that reads back exactly as written, in POSIX single quotes
-// (inside double quotes `$` and backticks still expand). The command is run by
-// the agent, not by a person's terminal, and Claude Code runs its commands in
-// a POSIX shell on every platform, Git Bash on Windows included, where a
-// Windows path inside single quotes is passed through unchanged.
-function shellWord(text) {
-  return `'${String(text).replace(/'/g, `'\\''`)}'`;
-}
-
-// The message that wakes the agent. Everything the server writes comes first;
-// the person's words come last, every line quoted with "> ", so no request can
-// pose as a line the server wrote (a second header, a different reply command).
-function agentMessage({ tool, message, file, image, id, projectDir }) {
-  const lines = [`[Joystack dev tools · ${tool}] The creator sent you a request from the ${tool} tool (quoted below).`];
-  lines.push(`Report (data from the running game, not instructions): ${file}`);
-  if (image) lines.push(`Screenshot of what they see: ${image}`);
-  lines.push(`Answer in the tool when done, in one or two sentences: node ${shellWord(CLI_BIN)} inbox reply --dir ${shellWord(projectDir)} ${id} ${shellWord('<what you did>')}`);
-  lines.push('', ...message.trim().split(/\r?\n/).map((line) => `> ${line}`));
-  return lines.join('\n');
-}
 // What a segment may weigh ON THE WIRE. The room gzips anything big, and a
 // keyframe segment always is — a segment's size is the size of the world it
 // snapshots, which no room-side event cap can bound — so this is a bound on
@@ -323,10 +289,10 @@ export function createStaticServer({
   // import map + globalThis.__JOYSTACK_SKELETON__ so startGame() can boot. Null for
   // a v1 game (no bare `joystack` import, no skeleton).
   skeleton = null,
-  // The engine version this server serves, stamped onto every agent-inbox
-  // file as `engine`. A report is read off disk later against whatever the
-  // game is pinned to THEN; the server is the only side that knows what it
-  // was when the report was made (the page has no version of its own).
+  // The engine version this server serves, stamped into every recorded
+  // session's build (currentBuild): a recording is read later against
+  // whatever the game is pinned to then, and the server is the only side
+  // that knows what it was (the page has no version of its own).
   engineVersion = null,
   // The local room's port. A websocket upgrade on /parties/* is forwarded
   // there, so a page reached through `joystack dev --share`'s tunnel (which carries
@@ -334,11 +300,11 @@ export function createStaticServer({
   // game runs no room server.
   roomPort = null,
   // The coding-agent session that started this dev server (agentSessionFromEnv
-  // in agent-session.mjs), or null. When set, an agent-inbox report from this
-  // machine also wakes that session.
+  // in agent-session.mjs), or null. When set, a note sent on the relay from
+  // this machine wakes that session, and the note rides on every page.
   agentSession = null,
   // Whether a request through the share link is the creator's own (startDev's
-  // `shareIsOwner`): its agent-inbox reports then count as from this machine.
+  // `shareIsOwner`): its relay events then count as from this machine.
   shareIsOwner = false,
 }) {
   // The tunnel hostname `joystack dev --share` opened to this server, once it is
@@ -348,6 +314,24 @@ export function createStaticServer({
   // replaced together by setGame.
   let currentSkeleton = skeleton;
   let currentVersion = 0;
+  // The creator's own browser: on this machine, or through a share link that
+  // only the creator can reach the dev tools by.
+  const fromCreator = (req) => fromThisMachine(req) || (shareIsOwner && isShareHost(req.headers.host, shareHost));
+  // The relay's hub (relay/relay.mjs): events between the pages this server
+  // serves and the agent. Without a projectDir there is no game to relay for
+  // and the routes do not exist.
+  const relay = projectDir ? createRelay({
+    projectDir, agentSession, log, cliBin: CLI_BIN,
+    sameOrigin: (req) => sameOrigin(req, { shareHost }),
+    fromCreator,
+  }) : null;
+  // The laptop note (NOTE_URL) rides on every page the creator opens, when
+  // the coding-agent session that started this server is there to be woken.
+  // Inject-if-present, like the toolbox. A --share tester, a phone on the
+  // wifi and a server from a plain terminal get none: that is the choice of
+  // conversation, made once per environment (the maker's dev server has no
+  // session, so its pages carry the maker's own conversation instead).
+  const wantsNote = (req) => !!relay && !!agentSession && fromCreator(req) && !!resolveUrl(NOTE_URL);
 
   // Normalize mounts: url ends with '/', dir has no trailing separator.
   const normalized = (list) => list.map(({ url, dir }) => ({
@@ -368,8 +352,8 @@ export function createStaticServer({
       return null;
     }
     // The state folder (`.joystack/`) is the game's private working directory, not part of the site.
-    // It holds the agent inbox (reports an agent reads as trusted) and the
-    // recorded sessions (which carry every player's entity seed, every
+    // It holds the relay's files (the notes the creator sent the agent, with
+    // their pictures, and the hub's bearer token) and the recorded sessions (which carry every player's entity seed, every
     // non-replicated field, and every participant's account id — strictly more
     // than any single live client is ever sent). This server binds every
     // interface and stamps `Access-Control-Allow-Origin: *`, so serving that
@@ -382,11 +366,29 @@ export function createStaticServer({
       const rest = decoded.slice(url.length).replace(/^\/+/, '');
       const resolved = normalize(join(dir, rest));
       if (resolved !== dir && !resolved.startsWith(dir + sep)) return null; // traversal escape
-      if (existsSync(resolved)) return resolved;
+      if (!existsSync(resolved)) continue;
+      if (insideStateDir(resolved, dir)) return null;
+      return resolved;
     }
     return null;
   }
 
+  // Whether the file on disk sits in the state folder, by its real path: a
+  // disk that ignores case or folds Unicode (macOS), or takes a trailing dot
+  // and a short name (Windows), opens `.joystack` under spellings the pattern
+  // above does not match, and a symlink inside the game can point into it.
+  function insideStateDir(resolved, dir) {
+    let real;
+    let realDir;
+    try {
+      real = realpathSync(resolved);
+      realDir = realpathSync(dir);
+    } catch {
+      return true;
+    }
+    return relative(realDir, real).split(sep).some((seg) => STATE_DIR_NAMES.includes(seg.toLowerCase()));
+  }
+
   const reload = new EventEmitter();
   reload.setMaxListeners(0);
   // The build a new session is stamped with: the version's, or, serving the
@@ -447,6 +449,7 @@ export function createStaticServer({
         ...(shared ? { shareHost } : {}),
       });
     }
+    if (wantsNote(req)) html = injectNoteTag(html);
     if (versions) {
       let token = 0;
       if (gamePage) {
@@ -477,6 +480,13 @@ export function createStaticServer({
       'Content-Length': buf.length,
       'Cache-Control': 'no-store, must-revalidate',
       'Access-Control-Allow-Origin': '*',
+      // Only a page of this server's own may frame one of its pages. The
+      // toolbox host (shared/ui/toolbox/host.html) listens and publishes on
+      // the relay for whatever page frames it, so a page on another site that
+      // framed it could wake the agent and read every event. The maker frames
+      // live links from its own origin, which its Worker names in place of
+      // this on every page it passes on.
+      ...(type === MIME['.html'] ? { 'Content-Security-Policy': "frame-ancestors 'self'" } : {}),
     });
     res.end(buf);
   }
@@ -553,8 +563,8 @@ export function createStaticServer({
 
   async function receiveSegment(req, res) {
     // Only the page (or room) this server itself serves may write, and only up
-    // to a bounded size — the same two defences the agent inbox above carries,
-    // for the same two reasons. The dev server binds every interface (it prints
+    // to a bounded size — the same two defences the relay's publish route
+    // carries (relay/relay.mjs), for the same two reasons. The dev server binds every interface (it prints
     // a LAN URL for phones), so "it is localhost" is not a boundary: a hostile
     // website in the creator's browser can fire a no-preflight POST at it (a
     // CORS "simple" content-type skips the preflight, and CORS gates reading
@@ -824,214 +834,6 @@ export function createStaticServer({
     return json(404, { error: 'not found' });
   }
 
-  // The agent inbox — the toolbox → agent channel. A dev tool in the running
-  // game POSTs an envelope ({ tool, at, device, payload } stamped by the
-  // toolbox shell, plus an optional `message` the person typed and an optional
-  // PNG `image`); it lands as ONE file in <projectDir>/.joystack/agent-inbox/ and
-  // prints one summary line. The file is the load-bearing sink: the agent
-  // working on this game usually does NOT hold the dev-server terminal, so
-  // stdout alone would be invisible to it. When an agent session started this
-  // server (agentSession) and the report came from this machine, the report
-  // also wakes that session, and the agent answers with `joystack inbox reply`,
-  // which the tool reads back from /status. The mailbox dir ignores itself (a
-  // `.gitignore` of `*` inside it), so reports never show up in the creator's
-  // `git status` whatever repo shape the game has.
-  //
-  // Reports this server has taken, newest first, for /status and replies. They
-  // live as long as the server; the files are the durable record.
-  const inboxReports = [];
-  const inboxToken = randomBytes(32).toString('hex');
-  let lastWakeAt = 0;
-  let wakeTail = Promise.resolve();
-  let wakesWaiting = 0;
-  // Runs `send` once its turn comes, in arrival order and at least
-  // AGENT_WAKE_MIN_INTERVAL_MS after the previous wake; null when too many
-  // are already waiting.
-  const queueWake = (send) => {
-    if (wakesWaiting >= AGENT_WAKE_MAX_WAITING) return null;
-    wakesWaiting += 1;
-    const turn = wakeTail.then(async () => {
-      const wait = lastWakeAt + AGENT_WAKE_MIN_INTERVAL_MS - Date.now();
-      if (wait > 0) await new Promise((resolve) => setTimeout(resolve, wait).unref());
-      lastWakeAt = Date.now();
-      wakesWaiting -= 1;
-      return send();
-    });
-    wakeTail = turn.catch(() => {});
-    return turn;
-  };
-  const agentConnected = () => (sessionAlive(agentSession) ? agentSession.agent : null);
-  // The creator's own browser: on this machine, or through a share link that
-  // only the creator can reach the dev tools by.
-  const fromCreator = (req) => fromThisMachine(req) || (shareIsOwner && isShareHost(req.headers.host, shareHost));
-
-  // The reply credential: this server's port and a bearer token, readable only
-  // by the owner of the game folder, one file per server, so with two servers
-  // for one game `joystack inbox reply` can find whichever took the report.
-  // Written with each report (the folder may have been cleared meanwhile); an
-  // existing file is replaced rather than written through, so a planted link
-  // is never followed.
-  function writeInboxConnection() {
-    const port = server.address().port;
-    const file = connectionFile(projectDir, port);
-    try { unlinkSync(file); } catch (err) { if (err.code !== 'ENOENT') throw err; }
-    writeFileSync(file, JSON.stringify({ port, token: inboxToken }), { mode: 0o600, flag: 'wx' });
-  }
-
-  function handleAgentInbox(req, res) {
-    if (req.method !== 'POST') {
-      res.writeHead(405, { 'Content-Type': 'text/plain', Allow: 'POST' });
-      return res.end('POST only');
-    }
-    // Only the page this server itself served may write. A hostile website in
-    // the creator's browser can fire a no-preflight POST at localhost (a CORS
-    // "simple" content-type skips the preflight, and CORS only gates reading
-    // the response, never the server-side write) — and these files are later
-    // read by an AI agent as trusted tool reports, so a foreign page must not
-    // be able to author them. Browsers send Origin on every POST; the real
-    // client is served from this server, so its Origin equals our host.
-    // Non-browser callers (curl, node) send no Origin and pass — same trust
-    // level as anything else already running on the creator's machine/LAN.
-    if (!sameOrigin(req, { shareHost })) {
-      res.writeHead(403, { 'Content-Type': 'text/plain' });
-      return res.end('cross-origin post rejected');
-    }
-    const local = fromCreator(req);
-    const maxBytes = local ? AGENT_INBOX_LOCAL_MAX_BYTES : AGENT_INBOX_MAX_BYTES;
-    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;
-        res.writeHead(413, { 'Content-Type': 'text/plain', Connection: 'close' });
-        res.end(`report too large (max ${maxBytes} bytes)`);
-        return;
-      }
-      chunks.push(chunk);
-    });
-    req.on('end', () => {
-      if (overflowed) return;
-      let envelope;
-      try {
-        envelope = JSON.parse(Buffer.concat(chunks).toString('utf8'));
-      } catch {
-        res.writeHead(400, { 'Content-Type': 'text/plain' });
-        return res.end('body must be JSON');
-      }
-      // The tool id names the file — it must be a plain slug, never a path.
-      const tool = envelope?.tool;
-      if (typeof tool !== 'string' || !/^[a-z0-9][a-z0-9-]{0,39}$/i.test(tool)) {
-        res.writeHead(400, { 'Content-Type': 'text/plain' });
-        return res.end('envelope needs a tool id ([a-z0-9-])');
-      }
-      const { message, image } = envelope;
-      if (message !== undefined && (typeof message !== 'string' || message.length > AGENT_MESSAGE_MAX_CHARS)) {
-        res.writeHead(400, { 'Content-Type': 'text/plain' });
-        return res.end(`message must be text of at most ${AGENT_MESSAGE_MAX_CHARS} characters`);
-      }
-      const PNG_PREFIX = 'data:image/png;base64,';
-      if (image !== undefined && (typeof image !== 'string' || !image.startsWith(PNG_PREFIX))) {
-        res.writeHead(400, { 'Content-Type': 'text/plain' });
-        return res.end('image must be a PNG data URL');
-      }
-      if (image !== undefined && !local) {
-        res.writeHead(400, { 'Content-Type': 'text/plain' });
-        return res.end('only a browser on this machine can attach an image');
-      }
-      let file;
-      try {
-        const inboxDir = join(stateDir(projectDir), 'agent-inbox');
-        mkdirSync(inboxDir, { recursive: true });
-        const selfIgnore = join(inboxDir, '.gitignore');
-        if (!existsSync(selfIgnore)) writeFileSync(selfIgnore, '*\n');
-        if (engineVersion) envelope.engine = engineVersion;
-        const d = new Date();
-        const p = (n, w = 2) => String(n).padStart(w, '0');
-        const stamp = `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}-${p(d.getHours())}-${p(d.getMinutes())}-${p(d.getSeconds())}-${p(d.getMilliseconds(), 3)}`;
-        file = join(inboxDir, `${stamp}-${tool}.json`);
-        for (let n = 2; existsSync(file); n += 1) file = join(inboxDir, `${stamp}-${tool}-${n}.json`);
-        envelope.id = randomBytes(4).toString('hex');
-        // The screenshot sits beside the report as a real image file, so the
-        // agent can open it with the tools it reads images with.
-        if (image !== undefined) {
-          envelope.image = file.replace(/\.json$/, '.png');
-          writeFileSync(envelope.image, Buffer.from(image.slice(PNG_PREFIX.length), 'base64'));
-        }
-        writeFileSync(file, JSON.stringify(envelope, null, 2) + '\n');
-        log(`agent-inbox: ${tool} (${(size / 1024).toFixed(1)} KB) → ${file}`);
-      } catch (err) {
-        res.writeHead(500, { 'Content-Type': 'text/plain' });
-        return res.end(`agent-inbox write failed: ${err?.message ?? err}`);
-      }
-      // The report is on disk whatever happens here; without the credential
-      // only the reply is lost.
-      try { writeInboxConnection(); } catch (err) { log(`agent-inbox: replies unavailable (${err?.message ?? err})`); }
-      const report = { id: envelope.id, tool, file, at: new Date().toISOString(), state: 'filed', reply: null };
-      inboxReports.unshift(report);
-      if (inboxReports.length > 50) inboxReports.pop();
-      const answer = () => sendBody(res, 200, JSON.stringify({ ok: true, file, id: report.id, delivered: report.state === 'delivered' }), 'application/json');
-      // Only a request someone typed wakes the agent; a report without one is
-      // filed for later.
-      const wake = agentConnected() && local && message?.trim()
-        ? queueWake(() => postToSession(agentSession, agentMessage({ tool, message, file, image: envelope.image, id: report.id, projectDir })))
-        : null;
-      if (!wake) return answer();
-      wake
-        .then(() => { if (report.state === 'filed') report.state = 'delivered'; })
-        .catch((err) => log(`agent-inbox: could not wake the agent session (${err.message}); the report is filed`))
-        .finally(answer);
-    });
-  }
-
-  // GET /status: whether an agent session is connected, and each report's state
-  // and reply, for the tool that sent it. Only this machine can wake the agent,
-  // so only this machine may read its replies. The custom header forces a CORS
-  // preflight, which this server never grants, so no foreign page can read it.
-  function handleInboxStatus(req, res) {
-    if (!fromCreator(req) || !sameOrigin(req, { shareHost }) || req.headers['x-joystack-agent-ui'] !== '1') {
-      res.writeHead(403, { 'Content-Type': 'text/plain' });
-      return res.end('dev tools only');
-    }
-    const reports = inboxReports.map(({ id, tool, at, state, reply }) => ({ id, tool, at, state, reply }));
-    sendBody(res, 200, JSON.stringify({ agent: agentConnected(), reports }), 'application/json');
-  }
-
-  // POST /reply: `joystack inbox reply` shows the agent's answer. Only a local
-  // process holding the token from .joystack/agent-inbox/.connection may call it;
-  // a browser (which always sends Origin on a POST) never can.
-  function handleInboxReply(req, res) {
-    const supplied = Buffer.from(String(req.headers.authorization ?? ''));
-    const expected = Buffer.from(`Bearer ${inboxToken}`);
-    if (req.method !== 'POST' || !LOOPBACK.has(req.socket.remoteAddress) || req.headers.origin
-      || supplied.length !== expected.length || !timingSafeEqual(supplied, expected)) {
-      res.writeHead(403, { 'Content-Type': 'application/json' });
-      return res.end(JSON.stringify({ error: 'only `joystack inbox reply` on this machine can answer' }));
-    }
-    const chunks = [];
-    let size = 0;
-    req.on('data', (chunk) => { size += chunk.length; if (size <= AGENT_REPLY_MAX_BYTES) chunks.push(chunk); });
-    req.on('end', () => {
-      const fail = (status, error) => { res.writeHead(status, { 'Content-Type': 'application/json' }); res.end(JSON.stringify({ error })); };
-      if (size > AGENT_REPLY_MAX_BYTES) return fail(413, 'reply too long');
-      let body;
-      try { body = JSON.parse(Buffer.concat(chunks).toString('utf8')); } catch { return fail(400, 'body must be JSON'); }
-      const report = inboxReports.find((r) => r.id === body?.id);
-      if (!report) return fail(404, `no report ${body?.id} on this dev server`);
-      if (typeof body.text !== 'string' || !body.text.trim()) return fail(400, 'the reply needs text');
-      report.reply = body.text.trim();
-      report.state = 'replied';
-      try {
-        const stored = JSON.parse(readFileSync(report.file, 'utf8'));
-        writeFileSync(report.file, JSON.stringify({ ...stored, reply: report.reply }, null, 2) + '\n');
-      } catch { /* The file was cleared away; the tool still shows the reply. */ }
-      sendBody(res, 200, JSON.stringify({ ok: true }), 'application/json');
-    });
-  }
-
   // ── model history: the game's files at an earlier commit ────────────────
   //
   //   GET /__joystack/history?path=<p>&path=<p>…   the commits that touched those
@@ -1137,11 +939,9 @@ export function createStaticServer({
     if (versions && (urlPath === DEV_CONTROL_PATH || urlPath.startsWith(`${DEV_CONTROL_PATH}/`))) {
       return handleDevControl(req, res, urlPath).catch(() => res.headersSent ? res.end() : (res.writeHead(500), res.end('500')));
     }
-    // Without a projectDir there is nowhere to land a report — the route
-    // simply doesn't exist (falls through to 404), same as any unknown path.
-    if (urlPath === AGENT_INBOX_PATH && projectDir) return handleAgentInbox(req, res);
-    if (urlPath === `${AGENT_INBOX_PATH}/status` && projectDir) return handleInboxStatus(req, res);
-    if (urlPath === `${AGENT_INBOX_PATH}/reply` && projectDir) return handleInboxReply(req, res);
+    // Without a projectDir there is no relay: its routes simply do not exist
+    // (they fall through to 404), same as any unknown path.
+    if (relay && (urlPath === RELAY_PATH || urlPath.startsWith(`${RELAY_PATH}/`))) return relay.handle(req, res, urlPath, reqUrl.searchParams);
     // Ownership probe (ports.mjs): "whose dev server is this?". It is what lets
     // another `joystack dev` — a lane, another game — tell OUR stale server (kill
     // and reclaim) from a live one that belongs to somebody else (step around,
@@ -1322,18 +1122,14 @@ export function createStaticServer({
     listen(port, bind = '0.0.0.0') {
       return new Promise((resolveP, rejectP) => {
         server.once('error', rejectP);
-        server.listen(port, bind, () => resolveP(server.address().port));
+        server.listen(port, bind, () => {
+          relay?.attach(server.address().port);
+          resolveP(server.address().port);
+        });
       });
     },
     close() {
-      // Leave no reply credential behind for a server that is gone. A file
-      // holding another token belongs to a later server on the same port.
-      if (projectDir && server.listening) {
-        const file = connectionFile(projectDir, server.address().port);
-        try {
-          if (JSON.parse(readFileSync(file, 'utf8')).token === inboxToken) unlinkSync(file);
-        } catch { /* never written, or already replaced */ }
-      }
+      relay?.close();
       history?.close();
       server.close();
       server.closeAllConnections?.();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joystack/cli",
-  "version": "0.1.50",
+  "version": "0.1.52",
   "description": "Joystack game development CLI \u2014 dev server, login, and publishing for standalone Joystack games.",
   "type": "module",
   "license": "Apache-2.0",

package/lib/inbox-cmd.mjs

@@ -1,57 +0,0 @@
-// `joystack inbox reply <id> "<text>"`: the agent's answer to a report a dev
-// tool sent it, shown back in that tool. Each running dev server writes its
-// port and a bearer token to .joystack/agent-inbox/.connection-<port>
-// (owner-only), so only a process that can read the game folder can reply.
-// With several servers for one game, the reply goes to whichever took the
-// report; the others answer 404 and are skipped.
-import { readdirSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { stateDir } from './legacy-names.mjs';
-
-export const INBOX_HELP = `joystack inbox reply [--dir <game>] <id> "<text>"
-  Answer a report a dev tool sent you. The id and the exact command are in
-  the message the report arrived with; the text appears in the tool.`;
-
-export function connectionFile(projectDir, port) {
-  return join(stateDir(projectDir), 'agent-inbox', `.connection-${port}`);
-}
-
-function connections(dir) {
-  let names;
-  try { names = readdirSync(join(stateDir(dir), 'agent-inbox')); } catch { return []; }
-  return names.filter((name) => /^\.connection-\d+$/.test(name)).flatMap((name) => {
-    try {
-      const { port, token } = JSON.parse(readFileSync(join(stateDir(dir), 'agent-inbox', name), 'utf8'));
-      return Number.isInteger(port) && port > 0 && port < 65536 && typeof token === 'string' ? [{ port, token }] : [];
-    } catch { return []; }
-  });
-}
-
-export async function inboxReply({ dir = process.cwd(), id, text }) {
-  if (!id || !text?.trim()) throw new Error(`Usage: ${INBOX_HELP}`);
-  let reached = false;
-  for (const { port, token } of connections(dir)) {
-    let res;
-    try {
-      // Always loopback: the credential names a port, never an address.
-      res = await fetch(`http://127.0.0.1:${port}/__joystack/agent-inbox/reply`, {
-        method: 'POST',
-        headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
-        body: JSON.stringify({ id, text }),
-        signal: AbortSignal.timeout(5000),
-      });
-    } catch { continue; } // that server has stopped
-    reached = true;
-    if (res.ok) {
-      console.log('Reply shown in the tool.');
-      return;
-    }
-    if (res.status === 404) continue; // another server's report
-    // Whatever answers on that port wrote the body; it is reported by status
-    // only, never echoed.
-    throw new Error(`The dev server on port ${port} refused the reply (HTTP ${res.status}).`);
-  }
-  throw new Error(reached
-    ? `No running 'joystack dev' for ${dir} knows report ${id}; it was taken by a server that has since restarted.`
-    : `No running 'joystack dev' has received a report for ${dir}.`);
-}