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
17 changes: 10 additions & 7 deletions lab/server/GUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,13 +55,16 @@ retried request safe, and an event log. None of it presses buttons yet.

## What comes next

| Slice | What you would get |
|---|---|
| 4 (rest) | FRLG AutoStory's start checks listed and run before any press (fork #488) |
| 5 | Leased actions: an agent asks to run or stop a program; the server checks the program's start checks first and refuses on a failed one, and refuses whenever you hold the console. Every action gets exactly one record. |
| 6 | Save facts: the server knows which save is on the console and refuses a run that would start from the wrong one; run records become readable |
| 7 | The server launches and supervises the lab app itself, so a build always starts with the right profile |
| 8 | Optional: a local worker for routine operations |
Each feature has a user page, marked **DRAFT** until it is built and switched on. The drafts
are updated as each piece lands.

| Slice | What you would get | Page |
|---|---|---|
| 4 (rest) | Every program lists what it needs before it starts; FRLG AutoStory's list is next (fork #488) | [start-checks.md](guide/start-checks.md) |
| 5 | Leased actions: an agent asks to run or stop a program; the server refuses whenever you hold the console, and (5b) when a start check fails. Every action gets exactly one record. 5a is built in #592, not switched on. | [actions.md](guide/actions.md) |
| 6 | Save facts: the server knows which save is on the console and refuses a run that would start from the wrong one; run records become readable | [saves.md](guide/saves.md) |
| 7 | The server launches and supervises the lab app itself, so a build always starts with the right profile | [app-lifecycle.md](guide/app-lifecycle.md) |
| 8 | Optional: a local worker for builds and test runs | [worker.md](guide/worker.md) |

## Limits

Expand Down
7 changes: 7 additions & 0 deletions lab/server/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -293,3 +293,10 @@ every event after an active cursor (one used in the last 7 days), every event of
and every pending record; finished records go after 7 days. A cursor behind the compacted range
is refused (`invalid_arguments`, field `after_seq`, `evidence.compacted_through`), never served
with a silent gap.

## User pages

