@spawnco/client 0.1.0 → 0.2.0

package/README.md

@@ -2,52 +2,92 @@
 
 The Spawn client for agents. Join a world as a real player with your own token, look around, walk, and run play scripts against the live game — the same `spawn client` Savi uses from her workshop.
 
+The package is a loader. The client it runs is the one the stack you join serves: `spawn` asks the stack (`SPAWN_ORIGIN`, default `https://www.spawn.co`) for its current client, fetches it by content (integrity-checked, cached under `~/.cache/spawnco-client/`), and runs it — so an installed copy is never older than the doors it dials. A stack that cannot be reached runs the client it last served you.
+
 ```sh
 curl -fsSL https://bun.sh/install | bash        # once — the client runs on Bun
 bun add -g @spawnco/client                       # the `spawn` command
 
 export SPAWN_TOKEN=sak_…                         # your account token (POST /api/agent/v1/signup, or the invite you were handed)
 spawn client join @alice/gauntlet                # a real body in the room, wearing your name
+spawn client join @alice/gauntlet --as bob       # a second body of yours — its own player, its own play
 spawn client where                               # your pose + the nearest objects
 spawn client players                             # every player body: who is here, who is parked
 spawn client run play.js                         # play
 spawn client leave                               # the body despawns
 ```
 
+## Verify a round without a person
+
+A room boots for a player, never for a door — so the room you need to look into is one you boot yourself, as the player you are. After a push:
+
+```sh
+spawn client join @@you/<slug> --ttl 600      # the world boots for your body; the boot verdict prints
+curl -H "Authorization: Bearer $SPAWN_TOKEN" -X POST $ORIGIN/api/sdk/v1/<worldId>/agent/exec \
+     -H 'content-type: application/json' -d '{"script":"return api.getPlayers().length"}'
+curl -H "Authorization: Bearer $SPAWN_TOKEN" $ORIGIN/api/sdk/v1/<worldId>/agent/logs
+spawn client leave                              # the room empties; the seat is returned
+```
+
+`join` prints what the room did for your body once the body stands:
+
+```
+boot: the room is live for your body — tree booted +512 ms · session live +640 ms · can move +1.5 s · body observed +2.3 s (engine e1ac83c7)
+body: player/c_actor:pa_… in <worldId>|main at (0.0, 0.0, 0.0)
+room: 6 entities · 1 player (You (you)) · this seat hosts <worldId>|main
+verify: agent/rooms lists this room (+3.1 s); agent/exec and agent/logs read it while the body stands (ttl 600 s) — `spawn client leave` ends it
+```
+
+`join` waits (bounded, 45 s) for `agent/rooms` to list the room before it prints that line — a room announces itself to the registry within 30 s of booting, and the line is true when printed; `agent/rooms` lists the room while the body stands; `agent/exec` (read-only JS in the live room — state, spawns, SQL through the world's own API) and `agent/logs` (the room's script log: a script fault names its path) answer from it; `spawn client run play.js` plays it with a body. A headless seat costs a seat like a person's (an unlinked account plays about 2 sessions at a time). A body that does not spawn inside the wait prints `body: not spawned inside the wait` and the session stands — `spawn client status` keeps reading it.
+
 ## What `join` does
 
-`spawn client join <world>` takes an address (`@alice/gauntlet`), a play URL, or a world id. With your `sak_` in `SPAWN_TOKEN` it reads your account's doors (`GET /api/agent/v1/me`), resolves the address (`GET /api/resolve-adventure?address=`), mints a session grant for that one world (`POST /api/session/grant/agent { world }`), and attaches a headless engine client through the kernel's session door — byte for byte the boot a browser tab performs. The room sees an agent-class player with a body; your play counts the way a person's does.
+`spawn client join <world>` takes an address (`@alice/gauntlet`), a play URL, or a world id. With your `sak_` in `SPAWN_TOKEN` it reads your account (`GET /api/agent/v1/me` — the doors, and your own worlds: a spelling that names one of them is answered there, by id), mints a session grant for that one world (`POST /api/session/grant/agent { world }` — the address goes in as you spelled it and kiln resolves it; the answer names the world and the door), and attaches a headless engine client through the kernel's session door — byte for byte the boot a browser tab performs. The room sees an agent-class player with a body; your play counts the way a person's does. A world that moved is named by its new address; a spelling no world answers to says so.
+
+The session is a detached process on your machine (its verbs answer on a loopback port); it self-expires at `--ttl` (default 900 s) and `leave` despawns the body deliberately. Several sessions run side by side under `--name`: a bare verb drives the FIRST-JOINED live session, every later one is the one you name.
 
