Русский · English · Español · 中文 · Português

«Space Now» — agent API

This page is for AI agents (and their humans). It explains how an agent connects to a live «Space Now» page (known.html) in a person's browser and what it can do there: everything the interface can do — open any object, fly the camera, scrub time, switch layers and filters, astronaut mode, find eclipses and planet parades, tell a story with voice and captions, show its own images, record video, read errors. Rendering happens in the person's browser (WebGL on their GPU); the agent sends commands and gets answers and screenshots.

1. Pairing

1. The person opens the site and presses the round 🤖 button (bottom-right, above the astronaut) — the agent bar opens; «Turn the agent on» shows a code (20 characters, e.g. r4fxjbjsxdy6ex3pf4hd). The code is the pass: whoever has it controls this tab. 🤖 only hides/shows the bar, the connection stays; «Disconnect» in the bar turns it off. The bar always has 📂 (open a story file or save the shown one — without an agent too) and «MCP ↗» (this page).
2. The person gives the code to the agent. The agent calls connect with it.
3. Permanent connection (optional): on the page — 📌 «Remember» in the agent bar (the code stays in this browser, the site connects by itself every time it opens); the agent — connect with save: true (code in ~/.orbit-agent.json, MCP connects on start). After that, just open the site. To forget: unpin 📌 and call forget.
4. «Disconnect» on the page (or the agent leaving) ends the session; the page then returns layers and interface to how they were before the agent, stops music, voice, captions, images and scenarios, and removes landing sites (sites), drawings and marks (draw, mark, flybys), media windows and own bodies (spawn) — regardless of onstop. The camera, time and selection come back too (by default; onstop {restore: false} — keep what the agent showed). Exception: play / story run with detach: true — the show plays to the end, then rolls back.

Sound (voice, music) starts only after the person has clicked the page at least once — browser rule. The voice is off by default: the person turns it on with 🔊 in the agent bar (remembered); captions are always shown.

Show checklist — always do this

[
  {"cmd":"onstop","args":{"restore":true}},        // first step: on end, Esc or ✕ everything comes back
  {"cmd":"reset"},
  {"cmd":"view","args":{"on":["oplanets"]}},        // only the layers you need: satellites, craft, orbits, constellations off
  {"cmd":"hideUi","args":{"on":true,"labels":false}},
  {"cmd":"time","args":{"at":"<moment>","rate":0}}, // set the time yourself; rate 0 — the lighting won't drift
  … flight (fly) …
  … the show …
]

• Don't rely on defaults: set layers, time, camera and interface explicitly.
• A view set with view (or a story's on field) is kept by show (keepView: false — the event's layers). fly, camera, sites, time don't touch layers; galaxy, scene and ambient set their own view — call view again after them if needed.
• After the show the scene must be as before it: onstop {restore: true} plus remove your own things — sites {on: false}, flybys {on: false}, draw {clear: true}, image {clear: true}, media {close: true}. When the agent leaves they are removed anyway.
• Check the frame with screenshot before telling the person «look».
• The caption sits bottom-left: keep title short, put long text into sub and text.
• A failing step in play goes to logs (level error), to play without args (lastError: {step, cmd, error}) and to the player as «⚠ step N». An unknown command in steps is an error at once, before the start.

2. Transport

Both sides connect to a relay room on the same site: wss://<site>/agent/<code>?r=agent (the page uses ?r=page). The room forwards messages between the two; nothing is stored. JSON messages:

agent → page   { "id": 1, "cmd": "go", "args": { "search": "?o=Mars" } }
page  → agent  { "id": 1, "ok": true, "result": … }   |   { "id": 1, "ok": false, "error": "…" }
room  → both   { "sys": "peer", "on": true|false }      (the other side joined / left)
keepalive      send { "sys": "ping" } every 30 s, the room answers { "sys": "pong" }

One connection per role (a new agent with the same code replaces the old one, close code 4000 — do not reconnect then). Messages up to 4 MB. Sites: https://space.bl2.ru, https://space.bl2.net (same site, ru/en by default).

3. MCP server

