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
2 changes: 2 additions & 0 deletions .github/workflows/agents-check.yml
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,8 @@ jobs:
run: python3 -m unittest discover -s lab/scripts -p test_label_shots.py -v
- name: Route review script tests
run: python3 -m unittest discover -s lab/scripts -p test_review_route.py -v
- name: Lab server contract tests
run: python3 -m unittest discover -s lab/server/tests -t lab/server -v
- name: Code health linter self-tests
run: |
python -m pip install -r devtools/code_health/requirements.txt
Expand Down
1 change: 1 addition & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,7 @@ There are two different checks, and neither replaces the other:

| What | Where | Use |
|---|---|---|
| Lab server (pa-lab console daemon, #131): version-1 contracts | [lab/server/](lab/server/README.md) | Slice 0: goldens + parser; `python3 -m pa_lab check app_state <file>` from `lab/server`. |
| Lab control: lock, channel, CFR batches | [lab/control/](lab/control/README.md) (`lablock.sh`, `labctl.sh`, `cfrun.sh`) | `sh lab/control/lablock.sh status`; one train on the console. Old copy: `devtools/lab` on `lab/main`. |
| Console B helpers | [lab/scripts/](lab/scripts/README.md) (`lc.sh`, `sel.sh`, `cfr.sh`, `env.sh`) | `sh lab/scripts/lc.sh state`; `printf ... \| sh lab/scripts/cfr.sh NAME`. |
| CFR syntax and the HOME gotcha | [lab/scripts/README.md](lab/scripts/README.md#cfr-batch-syntax) | Start each batch with a `shot`; at HOME, `press A` before any stick. |
Expand Down
112 changes: 112 additions & 0 deletions lab/server/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,112 @@
# pa-lab console daemon (`lab/server`)

The local server designed in `docs/design/Agent-Integration.md` (fork #131, branch
`design/agent-integration`). This directory is Slice 0 only: the version-1 contracts, golden
examples and a parser. There is no server, no network code and no app change here yet.

| Path | What |
|---|---|
| `pa_lab/contracts.py` | Version-1 specs for every document kind, `parse` / `validate` / `dump` / `describe` |
| `pa_lab/legacy.py` | The legacy `Lab/state` key=value file and its mapping to `Lab/state.json` |
| `pa_lab/__main__.py` | `python3 -m pa_lab check <kind> <file>`, `describe <kind>`, `kinds` |
| `contracts/v1/<kind>/*.json` | Golden examples, one folder per kind; canonical JSON (2-space indent, `\n` at end) |
| `contracts/v1/legacy/*.state` | Legacy `Lab/state` twins of three `app_state` goldens (`stopped_ui` is the real lab-B file of 2026-11-14) |
| `contracts/v1/invalid_cases.json` | Documents that must fail: name, kind, input, expected field path and message |
| `tests/test_contracts.py` | Golden parse, round-trip, invalid-case and legacy-mapping tests |

Stdlib only (Python 3.8+), so no venv yet; Slice 2 adds `requirements.txt` and a venv
(`~/.venvs/pa-lab`) for the MCP server. Run the tests from the repo root:

```sh
python3 -m unittest discover -s lab/server/tests -t lab/server -v
```

Check a real file (from `lab/server`):

```sh
python3 -m pa_lab check app_state "$HOME/Library/Application Support/SerialPrograms/Profiles/lab-B/Lab/state.json"
python3 -m pa_lab describe app_state # the full field tree of any kind
```

## Kinds and who writes them

The daemon never edits an app-authored document. Its resources embed one whole
(`console_state.app`, `save_resource.fact`) and put their own fields beside it, so the authorship
boundary is the object boundary.

| Kind | Writer | Where |
|---|---|---|
| `app_state` | app | `Lab/state.json`, rewritten atomically on every change and as a heartbeat |
| `save_fact` | app (a program that saved) | `Lab/save.json` |
| `console_state` | daemon | `console://B/state`: `app` + availability, lease, current refusals |
| `save_resource` | daemon | `console://B/save`: `known` / `stale` / `unknown`, reason, last fact |
| `request` | client | a mutating tool call (`acquire_console` ... `cfr_batch`) |
| `request_record` | daemon | request status and the stored result an exact retry gets back |
| `refusal` | daemon | a tool's error result, naming the failed check or field |
| `event` | daemon | one SQLite events row (and a JSONL export line) |
| `event_page` | daemon | the result of `next_events(after_seq)` |

## Rules for every kind

- **Version.** Every document has an integer `schema`; this reader supports `1`. A missing,
non-integer or unsupported version fails at `schema` before any other field is read. A
document embedded in another (`console_state.app`) carries its own `schema`.
- **Timestamps** are UTC strings with milliseconds and `Z`: `2026-11-14T06:10:12.124Z`. No
offsets, no epoch numbers. They round-trip as the exact string.
- **UUIDs** (`instance.id`, `request_id`) are lower-case `8-4-4-4-12`.
- **Required vs nullable.** "Required" means the key is present. A required key may still allow
`null` where the field tree says `| null`; `null` means "none" or "not known", never "ok".
Optional keys are omitted, not set to `null`, when a writer has nothing.
- **Unknown values.** Enums are closed within a version: a value the reader does not know fails
at that field (`video.signal: 'no_hdmi' is not one of ok, black, colour_bars, unknown`).
Observations that have no detector yet use the literal value `unknown`; a non-`unknown`
observation needs `observed_at` and `detector`.
- **Unknown fields.** Documents the app or daemon writes are *open*: a field the reader does not
know is kept verbatim, listed in `Parsed.unknown` and written back by `dump`, so diagnostics
survive a newer writer. Requests are *closed*: an unknown top-level key or tool argument is
refused, because requests are the daemon's input boundary.
- **Errors** name the field: `program.last_transition.request_id: required when source is lab`.
One parse reports every field error it found, except that a version error stops first.

### Compatibility

- Adding an optional field to an open object needs no version change; old readers keep it.
- Adding an enum value, adding a required field, removing, renaming or retyping a field, or
changing what a value means needs `schema: 2`, and the daemon keeps reading `1` until the app
stops writing it. A reader refuses versions it does not list; the daemon reports that as
`availability.reason: unsupported_schema`, not as a guess.

## `app_state` (`Lab/state.json`) and the legacy `Lab/state`

The app keeps writing the legacy file unchanged and writes `Lab/state.json` from the same state.
Every legacy field maps; only the owner token is reduced to a yes/no, so the token is not copied
into a second file.

| Legacy `Lab/state` | `Lab/state.json` |
|---|---|
| `seq=fs012327` | `channel.last_request` (`null` before the first request) |
| `state=STOPPED\|RUNNING\|STOPPING\|NOT_READY\|NO_PROGRAM` | `program.state`, lower case; `no_program` exactly when `panel.kind` is `other` |
| `program=PokemonFRLG:AutoStory` | `panel.id` when `panel.kind` is `program` (legacy writes empty otherwise) |
| `controller=ready\|none\|` | `controller.state` `ready` / `not_connected` / `no_console` |
| `owner=<token>` | `channel.owner_claimed` (bool); the token stays only in the legacy file |
| `error=` | `channel.last_error` (`null` when the last request succeeded) |
| `paused=<label>` | `program.paused` (optional; present only in builds with breakpoints) |

New in `state.json`: `written_at` (heartbeat), `instance.{id,pid,profile}`, `panel.kind`,
`program.run_id`, `program.last_transition.{action,source,request_id,at}`,
`video.{state,frame_seq,captured_at,signal}`, `observation.{game,screen}`.
`legacy.legacy_view()` is the mapping as code; `tests/test_contracts.py` checks the three twins.

## What Slice 1 (the app writer) must produce

- `Lab/state.json` replaced atomically (write beside, then rename) whenever the legacy file is
written, and at least every few seconds as a heartbeat with a fresh `written_at`.
- A new lower-case UUID in `instance.id` per app start; `instance.pid`; `instance.profile`.
- `program.last_transition` set where Start/Stop is called: `ui` from the widget, `lab` with the
inbox request's `request_id` (a UUID; the daemon will put it on the request), `program` when the
program ends itself, `error` when it ends by exception. `request_id` is `null` unless `lab`.
- `video.frame_seq` / `captured_at` from the frame cache; `state: live` requires both.
`signal`, `observation.game` and `observation.screen` stay `unknown` until their detectors exist.
- Lower-case enums exactly as listed by `python3 -m pa_lab describe app_state`.
- Checked by `python3 -m pa_lab check app_state <file>` and by a native serialization test
against the goldens in `contracts/v1/app_state/`.
57 changes: 57 additions & 0 deletions lab/server/contracts/v1/app_state/future_fields.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
{
"schema": 1,
"written_at": "2026-11-14T06:10:12.124Z",
"instance": {
"id": "d8ea6a9d-1eab-4a40-b355-d88072b289a1",
"pid": 4411,
"profile": "lab-B"
},
"panel": {
"id": "PokemonFRLG:AutoStory",
"kind": "program"
},
"program": {
"state": "stopped",
"run_id": null,
"last_transition": {
"action": "stop",
"source": "ui",
"request_id": null,
"at": "2026-11-14T06:10:10.002Z",
"note": "added by a newer app, same schema 1"
}
},
"controller": {
"state": "ready"
},
"video": {
"state": "live",
"frame_seq": 918274,
"captured_at": "2026-11-14T06:10:12.091Z",
"signal": "unknown",
"fps": 29.97
},
"observation": {
"game": {
"value": "unknown",
"observed_at": null,
"candidates": [
"PokemonFRLG",
"PokemonBDSP"
]
},
"screen": {
"value": "unknown",
"observed_at": null
}
},
"channel": {
"last_request": "fs012327",
"last_error": null,
"owner_claimed": false
},
"build": {
"commit": "abc1234",
"dirty": false
}
}
41 changes: 41 additions & 0 deletions lab/server/contracts/v1/app_state/no_program.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
{
"schema": 1,
"written_at": "2026-11-14T05:00:00.000Z",
"instance": {
"id": "0c7b3f52-91d4-4e8a-a3f6-5b2e7d10c9a4",
"pid": 3902
},
"panel": {
"id": null,
"kind": "other"
},
"program": {
"state": "no_program",
"run_id": null,
"last_transition": null
},
"controller": {
"state": "no_console"
},
"video": {
"state": "missing",
"frame_seq": null,
"captured_at": null,
"signal": "unknown"
},
"observation": {
"game": {
"value": "unknown",
"observed_at": null
},
"screen": {
"value": "unknown",
"observed_at": null
}
},
"channel": {
"last_request": "r1",
"last_error": "The selected panel is not a program.",
"owner_claimed": false
}
}
50 changes: 50 additions & 0 deletions lab/server/contracts/v1/app_state/running_lab.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
{
"schema": 1,
"written_at": "2026-11-14T07:02:41.500Z",
"instance": {
"id": "d8ea6a9d-1eab-4a40-b355-d88072b289a1",
"pid": 4411,
"profile": "lab-B"
},
"panel": {
"id": "PokemonBDSP:AutoStory",
"kind": "program"
},
"program": {
"state": "running",
"run_id": null,
"last_transition": {
"action": "start",
"source": "lab",
"request_id": "5f0c2a8e-3d41-4b7a-9c55-0e6a1f2b7c10",
"at": "2026-11-14T07:01:03.250Z"
},
"paused": "01.04 leg 3"
},
"controller": {
"state": "ready"
},
"video": {
"state": "live",
"frame_seq": 921930,
"captured_at": "2026-11-14T07:02:41.466Z",
"signal": "unknown"
},
"observation": {
"game": {
"value": "PokemonBDSP",
"observed_at": "2026-11-14T07:01:02.900Z",
"detector": "bdsp_overworld",
"confidence": 0.97
},
"screen": {
"value": "unknown",
"observed_at": null
}
},
"channel": {
"last_request": "r42",
"last_error": null,
"owner_claimed": true
}
}
47 changes: 47 additions & 0 deletions lab/server/contracts/v1/app_state/stopped_ui.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
{
"schema": 1,
"written_at": "2026-11-14T06:10:12.124Z",
"instance": {
"id": "d8ea6a9d-1eab-4a40-b355-d88072b289a1",
"pid": 4411,
"profile": "lab-B"
},
"panel": {
"id": "PokemonFRLG:AutoStory",
"kind": "program"
},
"program": {
"state": "stopped",
"run_id": null,
"last_transition": {
"action": "stop",
"source": "ui",
"request_id": null,
"at": "2026-11-14T06:10:10.002Z"
}
},
"controller": {
"state": "ready"
},
"video": {
"state": "live",
"frame_seq": 918274,
"captured_at": "2026-11-14T06:10:12.091Z",
"signal": "unknown"
},
"observation": {
"game": {
"value": "unknown",
"observed_at": null
},
"screen": {
"value": "unknown",
"observed_at": null
}
},
"channel": {
"last_request": "fs012327",
"last_error": null,
"owner_claimed": false
}
}
Loading
Loading