-The session is a detached process on your machine (its verbs answer on a loopback port); it self-expires at `--ttl` (default 900 s) and `leave` despawns the body deliberately. Several sessions run side by side under `--name`.
+**Several bodies, one account.** `--as <name>` stands a body of your own under the account — `spawn client join @alice/gauntlet --as alice` and `--as bob` are two players in the room at once, each wearing its name, each counting its own play (heartbeat with the same `persona` so the row is the body's). The account stays the owner behind every one of them; the session's handle defaults to the body's name (`spawn client move --name bob …`); joining a name you already stand re-joins that body. A join with no `--as` is your account's own body, wearing the account's name. An unlinked agent account stands 2 bodies at a time (`agent_session_budget_exceeded` past that — `leave` one); a linked account is not dialed.
 
 Flags an operator may need: `--origin <kiln>` (`SPAWN_ORIGIN`, default `https://www.spawn.co`), `--door <kernel origin>` (`SPAWN_DOOR_ORIGIN`, when the grant names no session door), `--engine <32-hex>` (`SPAWN_ENGINE`, when the door names no engine build), `--actor <agentActorId>` (a person's token embodying a seat it minted).
 
 ## Play scripts
 
-`spawn client run play.js` (or `run -e "<source>"`) runs a module against the live client:
+`spawn client run play.js` (or `run -e "<source>"`) runs a module against the live client. `spawn client run --help` opens on the verb list. The spellings a programmer tries are the same calls: move, goto → moveTo · look → face · click, mouse, cursor → point · me, self → where · find, getObject → entity · read → state · spawnAt, setPosition → teleport · sleep, delay → wait · screenshot → witness.
 
 ```js
 // play.js — export default async (play) => { … }
 export default async (play) => {
   const cube = (await play.where()).nearby.find((e) => e.specId === "cube-1");
-  await play.moveTo(cube.entityId, { arriveRadius: 2 });
+  await play.moveTo(cube.id, { arriveRadius: 2 }); // default 0.5 m
   const before = await play.state(); // the world's world/state ledger
   const pressed = await play.key("KeyE"); // resolved through THIS world's bindings
   const changed = await play.until(
     async () => JSON.stringify(await play.state()) !== JSON.stringify(before),
     { timeoutSec: 5 },
   );
-  return { pressed, changed: changed.met };
+  const ball = await play.entity("ball"); // { id, position, heading, state, simulator }
+  const others = (await play.players()).filter((p) => !p.isSelf);
+  await play.face(ball.id); // turn to face it — the frame hold() then walks in
+  play.walk(0, -1); // walk north (world-space) until released
+  await play.seconds(1);
+  play.release();
+  return {
+    pressed: pressed.ok,
+    changed: changed.met,
+    ball: ball.position,
+    others: others.length,
+  };
 };
 ```
 
-`play` is your body and your senses:
+`play` is your body and your senses. While the script runs your body counts as a player — the game's `getPlayers`, `ctx.place.players` and `tags: ["player"]` list it, so the referee you wrote sees you; a helper body is a helper again when the script ends (the transcript's first line says which). Every read answers plain objects:
 
-- hands — `hold(axis, value)` / `release(axis?)`, `press(action)` (hard-fails an action the world never declared), `key(code)` / `keyDown` / `keyUp` (a `KeyboardEvent.code`, a bare letter, or `space`; resolved through the world's own `inputs` — an unbound key is a finding, never a silent no-op), `moveTo(target)`, `lookAt(target)`, `teleport(x, y, z)` (the one labeled direct write — stage-setup, never play).
-- senses — `pose()` (position, camera yaw/pitch, `heading`, `grounded`, `contacts`), `where()` (pose + nearby), `players()`, `state(entityId?)` (an entity's `tome/state`; none = the world's `world/state`), `entities(components?)`, `inputs()`, `worldTick()`.
-- pacing — `seconds(n)`, `until(check, { timeoutSec })` (a timeout is a finding: `{ met: false }`), `log(line)`.
+- senses — `players()` → `[{ id, name, position, x, y, z, isSelf, parked }]`; `entities()` → `[{ id, specId, name, position, x, y, z, heading, state, simulator }]` (`feetPosition` is the same vector as `position` — the spec row's word; `simulator` is who drives it right now — `{ clientId, by, epoch }`; `clientId: null` = the place's host drives it, `by: "suspend"` = parked; the whole field `null` = no row); `entity(id)` → one of those or `null`; `where()` → `{ id, position, x, y, z, yaw, pitch, heading, placeId, worldId, tick, nearby: [{ id, specId, name, position, x, y, z, distance }] }` (`tick` is the world tick the read was cut at) — every row with a position carries `x`, `y`, `z` flat beside it (`where().y` and `where().position.y` are one number); `pose()` (+ `grounded`, `contacts`); `camera()` → `{ position, yaw, pitch, eyeRise }` (the camera your client presents — `eyeRise` is the eye over your feet in metres; `null` with none; a district's own camera reads here the tick you land in it); `hud()` → `{ ref, html, place }` (the HUD your place renders for you, as html — the same `render` call the screen makes); `state(id?)` (an entity's `tome/state` by id; none or `"world"` = the world's `world/state` — `{}` while it holds no rows; `"place"` = your place's own bag, what `ctx.place.state` reads); `logs({ level?, objectId?, limit? })` → the console rail your client holds (`[{ level, message, tick, entityId, data, count }]` — a script's faults, a clipped foreign verb's `law.faculty.refused`; `data` is the row's JSON text); `inputs()`; `worldTick()`.
+- hands — `hold(axis, value)` / `release(axis?)` is the HUMAN's stick: `moveX`/`moveZ` are camera-relative, exactly what WASD feeds, so a script with no viewport cannot know where a raw hold walks. `hold(action)` keeps the action's key down until `release(action)` — `pressed` on the down sample, `held` while down, `released` at the up (a held jump, a brake pedal); `press(action)` taps the same key. The world-frame pair: `walk(dx, dz)` walks a world-space direction (+X east, −Z north; the vector's length is the deflection) until `walk(0, 0)`, `release()`, or the script ends; `face(target)` turns to face a point or an entity id — the frame `hold` then walks in. `point(target)` puts your cursor on a point or an entity — the pointer ray a click aims under a cursor camera (a locked crosshair ignores the cursor; `face` is the aim there); `point(null)` lifts it, and the script's end lifts it too. `moveTo(target, { arriveRadius = 0.5, speed, timeoutSec })` walks there closed-loop under the game's own movement rules. `press(action)` (hard-fails an action the world never declared), `key(code)` / `keyDown(code)` / `keyUp(code)` (a `KeyboardEvent.code`, a bare letter, or `space`; resolved through the world's own `inputs` — an unbound key is a finding, never a silent no-op), `teleport(x, y, z)` or `teleport({ x, y, z })` (the one labeled direct write — stage-setup, never play).
+- eyes without a browser — `witness(outPath?)` writes the room top-down as SVG from the sim's facts: every entity's feet, facing and name, you marked; the file's text lists them too, so a kick's direction reads without a person (`spawn client witness --out kick.svg` is the same picture from the shell). `screenshot` still needs a connected browser player for pixels.
+- pacing — `wait(ms)` / `seconds(n)` (a wait under one sim tick — `wait(0.15)` — is read as seconds, and the transcript says so), `until(check, { timeoutSec })` (a timeout is a finding: `{ met: false }`; every `timeoutSec` on the handle is seconds — `timeout` spells the same), `settle(dropM)` (after a `teleport` that put you `dropM` metres above where you stand: waits out the fall under THIS world's gravity, stepped on its own tick — a moon world and a 30 Hz world each wait their own fall, never a wall-clock guess — then reads that you stand or float; `{ settled, how, grounded, y, gravityY, tickHz, ticks, ms }`, `settled: false` a finding), `log(line)`.
 
-The transcript (every input, in order, as the session saw it) 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. `god:*` actions are refused — a play script plays with a player's controls.
+The transcript (every input, in order, as the session saw it) and the return value come back; a thrown error or a timeout is an `ok: false` transcript. When the script ends — returned, threw, timed out — every held input is released AND every move it started is cancelled, so the next run starts clean; a callback that outlives its run finds the play handle closed. `god:*` actions are refused — a play script plays with a player's controls.
 
 ## Runtime
 

package/bin/spawn.mjs

@@ -1,6 +1,217 @@
 #!/usr/bin/env bun
-// `spawn` — the Spawn client for agents (@spawnco/client). Runs under Bun: the session shell
-// hosts a real engine client in a Bun Worker and serves its verbs over a loopback HTTP port.
-// The CLI, the session library and the shell supervisor are built into ../dist by
-// scripts/build.ts (prepack); this shim only points the CLI at its own bundles.
-import "../dist/spawn.mjs";
+// `spawn` — the Spawn client for agents (@spawnco/client). THE PACKAGE HOLDS NO CLIENT. The client an
+// agent runs is the one the stack it joins serves: this loader asks the stack for its current client
+// (`<origin>/api/client/manifest` → the stack's session door → `/v4/client/<hash>/agent/manifest.json`),
+// fetches the bundles named there by content (SRI-pinned, immutable by address), caches them, and runs
+// the CLI from the cache — the runtime worker's own law (the shell downloads the world's pinned engine
+// at boot) applied to the shell, the session library and the CLI, so an installed copy can never be
+// older than the doors it dials.
+//
+//   SPAWN_ORIGIN / --origin <kiln>   the stack (default https://www.spawn.co)
+//   SPAWN_CLIENT_DIST=<dir>          run the bundles in <dir> instead (a built dist, a downloaded copy)
+//   SPAWN_CLIENT_CACHE_DIR=<dir>     where fetched clients live (default ~/.cache/spawnco-client)
+//
+// A repo checkout runs the tree's client from source (src/bin.ts beside this file); no fetch, no build.
+
+import { createHash } from "node:crypto";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const DEFAULT_ORIGIN = "https://www.spawn.co";
+const MANIFEST_PATH = "/api/client/manifest";
+const CLI_FILE = "spawn.mjs";
+const FETCH_TIMEOUT_MS = 30_000;
+const VERSION_SEGMENT = /\/v4\/client\/([0-9a-f]{8,64})\//;
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+
+const treeEntry = path.join(here, "..", "src", "bin.ts");
+if (existsSync(treeEntry)) {
+  await import(pathToFileURL(treeEntry).href);
+} else if (process.env.SPAWN_CLIENT_DIST) {
+  await runDist(
+    path.resolve(process.env.SPAWN_CLIENT_DIST),
+    `SPAWN_CLIENT_DIST=${process.env.SPAWN_CLIENT_DIST}`,
+  );
+} else {
+  const origin = resolveOrigin(process.argv.slice(2), process.env);
+  const dist = await fetchClient(origin);
+  await runDist(dist, `the client ${origin} serves`);
+}
+
+/** `--origin <kiln>` / `--origin=<kiln>` anywhere on the line, else SPAWN_ORIGIN, else the product. */
+function resolveOrigin(argv, env) {
+  let origin = null;
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === "--origin" && argv[i + 1]) origin = argv[i + 1];
+    else if (argv[i].startsWith("--origin="))
+      origin = argv[i].slice("--origin=".length);
+  }
+  origin = origin ?? env.SPAWN_ORIGIN ?? DEFAULT_ORIGIN;
+  return origin.trim().replace(/\/+$/, "");
+}
+
+async function runDist(dir, named) {
+  const cli = path.join(dir, CLI_FILE);
+  if (!existsSync(cli))
+    die(
+      `no client at ${dir} (${named}): ${CLI_FILE} is missing beside its session library and shell`,
+    );
+  await import(pathToFileURL(cli).href);
+}
+
+/**
+ * The stack's current client, on disk: the manifest is read every run (it is small and names the
+ * bytes); a bundle already cached under the version it names is re-hashed and kept, anything else
+ * is fetched, verified against the manifest's SRI and written atomically. A stack that cannot be
+ * reached runs the client it last served this machine, and says so.
+ */
+async function fetchClient(origin) {
+  const cacheRoot =
+    process.env.SPAWN_CLIENT_CACHE_DIR ||
+    path.join(homedir(), ".cache", "spawnco-client");
+  const pointer = path.join(
+    cacheRoot,
+    "origins",
+    sha256Hex(origin).slice(0, 16),
+  );
+  const manifestUrl = `${origin}${MANIFEST_PATH}`;
+  let response;
+  try {
+    response = await fetch(manifestUrl, {
+      redirect: "follow",
+      headers: { accept: "application/json" },
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+    });
+  } catch (error) {
+    return cachedOrDie(
+      pointer,
+      cacheRoot,
+      `${origin} could not be reached (${errorText(error)})`,
+    );
+  }
+  if (!response.ok) {
+    const body = (await response.text().catch(() => ""))
+      .slice(0, 300)
+      .replace(/\s+/g, " ")
+      .trim();
+    return cachedOrDie(
+      pointer,
+      cacheRoot,
+      `${manifestUrl} answered HTTP ${response.status}${body ? ` — ${body}` : ""}`,
+    );
+  }
+  const manifestText = await response.text();
+  let manifest;
+  try {
+    manifest = JSON.parse(manifestText);
+  } catch {
+    return cachedOrDie(
+      pointer,
+      cacheRoot,
+      `${response.url} is not a client manifest (not JSON)`,
+    );
+  }
+  const files =
+    manifest &&
+    typeof manifest === "object" &&
+    manifest.files &&
+    typeof manifest.files === "object"
+      ? manifest.files
+      : null;
+  const cliName = typeof manifest?.cli === "string" ? manifest.cli : CLI_FILE;
+  if (!files || typeof files[cliName] !== "string") {
+    return cachedOrDie(
+      pointer,
+      cacheRoot,
+      `${response.url} names no ${cliName} — not a client manifest`,
+    );
+  }
+  const version =
+    VERSION_SEGMENT.exec(new URL(response.url).pathname)?.[1] ??
+    sha256Hex(manifestText).slice(0, 32);
+  const dir = path.join(cacheRoot, version);
+  mkdirSync(dir, { recursive: true });
+  for (const [name, sri] of Object.entries(files)) {
+    if (!/^[A-Za-z0-9._-]+\.mjs$/.test(name))
+      die(
+        `the client manifest at ${response.url} names a suspicious file "${name}" — refusing`,
+      );
+    if (typeof sri !== "string" || !/^sha256-[A-Za-z0-9+/=]+$/.test(sri))
+      die(
+        `the client manifest at ${response.url} carries no sha256 integrity for ${name} — refusing`,
+      );
+    const target = path.join(dir, name);
+    if (existsSync(target) && sha256Sri(readFileSync(target)) === sri) continue;
+    const fileUrl = new URL(name, response.url).href;
+    let fileResponse;
+    try {
+      fileResponse = await fetch(fileUrl, {
+        signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+      });
+    } catch (error) {
+      die(`${fileUrl} could not be fetched (${errorText(error)})`);
+    }
+    if (!fileResponse.ok)
+      die(
+        `${fileUrl} answered HTTP ${fileResponse.status} while fetching the client the stack named`,
+      );
+    const bytes = Buffer.from(await fileResponse.arrayBuffer());
+    const actual = sha256Sri(bytes);
+    if (actual !== sri)
+      die(
+        `${fileUrl} failed its integrity check (manifest ${sri}, got ${actual}) — the stack's client and its manifest disagree; nothing was run`,
+      );
+    const tmp = `${target}.${process.pid}.tmp`;
+    writeFileSync(tmp, bytes);
+    renameSync(tmp, target);
+  }
+  if (cliName !== CLI_FILE)
+    die(
+      `the client manifest names its CLI "${cliName}"; this loader runs ${CLI_FILE} — update the loader (bun add -g @spawnco/client)`,
+    );
+  mkdirSync(path.dirname(pointer), { recursive: true });
+  writeFileSync(pointer, `${version}\n`);
+  return dir;
+}
+
+function cachedOrDie(pointer, cacheRoot, why) {
+  if (existsSync(pointer)) {
+    const version = readFileSync(pointer, "utf8").trim();
+    const dir = path.join(cacheRoot, version);
+    if (version && existsSync(path.join(dir, CLI_FILE))) {
+      console.error(
+        `[spawn] ${why}; running the client this stack last served here (${version.slice(0, 12)})`,
+      );
+      return dir;
+    }
+  }
+  die(
+    `${why}\n  The client's bytes come from the stack you join: point SPAWN_ORIGIN (or --origin) at it — the product is ${DEFAULT_ORIGIN}; a dev stack is its kiln, e.g. http://localhost:3000.`,
+  );
+}
+
+function die(message) {
+  console.error(`spawn: ${message}`);
+  process.exit(2);
+}
+
+function errorText(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function sha256Hex(text) {
+  return createHash("sha256").update(text).digest("hex");
+}
+
+function sha256Sri(bytes) {
+  return `sha256-${createHash("sha256").update(bytes).digest("base64")}`;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@spawnco/client",
-  "version": "0.1.0",
-  "description": "The Spawn client for agents: join a world as a real player with your own token and run play scripts against it — the same `spawn client` Savi's workshop uses.",
+  "version": "0.2.0",
+  "description": "The Spawn client for agents: join a world as a real player with your own token and run play scripts against it — the same `spawn client` Savi's workshop uses. The package is a loader: the client it runs is the one the stack you join serves.",
   "license": "UNLICENSED",
   "type": "module",
   "bin": {
@@ -9,7 +9,6 @@
   },
   "files": [
     "bin",
-    "dist",
     "README.md"
   ],
   "engines": {
@@ -17,7 +16,6 @@
   },
   "scripts": {
     "build": "bun run scripts/build.ts",
-    "prepack": "bun run scripts/build.ts",
     "test": "bun test scripts",
     "tsc": "tsc --noEmit -p tsconfig.json"
   },