Ready-made MCP server (stdio): scripts/agent-mcp.mjs in the orbit-proto repository (Node ≥ 20, dependency ws). Every command below is a tool of the same name (hide_ui → page command hideUi), plus connect, disconnect, help (this page as text; lang: en). Files: image takes path, record saves to path, screenshot returns an image.

{ "mcpServers": { "orbit-space": { "command": "node", "args": ["scripts/agent-mcp.mjs"] } } }

Env: AGENT_SITE — default site, AGENT_CODE — connect at start.

Connecting without the MCP server (cloud agents)

• Many agents run in cloud sandboxes whose outbound network is limited to an allow-list, so wss://space.bl2.ru may be unreachable. Workaround: open the WebSocket from any browser tab on space.bl2.ru (this help page, for example) and send commands from there. Connection check: {"sys":"ping"} → {"sys":"pong"}.
• The agent leaving = play stops and the scene rolls back. An agent with short sessions (browser tools allow ~45 s per call) sends the show with detach: true — play {steps, detach: true} or story {action: 'run', story, detach: true} — and returns at once: the page plays the show itself and rolls back (with onstop) when it ends. Without detach keep the socket open until the scenario ends.
• Give every command its own timeout (say 8 s): otherwise one unanswered command hangs the whole call.

// «start and return» — from the console of a tab on space.bl2.ru (or Node ≥ 22)
const code = '<code>', ws = new WebSocket(`wss://space.bl2.ru/agent/${code}?r=agent`);
let id = 0; const wait = new Map();
const cmd = (name, args = {}, ms = 8000) => new Promise((res, rej) => {
  const i = ++id, t = setTimeout(() => (wait.delete(i), rej(new Error('timeout ' + name))), ms);
  wait.set(i, (m) => (clearTimeout(t), m.ok ? res(m.result) : rej(new Error(m.error))));
  ws.send(JSON.stringify({ id: i, cmd: name, args }));
});
ws.onmessage = (e) => { const m = JSON.parse(e.data); if (!m.sys) wait.get(m.id)?.(m), wait.delete(m.id); };
ws.onopen = async () => {
  await cmd('onstop', { restore: true });
  await cmd('play', { detach: true, onError: 'skip', steps: [
    { cmd: 'reset' },
    { cmd: 'view', args: { on: ['oplanets'] } },
    { cmd: 'hideUi', args: { on: true, labels: false } },
    { cmd: 'fly', args: { name: 'Saturn', size: 0.5, lit: true }, wait: 6500 },
    { cmd: 'caption', args: { title: 'Saturn', sub: '1.4 billion km from the Sun' }, wait: 8000 },
  ] });
  ws.close(); // the show plays on by itself, then puts everything back
};

4. Commands

Look and state

View, camera, time, layers

Events (computed by the page, no formulas needed)

Whole interface

Telling a story

One entry point: WS, MCP, console, story

Commands and the language are the same wherever they come from: WebSocket from any language, MCP, the page console (the >_ button in the agent bar) or a story. Write a whole scenario and give it to story, or call commands one by one. New: exec {steps} — run language steps now (variables persist between calls), expr {e} — evaluate an expression, js {code, timeout} — JavaScript in a sandbox (isolated iframe + Web Worker: no DOM, cookies or network; inside — await cmd(name, args), await expr('…'), log(), sleep(), return).

Console: fly Mars size=0.6 (a command, the first word is name), a JSON command, steps {…} / […], an expression = …, code js ….

Base script — Node.js:

// node agent.mjs <код>   (Node ≥ 22 — WebSocket встроен)
const code = process.argv[2], ws = new WebSocket(`wss://space.bl2.ru/agent/${code}?r=agent`);
let id = 0; const wait = new Map();
const cmd = (name, args = {}) => new Promise((res, rej) => {
  const i = ++id; wait.set(i, { res, rej }); ws.send(JSON.stringify({ id: i, cmd: name, args }));
});
ws.onmessage = (e) => {
  const m = JSON.parse(e.data);
  if (m.sys) return;                                   // peer / pong
  const w = wait.get(m.id); wait.delete(m.id);
  m.ok ? w.res(m.result) : w.rej(new Error(m.error));
};
setInterval(() => ws.send('{"sys":"ping"}'), 30000);
ws.onopen = async () => {
  await cmd('fly', { name: 'Mars', size: 0.6, lit: true });
  console.log(await cmd('expr', { e: "round(au(get('Mars','sun')),3)" }));
  await cmd('exec', { steps: [{ wait: "dist('camera','Mars') < 1e5 km" }, { cmd: 'caption', args: { title: 'Mars' } }] });
  process.exit(0);
};

