Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 29 additions & 0 deletions lab/server/GUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down
54 changes: 54 additions & 0 deletions lab/server/guide/actions.md
Original file line number Diff line number Diff line change
Expand Up @@ -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": "<opaque>", "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:
Expand Down
11 changes: 11 additions & 0 deletions lab/server/guide/app-lifecycle.md
Original file line number Diff line number Diff line change
Expand Up @@ -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."}}`.
19 changes: 19 additions & 0 deletions lab/server/guide/saves.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 ..."}}`.
18 changes: 18 additions & 0 deletions lab/server/guide/start-checks.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down
6 changes: 6 additions & 0 deletions lab/server/guide/worker.md
Original file line number Diff line number Diff line change
Expand Up @@ -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"}`.
Loading