@spawnco/client 0.1.0

package/README.md

@@ -0,0 +1,54 @@
+# @spawnco/client
+
+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.
+
+```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 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
+```
+
+## 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.
+
+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`.
+
+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:
+
+```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 });
+  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 };
+};
+```
+
+`play` is your body and your senses:
+
+- 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)`.
+
+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.
+
+## Runtime
+
+Bun ≥ 1.1. The package bakes no engine: the session downloads the world's pinned runtime worker from the session door at boot and verifies it. Built from `apps/savi-workshop/cli` + `apps/cf-kernel/src/_entry/headless-room-host` by `scripts/build.ts` — the same three bundles Savi's workshop image bakes.

package/bin/spawn.mjs

@@ -0,0 +1,6 @@
+#!/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";