@spawnco/client 0.1.0

package/dist/spawn.mjs

@@ -0,0 +1,1389 @@
+// @bun
+// src/bin.ts
+import { existsSync as existsSync2 } from "fs";
+import path3 from "path";
+import { fileURLToPath } from "url";
+
+// ../../apps/savi-workshop/cli/cli.ts
+import { existsSync } from "fs";
+import { mkdir, readFile, stat as stat2, writeFile as writeFile2 } from "fs/promises";
+import { tmpdir } from "os";
+import path2 from "path";
+
+// ../../apps/savi-workshop/server/io-client.ts
+class IoApiError extends Error {
+  code;
+  status;
+  detail;
+  constructor(code, status, message, detail) {
+    super(message ?? code);
+    this.code = code;
+    this.status = status;
+    this.detail = detail;
+    this.name = "IoApiError";
+  }
+}
+var REF_CORPUS_HEADER = "x-spawn-ref-corpus";
+class IoClient {
+  origin;
+  token;
+  fetchImpl;
+  constructor(options) {
+    this.origin = options.apiOrigin.replace(/\/+$/, "");
+    this.token = options.token;
+    this.fetchImpl = options.fetchImpl ?? fetch;
+  }
+  setToken(token) {
+    if (!token || token === this.token)
+      return false;
+    this.token = token;
+    return true;
+  }
+  async manifest() {
+    const body = await this.request("GET", "/workshop/io/manifest");
+    const files = body.files;
+    return Array.isArray(files) ? files : [];
+  }
+  async presign(op, paths) {
+    if (paths.length === 0)
+      return new Map;
+    const body = await this.request("POST", "/workshop/io/presign", {
+      op,
+      paths
+    });
+    return normalizePresignUrls(body.urls);
+  }
+  async ingest(meta) {
+    const body = await this.request("POST", "/workshop/io/ingest", meta);
+    return body;
+  }
+  async assets() {
+    const body = await this.request("GET", "/workshop/io/assets");
+    const assets = body.assets;
+    return Array.isArray(assets) ? assets : [];
+  }
+  async fetchAsset(reference) {
+    return this.fetchImpl(`${this.origin}${buildAssetDoorPath(reference)}`, {
+      headers: { authorization: `Bearer ${this.token}` }
+    });
+  }
+  async attachments() {
+    const body = await this.request("GET", "/workshop/io/attachments");
+    const attachments = body.attachments;
+    return Array.isArray(attachments) ? attachments : [];
+  }
+  async fetchAttachment(id) {
+    return this.fetchImpl(`${this.origin}/workshop/io/attachments/${encodeURIComponent(id)}`, { headers: { authorization: `Bearer ${this.token}` } });
+  }
+  async refSkills(engine) {
+    const q = engine ? `?engine=${encodeURIComponent(engine)}` : "";
+    const response = await this.fetchImpl(`${this.origin}/workshop/io/ref/skills${q}`, { headers: { authorization: `Bearer ${this.token}` } });
+    if (!response.ok)
+      throw await this.errorFrom(response);
+    const body = await response.json();
+    return {
+      skills: Array.isArray(body.skills) ? body.skills : [],
+      corpus: response.headers.get(REF_CORPUS_HEADER) ?? (typeof body.corpus === "string" ? body.corpus : null)
+    };
+  }
+  async refSkillStream(id, engine) {
+    const q = engine ? `?engine=${encodeURIComponent(engine)}` : "";
+    const response = await this.fetchImpl(`${this.origin}/workshop/io/ref/skills/${encodeURIComponent(id)}${q}`, { headers: { authorization: `Bearer ${this.token}` } });
+    if (!response.ok)
+      throw await this.errorFrom(response);
+    return response;
+  }
+  async refSkill(id, engine) {
+    return (await this.refSkillStream(id, engine)).text();
+  }
+  async refGrep(pattern, engine) {
+    const q = new URLSearchParams({ q: pattern });
+    if (engine)
+      q.set("engine", engine);
+    const body = await this.request("GET", `/workshop/io/ref/grep?${q.toString()}`);
+    return {
+      hits: Array.isArray(body.hits) ? body.hits : [],
+      truncated: body.truncated === true
+    };
+  }
+  async toolList(lane) {
+    const q = lane ? `?lane=${encodeURIComponent(lane)}` : "";
+    const body = await this.request("GET", `/workshop/io/tool${q}`);
+    return Array.isArray(body.verbs) ? body.verbs : [];
+  }
+  async toolDescribe(name, lane) {
+    const q = lane ? `?lane=${encodeURIComponent(lane)}` : "";
+    const body = await this.request("GET", `/workshop/io/tool/${encodeURIComponent(name)}${q}`);
+    return body.verb ?? null;
+  }
+  async toolRun(name, args, lane) {
+    const body = await this.request("POST", `/workshop/io/tool/${encodeURIComponent(name)}`, { args, ...lane ? { lane } : {} });
+    return {
+      ok: body.ok === true,
+      kind: typeof body.kind === "string" ? body.kind : "text",
+      code: typeof body.code === "string" ? body.code : undefined,
+      text: typeof body.text === "string" ? body.text : "",
+      media: Array.isArray(body.media) ? body.media : undefined
+    };
+  }
+  async errorFrom(response) {
+    let code = `HTTP_${response.status}`;
+    let detail;
+    try {
+      const parsed = await response.json();
+      if (parsed && typeof parsed.error === "string")
+        code = parsed.error;
+      if (parsed && typeof parsed.message === "string" && parsed.message.length > 0) {
+        detail = parsed.message;
+        if (Array.isArray(parsed.available) && parsed.available.length > 0) {
+          detail += ` \u2014 available: ${parsed.available.join(", ")}`;
+        }
+      }
+    } catch {}
+    return new IoApiError(code, response.status, undefined, detail);
+  }
+  async request(method, path, body) {
+    const response = await this.fetchImpl(`${this.origin}${path}`, {
+      method,
+      headers: {
+        authorization: `Bearer ${this.token}`,
+        ...body !== undefined ? { "content-type": "application/json" } : {}
+      },
+      ...body !== undefined ? { body: JSON.stringify(body) } : {}
+    });
+    if (!response.ok) {
+      let code = `HTTP_${response.status}`;
+      let detail;
+      try {
+        const parsed = await response.json();
+        if (parsed && typeof parsed.error === "string")
+          code = parsed.error;
+        if (parsed && typeof parsed.message === "string" && parsed.message.length > 0) {
+          detail = parsed.message;
+        }
+      } catch {}
+      throw new IoApiError(code, response.status, `${method} ${path} \u2192 ${code}${detail ? `: ${detail}` : ""}`, detail);
+    }
+    return response.json();
+  }
+}
+function buildAssetDoorPath(reference) {
+  const queryIndex = reference.indexOf("?");
+  const path = queryIndex === -1 ? reference : reference.slice(0, queryIndex);
+  const query = queryIndex === -1 ? "" : reference.slice(queryIndex);
+  const encodedPath = path.split("/").map((segment) => encodeURIComponent(segment)).join("/");
+  return `/workshop/io/asset/${encodedPath}${query}`;
+}
+function normalizePresignUrls(urls) {
+  const map = new Map;
+  if (Array.isArray(urls)) {
+    for (const entry of urls) {
+      if (!entry || typeof entry !== "object")
+        continue;
+      const record = entry;
+      if (typeof record.path === "string" && typeof record.url === "string") {
+        map.set(record.path, record.url);
+        continue;
+      }
+      for (const [key, value] of Object.entries(record)) {
+        if (typeof value === "string")
+          map.set(key, value);
+      }
+    }
+    return map;
+  }
+  if (urls && typeof urls === "object") {
+    for (const [key, value] of Object.entries(urls)) {
+      if (typeof value === "string")
+        map.set(key, value);
+    }
+  }
+  return map;
+}
+
+// ../../apps/savi-workshop/server/scan.ts
+import { readdir, stat } from "fs/promises";
+import path from "path";
+var MANIFEST_FILENAME = ".workshop-manifest.json";
+async function walkWorkspace(root) {
+  const snapshot = {};
+  const walk = async (dir) => {
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const abs = path.join(dir, entry.name);
+      const rel = path.relative(root, abs).split(path.sep).join("/");
+      if (rel === MANIFEST_FILENAME)
+        continue;
+      if (entry.isDirectory()) {
+        await walk(abs);
+      } else if (entry.isFile()) {
+        try {
+          const st = await stat(abs);
+          snapshot[rel] = { size: st.size, mtimeMs: st.mtimeMs };
+        } catch {}
+      }
+    }
+  };
+  await walk(root);
+  return snapshot;
+}
+
+// ../../apps/savi-workshop/server/status.ts
+import { writeFile } from "fs/promises";
+var STATUS_FILE_PATH = "/tmp/.workshop-status.json";
+class StatusFile {
+  path;
+  appId;
+  quotaSoftBytes;
+  quotaHardBytes;
+  startedAt = new Date().toISOString();
+  budget = null;
+  constructor(path2, appId, quotaSoftBytes, quotaHardBytes) {
+    this.path = path2;
+    this.appId = appId;
+    this.quotaSoftBytes = quotaSoftBytes;
+    this.quotaHardBytes = quotaHardBytes;
+  }
+  recordBudgetHeader(raw) {
+    if (raw === null || raw === "")
+      return;
+    try {
+      this.budget = JSON.parse(raw);
+    } catch {
+      this.budget = raw;
+    }
+  }
+  async write(workspace) {
+    const status = {
+      started_at: this.startedAt,
+      updated_at: new Date().toISOString(),
+      app_id: this.appId,
+      workspace_bytes: workspace.bytes,
+      workspace_files: workspace.files,
+      quota_soft_bytes: this.quotaSoftBytes,
+      quota_hard_bytes: this.quotaHardBytes,
+      budget: this.budget
+    };
+    try {
+      await writeFile(this.path, `${JSON.stringify(status, null, 2)}
+`);
+    } catch (error) {
+      console.error(`[workshop] status write failed: ${String(error)}`);
+    }
+  }
+}
+
+// ../../apps/savi-workshop/cli/cli.ts
+var UPLOAD_CAP_BYTES = 100 * 1024 * 1024;
+var USAGE = `spawn \u2014 bridge between this workspace and the Spawn project
+
+usage:
+  spawn upload <file> [--name <display>]   upload a file as a project asset
+  spawn fetch <url-or-cdn-ref> [dest]      download into the workspace
+  spawn attachments list                   creator-shared reference images from this game's chat
+  spawn attachments download <id> [dest]   pull one into the workspace (images only)
+  spawn ls [--assets|--workspace]          list uploaded assets / workspace files
+  spawn status                             workspace quota, budget, uptime
+
+  spawn ref ls                             the engine's skills \u2014 the craft, one line each
+  spawn ref read <skill>                   one skill, WHOLE (read it before building in its territory)
+  spawn ref grep <regex>                   which skill teaches a word
+
+  spawn tools                              the room's own verbs this shell carries (one line each)
+  spawn <tool> [action] [words\u2026] [--key value \u2026]
+                                           run one of them \u2014 the same tool the room runs, through
+                                           this shell: a value that reads as JSON is JSON, a bare
+                                           --flag is true; an image it answers is written under
+                                           /workspace/spawn-media/
+  spawn <tool> --help                      the whole contract: description + every input key
+
+  spawn client join [<@user/world>] [--as <name>] [--body <model-url>]
+                    [--materials-json <path-or-inline>] [--ttl <s>] [--name <session>]
+                                           a real player in the world \u2014 this box's own grant, or
+                                           (with SPAWN_TOKEN=sak_\u2026 + a world) your account's
+  spawn client move <x> <y> <z> | --to <objectId> [--speed walk|run|teleport]
+                                           walk the body by input (teleport = labeled write)
+  spawn client look --at <objectId|x,y,z>  aim the session's view
+  spawn client where                       position + world + place + nearest objects (sim read)
+  spawn client players                     every player body: who is here, who is parked
+  spawn client inputs                      the world's declared inputs \u2014 what a key does here
+  spawn client run <file> | -e "<source>"  run a play script against the live client
+  spawn client crossing                    resident world, portal directives heard, slot census
+  spawn client screenshot [--out <file>]   booth pixels when configured, else labeled sim-only
+  spawn client leave                       graceful depart \u2014 despawn journaled before close
+  spawn client status                      session liveness, entity id, ttl remaining
+  (client verbs take [--name <session>]; sessions self-expire at ttl)
+
+fetch takes any https URL, or a /cdn/<filename> reference exactly as the
+game spec carries it (query variants like ?animated=run-loop included).
+`;
+async function runCli(argv, deps) {
+  const [command, ...rest] = argv;
+  switch (command) {
+    case "upload":
+      return upload(rest, deps);
+    case "fetch":
+      return fetchCommand(rest, deps);
+    case "attachments":
+      return attachments(rest, deps);
+    case "ls":
+      return ls(rest, deps);
+    case "status":
+      return status(deps);
+    case "client":
+      return client(rest, deps);
+    case "ref":
+      return ref(rest, deps);
+    case "tools":
+      return roomTools(deps);
+    case undefined:
+    case "help":
+    case "--help":
+    case "-h":
+      deps.stdout(USAGE);
+      return command === undefined ? 2 : 0;
+    default:
+      return roomVerb(command, rest, deps);
+  }
+}
+var SPAWN_MEDIA_DIR = "spawn-media";
+var extensionFor = (mediaType) => {
+  const subtype = mediaType.split("/")[1]?.split(";")[0]?.toLowerCase() ?? "";
+  if (subtype === "jpeg")
+    return "jpg";
+  if (subtype === "svg+xml")
+    return "svg";
+  return subtype.replace(/[^a-z0-9]/g, "") || "bin";
+};
+var laneOf = (deps) => deps.env.SPAWN_WISP_ID?.trim() || null;
+function renderContract(verb) {
+  const schema = verb.inputSchema;
+  const lines = [
+    `spawn ${verb.name} \u2014 ${verb.hook}`,
+    "",
+    verb.description,
+    "",
+    `usage: spawn ${verb.name}${schema?.properties?.action ? " <action>" : ""}${verb.positional.map((p) => ` [<${p}>]`).join("")} [--key value \u2026]`
+  ];
+  const properties = schema?.properties ?? {};
+  const required = new Set(schema?.required ?? []);
+  const keys = Object.keys(properties);
+  if (keys.length > 0) {
+    lines.push("", "input:");
+    for (const key of keys) {
+      const property = properties[key] ?? {};
+      const type = Array.isArray(property.enum) ? property.enum.map(String).join(" | ") : Array.isArray(property.type) ? property.type.join(" | ") : typeof property.type === "string" ? property.type : "json";
+      const description = typeof property.description === "string" ? property.description : "";
+      lines.push(`  --${key} <${type}>${required.has(key) ? "  (required)" : ""}${description ? `
+      ${description}` : ""}`);
+    }
+  }
+  if (verb.positional.length > 0 || schema?.properties?.action) {
+    lines.push("", `bare words fill: ${[...schema?.properties?.action ? ["action"] : [], ...verb.positional].join(", ")}`);
+  }
+  return lines.join(`
+`);
+}
+async function roomTools(deps) {
+  const client = makeClient(deps);
+  if (!client)
+    return 1;
+  let verbs;
+  try {
+    verbs = await client.toolList(laneOf(deps));
+  } catch (error) {
+    deps.stderr(`spawn tools: ${describeToolDoorError(error)}`);
+    return 1;
+  }
+  if (verbs.length === 0) {
+    deps.stdout("this shell carries none of the room's verbs");
+    return 0;
+  }
+  const width = Math.min(28, Math.max(...verbs.map((v) => v.name.length)));
+  for (const verb of verbs)
+    deps.stdout(`${verb.name.padEnd(width)}  ${verb.hook}`);
+  deps.stdout(`
+${verbs.length} verbs \u2014 \`spawn <tool> --help\` for one's whole contract`);
+  return 0;
+}
+async function roomVerb(name, args, deps) {
+  const client = makeClient(deps);
+  if (!client) {
+    deps.stderr(`spawn: unknown command "${name}"
+
+${USAGE}`);
+    return 2;
+  }
+  const lane = laneOf(deps);
+  if (args.includes("--help") || args.includes("-h")) {
+    try {
+      const verb = await client.toolDescribe(name, lane);
+      if (!verb) {
+        deps.stderr(`spawn: unknown command "${name}"
+
+${USAGE}`);
+        return 2;
+      }
+      deps.stdout(renderContract(verb));
+      return 0;
+    } catch (error) {
+      if (error instanceof IoApiError && error.code === "UNKNOWN_VERB") {
+        deps.stderr(`spawn: unknown command "${name}"
+
+${USAGE}`);
+        return 2;
+      }
+      deps.stderr(`spawn ${name} --help: ${describeToolDoorError(error)}`);
+      return 1;
+    }
+  }
+  let answer;
+  try {
+    answer = await client.toolRun(name, args, lane);
+  } catch (error) {
+    deps.stderr(`spawn ${name}: ${describeToolDoorError(error)}`);
+    return 1;
+  }
+  if (!answer.ok && answer.code === "tool_unavailable") {
+    deps.stderr(`spawn: unknown command "${name}"
+
+${USAGE}`);
+    return 2;
+  }
+  const mediaLines = [];
+  for (const [index, item] of (answer.media ?? []).entries()) {
+    const dir = path2.resolve(deps.cwd ?? process.cwd(), SPAWN_MEDIA_DIR);
+    const file = path2.join(dir, `${name}-${Date.now()}-${index + 1}.${extensionFor(item.mediaType)}`);
+    try {
+      await mkdir(dir, { recursive: true });
+      await writeFile2(file, Buffer.from(item.data, "base64"));
+      mediaLines.push(`image saved: ${file} (${item.mediaType}${item.label ? ` \u2014 ${item.label}` : ""}) \u2014 \`spawn upload\` it and look { reference: <the printed url> } to see it`);
+    } catch (error) {
+      mediaLines.push(`image not saved (${String(error)}) \u2014 ${item.mediaType}${item.label ? ` \u2014 ${item.label}` : ""}`);
+    }
+  }
+  const out = [answer.text, ...mediaLines].filter((line) => line.length > 0);
+  (answer.ok ? deps.stdout : deps.stderr)(out.join(`
+`));
+  return answer.ok ? 0 : 1;
+}
+function describeToolDoorError(error) {
+  if (error instanceof IoApiError) {
+    if (error.code === "WORKSHOP_NOT_CONFIGURED") {
+      return "this environment has no chat-room lane for the room's verbs";
+    }
+    return error.detail ?? error.message;
+  }
+  return String(error);
+}
+var CLIENT_USAGE = `spawn client \u2014 a real engine client in a world, driven from here (your body in the game)
+
+  join [<@user/world>] [--as <name>] [--body <model-url>] [--materials-json <path-or-inline>]
+       [--ttl <s>] [--ready-timeout <ms>] [--name <session>]
+       [--actor <agentActorId>] [--origin <kiln>] [--door <kernel origin>] [--engine <32hex>]
+  move <x> <y> <z> | --to <objectId> [--speed walk|run|teleport] [--timeout <s>] [--name <session>]
+  look --at <objectId|x,y,z> [--name <session>]
+  where [--name <session>]
+  players [--name <session>]                     (every player body: entity id, name, you, parked)
+  inputs [--name <session>]                      (the world's declared actions + axes + their keys)
+  run <file> | -e "<source>" [--timeout <s>] [--name <session>]
+                                                 (a play module \u2014 export default async (play) => {\u2026} \u2014
+                                                   against the LIVE client; the transcript is the answer)
+  crossing [--name <session>]                    (resident world \xB7 portal directives the sim posted
+                                                   and what the shell did \xB7 the world-slot census)
+  prefetch --world <id> --manifest <hash> --hex <32hex> [--name <session>]
+                                                 (arm the approach: the sim boots the target into
+                                                   a foreign slot before you walk the portal)
+  screenshot [--out <file>] [--name <session>]   (real pixels through a CONNECTED PLAYER'S client,
+                                                   rendered from this session's viewpoint; sim-only
+                                                   JSON when nobody is connected \u2014 the tier is printed)
+  leave [--name <session>]
+  status
+
+TWO WAYS IN. With YOUR ACCOUNT TOKEN (SPAWN_TOKEN=sak_\u2026, the token signup or an invite answered)
+name the world: \`spawn client join @alice/gauntlet\` resolves the address, mints a session grant
+for that world at kiln's play doors, and attaches a real player \u2014 a body the room sees, wearing
+your account's name. --origin (SPAWN_ORIGIN) points at another kiln; --door (SPAWN_DOOR_ORIGIN)
+names the kernel's session door when the deployment spells none; --engine (SPAWN_ENGINE) pins the
+engine build when the door names none; --actor is for a person's token embodying a seat it minted.
+On a box that already holds a session grant (Savi's workshop), \`spawn client join\` with no world
+attaches with that grant \u2014 the same boot a browser tab performs.
+Walking into a portal crosses for real: the sim names the session the traveler and the shell
+re-dials the session to the target world (where/crossing then report the new world).
+Pre-6.0 rooms join as a DEV-room client (SPAWN_PROBE/Savi family). Sessions self-expire at
+--ttl (default 900s); leave journals the despawn before the socket closes. --body dresses the
+avatar; --materials-json paints its parts (the a3dc/model materials map \u2014 a JSON file path or
+inline JSON; requires --body).
+
+THE PLAY SCRIPT (\`run\`): \`play\` is your body and senses \u2014 hold(axis, v) / release(axis?) \xB7
+press(action) \xB7 key("KeyE") (resolved through this world's own bindings; an unbound key is a
+finding) \xB7 moveTo(target) \xB7 lookAt(target) \xB7 teleport(x, y, z) (the one labeled write) \xB7
+pose() \xB7 where() \xB7 players() \xB7 state(entityId?) (an entity's tome/state; none = the world's
+world/state ledger) \xB7 entities() \xB7 inputs() \xB7 until(check, {timeoutSec}) \xB7 seconds(n) \xB7 log(line).
+The transcript and the return value come back; a thrown error or a timeout is an ok:false
+transcript, and every held input is released when the script ends.
+`;
+async function resolveMaterialsFlag(raw) {
+  let text = raw;
+  if (!raw.trimStart().startsWith("{")) {
+    try {
+      text = await readFile(raw, "utf8");
+    } catch (error) {
+      return `--materials-json: could not read "${raw}" as a file (${String(error)}) \u2014 pass a JSON file path or inline JSON starting with '{'`;
+    }
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch (error) {
+    return `--materials-json: invalid JSON (${error instanceof Error ? error.message : String(error)})`;
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return "--materials-json: must be a JSON object mapping part names to material entries";
+  }
+  return parsed;
+}
+async function loadSessionLib(deps) {
+  if (deps.sessionLibFactory)
+    return deps.sessionLibFactory(deps.env);
+  if (deps.sessionLib)
+    return deps.sessionLib;
+  const explicit = deps.env.SPAWN_CLIENT_SESSION_LIB?.trim();
+  const inRepo = new URL("../../cf-kernel/src/_entry/headless-room-host/session/index.ts", import.meta.url);
+  const candidate = explicit ?? (existsSync(inRepo.pathname) ? inRepo.href : null);
+  if (!candidate) {
+    deps.stderr("spawn client: session library not available in this shell \u2014 set SPAWN_CLIENT_SESSION_LIB to a built session library (repo checkouts find apps/cf-kernel/src/_entry/headless-room-host/session automatically)");
+    return null;
+  }
+  let mod;
+  try {
+    mod = await import(candidate);
+  } catch (error) {
+    deps.stderr(`spawn client: session library failed to load from ${candidate}: ${String(error)}`);
+    return null;
+  }
+  const factory = mod.createClientSessionLib;
+  if (typeof factory !== "function") {
+    deps.stderr(`spawn client: ${candidate} exports no createClientSessionLib`);
+    return null;
+  }
+  return factory(deps.env, deps.fetchImpl);
+}
+var fmtPos = (position) => position ? `(${position.x.toFixed(1)}, ${position.y.toFixed(1)}, ${position.z.toFixed(1)})` : "(unknown)";
+var SENSES_CARD = [
+  "you are embodied \u2014 your senses and hands:",
+  "  eyes : spawn client where \xB7 players \xB7 inputs        (pose + nearby \xB7 every body \xB7 what a key does here)",
+  "  hands: spawn client move <x> <y> <z> | --to <id> \xB7 look --at <id|x,y,z>",
+  '  play : spawn client run play.js | -e "export default async (play) => { \u2026 }"',
+  "         play.key('KeyE') \xB7 press(action) \xB7 hold/release \xB7 moveTo \xB7 lookAt \xB7 pose() \xB7 players() \xB7 state() \xB7 until()",
+  "  leave: spawn client leave                           (the body despawns; the session self-expires at --ttl)"
+].join(`
+`);
+async function client(args, deps) {
+  const [verb, ...rest] = args;
+  if (!verb || verb === "help" || verb === "--help") {
+    deps.stdout(CLIENT_USAGE);
+    return verb ? 0 : 2;
+  }
+  const { positional, flags } = parseArgs(rest, [
+    "--room",
+    "--as",
+    "--body",
+    "--materials-json",
+    "--ttl",
+    "--ready-timeout",
+    "--name",
+    "--to",
+    "--speed",
+    "--timeout",
+    "--at",
+    "--out",
+    "--world",
+    "--manifest",
+    "--hex",
+    "--actor",
+    "--origin",
+    "--door",
+    "--engine",
+    "-e"
+  ]);
+  const env = {
+    ...deps.env,
+    ...flags["--origin"] ? { SPAWN_ORIGIN: flags["--origin"] } : {},
+    ...flags["--door"] ? { SPAWN_DOOR_ORIGIN: flags["--door"] } : {},
+    ...flags["--engine"] ? { SPAWN_ENGINE: flags["--engine"] } : {}
+  };
+  const lib = await loadSessionLib({ ...deps, env });
+  if (!lib)
+    return 1;
+  const ownSession = env.SPAWN_SESSION || undefined;
+  const sessionName = flags["--name"] || ownSession;
+  if (ownSession && flags["--name"] && flags["--name"] !== ownSession && verb !== "join" && verb !== "status") {
+    deps.stderr(`spawn client ${verb}: your body is session "${ownSession}" \u2014 you never drive another agent's session ("${flags["--name"]}"). Each agent controls its own body; to move another agent, brief it.`);
+    return 2;
+  }
+  try {
+    switch (verb) {
+      case "join": {
+        const ttlRaw = flags["--ttl"];
+        const ttlS = ttlRaw !== undefined && ttlRaw !== "" ? Number(ttlRaw) : undefined;
+        if (ttlS !== undefined && (!Number.isFinite(ttlS) || ttlS <= 0)) {
+          deps.stderr(`spawn client join: --ttl must be a positive number of seconds, got "${ttlRaw}"`);
+          return 2;
+        }
+        const readyRaw = flags["--ready-timeout"];
+        const readyTimeoutMs = readyRaw !== undefined && readyRaw !== "" ? Number(readyRaw) : undefined;
+        if (readyTimeoutMs !== undefined && (!Number.isFinite(readyTimeoutMs) || readyTimeoutMs <= 0)) {
+          deps.stderr(`spawn client join: --ready-timeout must be a positive number of milliseconds, got "${readyRaw}"`);
+          return 2;
+        }
+        const world = positional[0] || undefined;
+        const agentActorId = flags["--actor"] || undefined;
+        let bodyMaterials;
+        const materialsRaw = flags["--materials-json"];
+        if (materialsRaw) {
+          if (!flags["--body"]) {
+            deps.stderr("spawn client join: --materials-json paints a session avatar \u2014 pass --body <model-url> alongside it");
+            return 2;
+          }
+          const resolved = await resolveMaterialsFlag(materialsRaw);
+          if (typeof resolved === "string") {
+            deps.stderr(`spawn client join: ${resolved}`);
+            return 2;
+          }
+          bodyMaterials = resolved;
+        }
+        const record = await lib.join({
+          name: sessionName,
+          ...world !== undefined ? { world } : {},
+          ...agentActorId !== undefined ? { agentActorId } : {},
+          roomId: flags["--room"] || undefined,
+          as: flags["--as"] || undefined,
+          bodyModelUrl: flags["--body"] || undefined,
+          ...bodyMaterials !== undefined ? { bodyMaterials } : {},
+          ttlS,
+          ...readyTimeoutMs !== undefined ? { readyTimeoutMs } : {}
+        });
+        deps.stdout(`joined: session "${record.name}" \u2192 ${record.worldAddress ? `${record.worldAddress} (world ${record.roomId})` : `room ${record.roomId}`} as "${record.playerName}"${record.handle ? ` [${record.handle}]` : ""} (pid ${record.pid}, http :${record.httpPort})`);
+        deps.stdout(`entity: ${record.entityId ?? "(spawning \u2014 check status)"}`);
+        if (record.ttlDeadlineMs)
+          deps.stdout(`ttl: self-departs at ${new Date(record.ttlDeadlineMs).toISOString()}`);
+        deps.stdout(`log: ${record.logPath}`);
+        deps.stdout(SENSES_CARD);
+        return 0;
+      }
+      case "players": {
+        if (!lib.players) {
+          deps.stderr("spawn client players: this session library predates the play surface");
+          return 1;
+        }
+        const view = await lib.players(sessionName);
+        if (view.players.length === 0)
+          deps.stdout("no player bodies in this world yet");
+        for (const row of view.players) {
+          deps.stdout(`  ${row.isSelf ? "you" : "   "}  ${fmtPos(row.position).padEnd(22)}  ${row.entityId}${row.displayName ? `  "${row.displayName}"` : ""}${row.parked ? "  (parked \u2014 no socket drives this body)" : ""}`);
+        }
+        return 0;
+      }
+      case "inputs": {
+        if (!lib.inputs) {
+          deps.stderr("spawn client inputs: this session library predates the play surface");
+          return 1;
+        }
+        const view = await lib.inputs(sessionName);
+        if (!view.inputs) {
+          deps.stdout("inputs: not readable yet (no spec mounted on this session \u2014 try again in a moment)");
+          return 1;
+        }
+        deps.stdout(JSON.stringify(view.inputs, null, 2));
+        return 0;
+      }
+      case "run": {
+        if (!lib.run) {
+          deps.stderr("spawn client run: this session library predates the play surface");
+          return 1;
+        }
+        const inline = flags["-e"];
+        const file = positional[0];
+        if (!inline && !file) {
+          deps.stderr('spawn client run: needs a module path or -e "<source>" \u2014 export default async (play) => { \u2026 }');
+          return 2;
+        }
+        let scriptPath;
+        if (inline) {
+          const scriptsDir = path2.join(sessionScriptsDir(env), "scripts");
+          await mkdir(scriptsDir, { recursive: true });
+          scriptPath = path2.join(scriptsDir, `inline-${Date.now()}.mjs`);
+          await writeFile2(scriptPath, inline.trim().startsWith("export") ? inline : `export default async (play) => {
+${inline}
+};
+`);
+        } else {
+          scriptPath = path2.resolve(deps.cwd ?? process.cwd(), file);
+        }
+        const timeoutRaw = Number(flags["--timeout"]);
+        const timeoutSec = Number.isFinite(timeoutRaw) && timeoutRaw > 0 ? timeoutRaw : undefined;
+        const outcome = await lib.run({
+          scriptPath,
+          ...timeoutSec !== undefined ? { timeoutSec } : {}
+        }, sessionName);
+        for (const ev of outcome.events) {
+          deps.stdout(`  ${(ev.atMs / 1000).toFixed(1).padStart(6)}s  ${ev.kind.padEnd(9)} ${ev.detail}`);
+        }
+        const resultTail = outcome.result === undefined || outcome.result === null ? "" : `  \u2192 ${typeof outcome.result === "string" ? outcome.result : JSON.stringify(outcome.result)}`;
+        (outcome.ok ? deps.stdout : deps.stderr)(`play ${outcome.ok ? "ok" : "FAILED"} in ${(outcome.elapsedMs / 1000).toFixed(1)}s${outcome.error ? ` \u2014 ${outcome.error}` : ""}${resultTail}`);
+        return outcome.ok ? 0 : 1;
+      }
+      case "move": {
+        const speedRaw = flags["--speed"] || "walk";
+        if (speedRaw !== "walk" && speedRaw !== "run" && speedRaw !== "teleport") {
+          deps.stderr(`spawn client move: --speed must be walk|run|teleport, got "${speedRaw}"`);
+          return 2;
+        }
+        const timeoutRaw = flags["--timeout"];
+        const timeoutS = timeoutRaw !== undefined && timeoutRaw !== "" ? Number(timeoutRaw) : undefined;
+        let moveArgs;
+        if (flags["--to"]) {
+          moveArgs = { to: flags["--to"], speed: speedRaw, timeoutS };
+        } else {
+          const [x, y, z] = positional.map(Number);
+          if (positional.length < 3 || ![x, y, z].every(Number.isFinite)) {
+            deps.stderr("spawn client move: needs <x> <y> <z> or --to <objectId>");
+            return 2;
+          }
+          moveArgs = { x, y, z, speed: speedRaw, timeoutS };
+        }
+        const outcome = await lib.move(moveArgs, sessionName);
+        const line = `${outcome.arrived ? "arrived" : "did not arrive"} [${outcome.mode}] at ${fmtPos(outcome.finalPosition)}${outcome.distanceRemaining !== null ? ` \u2014 ${outcome.distanceRemaining.toFixed(1)}m from target` : ""}`;
+        (outcome.arrived ? deps.stdout : deps.stderr)(`${line}
+${outcome.note}`);
+        return outcome.arrived ? 0 : 1;
+      }
+      case "look": {
+        const at = flags["--at"] || positional[0];
+        if (!at) {
+          deps.stderr("spawn client look: needs --at <objectId|x,y,z>");
+          return 2;
+        }
+        const outcome = await lib.look({ at }, sessionName);
+        (outcome.aimed ? deps.stdout : deps.stderr)(`${outcome.aimed ? "aimed" : "not aimed"}${outcome.yaw !== null ? ` (yaw ${outcome.yaw.toFixed(2)}rad)` : ""} \u2014 ${outcome.note}`);
+        return outcome.aimed ? 0 : 1;
+      }
+      case "where": {
+        const view = await lib.where(sessionName);
+        deps.stdout(`position: ${fmtPos(view.position)}  world: ${view.worldId ?? "?"}  place: ${view.placeId ?? "?"}  entity: ${view.entityId ?? "?"}  [${view.tier}]`);
+        if (view.nearby.length === 0)
+          deps.stdout("nearby: nothing with a position in range");
+        for (const row of view.nearby) {
+          deps.stdout(`  ${row.distance.toFixed(1).padStart(6)}m  ${row.entityId}${row.specId && row.specId !== row.entityId ? `  (spec ${row.specId})` : ""}${row.displayName ? `  "${row.displayName}"` : ""}`);
+        }
+        return 0;
+      }
+      case "crossing": {
+        if (!lib.crossing) {
+          deps.stderr("spawn client crossing: this session library predates the crossing seam");
+          return 1;
+        }
+        const view = await lib.crossing(sessionName);
+        deps.stdout(`resident world: ${view.residentWorldId}${view.residentWorldId !== view.bootWorldId ? `  (booted into ${view.bootWorldId})` : ""}  [${view.lane} lane]`);
+        if (view.directives.length === 0)
+          deps.stdout("directives: none heard yet");
+        for (const row of view.directives) {
+          deps.stdout(`  ${new Date(row.heardAtMs).toISOString()}  ${row.outcome.padEnd(8)}  ${row.fromWorldId} \u2192 ${row.targetWorldId ?? "?"}  link "${row.link}"${row.entryEntityId ? `  via #${row.entryEntityId}` : ""}${row.why ? `  (${row.why})` : ""}`);
+        }
+        if (!view.slots.slotTable) {
+          deps.stdout("slots: no slot table (single-world session that never prefetched or crossed)");
+        } else {
+          const r = view.slots.resident;
+          deps.stdout(`slots: resident ${r ? `${r.worldId} (${r.namespace === null ? "bare" : `ns ${r.namespace}`}, ${r.entities.length} entities)` : "none"}`);
+          for (const slot of view.slots.foreign) {
+            deps.stdout(`  foreign ${slot.worldId} (ns ${slot.namespace ?? "bare"}, ${slot.entities.length} entities)`);
+          }
+        }
+        return 0;
+      }
+      case "prefetch": {
+        if (!lib.prefetch) {
+          deps.stderr("spawn client prefetch: this session library predates the crossing seam");
+          return 1;
+        }
+        const worldId = flags["--world"];
+        const manifest = flags["--manifest"];
+        const worldHex = flags["--hex"];
+        if (!worldId || !manifest || !worldHex) {
+          deps.stderr("spawn client prefetch: needs --world <id> --manifest <hash> --hex <32hex>");
+          return 2;
+        }
+        const outcome = await lib.prefetch({ worldId, manifest, worldHex }, sessionName);
+        (outcome.ok ? deps.stdout : deps.stderr)(outcome.note);
+        return outcome.ok ? 0 : 1;
+      }
+      case "screenshot": {
+        const out = flags["--out"] || `spawn-client-screenshot-${Date.now()}.png`;
+        const absOut = path2.resolve(deps.cwd ?? process.cwd(), out);
+        const shot = await lib.screenshot(absOut, sessionName);
+        deps.stdout(`screenshot [${shot.tier}]: ${shot.outPath}`);
+        deps.stdout(`label: ${shot.label}`);
+        if (shot.note)
+          deps.stdout(shot.note);
+        return 0;
+      }
+      case "leave": {
+        const outcome = await lib.leave(sessionName);
+        (outcome.exited ? deps.stdout : deps.stderr)(`left "${outcome.name}": ${outcome.note}`);
+        return outcome.exited ? 0 : 1;
+      }
+      case "status": {
+        const { sessions, reaped } = await lib.status();
+        if (sessions.length === 0)
+          deps.stdout("no live client sessions");
+        for (const row of sessions) {
+          deps.stdout(`${row.name}: pid ${row.pid}  ${row.worldAddress ? `world ${row.worldAddress} (${row.roomId})` : `room ${row.roomId}`}  phase ${row.phase ?? "unreachable"}  entity ${row.entityId ?? "?"}  ttl ${row.ttlRemainingS !== null ? `${row.ttlRemainingS}s` : "none"}  "${row.playerName}"${row.handle ? ` [${row.handle}]` : ""}`);
+        }
+        for (const line of reaped)
+          deps.stdout(`reaped: ${line}`);
+        return 0;
+      }
+      default:
+        deps.stderr(`spawn client: unknown verb "${verb}"
+
+${CLIENT_USAGE}`);
+        return 2;
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (ownSession && !flags["--name"] && message.startsWith(`no session named "${ownSession}"`)) {
+      deps.stderr(`spawn client ${verb}: your session "${ownSession}" has ended (a recycle or expiry). It re-embodies on its own \u2014 wait a beat and retry. Never drive another agent's session in the meantime.`);
+      return 1;
+    }
+    deps.stderr(`spawn client ${verb}: ${message}`);
+    return 1;
+  }
+}
+function sessionScriptsDir(env) {
+  const explicit = env.SPAWN_CLIENT_SESSION_DIR?.trim();
+  if (explicit)
+    return explicit;
+  const home = env.HOME?.trim();
+  return home ? path2.join(home, ".spawn", "client-sessions") : path2.join(tmpdir(), "spawn-client-sessions");
+}
+function makeClient(deps) {
+  const apiOrigin = deps.env.SPAWN_WORKSHOP_API;
+  const token = deps.env.SPAWN_WORKSHOP_TOKEN;
+  if (!apiOrigin || !token) {
+    deps.stderr("spawn: SPAWN_WORKSHOP_API / SPAWN_WORKSHOP_TOKEN not set \u2014 the project bridge is unavailable in this shell");
+    return null;
+  }
+  return new IoClient({
+    apiOrigin,
+    token,
+    fetchImpl: deps.fetchImpl
+  });
+}
+async function upload(args, deps) {
+  const { positional, flags } = parseArgs(args, ["--name"]);
+  const file = positional[0];
+  if (!file) {
+    deps.stderr("spawn upload: missing <file>");
+    return 2;
+  }
+  const abs = path2.resolve(deps.cwd ?? process.cwd(), file);
+  let size;
+  try {
+    const st = await stat2(abs);
+    if (!st.isFile()) {
+      deps.stderr(`spawn upload: not a file: ${file}`);
+      return 1;
+    }
+    size = st.size;
+  } catch {
+    deps.stderr(`spawn upload: no such file: ${file}`);
+    return 1;
+  }
+  const cap = deps.uploadCapBytes ?? UPLOAD_CAP_BYTES;
+  if (size > cap) {
+    deps.stderr(`spawn upload: ${file} is ${formatBytes(size)} \u2014 over the ${formatBytes(cap)} upload cap`);
+    return 1;
+  }
+  const client2 = makeClient(deps);
+  if (!client2)
+    return 1;
+  const filename = flags["--name"] ?? path2.basename(abs);
+  let grant;
+  try {
+    grant = await client2.ingest({
+      filename,
+      content_type: contentTypeFor(abs),
+      size
+    });
+  } catch (error) {
+    if (error instanceof IoApiError && error.code === "INGEST_NOT_CONFIGURED") {
+      deps.stderr("spawn upload: asset ingest is not configured for this environment yet \u2014 the file is still in this workspace, but it cannot become a project asset from here");
+      return 1;
+    }
+    deps.stderr(`spawn upload: ingest failed: ${String(error)}`);
+    return 1;
+  }
+  const put = await (deps.fetchImpl ?? fetch)(grant.put_url, {
+    method: "PUT",
+    headers: { "content-type": contentTypeFor(abs) },
+    body: await readFile(abs)
+  });
+  if (!put.ok) {
+    const { code, message } = await readErrorBody(put);
+    deps.stderr(`spawn upload: byte upload failed (${code ?? put.status})${message ? `: ${message}` : ""}`);
+    return 1;
+  }
+  deps.stdout(`uploaded: ${grant.asset_url}`);
+  return 0;
+}
+async function fetchCommand(args, deps) {
+  const { positional } = parseArgs(args, []);
+  const source = positional[0];
+  if (!source) {
+    deps.stderr("spawn fetch: missing <url-or-cdn-ref>");
+    return 2;
+  }
+  if (/^https?:\/\//.test(source)) {
+    let dest2 = positional[1];
+    if (!dest2) {
+      const fromUrl = path2.basename(new URL(source).pathname);
+      dest2 = fromUrl.length > 0 ? fromUrl : source;
+    }
+    const absDest2 = path2.resolve(deps.cwd ?? process.cwd(), dest2);
+    const response2 = await (deps.fetchImpl ?? fetch)(source);
+    if (!response2.ok) {
+      deps.stderr(`spawn fetch: download failed (${response2.status}) for ${source}`);
+      return 1;
+    }
+    await Bun.write(absDest2, response2);
+    const st2 = await stat2(absDest2);
+    deps.stdout(`fetched: ${dest2} (${formatBytes(st2.size)})`);
+    return 0;
+  }
+  const reference = source.replace(/^\/+/, "").replace(/^cdn\//, "");
+  if (reference.length === 0) {
+    deps.stderr(`spawn fetch: not an asset reference: ${source}`);
+    return 2;
+  }
+  const client2 = makeClient(deps);
+  if (!client2)
+    return 1;
+  let response;
+  try {
+    response = await client2.fetchAsset(reference);
+  } catch (error) {
+    deps.stderr(`spawn fetch: asset door unreachable: ${String(error)}`);
+    return 1;
+  }
+  const displayName = path2.basename(referencePath(reference));
+  if (response.status === 202) {
+    deps.stderr(`spawn fetch: ${displayName} is still generating \u2014 magic assets bake asynchronously. ` + `Re-run this fetch in a few seconds if you need the bytes here; the live render shows the paint the moment it serves.`);
+    return 1;
+  }
+  if (!response.ok) {
+    const { code, message } = await readErrorBody(response);
+    if (code === "NOT_FOUND") {
+      deps.stderr(`spawn fetch: this environment's worker has no asset door yet \u2014 pass the full https asset URL instead`);
+      return 1;
+    }
+    if (code === "ASSET_NOT_SERVABLE") {
+      deps.stderr(`spawn fetch: ${displayName} is not servable \u2014 ${message ?? `the CDN refused it (${response.status})`}. Check the reference against the spec.`);
+      return 1;
+    }
+    deps.stderr(`spawn fetch: asset fetch failed (${code ?? response.status})${message ? `: ${message}` : ""}`);
+    return 1;
+  }
+  const dest = positional[1] ?? displayName;
+  const absDest = path2.resolve(deps.cwd ?? process.cwd(), dest);
+  await Bun.write(absDest, response);
+  const st = await stat2(absDest);
+  deps.stdout(`fetched: ${dest} (${formatBytes(st.size)})`);
+  return 0;
+}
+var ATTACHMENTS_USAGE = `spawn attachments \u2014 the creator-shared reference images from this game's chat
+
+  list                 what the creator shared: id, mime, when, the upload pipeline's summary
+  download <id> [dest] write one into the workspace (images only for now)
+
+To SEE one with model eyes, read_url its "/cdn/<id>" reference \u2014 the list
+prints the exact call. Entries marked url-only can be downloaded here but
+have no /cdn/ reference to view.
+`;
+async function attachments(args, deps) {
+  const [verb, ...rest] = args;
+  if (!verb || verb === "help" || verb === "--help") {
+    deps.stdout(ATTACHMENTS_USAGE);
+    return verb ? 0 : 2;
+  }
+  const client2 = makeClient(deps);
+  if (!client2)
+    return 1;
+  switch (verb) {
+    case "list":
+      return attachmentsList(client2, deps);
+    case "download":
+      return attachmentsDownload(client2, rest, deps);
+    default:
+      deps.stderr(`spawn attachments: unknown verb "${verb}"
+
+${ATTACHMENTS_USAGE}`);
+      return 2;
+  }
+}
+async function attachmentsList(client2, deps) {
+  let entries;
+  try {
+    entries = await client2.attachments();
+  } catch (error) {
+    deps.stderr(`spawn attachments list: ${describeAttachmentsError(error)}`);
+    return 1;
+  }
+  if (entries.length === 0) {
+    deps.stdout("no creator-shared reference images in this game's chat yet \u2014 images the creator uploads or pastes into the conversation land here");
+    return 0;
+  }
+  deps.stdout(`attachments (${entries.length} creator-shared reference image${entries.length === 1 ? "" : "s"}, newest last):`);
+  for (const entry of entries) {
+    const when = Number.isFinite(entry.sharedAt) ? new Date(entry.sharedAt).toISOString() : "unknown-time";
+    deps.stdout(`  ${entry.id}  ${entry.mime}  shared ${when}`);
+    if (entry.summary) {
+      deps.stdout(`      "${entry.summary}"`);
+    }
+    deps.stdout(entry.urlOnly ? `      download-only from this shell (no /cdn/ reference): spawn attachments download ${entry.id}` : `      see it (model eyes): read_url "/cdn/${entry.id}"  \xB7  bytes: spawn attachments download ${entry.id}`);
+  }
+  return 0;
+}
+async function attachmentsDownload(client2, args, deps) {
+  const { positional } = parseArgs(args, []);
+  const id = positional[0];
+  if (!id) {
+    deps.stderr("spawn attachments download: missing <id> \u2014 `spawn attachments list` names them");
+    return 2;
+  }
+  let entry;
+  try {
+    const entries = await client2.attachments();
+    const bare = id.replace(/^\/?(?:cdn\/)?/i, "");
+    entry = entries.find((candidate) => candidate.id === id || candidate.id === bare || candidate.magicCdnPath === `/cdn/${bare}`);
+  } catch (error) {
+    deps.stderr(`spawn attachments download: ${describeAttachmentsError(error)}`);
+    return 1;
+  }
+  if (!entry) {
+    deps.stderr(`spawn attachments download: "${id}" is not a creator-shared attachment in this game's chat \u2014 \`spawn attachments list\` names what exists`);
+    return 1;
+  }
+  if (!entry.mime.startsWith("image/")) {
+    deps.stderr(`spawn attachments download: "${entry.id}" reads as ${entry.mime} \u2014 attachments serve images only for now`);
+    return 1;
+  }
+  let response;
+  try {
+    response = await client2.fetchAttachment(entry.id);
+  } catch (error) {
+    deps.stderr(`spawn attachments download: ${describeAttachmentsError(error)}`);
+    return 1;
+  }
+  if (response.status === 202) {
+    deps.stderr(`spawn attachments download: ${id} is still processing on the CDN \u2014 re-run this in a few seconds`);
+    return 1;
+  }
+  if (!response.ok) {
+    const { code, message } = await readErrorBody(response);
+    deps.stderr(`spawn attachments download: failed (${code ?? response.status})${message ? `: ${message}` : ""}`);
+    return 1;
+  }
+  const dest = positional[1] ?? entry.id;
+  const absDest = path2.resolve(deps.cwd ?? process.cwd(), dest);
+  await Bun.write(absDest, response);
+  const st = await stat2(absDest);
+  const mime = response.headers.get("content-type");
+  deps.stdout(`downloaded: ${dest} (${formatBytes(st.size)}${mime ? `, ${mime}` : ""})`);
+  if (!entry.urlOnly) {
+    deps.stdout(`see it with model eyes: read_url "/cdn/${entry.id}"`);
+  }
+  return 0;
+}
+var REF_USAGE = `spawn ref \u2014 the engine's reference: its skills, whole
+
+  ls                   every skill, one line: id \u2014 what it is for
+  read <skill>         the whole skill (markdown) \u2014 read it BEFORE building in its territory
+  grep <regex>         which skill teaches a word (skill:line: text)
+
+The corpus is the engine this world runs (ROOM_HOST_ENGINE_SEMVER); the engine source itself is
+not here \u2014 this lane serves what the engine teaches, not how it is built.
+`;
+async function ref(args, deps) {
+  const [verb, ...rest] = args;
+  if (!verb || verb === "help" || verb === "--help") {
+    deps.stdout(REF_USAGE);
+    return verb ? 0 : 2;
+  }
+  const client2 = makeClient(deps);
+  if (!client2)
+    return 1;
+  const engine = deps.env.ROOM_HOST_ENGINE_SEMVER?.trim() || deps.env.ROOM_HOST_ENGINE_VERSION?.trim() || null;
+  try {
+    switch (verb) {
+      case "ls": {
+        const { skills: rows, corpus } = await client2.refSkills(engine);
+        if (rows.length === 0) {
+          deps.stdout("no skills in this engine's reference");
+          return 0;
+        }
+        const width = Math.min(28, Math.max(...rows.map((r) => r.id.length)));
+        for (const row of rows)
+          deps.stdout(`${row.id.padEnd(width)}  ${row.hook}`);
+        deps.stdout(`
+${rows.length} skills \u2014 \`spawn ref read <skill>\` for the whole of one`);
+        deps.stdout(describeRefCorpus(corpus, engine));
+        return 0;
+      }
+      case "read": {
+        const id = rest[0]?.trim();
+        if (!id) {
+          deps.stderr("spawn ref read: which skill? \u2014 `spawn ref ls` names them");
+          return 2;
+        }
+        const response = await client2.refSkillStream(id, engine);
+        if (deps.stdoutStream && response.body) {
+          const reader = response.body.getReader();
+          for (;; ) {
+            const { done, value } = await reader.read();
+            if (done)
+              break;
+            if (value)
+              await deps.stdoutStream(value);
+          }
+          return 0;
+        }
+        deps.stdout(await response.text());
+        return 0;
+      }
+      case "grep": {
+        const pattern = rest.join(" ").trim();
+        if (!pattern) {
+          deps.stderr("spawn ref grep: a regex, please");
+          return 2;
+        }
+        const { hits, truncated } = await client2.refGrep(pattern, engine);
+        if (hits.length === 0) {
+          deps.stdout(`no skill mentions /${pattern}/`);
+          return 0;
+        }
+        for (const hit of hits)
+          deps.stdout(`${hit.skill}:${hit.line}: ${hit.text}`);
+        if (truncated)
+          deps.stdout(`\u2026 more hits than shown \u2014 narrow the pattern`);
+        return 0;
+      }
+      default:
+        deps.stderr(`spawn ref: unknown verb "${verb}"
+
+${REF_USAGE}`);
+        return 2;
+    }
+  } catch (error) {
+    deps.stderr(`spawn ref ${verb}: ${error instanceof IoApiError ? error.detail ?? error.message : String(error)}`);
+    return 1;
+  }
+}
+function describeRefCorpus(corpus, engine) {
+  if (!corpus)
+    return `corpus: unknown (an older reference door \u2014 engine ${engine ?? "unset"})`;
+  if (corpus.startsWith("versioned:")) {
+    return `corpus: ${corpus} \u2014 the bundle this world's engine runs`;
+  }
+  if (corpus === "codebase") {
+    return engine ? `corpus: codebase \u2014 the deploy's own tree, NOT a bundle for engine ${engine} (local dev, or no bundle published for that pin)` : "corpus: codebase \u2014 the deploy's own tree (no engine named in this box)";
+  }
+  return `corpus: ${corpus}`;
+}
+function describeAttachmentsError(error) {
+  if (error instanceof IoApiError) {
+    if (error.code === "WORKSHOP_NOT_CONFIGURED") {
+      return "this environment has no chat-room lane for attachments yet";
+    }
+    return error.detail ?? error.message;
+  }
+  return String(error);
+}
+function referencePath(reference) {
+  const queryIndex = reference.indexOf("?");
+  return queryIndex === -1 ? reference : reference.slice(0, queryIndex);
+}
+async function readErrorBody(response) {
+  try {
+    const parsed = await response.json();
+    return {
+      code: typeof parsed.error === "string" ? parsed.error : null,
+      message: typeof parsed.message === "string" ? parsed.message : null
+    };
+  } catch {
+    return { code: null, message: null };
+  }
+}
+async function ls(args, deps) {
+  const { flags } = parseArgs(args, ["--assets", "--workspace"]);
+  const assetsOnly = "--assets" in flags;
+  const workspaceOnly = "--workspace" in flags;
+  const both = !assetsOnly && !workspaceOnly;
+  let exitCode = 0;
+  if (assetsOnly || both) {
+    const client2 = makeClient(deps);
+    if (client2) {
+      try {
+        const assets = await client2.assets();
+        deps.stdout(`assets (${assets.length}):`);
+        for (const asset of assets) {
+          deps.stdout(`  ${asset.id}  ${asset.kind ?? "-"}  ${asset.name ?? "-"}  ${asset.url}`);
+        }
+      } catch (error) {
+        deps.stderr(`spawn ls: asset list failed: ${String(error)}`);
+        exitCode = 1;
+      }
+    } else if (assetsOnly) {
+      return 1;
+    }
+  }
+  if (workspaceOnly || both) {
+    const root = deps.env.SPAWN_WORKSPACE_ROOT ?? "/workspace";
+    if (!existsSync(root)) {
+      deps.stdout(`workspace (${root}): empty`);
+      return exitCode;
+    }
+    const snapshot = await walkWorkspace(root);
+    const files = Object.keys(snapshot).sort();
+    const total = files.reduce((sum, file) => sum + snapshot[file].size, 0);
+    deps.stdout(`workspace (${files.length} files, ${formatBytes(total)}):`);
+    for (const file of files) {
+      deps.stdout(`  ${formatBytes(snapshot[file].size).padStart(10)}  ${file}`);
+    }
+  }
+  return exitCode;
+}
+async function status(deps) {
+  const statusPath = deps.env.SPAWN_STATUS_FILE ?? STATUS_FILE_PATH;
+  let parsed;
+  try {
+    parsed = JSON.parse(await readFile(statusPath, "utf8"));
+  } catch {
+    deps.stderr("spawn status: no status yet (the workshop server has not written one)");
+    return 1;
+  }
+  const uptimeS = Math.max(0, Math.floor((Date.now() - Date.parse(parsed.started_at)) / 1000));
+  deps.stdout(`app: ${parsed.app_id ?? "unknown"}`);
+  deps.stdout(`workspace: ${formatBytes(parsed.workspace_bytes)} of ${formatBytes(parsed.quota_soft_bytes)} soft quota (hard cap ${formatBytes(parsed.quota_hard_bytes)}), ${parsed.workspace_files} files`);
+  deps.stdout(`uptime: ${formatDuration(uptimeS)}`);
+  if (parsed.budget !== null && parsed.budget !== undefined) {
+    deps.stdout(`budget: ${JSON.stringify(parsed.budget)}`);
+  }
+  return 0;
+}
+var VALUE_FLAGS = new Set([
+  "-n",
+  "-e",
+  "--name",
+  "--room",
+  "--as",
+  "--body",
+  "--materials-json",
+  "--ttl",
+  "--ready-timeout",
+  "--to",
+  "--speed",
+  "--timeout",
+  "--at",
+  "--out",
+  "--world",
+  "--manifest",
+  "--hex",
+  "--actor",
+  "--origin",
+  "--door",
+  "--engine"
+]);
+function parseArgs(args, known) {
+  const positional = [];
+  const flags = {};
+  for (let i = 0;i < args.length; i += 1) {
+    const arg = args[i];
+    if (known.includes(arg)) {
+      const next = args[i + 1];
+      if (arg.startsWith("-") && next !== undefined && !next.startsWith("--") && VALUE_FLAGS.has(arg)) {
+        flags[arg] = next;
+        i += 1;
+        continue;
+      }
+      flags[arg] = "";
+    } else {
+      positional.push(arg);
+    }
+  }
+  return { positional, flags };
+}
+var CONTENT_TYPES = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".svg": "image/svg+xml",
+  ".glb": "model/gltf-binary",
+  ".gltf": "model/gltf+json",
+  ".mp4": "video/mp4",
+  ".webm": "video/webm",
+  ".mp3": "audio/mpeg",
+  ".wav": "audio/wav",
+  ".ogg": "audio/ogg",
+  ".json": "application/json",
+  ".md": "text/markdown",
+  ".txt": "text/plain",
+  ".pdf": "application/pdf"
+};
+function contentTypeFor(filePath) {
+  return CONTENT_TYPES[path2.extname(filePath).toLowerCase()] ?? "application/octet-stream";
+}
+function formatBytes(bytes) {
+  if (bytes < 1024)
+    return `${bytes}B`;
+  if (bytes < 1048576)
+    return `${(bytes / 1024).toFixed(1)}KB`;
+  if (bytes < 1073741824)
+    return `${(bytes / 1048576).toFixed(1)}MB`;
+  return `${(bytes / 1073741824).toFixed(2)}GB`;
+}
+function formatDuration(totalSeconds) {
+  const hours = Math.floor(totalSeconds / 3600);
+  const minutes = Math.floor(totalSeconds % 3600 / 60);
+  const seconds = totalSeconds % 60;
+  if (hours > 0)
+    return `${hours}h${minutes}m`;
+  if (minutes > 0)
+    return `${minutes}m${seconds}s`;
+  return `${seconds}s`;
+}
+
+// src/bin.ts
+var here = path3.dirname(fileURLToPath(import.meta.url));
+var sessionLib = path3.join(here, "session-lib.mjs");
+var shellEntry = path3.join(here, "main.mjs");
+if (!process.env.SPAWN_CLIENT_SESSION_LIB && existsSync2(sessionLib))
+  process.env.SPAWN_CLIENT_SESSION_LIB = sessionLib;
+if (!process.env.SPAWN_CLIENT_SHELL_ENTRY && existsSync2(shellEntry))
+  process.env.SPAWN_CLIENT_SHELL_ENTRY = shellEntry;
+var code = await runCli(process.argv.slice(2), {
+  env: process.env,
+  stdout: (line) => console.log(line),
+  stderr: (line) => console.error(line),
+  stdoutStream: (chunk) => new Promise((resolve, reject) => {
+    process.stdout.write(chunk, (error) => error ? reject(error) : resolve());
+  })
+});
+process.exit(code);