@spawnco/client 0.1.0

package/dist/session-lib.mjs

@@ -0,0 +1,765 @@
+// @bun
+// ../../apps/cf-kernel/src/_entry/headless-room-host/session/launch.ts
+import { spawn } from "child_process";
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, openSync, readFileSync as readFileSync2 } from "fs";
+import { createServer } from "net";
+import path2 from "path";
+import { fileURLToPath } from "url";
+
+// ../../apps/cf-kernel/src/waist/guards.ts
+function isObject(value) {
+  return typeof value === "object" && value !== null;
+}
+
+// ../../apps/cf-kernel/src/_entry/headless-room-host/session/account-lane.ts
+var ACCOUNT_TOKEN_PREFIX = "sak_";
+var DEFAULT_SPAWN_ORIGIN = "https://www.spawn.co";
+var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+var ENGINE_HASH_RE = /^[0-9a-f]{32}$/;
+var isAccountToken = (token) => typeof token === "string" && token.trim().startsWith(ACCOUNT_TOKEN_PREFIX);
+var trimSlash = (value) => value.replace(/\/+$/, "");
+var nonEmpty = (value) => {
+  const trimmed = value?.trim();
+  return trimmed !== undefined && trimmed.length > 0 ? trimmed : undefined;
+};
+var originOf = (url) => {
+  try {
+    return new URL(url).origin;
+  } catch {
+    return null;
+  }
+};
+var asHttp = (origin) => origin.replace(/^wss:/, "https:").replace(/^ws:/, "http:");
+async function fetchJson(fetchImpl, url, init) {
+  let response;
+  try {
+    response = await fetchImpl(url, { ...init, signal: AbortSignal.timeout(15000) });
+  } catch (error) {
+    return { status: 0, body: { error: `fetch failed: ${error instanceof Error ? error.message : String(error)}` } };
+  }
+  const body = await response.json().catch(() => null);
+  return { status: response.status, body };
+}
+var errorLine = (body, status) => {
+  if (isObject(body)) {
+    const parts = [typeof body.error === "string" ? body.error : null, typeof body.verdict === "string" ? body.verdict : null, typeof body.note === "string" ? body.note : null].filter((part) => part !== null);
+    if (parts.length > 0)
+      return parts.join(" \u2014 ");
+  }
+  return `HTTP ${status}`;
+};
+function readPlayDoors(me, origin) {
+  const doors = isObject(me) && isObject(me.doors) ? me.doors : null;
+  const play = doors && isObject(doors.play) ? doors.play : null;
+  const fallback = { resolve: `${origin}/api/resolve-adventure`, grant: `${origin}/api/session/grant/agent`, attach: null };
+  if (!play)
+    return fallback;
+  return {
+    resolve: typeof play.resolve === "string" ? play.resolve : fallback.resolve,
+    grant: typeof play.grant === "string" ? play.grant : fallback.grant,
+    attach: typeof play.attach === "string" ? play.attach : null
+  };
+}
+async function resolveWorldId(fetchImpl, doors, world) {
+  if (UUID_RE.test(world))
+    return { ok: true, worldId: world.toLowerCase(), address: world.toLowerCase() };
+  const url = `${doors.resolve}${doors.resolve.includes("?") ? "&" : "?"}address=${encodeURIComponent(world)}`;
+  const { status, body } = await fetchJson(fetchImpl, url, { method: "GET" });
+  if (status !== 200 || !isObject(body) || body.ok !== true || !isObject(body.result)) {
+    return { ok: false, verdict: `could not resolve "${world}" (${errorLine(body, status)}) \u2014 spell the world as @user/world, its play URL, or its uuid` };
+  }
+  const result = body.result;
+  if (result.type === "found" && typeof result.rootVariantId === "string") {
+    const username = typeof result.username === "string" ? result.username : null;
+    const adventure = typeof result.adventureName === "string" ? result.adventureName : null;
+    return { ok: true, worldId: result.rootVariantId, address: username && adventure ? `@${username}/${adventure}` : world };
+  }
+  if (result.type === "redirect" && typeof result.username === "string" && typeof result.adventureName === "string") {
+    return { ok: false, verdict: `"${world}" moved \u2014 it lives at @${result.username}/${result.adventureName} now; join that address` };
+  }
+  return { ok: false, verdict: `no world at "${world}" \u2014 check the address (the public ones are in GET /api/feed)` };
+}
+async function mintGrant(fetchImpl, doors, token, worldId, agentActorId) {
+  const { status, body } = await fetchJson(fetchImpl, doors.grant, {
+    method: "POST",
+    headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+    body: JSON.stringify({ world: worldId, ...agentActorId !== undefined ? { agentActorId } : {} })
+  });
+  if (status === 401)
+    return { ok: false, verdict: `the token was refused (${errorLine(body, status)}) \u2014 an agent signs up at POST /api/agent/v1/signup; a human mints a token at /settings/tokens` };
+  if (status === 400 && isObject(body) && typeof body.error === "string" && /agentActorId/.test(body.error)) {
+    return { ok: false, verdict: `${body.error} \u2014 a person's token embodies a seat it minted: pass --actor <agentActorId> (an agent account's own token needs none)` };
+  }
+  if (status !== 200 || !isObject(body) || typeof body.grantWire !== "string") {
+    return { ok: false, verdict: `the grant was refused for world ${worldId} (${errorLine(body, status)})` };
+  }
+  const engine = isObject(body.engine) ? body.engine : null;
+  return {
+    ok: true,
+    grant: {
+      grantWire: body.grantWire,
+      presentationWire: typeof body.presentationWire === "string" && body.presentationWire.length > 0 ? body.presentationWire : null,
+      worldId: typeof body.worldId === "string" && body.worldId.length > 0 ? body.worldId : null,
+      attachUrl: typeof body.attachUrl === "string" && body.attachUrl.length > 0 ? body.attachUrl : null,
+      engineHash: engine && typeof engine.hash === "string" && ENGINE_HASH_RE.test(engine.hash) ? engine.hash : null,
+      engineSemver: engine && typeof engine.semver === "string" && engine.semver.length > 0 ? engine.semver : null
+    }
+  };
+}
+async function discoverEngineHash(fetchImpl, doorOrigin, worldId, grantWire) {
+  const http = asHttp(doorOrigin);
+  try {
+    const shell = await fetchImpl(`${http}/session/${encodeURIComponent(worldId)}?grant=${encodeURIComponent(grantWire)}`, { signal: AbortSignal.timeout(15000) });
+    if (shell.ok) {
+      const html = await shell.text();
+      const match = /\/v4\/client\/([0-9a-f]{32})\//.exec(html);
+      if (match?.[1])
+        return { hash: match[1], source: "shell" };
+    }
+  } catch {}
+  try {
+    const stamp = await fetchImpl(`${http}/build-stamp.json`, { signal: AbortSignal.timeout(1e4) });
+    if (stamp.ok) {
+      const body = await stamp.json().catch(() => null);
+      const fingerprint = isObject(body) && typeof body.fingerprint === "string" ? body.fingerprint.slice(0, 32).toLowerCase() : null;
+      if (fingerprint && ENGINE_HASH_RE.test(fingerprint))
+        return { hash: fingerprint, source: "build-stamp" };
+    }
+  } catch {}
+  return null;
+}
+async function resolveAccountJoin(deps, request) {
+  const fetchImpl = deps.fetchImpl ?? fetch;
+  const token = nonEmpty(deps.env.SPAWN_TOKEN);
+  if (!token || !isAccountToken(token))
+    return { ok: false, verdict: "spawn client join <world> needs your account token in SPAWN_TOKEN (sak_\u2026) \u2014 an agent signs up at POST /api/agent/v1/signup; a human mints one at /settings/tokens" };
+  const origin = trimSlash(nonEmpty(deps.env.SPAWN_ORIGIN) ?? DEFAULT_SPAWN_ORIGIN);
+  const me = await fetchJson(fetchImpl, `${origin}/api/agent/v1/me`, { method: "GET", headers: { authorization: `Bearer ${token}` } });
+  if (me.status === 401)
+    return { ok: false, verdict: `${origin} refused the token (${errorLine(me.body, me.status)}) \u2014 an agent signs up at POST /api/agent/v1/signup; a human mints a token at /settings/tokens` };
+  if (me.status !== 200 || !isObject(me.body))
+    return { ok: false, verdict: `${origin}/api/agent/v1/me answered ${errorLine(me.body, me.status)} \u2014 is SPAWN_ORIGIN right?` };
+  const doors = readPlayDoors(me.body, origin);
+  const handle = typeof me.body.handle === "string" ? me.body.handle : null;
+  const name = typeof me.body.name === "string" ? me.body.name : null;
+  const resolved = await resolveWorldId(fetchImpl, doors, request.world.trim());
+  if (!resolved.ok)
+    return resolved;
+  const minted = await mintGrant(fetchImpl, doors, token, resolved.worldId, request.agentActorId);
+  if (!minted.ok)
+    return minted;
+  const { grant } = minted;
+  const worldId = grant.worldId ?? resolved.worldId;
+  const doorOverride = nonEmpty(deps.env.SPAWN_DOOR_ORIGIN);
+  const doorOrigin = (grant.attachUrl ? originOf(grant.attachUrl) : null) ?? (doors.attach ? originOf(doors.attach) : null) ?? (doorOverride ? originOf(doorOverride) : null);
+  if (!doorOrigin)
+    return { ok: false, verdict: `the grant names no session door for ${origin} (no attachUrl, no doors.play.attach) \u2014 pass --door <the kernel origin> (SPAWN_DOOR_ORIGIN), e.g. --door http://localhost:8787 on a dev stack` };
+  const engineOverride = nonEmpty(deps.env.SPAWN_ENGINE)?.toLowerCase();
+  let engineHash = null;
+  let engineSource = null;
+  if (engineOverride) {
+    if (!ENGINE_HASH_RE.test(engineOverride))
+      return { ok: false, verdict: `SPAWN_ENGINE / --engine must be the 32-hex engine hash, got "${engineOverride}"` };
+    engineHash = engineOverride;
+    engineSource = "override";
+  } else if (grant.engineHash) {
+    engineHash = grant.engineHash;
+    engineSource = "grant";
+  } else {
+    const discovered = await discoverEngineHash(fetchImpl, doorOrigin, worldId, grant.grantWire);
+    if (discovered) {
+      engineHash = discovered.hash;
+      engineSource = discovered.source;
+    }
+  }
+  if (!engineHash || !engineSource)
+    return { ok: false, verdict: `could not learn the engine build at ${doorOrigin} (the grant names none, the session shell names no /v4/client/<hash>/, no build-stamp) \u2014 pass --engine <32-hex hash> (SPAWN_ENGINE)` };
+  const http = asHttp(doorOrigin);
+  const env = {
+    SPAWN_TOKEN: grant.grantWire,
+    ...grant.presentationWire ? { SPAWN_PRESENTATION_CARD: grant.presentationWire } : {},
+    ROOM_HOST_VARIANT_ID: worldId,
+    ROOM_HOST_EDGE_ORIGIN: http,
+    ROOM_HOST_KILN_ORIGIN: origin,
+    ROOM_HOST_ASSET_ORIGIN: origin,
+    ROOM_HOST_ENGINE_VERSION: engineHash,
+    ...grant.engineSemver ? { ROOM_HOST_ENGINE_SEMVER: grant.engineSemver } : {},
+    ROOM_HOST_ENGINE_BASE_URL: http
+  };
+  return { ok: true, env, worldId, worldAddress: resolved.address, doorOrigin, engineHash, engineSource, handle, name };
+}
+
+// ../../apps/cf-kernel/src/_entry/headless-room-host/session/shell-client.ts
+class ShellUnreachableError extends Error {
+  constructor(detail) {
+    super(`session shell unreachable: ${detail}`);
+    this.name = "ShellUnreachableError";
+  }
+}
+async function requestJson(options, path, init, timeoutMs) {
+  const doFetch = options.fetchImpl ?? fetch;
+  const controller = new AbortController;
+  const budget = timeoutMs ?? options.timeoutMs ?? 1e4;
+  const timer = setTimeout(() => controller.abort(), budget);
+  let response;
+  try {
+    response = await doFetch(new URL(path, options.baseUrl), { ...init, signal: controller.signal });
+  } catch (error) {
+    throw new ShellUnreachableError(error instanceof Error ? error.message : String(error));
+  } finally {
+    clearTimeout(timer);
+  }
+  const body = await response.json().catch(() => null);
+  if (!response.ok) {
+    const detail = typeof body === "object" && body !== null && "error" in body && typeof body.error === "string" ? body.error : `HTTP ${response.status}`;
+    throw new Error(`${path} \u2192 ${detail}`);
+  }
+  return body;
+}
+function shellHealth(options) {
+  return requestJson(options, "/healthz");
+}
+function shellWhere(options) {
+  return requestJson(options, "/where");
+}
+function shellSceneSnapshot(options) {
+  return requestJson(options, "/scene-snapshot");
+}
+function shellCrossing(options) {
+  return requestJson(options, "/crossing");
+}
+function shellCrossingPrefetch(options, args) {
+  return requestJson(options, "/crossing/prefetch", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(args) });
+}
+function shellMove(options, args) {
+  const budget = (Math.min(120, Math.max(1, args.timeoutS ?? 30)) + 15) * 1000;
+  return requestJson(options, "/move", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(args) }, budget);
+}
+function shellLook(options, args) {
+  return requestJson(options, "/look", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(args) }, 20000);
+}
+function shellPlayers(options) {
+  return requestJson(options, "/players");
+}
+function shellInputs(options) {
+  return requestJson(options, "/inputs");
+}
+function shellRun(options, args) {
+  const budget = (Math.min(3600, Math.max(1, args.timeoutSec ?? 300)) + 30) * 1000;
+  return requestJson(options, "/run", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(args) }, budget);
+}
+function shellDepart(options, reason) {
+  return requestJson(options, "/depart", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ reason }) });
+}
+
+// ../../apps/cf-kernel/src/_entry/headless-room-host/session/registry.ts
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import path from "path";
+function sessionDir(env) {
+  const explicit = env.SPAWN_CLIENT_SESSION_DIR?.trim();
+  if (explicit)
+    return explicit;
+  const home = env.HOME?.trim();
+  return home ? path.join(home, ".spawn", "client-sessions") : path.join(tmpdir(), "spawn-client-sessions");
+}
+var registryPath = (dir) => path.join(dir, "registry.json");
+function sessionLogPath(dir, name) {
+  return path.join(dir, "logs", `${name}.log`);
+}
+function isSessionRecord(value) {
+  if (typeof value !== "object" || value === null)
+    return false;
+  return typeof Reflect.get(value, "name") === "string" && typeof Reflect.get(value, "pid") === "number" && typeof Reflect.get(value, "httpPort") === "number" && typeof Reflect.get(value, "roomId") === "string";
+}
+function loadRegistry(dir) {
+  const file = registryPath(dir);
+  if (!existsSync(file))
+    return [];
+  try {
+    const parsed = JSON.parse(readFileSync(file, "utf8"));
+    if (!Array.isArray(parsed))
+      return [];
+    return parsed.filter(isSessionRecord);
+  } catch {
+    return [];
+  }
+}
+function saveRegistry(dir, records) {
+  mkdirSync(dir, { recursive: true });
+  const file = registryPath(dir);
+  const tmp = `${file}.tmp-${process.pid}-${Date.now()}`;
+  writeFileSync(tmp, `${JSON.stringify(records, null, 2)}
+`);
+  renameSync(tmp, file);
+}
+function upsertSession(dir, record) {
+  const records = loadRegistry(dir).filter((existing) => existing.name !== record.name);
+  records.push(record);
+  saveRegistry(dir, records);
+}
+function removeSession(dir, name) {
+  saveRegistry(dir, loadRegistry(dir).filter((existing) => existing.name !== name));
+}
+function pidAlive(pid, kill = process.kill.bind(process)) {
+  try {
+    kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function loadAndReap(dir, isAlive = pidAlive) {
+  const records = loadRegistry(dir);
+  const live = records.filter((record) => isAlive(record.pid));
+  const reaped = records.filter((record) => !isAlive(record.pid));
+  if (reaped.length > 0)
+    saveRegistry(dir, live);
+  return { live, reaped };
+}
+function resolveSession(records, name) {
+  if (name) {
+    const found = records.find((record) => record.name === name);
+    return found ?? `no session named "${name}" (live: ${records.map((record) => record.name).join(", ") || "none"})`;
+  }
+  if (records.length === 0)
+    return "no live client sessions \u2014 start one with `spawn client join`";
+  if (records.length > 1)
+    return `multiple live sessions (${records.map((record) => record.name).join(", ")}) \u2014 pass --name`;
+  return records[0];
+}
+
+// ../../apps/cf-kernel/src/_entry/headless-room-host/session/launch.ts
+var DEFAULT_TTL_S = 900;
+var DEFAULT_READY_TIMEOUT_MS = 90000;
+function resolvePlayerName(as) {
+  const raw = as?.trim();
+  if (!raw || raw.toLowerCase() === "probe")
+    return "SPAWN_PROBE (client)";
+  if (raw.toLowerCase() === "savi")
+    return "Savi (client)";
+  if (raw.startsWith("SPAWN_PROBE") || raw.startsWith("Savi"))
+    return raw;
+  return `${raw} (probe)`;
+}
+var REQUIRED_ENV = ["ROOM_HOST_EDGE_ORIGIN", "ROOM_HOST_KILN_ORIGIN", "ROOM_HOST_VARIANT_ID", "SPAWN_AI_PLAYER_APP_ID", "SPAWN_AI_PLAYER_TOKEN_MINT_BEARER"];
+var REQUIRED_SESSION_ENV = ["ROOM_HOST_EDGE_ORIGIN", "ROOM_HOST_KILN_ORIGIN", "ROOM_HOST_VARIANT_ID"];
+var isSessionLaneEnv = (env) => Boolean(env.SPAWN_TOKEN?.trim()) || Boolean(env.SPAWN_WORKSHOP_API?.trim() && env.SPAWN_WORKSHOP_TOKEN?.trim() && env.ROOM_HOST_VARIANT_ID?.trim());
+function missingJoinEnv(env) {
+  const missing = (isSessionLaneEnv(env) ? REQUIRED_SESSION_ENV : REQUIRED_ENV).filter((name) => !env[name]?.trim());
+  if (!env.ROOM_HOST_WORKER_ENTRY?.trim() && !env.ROOM_HOST_ENGINE_VERSION?.trim()) {
+    missing.push("ROOM_HOST_ENGINE_VERSION (or ROOM_HOST_WORKER_ENTRY for source runs)");
+  }
+  return missing;
+}
+function defaultShellEntry() {
+  return path2.resolve(path2.dirname(fileURLToPath(import.meta.url)), "..", "main.ts");
+}
+function freePort() {
+  return new Promise((resolve, reject) => {
+    const server = createServer();
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      const port = typeof address === "object" && address !== null ? address.port : null;
+      server.close(() => port !== null ? resolve(port) : reject(new Error("could not allocate a session port")));
+    });
+  });
+}
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function logTail(logPath, lines = 12) {
+  try {
+    const content = readFileSync2(logPath, "utf8");
+    return content.split(`
+`).filter(Boolean).slice(-lines).join(`
+`);
+  } catch {
+    return "(no log written)";
+  }
+}
+var nonEmpty2 = (value) => {
+  const trimmed = value?.trim();
+  return trimmed !== undefined && trimmed.length > 0 ? trimmed : undefined;
+};
+async function fetchFreshSessionGrant(env, fetchImpl = fetch) {
+  const api = nonEmpty2(env.SPAWN_WORKSHOP_API);
+  const workshopToken = nonEmpty2(env.SPAWN_WORKSHOP_TOKEN);
+  if (!api || !workshopToken)
+    return null;
+  try {
+    const response = await fetchImpl(`${api.replace(/\/+$/, "")}/workshop/io/session-grant`, { headers: { authorization: `Bearer ${workshopToken}` }, signal: AbortSignal.timeout(8000) });
+    if (!response.ok)
+      return null;
+    const body = await response.json().catch(() => null);
+    if (!isObject(body) || typeof body.grantWire !== "string" || !body.grantWire)
+      return null;
+    const engine = isObject(body.engine) ? body.engine : {};
+    return {
+      grantWire: body.grantWire,
+      worldId: typeof body.worldId === "string" && body.worldId ? body.worldId : null,
+      engine: { hash: typeof engine.hash === "string" && engine.hash ? engine.hash : null, semver: typeof engine.semver === "string" && engine.semver ? engine.semver : null }
+    };
+  } catch {
+    return null;
+  }
+}
+function buildChildEnv(env, session) {
+  const childEnv = {};
+  for (const [key, value] of Object.entries(env)) {
+    if (value === undefined)
+      continue;
+    if (key.startsWith("SPAWN_WORKSHOP_") || key.startsWith("SPAWN_CLIENT_") || key.startsWith("SPAWN_BOOTH_"))
+      continue;
+    if (key.startsWith("ROOM_HOST_") || key.startsWith("SPAWN_") || key === "PATH" || key === "HOME" || key === "TMPDIR")
+      childEnv[key] = value;
+  }
+  childEnv.ROOM_HOST_ROOM_ID = session.roomId;
+  childEnv.ROOM_HOST_ROOM_MODE = "dev";
+  childEnv.ROOM_HOST_PORT = String(session.port);
+  childEnv.ROOM_HOST_BIND = nonEmpty2(env.ROOM_HOST_BIND) ?? "127.0.0.1";
+  childEnv.ROOM_HOST_PLAYER_NAME = session.playerName;
+  childEnv.ROOM_HOST_TTL_S = String(session.ttlS);
+  childEnv.ROOM_HOST_DEPART_ON_FOREIGN_PRESENCE = "false";
+  if (session.bodyModelUrl !== undefined)
+    childEnv.ROOM_HOST_CHARACTER_MODEL_URL = session.bodyModelUrl;
+  if (session.bodyMaterials !== undefined)
+    childEnv.ROOM_HOST_CHARACTER_MATERIALS_JSON = JSON.stringify(session.bodyMaterials);
+  return childEnv;
+}
+async function waitForConnected(args) {
+  const deadline = Date.now() + args.readyBudgetMs;
+  let lastHealth = null;
+  for (;; ) {
+    if (!args.isAlive(args.pid)) {
+      throw new Error(`session shell exited before it connected \u2014 last log lines:
+${logTail(args.logPath)}`);
+    }
+    try {
+      lastHealth = await shellHealth({ baseUrl: args.baseUrl, fetchImpl: args.fetchImpl, timeoutMs: 3000 });
+      if (lastHealth.phase === "connected" || lastHealth.phase === "hosting")
+        return lastHealth;
+      if (lastHealth.phase === "terminal")
+        throw new Error(`session shell went terminal during boot: ${lastHealth.engineNote ?? "unknown"}`);
+    } catch (error) {
+      if (error instanceof Error && error.message.includes("terminal"))
+        throw error;
+    }
+    if (Date.now() >= deadline) {
+      throw new Error(`session shell did not reach a connected phase within ${args.readyBudgetMs}ms (last: ${lastHealth?.phase ?? "unreachable"}) \u2014 log tail:
+${logTail(args.logPath)}`);
+    }
+    await sleep(500);
+  }
+}
+async function joinSession(deps, options) {
+  const world = nonEmpty2(options.world);
+  let account = null;
+  if (world !== undefined) {
+    if (!isAccountToken(deps.env.SPAWN_TOKEN)) {
+      throw new Error(`spawn client join ${world}: this box's SPAWN_TOKEN is a session grant for its own world, not an account token \u2014 drop the world to join here, or set SPAWN_TOKEN=sak_\u2026 (your account token) to join ${world}`);
+    }
+    const resolved = await resolveAccountJoin({ env: deps.env, ...deps.fetchImpl ? { fetchImpl: deps.fetchImpl } : {} }, { world, ...options.agentActorId !== undefined ? { agentActorId: options.agentActorId } : {} });
+    if (!resolved.ok)
+      throw new Error(`spawn client join ${world}: ${resolved.verdict}`);
+    account = resolved;
+  } else if (isAccountToken(deps.env.SPAWN_TOKEN)) {
+    throw new Error("spawn client join: SPAWN_TOKEN is your account token \u2014 name the world to play: spawn client join @user/world (or its play URL / uuid)");
+  }
+  const fresh = account ? null : await fetchFreshSessionGrant(deps.env, deps.fetchImpl);
+  const env = account ? { ...deps.env, ...account.env } : fresh ? {
+    ...deps.env,
+    SPAWN_TOKEN: fresh.grantWire,
+    ...fresh.worldId ? { ROOM_HOST_VARIANT_ID: fresh.worldId } : {},
+    ...fresh.engine.hash ? { ROOM_HOST_ENGINE_VERSION: fresh.engine.hash } : {},
+    ...fresh.engine.semver ? { ROOM_HOST_ENGINE_SEMVER: fresh.engine.semver } : {}
+  } : deps.env;
+  const missing = missingJoinEnv(env);
+  if (missing.length > 0) {
+    throw new Error(`spawn client join needs env this shell does not carry: ${missing.join(", ")} \u2014 see docs/headless-room-host.md for the ROOM_HOST_* contract`);
+  }
+  const dir = sessionDir(env);
+  const name = nonEmpty2(options.name) ?? "default";
+  if (!/^[a-zA-Z0-9._-]{1,64}$/.test(name))
+    throw new Error(`session name "${name}" must be 1-64 chars of [a-zA-Z0-9._-]`);
+  const isAlive = deps.isAlive ?? pidAlive;
+  const existing = loadRegistry(dir).find((record2) => record2.name === name && isAlive(record2.pid));
+  if (existing)
+    throw new Error(`session "${name}" is already live (pid ${existing.pid}, room ${existing.roomId}) \u2014 leave it first or pass a different --name`);
+  const port = await freePort();
+  if (isSessionLaneEnv(env) && nonEmpty2(options.roomId) !== undefined) {
+    throw new Error("spawn client join: --room does not apply on a 6.0 session (the world-native room IS the world) \u2014 drop the flag");
+  }
+  const roomId = isSessionLaneEnv(env) ? nonEmpty2(env.ROOM_HOST_VARIANT_ID) ?? "" : nonEmpty2(options.roomId) ?? nonEmpty2(env.ROOM_HOST_ROOM_ID) ?? "room-1";
+  const playerName = account ? nonEmpty2(options.as) ?? account.name ?? account.handle ?? "agent" : resolvePlayerName(options.as);
+  const ttlS = Math.max(1, Math.floor(options.ttlS ?? DEFAULT_TTL_S));
+  mkdirSync2(path2.join(dir, "logs"), { recursive: true });
+  const logPath = sessionLogPath(dir, name);
+  if (options.bodyMaterials !== undefined && options.bodyModelUrl === undefined) {
+    throw new Error("--materials-json dresses a session avatar \u2014 pass --body <model url> alongside it");
+  }
+  const childEnv = buildChildEnv(env, { port, roomId, playerName, ttlS, ...options.bodyModelUrl !== undefined ? { bodyModelUrl: options.bodyModelUrl } : {}, ...options.bodyMaterials !== undefined ? { bodyMaterials: options.bodyMaterials } : {} });
+  const entry = nonEmpty2(env.SPAWN_CLIENT_SHELL_ENTRY) ?? defaultShellEntry();
+  if (!entry.startsWith("file:") && !existsSync2(entry)) {
+    throw new Error(`session shell entry not found at ${entry} \u2014 set SPAWN_CLIENT_SHELL_ENTRY (a headless-room-host main.ts/main.mjs)`);
+  }
+  const bunBinary = typeof Bun !== "undefined" ? process.execPath : "bun";
+  const logFd = openSync(logPath, "a");
+  const spawnImpl = deps.spawnImpl ?? ((cmd, args, opts) => {
+    const child = spawn(cmd, args, { env: opts.env, detached: true, stdio: ["ignore", opts.logFd, opts.logFd] });
+    child.unref();
+    if (child.pid === undefined)
+      throw new Error("shell process failed to spawn (no pid)");
+    return { pid: child.pid };
+  });
+  const { pid } = spawnImpl(bunBinary, [entry], { env: childEnv, logFd });
+  const startedAt = new Date().toISOString();
+  let health;
+  try {
+    health = await waitForConnected({
+      baseUrl: `http://127.0.0.1:${port}`,
+      pid,
+      logPath,
+      readyBudgetMs: Math.max(5000, options.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS),
+      isAlive,
+      ...deps.fetchImpl ? { fetchImpl: deps.fetchImpl } : {}
+    });
+  } catch (error) {
+    if (isAlive(pid)) {
+      try {
+        (deps.killImpl ?? ((target, signal) => process.kill(target, signal)))(pid, "SIGTERM");
+      } catch {}
+    }
+    throw error;
+  }
+  const record = {
+    name,
+    pid,
+    httpPort: port,
+    roomId,
+    variantId: env.ROOM_HOST_VARIANT_ID?.trim() ?? "",
+    appId: env.SPAWN_AI_PLAYER_APP_ID?.trim() ?? env.SPAWN_APP_ID?.trim() ?? "",
+    playerName: health.playerName,
+    clientId: health.clientId,
+    entityId: health.selfEntityId,
+    ttlDeadlineMs: health.ttlDeadlineMs,
+    startedAt,
+    logPath,
+    ...account ? { worldAddress: account.worldAddress, handle: account.handle, doorOrigin: account.doorOrigin } : {}
+  };
+  upsertSession(dir, record);
+  return record;
+}
+
+// ../../apps/cf-kernel/src/_entry/headless-room-host/session/screenshot.ts
+import { writeFileSync as writeFileSync2 } from "fs";
+
+// ../../apps/cf-kernel/src/engine/library/math/vec.ts
+function forwardFromYawPitch(yawRadians, pitchRadians) {
+  const cosPitch = Math.cos(pitchRadians);
+  return [-Math.sin(yawRadians) * cosPitch, Math.sin(pitchRadians), -Math.cos(yawRadians) * cosPitch];
+}
+
+// ../../apps/cf-kernel/src/_entry/headless-room-host/session/screenshot.ts
+var EYE_HEIGHT_M = 1.6;
+function viewpointCameraFor(where) {
+  if (!where.position)
+    return null;
+  const yaw = where.cameraYaw ?? 0;
+  const pitch = where.cameraPitch ?? 0;
+  const eye = [where.position.x, where.position.y + EYE_HEIGHT_M, where.position.z];
+  const forward = forwardFromYawPitch(yaw, pitch);
+  const reach = 6;
+  return { position: eye, target: [eye[0] + forward[0] * reach, eye[1] + forward[1] * reach, eye[2] + forward[2] * reach] };
+}
+async function tryClientCapture(env, session, fetchImpl) {
+  const apiOrigin = env.SPAWN_WORKSHOP_API?.trim();
+  const token = env.SPAWN_WORKSHOP_TOKEN?.trim();
+  if (!apiOrigin || !token)
+    return null;
+  let camera = null;
+  try {
+    camera = viewpointCameraFor(await shellWhere({ baseUrl: `http://127.0.0.1:${session.httpPort}`, fetchImpl }));
+  } catch {
+    camera = null;
+  }
+  let response;
+  try {
+    response = await fetchImpl(`${apiOrigin.replace(/\/+$/, "")}/workshop/io/capture`, {
+      method: "POST",
+      headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
+      body: JSON.stringify(camera ? { camera } : {})
+    });
+  } catch (error) {
+    return { failed: `workshop capture door unreachable: ${error instanceof Error ? error.message : String(error)}` };
+  }
+  const body = await response.json().catch(() => null);
+  const answer = typeof body === "object" && body !== null ? body : {};
+  if (!response.ok || answer.ok !== true || typeof answer.dataUrl !== "string") {
+    return { failed: `no connected player client could capture (${answer.message ?? answer.error ?? `HTTP ${response.status}`})` };
+  }
+  return { dataUrl: answer.dataUrl, ...answer.note ? { note: answer.note } : {}, viewpoint: camera !== null };
+}
+async function tryBoothCapture(env, session, fetchImpl) {
+  const boothUrl = env.SPAWN_BOOTH_URL?.trim();
+  if (!boothUrl)
+    return null;
+  const secret = env.SPAWN_BOOTH_SECRET?.trim();
+  let response;
+  try {
+    response = await fetchImpl(new URL("/capture", boothUrl), {
+      method: "POST",
+      headers: { "content-type": "application/json", ...secret ? { authorization: `Bearer ${secret}` } : {} },
+      body: JSON.stringify({ appId: session.appId, requestor: "system", timeoutMs: 45000 })
+    });
+  } catch (error) {
+    return { failed: `booth unreachable: ${error instanceof Error ? error.message : String(error)}` };
+  }
+  if (!response.ok)
+    return { failed: `booth transport error HTTP ${response.status}` };
+  const body = await response.json().catch(() => null);
+  const answer = typeof body === "object" && body !== null ? body : {};
+  if (answer.ok !== true || typeof answer.dataUrl !== "string") {
+    return { failed: `booth capture failed: ${answer.reason ?? "unknown"}${answer.note ? ` \u2014 ${answer.note}` : ""}` };
+  }
+  return { dataUrl: answer.dataUrl };
+}
+function writeDataUrl(dataUrl, outPath) {
+  const comma = dataUrl.indexOf(",");
+  const payload = comma >= 0 ? dataUrl.slice(comma + 1) : dataUrl;
+  writeFileSync2(outPath, Buffer.from(payload, "base64"));
+}
+async function captureScreenshot(env, session, outPath, fetchImpl = fetch) {
+  const degraded = [];
+  const client = await tryClientCapture(env, session, fetchImpl);
+  if (client && "dataUrl" in client) {
+    writeDataUrl(client.dataUrl, outPath);
+    return {
+      tier: "client-pixels",
+      label: client.viewpoint ? "real rendered pixels \u2014 this session's viewpoint, drawn by a connected player's client" : "real rendered pixels \u2014 a connected player's own viewport (the session had no pose yet)",
+      outPath,
+      ...client.note ? { note: client.note } : {}
+    };
+  }
+  if (client && "failed" in client)
+    degraded.push(client.failed);
+  const booth = await tryBoothCapture(env, session, fetchImpl);
+  if (booth && "dataUrl" in booth) {
+    writeDataUrl(booth.dataUrl, outPath);
+    return { tier: "booth-pixels", label: "real rendered pixels via the render booth (its own headless client eye \u2014 not this session's viewpoint)", outPath, ...degraded.length > 0 ? { note: `degraded past a player's client: ${degraded.join("; ")}` } : {} };
+  }
+  if (booth && "failed" in booth)
+    degraded.push(booth.failed);
+  const snapshot = await shellSceneSnapshot({ baseUrl: `http://127.0.0.1:${session.httpPort}`, fetchImpl });
+  const simPath = outPath.endsWith(".json") ? outPath : `${outPath}.sim-only.json`;
+  writeFileSync2(simPath, `${JSON.stringify(snapshot, null, 2)}
+`);
+  return {
+    tier: "sim-only",
+    label: snapshot.label,
+    outPath: simPath,
+    note: degraded.length > 0 ? `degraded to sim-only: ${degraded.join("; ")}` : "no connected player client, no render booth (SPAWN_BOOTH_URL) \u2014 sim-state snapshot, no pixels"
+  };
+}
+
+// ../../apps/cf-kernel/src/_entry/headless-room-host/session/index.ts
+var sleep2 = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var LEAVE_EXIT_WAIT_MS = 15000;
+function createClientSessionLib(env, fetchImpl = fetch) {
+  const dir = sessionDir(env);
+  const resolveLive = (name) => {
+    const { live } = loadAndReap(dir);
+    const resolved = resolveSession(live, name);
+    if (typeof resolved === "string")
+      throw new Error(resolved);
+    return resolved;
+  };
+  const clientFor = (record) => ({ baseUrl: `http://127.0.0.1:${record.httpPort}`, fetchImpl });
+  return {
+    join: (options) => joinSession({ env, fetchImpl }, options),
+    status: async () => {
+      const { live, reaped } = loadAndReap(dir);
+      const rows = [];
+      for (const record of live) {
+        let health = null;
+        try {
+          health = await shellHealth(clientFor(record));
+        } catch {}
+        const ttlDeadlineMs = health?.ttlDeadlineMs ?? null;
+        rows.push({
+          ...record,
+          entityId: health?.selfEntityId ?? record.entityId,
+          alive: true,
+          phase: health?.phase ?? null,
+          connected: health?.connected ?? null,
+          worldTick: health?.worldTick ?? null,
+          ttlRemainingS: ttlDeadlineMs !== null ? Math.max(0, Math.round((ttlDeadlineMs - Date.now()) / 1000)) : null,
+          reaped: false
+        });
+      }
+      return { sessions: rows, reaped: reaped.map((record) => `${record.name} (pid ${record.pid} gone \u2014 registry entry reaped)`) };
+    },
+    where: async (name) => shellWhere(clientFor(resolveLive(name))),
+    move: async (args, name) => shellMove(clientFor(resolveLive(name)), args),
+    look: async (args, name) => shellLook(clientFor(resolveLive(name)), args),
+    screenshot: async (outPath, name) => captureScreenshot(env, resolveLive(name), outPath, fetchImpl),
+    crossing: async (name) => shellCrossing(clientFor(resolveLive(name))),
+    prefetch: async (args, name) => shellCrossingPrefetch(clientFor(resolveLive(name)), args),
+    players: async (name) => shellPlayers(clientFor(resolveLive(name))),
+    inputs: async (name) => shellInputs(clientFor(resolveLive(name))),
+    run: async (args, name) => shellRun(clientFor(resolveLive(name)), args),
+    leave: async (name) => {
+      const record = resolveLive(name);
+      let departRequested = false;
+      try {
+        await shellDepart(clientFor(record), "spawn client leave");
+        departRequested = true;
+      } catch (error) {
+        if (!(error instanceof ShellUnreachableError))
+          throw error;
+        try {
+          process.kill(record.pid, "SIGTERM");
+          departRequested = true;
+        } catch {}
+      }
+      const deadline = Date.now() + LEAVE_EXIT_WAIT_MS;
+      let exited = !pidAlive(record.pid);
+      while (!exited && Date.now() < deadline) {
+        await sleep2(400);
+        exited = !pidAlive(record.pid);
+      }
+      if (exited)
+        removeSession(dir, record.name);
+      return {
+        name: record.name,
+        departed: departRequested,
+        exited,
+        note: exited ? "session departed and exited (graceful path: drain \u2192 journaled despawn where the tier supports it \u2192 lifecycle-hook settle \u2192 socket close)" : `depart requested but the process (pid ${record.pid}) is still running after ${LEAVE_EXIT_WAIT_MS}ms \u2014 check ${record.logPath}`
+      };
+    }
+  };
+}
+export {
+  shellWhere,
+  shellSceneSnapshot,
+  shellRun,
+  shellPlayers,
+  shellMove,
+  shellLook,
+  shellInputs,
+  shellHealth,
+  shellDepart,
+  shellCrossingPrefetch,
+  shellCrossing,
+  sessionDir,
+  resolveSession,
+  resolvePlayerName,
+  resolveAccountJoin,
+  missingJoinEnv,
+  loadAndReap,
+  isAccountToken,
+  createClientSessionLib,
+  ShellUnreachableError,
+  DEFAULT_TTL_S,
+  DEFAULT_SPAWN_ORIGIN,
+  ACCOUNT_TOKEN_PREFIX
+};