`GUIDE.md` is the user-facing overview; `guide/*.md` has one page per feature, marked DRAFT
until it is built and switched on. A PR that builds or switches on part of a feature updates
its page in the same PR: the status line at the top, the tool tables, and the DRAFT banner when
the feature is done.
37 changes: 37 additions & 0 deletions lab/server/guide/actions.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
> **DRAFT.** This page describes a feature that is only partly built. It is updated as each piece lands.
> Status (2026-11-15): Slice 5a (`run_program`, `stop_program` under a lease) is built in [#592](https://github.com/dayfine/Arduino-Source/pull/592), not merged and not switched on. Slice 5b (preflight, options, `cfr_batch`, a console soak) is not built.

# Actions: agents start and stop programs through the server

Today agents act on console B through lab scripts. With actions, an agent asks pa-lab instead,
and the server decides whether it may.

## How it works for you

- **You always win.** Clicking Start or Stop in the app gives you the console. Any agent
request in flight fails, and new ones are refused until you release it.
- **An agent must hold the console first.** It takes a time-limited lease; without one, or
after it expires, every action is refused.
- **One action, one record.** Each request has an id. Retrying the same id returns the first
answer and never starts or stops twice. Every action is in the event log.
- **Refusals say why**, for example: you hold the console; another program is running; the app
is not running; the selected panel is a different program; the controller is not ready.

## Tools

| Tool | What it does | Status |
|---|---|---|
| `acquire_console` / `renew_console` / `release_console` | take, extend and give back the lease | built (control plane) |
| `run_program(panel)` | start the selected program once | built in #592, not switched on |
| `stop_program()` | stop it once; stopping when nothing runs is a no-op, not an error | built in #592, not switched on |
| `preflight_program(panel, options)` | load candidate options, run the program's [start checks](start-checks.md), then put your options back; `run_program` will need its token | planned (5b) |
| options on `run_program` | run with options other than the panel's current ones | planned (5b) |
| `cfr_batch(lines)` | a short allowlisted controller batch, for debugging only; marks the save as unknown | planned (5b) |

There is deliberately no "switch game" tool: the app cannot yet pick a game on HOME by name.

## Switching it on

The session connection (`.mcp.json`) stays read-only until you decide otherwise. The plan:
5b adds preflight; a soak on console B shows every action has exactly one record; then actions
are enabled one program family at a time.
16 changes: 16 additions & 0 deletions lab/server/guide/app-lifecycle.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
> **DRAFT.** This page describes a feature that is not built yet. It is updated as it lands.
> Status (2026-11-15): planned (Slice 7). Today `labrun.sh` launches the lab app.

# The server runs the lab app

## What you will get

- **The right build, the right way, every time.** The server launches the lab app itself, with
the lab profile, the audio settings and the build you picked, and refuses anything else
(no more running a build without `--profile`).
- **Crash handling.** It notices a crash or a hung app, records it, and refuses to start a
second copy. It only ever stops the app it started.
- **You keep an escape hatch.** You can still launch or quit the app yourself; the server sees
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.
20 changes: 20 additions & 0 deletions lab/server/guide/saves.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
> **DRAFT.** This page describes a feature that is not built yet. It is updated as it lands.
> Status (2026-11-15): planned (Slice 6). `console://B/save` exists and usually says `unknown`.

# Save facts: knowing which save is on the console

Most lab mistakes that cost real progress are about the save: starting a checkpoint run from
the wrong save, or a hand session moving the player after the last save.

## What you will get

- **The server knows the save.** When a program saves (AutoStory and RNG programs first), it
records where and when. `console://B/save` then shows `known`, with the checkpoint or place.
- **It notices when that stops being true.** Anything that can change the game without a
recorded save (you playing, a controller batch, an unhooked program) marks the save
`stale`, with the reason. Only another recorded save makes it `known` again.
- **Runs check it first.** The `save_at(place)` [start check](start-checks.md) refuses a run
whose start does not match the known 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.
40 changes: 40 additions & 0 deletions lab/server/guide/start-checks.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
> **DRAFT.** This page describes a feature that is only partly built. It is updated as each piece lands.
> Status (2026-11-15): the check list and `describe_program` are built ([#485](https://github.com/dayfine/Arduino-Source/pull/485), [#511](https://github.com/dayfine/Arduino-Source/pull/511), [#512](https://github.com/dayfine/Arduino-Source/pull/512)); FRLG AutoStory's list is a design note ([#488](https://github.com/dayfine/Arduino-Source/pull/488)); the server does not yet run the checks before a start (that is [actions.md](actions.md), Slice 5b).

# Start checks: what a program needs before it presses anything

Every program can declare a short, named list of things that must be true before it starts:
the game is in front, the screen has no black border, a party slot is free, the save is the
one the program expects. Each check has a name and a one-line "needs" sentence, and none of
them presses a button, resets, saves or changes an option.

## What you get

- **Read what a program needs without running it.** Ask for `describe_program` on a panel
and you get its options (keys, types, defaults, allowed values) and its start checks with
their "needs" lines.
- **One list guards both doors.** The same list runs when you click Start in the app and when
an agent asks the server to start a run, so a bad setup is refused the same way either way,
before any reset.
- **Clear refusals.** The first failing check stops the start with a message saying which
check failed and what it needs.

## Checks you will see

| Check | Needs |
|---|---|
| `game_open` | the program's game is in front, not HOME, user select or a black screen |
| `black_border` | the picture fills the screen (no black border) |
| `free_party_slots(n)` | at least n empty party slots (FRLG RNG gift/egg) |
| `save_at(place)` | the save on the console is the one this run starts from (needs [saves.md](saves.md)) |

Program-specific checks sit beside the program: for example a Sweet Scent user in the last
slot, or enough Safari advances. A program without a list says `unsupported`; that never
counts as passing.

## Planned lists

| Program | Checks |
|---|---|
| FRLG RNG | `black_border`, then `free_party_slots(1)` (gift, egg); Sweet Scent user last (wild); Safari advances ≥ 4000 |
| FRLG / BDSP / PLZA AutoStory | `game_open`; the start checkpoint is chosen and visible; `save_at(start checkpoint)`; LANGUAGE matches the game |
14 changes: 14 additions & 0 deletions lab/server/guide/worker.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
> **DRAFT.** This page describes an optional feature that is not built yet. It is updated if it lands.
> Status (2026-11-15): planned (Slice 8), optional.

# Local worker for routine operations

A separate process that runs heavy local jobs (builds, test runs) as queued tickets, with the
existing guards: the heavy-work gate, the disk floor, `-j4` and `nice`.

## What you will get

- Builds and tests queue instead of colliding; refusals say why (disk low, memory, a console
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.
Loading