diff --git a/lab/server/GUIDE.md b/lab/server/GUIDE.md index 209aa05f97..b6e333f0a8 100644 --- a/lab/server/GUIDE.md +++ b/lab/server/GUIDE.md @@ -31,6 +31,35 @@ check-ins). It returns: | `newest_failure_frame`, `newest_screenshot` | Paths to the latest failure frame and screenshot | | `log_tail` | The last log lines (how many is a parameter) | +Example. Ask in a session: *"what's console B doing?"* Claude calls +`console_status(console="B", log_lines=3)` and gets (real output from 2026-11-15, trimmed): + +```json +{ + "console": "B", + "app": {"pid": 87625, "deployment": "slot-B-plza/f0caeb52e879-b440bb4e"}, + "lab_state": {"state": "STOPPING", "program": "PokemonSV:AutoStory", "controller": "ready", "error": ""}, + "console_state": { + "availability": {"state": "available", "reason": null}, + "video": {"state": "live", "frame_seq": 7445}, + "lease": {"state": "user", "owner": "user", "acquired_at": "2026-11-16T00:00:51.929Z"}, + "blocked": [ + {"code": "console_held_by_user", "message": "The user clicked Stop in the app at 00:00; console B is theirs until they release it."}, + {"code": "program_running", "message": "PokemonSV:AutoStory is stopping."} + ] + }, + "program_state": "2026-11-15 16:00:51.929720 - [Program]: Program State: STOPPING", + "last_run": ["... [Checkpoint] 18.02: passed on attempt 1 (one-shot)"], + "last_press": "16:00:21", + "keepawake": "15:57:35 idle 189s: pressed B through Lab inbox (NO_PROGRAM)", + "newest_failure_frame": ".../Screenshots/AutoStory/failures/20261115-151031611644-by_pad_to_bottom_right.png", + "log_tail": ["...", "...", "..."] +} +``` + +With the app closed, `app` is `null` and `blocked` says +`{"code": "app_unavailable", "message": "The app that wrote Lab/state.json (pid 96761) is not running."}`. + **Two resources**, for clients that read resources instead of calling tools: `console://B/state` (the same console state) and `console://B/save` (what is known about the save on the console; today usually `unknown`, see Slice 6 below). diff --git a/lab/server/guide/actions.md b/lab/server/guide/actions.md index a986f0e5f8..8f9f0bba9f 100644 --- a/lab/server/guide/actions.md +++ b/lab/server/guide/actions.md @@ -30,6 +30,60 @@ and the server decides whether it may. There is deliberately no "switch game" tool: the app cannot yet pick a game on HOME by name. +## Examples + +These are the request and answer shapes from the server's contract files +(`contracts/v1/`), with example ids. They are what an agent sends and gets back; you would +ask Claude in plain words ("take console B and run FRLG 13.01 to 13.02"). + +**Take the console.** `acquire_console(console="B", owner="agent:frlg-lane", ttl_s=1200)`: + +```json +{"lease_token": "", "expires_at": "2026-11-14T06:40:00.000Z"} +``` + +If you hold it, the answer is a refusal instead: + +```json +{"request_id": "5f0c2a8e-...", "tool": "acquire_console", + "refusal": {"code": "console_held_by_user", + "message": "The user holds console B (Stop clicked in the app at 06:10); ask them to release it."}} +``` + +**Start the selected program** (5a: the panel's current options): +`run_program(console="B", request_id="9b1d7e44-...", lease_token=..., panel="PokemonFRLG:AutoStory")`. +The stored record once the app has started it: + +```json +{"request_id": "9b1d7e44-...", "tool": "run_program", "status": "completed", + "created_at": "2026-11-14T06:20:00.000Z", "completed_at": "2026-11-14T06:20:02.150Z", + "result": {"run_id": null, "started_at": "2026-11-14T06:20:02.100Z", + "instance_id": "d8ea6a9d-..."}, + "refusal": null} +``` + +Sending the same `request_id` again returns this same record and starts nothing. Refusal codes +you can get: `console_held_by_user`, `console_held_by_agent`, `program_running`, +`app_not_running`, `panel_not_program`, `channel_owned`, `invalid_arguments`. + +**Stop it.** `stop_program(console="B", request_id=..., lease_token=...)` answers with who +stopped it and when, e.g. `{"sent": true, "stopped_at": "...", "stopped_by": "lab"}`. If nothing +was running: `{"sent": false, "state": "stopped", ...}`, which is not an error. + +**Preflight (planned, 5b).** `preflight_program(console="B", panel="PokemonFRLG:RngStatic", options={...})` +returns a token for `run_program`, or the first failed start check: + +```json +{"tool": "preflight_program", + "refusal": {"code": "precheck_failed", "check": "free_party_slots", + "message": "Free party slots: needs 1 empty slot, found 0.", + "evidence": {"needed": 1, "found": 0}}} +``` + +**Controller batch (planned, 5b, debugging only).** +`cfr_batch(console="B", lines=["shot before", "press B 160 640", "shot after"])` runs the lines +with the program stopped and marks the save `stale`. + ## Switching it on The session connection (`.mcp.json`) stays read-only until you decide otherwise. The plan: diff --git a/lab/server/guide/app-lifecycle.md b/lab/server/guide/app-lifecycle.md index 3f2c8a6d04..f89abe47b2 100644 --- a/lab/server/guide/app-lifecycle.md +++ b/lab/server/guide/app-lifecycle.md @@ -14,3 +14,14 @@ that and stands back. - **Agents stop launching apps directly.** After a soak, agents ask the server instead of running `labrun.sh` or writing to the app's inbox. + +## Example (sketch, not built) + +*"Start the lab app on the newest FRLG build."* The server answers with what it launched: + +```json +{"pid": 13122, "game": "frlg", "commit": "72f365065", "profile": "lab-B", + "deployment": "slot-B-frlg/72f3650657d2-8bf901e7"} +``` + +or refuses, e.g. `{"refusal": {"code": "app_running_program", "message": "PokemonFRLG:AutoStory is running; stop it first."}}`. diff --git a/lab/server/guide/saves.md b/lab/server/guide/saves.md index 17ae617815..039439a122 100644 --- a/lab/server/guide/saves.md +++ b/lab/server/guide/saves.md @@ -18,3 +18,22 @@ the wrong save, or a hand session moving the player after the last save. - **Run records you can read.** Each run ends as one record (passed, failed, or stopped and by whom), with checkpoint results, RNG hits and links to failure screenshots, shown through the server's resources and events. + +## Example (sketch, not built) + +Read `console://B/save` after an AutoStory checkpoint saved: + +```json +{"state": "known", "fact": {"program": "PokemonFRLG:AutoStory", "checkpoint": "18.02", + "saved_at": "2026-11-15T23:44:13.115Z"}} +``` + +After you play by hand or a controller batch runs: + +```json +{"state": "stale", "reason": "user input after the last recorded save (2026-11-15T23:50:02Z)", + "fact": {"checkpoint": "18.02", "saved_at": "2026-11-15T23:44:13.115Z"}} +``` + +A run whose start does not match then gets +`{"refusal": {"code": "precheck_failed", "check": "save_at", "message": "The save on console B is stale ..."}}`. diff --git a/lab/server/guide/start-checks.md b/lab/server/guide/start-checks.md index 7073024119..41ea554e01 100644 --- a/lab/server/guide/start-checks.md +++ b/lab/server/guide/start-checks.md @@ -19,6 +19,24 @@ them presses a button, resets, saves or changes an option. - **Clear refusals.** The first failing check stops the start with a message saying which check failed and what it needs. +## Example + +Ask: *"what does FRLG Static RNG need before it starts?"* Claude calls +`describe_program(console="B", panel="PokemonFRLG:RngStatic")`. The answer lists the options +and the checks; the check part looks like this (shape sketch, field names may change): + +```json +{"program": "PokemonFRLG:RngStatic", + "prechecks": [ + {"name": "black_border", "needs": "The picture fills the screen: no black border."}, + {"name": "free_party_slots", "needs": "At least 1 empty party slot."} + ]} +``` + +A program with no list answers `"prechecks": "unsupported"`. When a check fails at Start, the +program stops before any reset with a message like +`Free party slots: needs 1 empty slot, found 0.` + ## Checks you will see | Check | Needs | diff --git a/lab/server/guide/worker.md b/lab/server/guide/worker.md index 8255d0b26e..44caf658e1 100644 --- a/lab/server/guide/worker.md +++ b/lab/server/guide/worker.md @@ -12,3 +12,9 @@ existing guards: the heavy-work gate, the disk floor, `-j4` and `nice`. run in progress). - A console run is never slowed down or stopped by a build. - It does not touch GitHub, PRs or worktrees, and the existing daily cleanup jobs stay. + +## Example (sketch, not built) + +*"Build the PLZA lab tree."* → `{"ticket": 41, "state": "queued", "ahead": 1}`; later +`{"ticket": 41, "state": "done", "exit": 0, "log": "~/BDSPLab/build-plza.log"}`, or +`{"ticket": 41, "state": "refused", "reason": "console run in progress"}`.