Python:

# python agent.py <код>    (pip install websockets)
import asyncio, json, sys, websockets
async def main(code):
    async with websockets.connect(f"wss://space.bl2.ru/agent/{code}?r=agent") as ws:
        n = 0
        async def cmd(name, **args):
            nonlocal n; n += 1
            await ws.send(json.dumps({"id": n, "cmd": name, "args": args}))
            while True:
                m = json.loads(await ws.recv())
                if m.get("id") == n:
                    if not m["ok"]: raise RuntimeError(m["error"])
                    return m["result"]
        await cmd("fly", name="Saturn", size=0.6, lit=True)
        print(await cmd("expr", e="get('Saturn','moons')"))
asyncio.run(main(sys.argv[1]))

Scenario language v2

Versions: a story without v (or v: 1) — steps and slides as above; v: 2 — a language with conditions. A new handler version never changes old ones.

{ "v": 2, "title": "…", "on": ["oplanets"], "vars": { "n": 0 }, "steps": [
  { "cmd": "fly", "args": { "name": "Mars", "size": 0.5, "lit": true } },
  { "wait": "dist('camera', 'Mars') < 50000 km", "timeout": 20 },
  { "set": { "n": "n + 1" } },
  { "if": "visible('Mars')", "then": [ { "cmd": "caption", "args": { "title": "Mars", "sub": "{round(au(dist('camera','Sun')),3)} AU from the Sun" } } ] },
  { "repeat": 2, "do": [ { "wait": 1 } ] }
] }

Steps: {cmd, args, wait} (wait — ms or an expression), {wait: expression | seconds, timeout}, {if, then, else}, {repeat: n | expression, do}, {set: {name: expression}}, {on: [...]}. Expressions — no eval: numbers with units km au ly m, strings '…', variables, + - * / %, < > <= >= == !=, && || !; functions dist(a, b) ('camera' or a body, km), visible(body), elapsed(), time(), camdist(), au(x), ly(x), round(x, d), abs min max. Properties on the fly: get(body | 'camera', 'prop') — a body has name, kind, radius, parent, moons, x y z, sun (km from the Sun), earth, camera (km from the camera), center, visible; the camera has dist, yaw, pitch, fov, x y z, sun, center; without a prop — the whole object. A command result into a variable: {cmd, args, as: 'r'}, a field — field(r, 'rows.0.text'), size — count(x). In args strings — {expression}. Errors go to logs. Next: triggers (when/once/every) and a sandbox (spawn bodies and 3D models). Own functions: {def: name, params, e} — in expressions, {def, params, steps} — as a step {call, args, as}, {local}, {return}; in a story — funcs. More functions: angle(a, b) — degrees between directions from the camera, edge(a, b) — how many degrees a shows past the limb of b, sin cos (degrees), pow sqrt. wait: true on a command — until it finishes. For scenes: fitdist(r[, margin]) — the distance from which a circle of radius r km fits the screen (narrow side; a body also has day — rotation period, s); satcount('all' | 'active' | 'debris' | 'rb' | 'dead') — catalogue objects around Earth; mstat(craft, 'launch' | 'km' | 'turns' | 'rmin' | 'rnow' | 'flybys') — mission numbers from its trajectory, as of today. Spacecraft trajectories and flybys come from the import (scripts/fetch-missions.mjs, JPL Horizons, daily): a new craft in the base gets its flybys and numbers automatically; flybys {craft} draws the flyby points on its path. Media in scenes: media {url | file, title, x, y, w, h, volume, loop, start, id} — a window with audio or video: an mp3/video link or YouTube; file — a file from the person's computer (the site stores no files: the person picks it in the window, then it plays offline); close: true closes the windows. State: remember {name} — save the camera, time, view and interface; recall {name} — bring it back; onstop {restore: true} (in a story file — the field "onstop": "restore") — on end, Esc or ✕ put everything back as before the start. Tell the person: stories and the screensaver can be driven by a remote — a presentation clicker (PageDown/PageUp, «.» or B — black screen), media keys on keyboards, headphones and TV boxes (next, previous, pause), a gamepad (D-pad ←/→, A — pause, B — black screen), keyboard arrows, Space, Esc. Direct links: ?ambient — the screensaver, ?ambient=<scene code from ☰> — starting from that scene (e.g. ?ambient=landings:Moon:apollo), ?story=<id>&step=N or &slide=N — a published story from that point; the 🔗 button in the player copies a link to what is playing. The ambient {play: code} command does the same from an agent; reset resets camera, time and view before a scene.

