Skip to content
Draft
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
15 changes: 12 additions & 3 deletions lab/server/GUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,8 @@ SerialPrograms lab app on profile `lab-B`, and its log) through MCP, the protoco
uses for tools. Instead of an agent running shell scripts and grepping logs to work out what
the console is doing, it asks pa-lab and gets one structured answer.

Today it only reads. Nothing in it presses a button, starts or stops a program, or writes to
the app. Console A is never part of it.
Today, as connected to your sessions, it only reads: nothing there presses a button, starts or
stops a program, or writes to the app. Console A is never part of it.

Developer details (contracts, slices, tests) are in [README.md](README.md); the design is
`docs/design/Agent-Integration.md` on branch `design/agent-integration`.
Expand Down Expand Up @@ -53,12 +53,21 @@ game in front, or HOME / user select / black screen), `shot` (a fresh screenshot
`ensure_game`. The control plane is also built: console leases, request records that make a
retried request safe, and an event log. None of it presses buttons yet.

**Starting and stopping a program (Slice 5a).** `run_program` and `stop_program` exist, but only
when the server is started with `serve --actions`, which nothing uses yet; your session connection
stays read-only. An agent holding the console's lease can start the program selected in the app
(with its current options) and stop it. It is refused whenever you hold the console (you clicked
Start or Stop), when another program is running, when the app is not running, or when the
selected program is not the one asked for. If you click Start or Stop while an agent's start or
stop is under way, yours wins and the agent's request is marked failed. Every start and stop is
one record, and a retried request never starts the program twice.

## 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. |
| 5 (rest) | The server runs the program's start checks before a start and refuses on a failed one (`preflight_program`), passes options, and runs debug button batches (`cfr_batch`); then a soak on console B |
| 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 |
Expand Down
68 changes: 66 additions & 2 deletions lab/server/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,9 @@ The local server designed in `docs/design/Agent-Integration.md` (fork #131, bran
`design/agent-integration`). Slice 0: the version-1 contracts, golden examples and a parser.
Slice 2: the attach-only read server ([below](#slice-2-the-attach-only-read-server)). Slice 3: the
durable control plane ([below](#slice-3-the-durable-control-plane)): leases, request records,
tickets and events in SQLite. Nothing presses a button yet: that is Slice 5.
tickets and events in SQLite. Slice 5a: leased `run_program` and `stop_program`
([below](#slice-5a-run_program-and-stop_program)), served only by `serve --actions`, which nothing is
wired to yet. Nothing presses a button: that is Slice 5b's `cfr_batch`.

New here? Start with [GUIDE.md](GUIDE.md): what pa-lab is and what it gives you today.

Expand All @@ -22,12 +24,14 @@ New here? Start with [GUIDE.md](GUIDE.md): what pa-lab is and what it gives you
| `pa_lab/tools.py`, `pa_lab/shot.py` | `ensure_game` (verification only) and `shot` (newer than the call) |
| `pa_lab/mcp_server.py` | MCP over Streamable HTTP on `127.0.0.1`: bearer, Host/Origin, sessions, size caps |
| `pa_lab/app_query.py` | `describe_program` and `game_open`: one-line reads through the app's channel (#504) |
| `tests/fake_lab.py` | A fake `Lab/` folder and a fake app answering `snapshot`, `describe_program` and `game_open` requests, in temp dirs |
| `tests/fake_lab.py` | A fake `Lab/` folder and a fake app answering `snapshot`, `describe_program`, `game_open`, `start` and `stop` requests, in temp dirs |
| `tests/test_{lab_reader,ensure_game,shot,config,mcp_server}.py` | Slice 2's fake-lab tests |
| `tests/test_app_query.py` | `describe_program` and `game_open` against the fake app |
| `pa_lab/db.py` | The SQLite file: migrations (`PRAGMA user_version`), owner-only file, `BEGIN IMMEDIATE` writes |
| `pa_lab/control.py` | Leases, idempotent requests, tickets, events, `next_events`, reconciliation, compaction |
| `tests/test_{db,control,control_concurrency,control_mcp}.py` | Slice 3's tests: restarts, threads and processes racing, kills mid-write |
| `pa_lab/actions.py` | Slice 5a: `run_program` / `stop_program` through the control plane and the app's `start` / `stop` channel commands |
| `tests/test_actions.py` | Slice 5a's refusals, retries and races against the fake app |
| `pa_lab/status.py`, `pa_lab/stdio_server.py`, `smoke_readonly.py` | Read-only stdio mode for `.mcp.json`: `console_status` ([below](#read-only-stdio-mode-mcpjson)) |
| `tests/test_status_readonly.py` | `console_status` and the read-only gate against a fake profile |

Expand Down Expand Up @@ -293,3 +297,63 @@ 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.

## Slice 5a: `run_program` and `stop_program`

`python3 -m pa_lab serve --config ... --actions` adds the two tools to the HTTP server (and
`ACTION_INSTRUCTIONS` to `initialize`). Without `--actions` they are neither listed nor callable;
`--read-only` and `serve-stdio` (the `.mcp.json` entry) never have them, and `--read-only --actions`
is a usage error.

```text
run_program(console, request_id, lease_token, panel, options={}) # options must be {} in 5a
stop_program(console, request_id, lease_token)
```

Each call is one request record (`ControlPlane.begin_action`, one transaction): an exact retry gets
the stored record, refusals included, and never sends a second line; the same `request_id` with
other arguments is `request_id_reused` (not stored). The checks run in this order; a failed one is
stored as a `refused` record with a `request_failed` event, and nothing reaches `Lab/inbox`.

| Check | Refusal |
|---|---|
| the request's token holds the lease (idle or running) | `lease_invalid`, `lease_expired`, `console_held_by_user` (a UI Start/Stop or the operator) |
| no earlier run/stop on the console is still pending | `program_not_stopped`, `evidence.pending_tool` |
| `Lab/state.json` is live | `app_unavailable`, `evidence.reason` = the availability reason |
| run: `options` is `{}`, no `preflight_token` | `invalid_arguments` (`options`, `preflight_token`) |
| run: `panel` is the selected program | `invalid_arguments`, field `panel`, `evidence.selected`; `panel_not_program` on the settings page |
| run: `console://B/state`'s `blocked` (program state, controller, video) | `program_running`, `program_not_stopped` (loading), `controller_not_ready`, `video_stale`, `video_bad_signal` |
| the channel's owner lock is not claimed (`channel.owner_claimed`) | `console_held_by_agent`, `evidence.reason: channel_owned` |
| stop: a program is running | not a refusal: `completed` with `sent: false` and the program state |

A passing request is stored `pending` with the app instance it was checked against (table
`actions`, migration 2), and the daemon writes `request <request_id>` / `start 10` (or `stop`)
into `Lab/inbox`, the commands `labctl.sh start|stop` sends; the client's `request_id` is the
channel's request id. It then reads the journal and `state.json` (up to 13 s for a start, 10 s for
a stop) and resolves the record:

| The app shows | Record |
|---|---|
| `last_transition` = this request's start | `completed`, `correlated_by: request_id`; the lease enters `agent_running` in the same transaction, unless `observe` already applied a newer transition |
| `last_transition` = this request's stop, `program.state` `stopped` | `completed`, `stopped_by: lab` |
| after the start's `ok`, a stop by `program` / `error` dated after the request | `completed` with `ended: {source, at}`, `correlated_by: time`; the lease stays idle |
| (stop) a stop by `program` / `error` dated after the request | `completed`, `stopped_by` that source, `correlated_by: time` (the terminal event completes it) |
| a UI transition dated after the request | `failed`, `console_held_by_user` (the user lease is already installed) |
| another `instance.id` without this request's id | `failed`, `app_unavailable`, `instance_replaced` |
| the line failed | `failed`: `owned by` → `console_held_by_agent` (the token is not copied); `Program is RUNNING.` → `program_running`; `controller not connected` → `controller_not_ready`; else `app_unavailable` with the journal |
| no answer, request still in the inbox | withdrawn; `failed`, `timeout` (nothing was sent) |
| no answer, request taken | stays `pending`; settled from `state.json` on the next `request_status`, `next_events`, `console://B/state` read or action call, also after a daemon restart; `failed` / `app_unavailable` if the app exits |

**What Slice 1's data does not give.** `last_transition` keeps only the newest start or stop, and
`run_id` is null until run records exist (#116). So a run that ends before the daemon reads
`state.json` is matched by time (a `program`/`error` stop dated after the request, on the same
instance, after the start's `ok` line), not by id, and its `started_at` is unknown. A `run_id` on
the stop transition, or the app keeping the start beside the stop, would make that match exact.

**Left for Slice 5b.** `preflight_program`: the app has no channel command that runs a program's
prechecks (or stages candidate options) without starting it, so 5a sends no preflight, runs the
panel's current options, and the program's own `run_prechecks()` at Start are the only checks;
`run_program`'s `preflight_token` became optional in the v1 request contract for this and 5b makes
it required again. Also 5b: staging `options`, claiming the channel's owner token (a claimed
channel is refused today), `cfr_batch`, and the console-B soak (every mutation has exactly one
record).
7 changes: 4 additions & 3 deletions lab/server/contracts/v1/invalid_cases.json
Original file line number Diff line number Diff line change
Expand Up @@ -1911,7 +1911,7 @@
}
},
{
"name": "run without preflight token",
"name": "run with a preflight token that is not a string",
"kind": "request",
"input": {
"json": {
Expand All @@ -1927,13 +1927,14 @@
"START_CHECKPOINT": "13.01",
"END_CHECKPOINT": "13.02",
"SAVE_MODE": "none"
}
},
"preflight_token": 5
}
}
},
"expectation": {
"path": "arguments.preflight_token",
"contains": "required field is missing"
"contains": "expected a string"
}
},
{
Expand Down
17 changes: 13 additions & 4 deletions lab/server/pa_lab/__main__.py
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
python3 -m pa_lab describe app_state
python3 -m pa_lab kinds
python3 -m pa_lab init-token ~/.config/pa-lab/token
python3 -m pa_lab serve --config ~/.config/pa-lab/server.json [--read-only]
python3 -m pa_lab serve --config ~/.config/pa-lab/server.json [--read-only | --actions]
python3 -m pa_lab serve-stdio --profile-dir ~/Library/Application\\ Support/SerialPrograms/Profiles/lab-B
python3 -m pa_lab lease --config ~/.config/pa-lab/server.json show|claim-user|release-user

Expand Down Expand Up @@ -35,6 +35,8 @@ def main(argv=None) -> int:
serve.add_argument('--config', required=True)
serve.add_argument('--read-only', action='store_true',
help='serve only console_status and the resources: no inbox tools, no control plane')
serve.add_argument('--actions', action='store_true',
help='also serve run_program and stop_program (Slice 5a): they start and stop the program')
stdio = sub.add_parser('serve-stdio', help='run the read-only MCP server on stdio (for .mcp.json)')
stdio.add_argument('--profile-dir', required=True, help="the console's SerialPrograms profile folder")
stdio.add_argument('--keepawake-log', default='~/BDSPLab/keepawake.log')
Expand Down Expand Up @@ -77,7 +79,10 @@ def main(argv=None) -> int:
print('wrote {}'.format(args.path))
return 0
if args.command == 'serve':
return _serve(args.config, args.read_only)
if args.read_only and args.actions:
print('error --read-only and --actions exclude each other')
return 2
return _serve(args.config, args.read_only, args.actions)
if args.command == 'serve-stdio':
from pa_lab import stdio_server
return stdio_server.main(args.profile_dir, args.keepawake_log)
Expand All @@ -87,7 +92,7 @@ def main(argv=None) -> int:
return 2


def _serve(path: str, read_only: bool = False) -> int:
def _serve(path: str, read_only: bool = False, actions: bool = False) -> int:
from pa_lab import lab_reader, mcp_server
try:
cfg = config.load(path)
Expand All @@ -112,7 +117,11 @@ def _serve(path: str, read_only: bool = False) -> int:
for reader in readers.values(): # restart reconciliation: apply what the app shows now
reader.console_state()
plane.compact()
server = mcp_server.make_server(cfg.port, token, readers, control_plane=plane)
program_actions = None
if actions:
from pa_lab import actions as actions_module
program_actions = actions_module.ProgramActions(plane, readers)
server = mcp_server.make_server(cfg.port, token, readers, control_plane=plane, actions=program_actions)
return _serve_forever(server, readers, mcp_server.ENDPOINT)


Expand Down
Loading
Loading