Scripts

Manage SeraphRuntime Lua scripts — the same engine the in-app editor uses. Each script is keyed by (client_id, script_id) so multiple scripts can run concurrently across multiple bots.

Method	Path	Body / Query
POST	/api/scripts/execute	{client_id, script_id, source}
POST	/api/scripts/stop	{client_id, script_id}
GET	/api/scripts/status	?client_id&script_id
GET	/api/scripts/console	?client_id&script_id
POST	/api/scripts/console/clear	{client_id, script_id}

POST /api/scripts/execute

Compile + start a Lua source against a bot. The script runs detached on a background scheduler — this call returns the moment the runtime has accepted the source.

Body:

{
  "client_id": "bot-1",
  "script_id": "auto-mine",
  "source":    "while true do sleep(1000); print(\"tick\"); end"
}

Response (200):

{ "ok": true }

Errors:

Status	Body
404	{"error":"unknown bot: bot-99"}
500	{"error":"lua compile: <line>: unexpected symbol near 'end'"}

POST /api/scripts/stop

Cancel a running script. The runtime sends a cancellation signal through every coroutine the script spawned; if the script registered a cleanup block it gets to finish before the VM is dropped.

Body:

{ "client_id": "bot-1", "script_id": "auto-mine" }

Response (200):

{ "ok": true }

Idempotent — stopping a script that isn't running still returns 200.

GET /api/scripts/status

Query: ?client_id=bot-1&script_id=auto-mine

Response (200):

{
  "running":    true,
  "last_error": null
}

last_error is null while running and on clean exit; populated when the VM dies with a runtime error ("executor:42: attempt to index nil value (field 'world')").

GET /api/scripts/console

Captured stdout buffer for the script. Every print(...) from the Lua side appends a line; the runtime trims the buffer at ~5,000 entries so a long-running script doesn't OOM the host.

Query: ?client_id=bot-1&script_id=auto-mine

Response (200):

{
  "lines": [
    { "ts_ms": 1778205616123, "level": "info",  "text": "tick" },
    { "ts_ms": 1778205617123, "level": "info",  "text": "tick" },
    { "ts_ms": 1778205618400, "level": "error", "text": "executor:8: tile not found" }
  ]
}

level is one of info, warn, error — set by the corresponding Lua call (print, warn, error throw).

POST /api/scripts/console/clear

Truncate the console buffer.

Body:

{ "client_id": "bot-1", "script_id": "auto-mine" }

Response (200): { "ok": true }