Camera and motion

Showing a small body (a comet, an interstellar object — invisible from tens of millions of km): follow {name} or fly {name}, then mark {name, label: true} — a blinking multicoloured marker at the body (visible with hideUi too; also color, speed), select {name} — its path bright. Remove: mark {remove: name} or mark {clear: true}, select {name: ''}; the onstop rollback and the agent leaving remove marks by themselves.

Easing ease — like a CSS timing function: linear, ease, ease-in, ease-out, ease-in-out, smooth, cubic-bezier(x1,y1,x2,y2) or a formula of t (0…1): 1-pow(1-t,2), t*t*t*(t*(6*t-15)+10).

Overlap: {cmd, args, then: [steps], before_end: ms | after_begin: ms | when: "condition"} — nested steps run alongside the command. Example: orbit the Earth, turn to Io, fly to it:

[ {"cmd": "fly", "args": {"name": "Earth", "size": 0.4, "rel": {"to": "sun", "deg": 0, "elev": 10}, "ms": 3000, "ease": "ease-in-out"}, "wait": true},
  {"cmd": "orbit", "args": {"speed": 60, "ms": 6000, "ease": "ease-in"},
   "when": "edge('Io','Earth') < 15", "then": [{"cmd": "look", "args": {"to": "Io", "ms": 1500}, "wait": true}], "wait": true},
  {"cmd": "fly", "args": {"name": "Io", "size": 0.15, "rel": {"to": "Jupiter", "deg": 180, "elev": 15}, "ms": 8000, "ease": "ease-out"}, "wait": true} ]

Sandbox, drawing, astronaut

Page console — the backquote key (ё on a Russian layout).

How to work

1. Read this page (help), connect with the code.
2. Ask the page for data: search / open (objects), body (sizes, lit side), where (positions), find (events), layers, state.
3. Prepare the actions from that data: one play scenario, or a deck of slides the person steps through, or buttons.
4. Run it; check with screenshot and logs; adjust.

5. Example: «tell me about the planets»

connect {code}
layers → layer {key, visible:false} for everything except oplanets
music {theme: 0, volume: 0.4};  hide_ui {on: true}
play {steps: [
  {cmd:"fly", args:{name:"Mars"}, wait: 3800},
  {cmd:"camera", args:{yaw: …, pitch: …, dist: …, ms: 3000}, wait: 3200},   // values from body {name:"Mars"}
  {cmd:"say", args:{title:"Mars", sub:"228 million km · light takes 13 min", text:"…", audio:"mars.mp3"}, wait: "speech"}, // voice is Piper in the browser (ru ruslan, en amy); audio — a ready mp3 instead
  …
]}

6. Resources

• Bodies: Sun, 8 planets with moons, dwarf planets, ~1.4 M asteroids (by size groups), comets, interplanetary spacecraft, ~30 000 Earth satellites (CelesTrak, daily), constellations in 3D, Milky Way model with nebulae and clusters, 44 000 galaxies (2MRS).
• Names work in Russian and English (Марс / Mars); positions are J2000 equatorial, km.
• Time range: any date (ephemerides degrade far from today; satellites only ±90 days from the catalog).
• Share links (?o=…&d=…&v=…&t=…) open the same view for anyone.

Rules: the page accepts only these commands; no navigation to other sites, no personal data. Keep the person in control — they can press «Disconnect» any time.