diff --git a/lab/server/README.md b/lab/server/README.md index e67810ac60..8c33023fa0 100644 --- a/lab/server/README.md +++ b/lab/server/README.md @@ -4,7 +4,8 @@ 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 5 ([below](#slice-5-leased-actions)): `stop_program`, the first +leased action, and `cfr_batch`, allowlisted console lines for debugging. Nothing starts a program yet. | Path | What | |---|---| @@ -26,6 +27,10 @@ tickets and events in SQLite. Nothing presses a button yet: that is Slice 5. | `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` | Leased actions (Slice 5): `stop_program`, the channel request it sends and how its reply is read | +| `tests/test_actions.py` | Slice 5's tests: the ticket, retries, refusals, UI takeover, app restart, a terminal event before the response | +| `pa_lab/cfr.py` | The `cfr_batch` allowlist: allowed commands, bounds, the batch's worst-case time | +| `tests/test_cfr.py`, `tests/test_cfr_batch.py` | Slice 5b's tests: every allowed and refused line form; the batch's refusals, journal, save staleness and races | Stdlib only (Python 3.8+), so no venv: the MCP transport is small enough to write on `http.server`. Run the tests from the repo root: @@ -137,7 +142,9 @@ python3 -m pa_lab serve --config ~/.config/pa-lab/server.json "profile": "lab-B"}}} ``` -The config is the server's own, closed, and must list exactly `B`; it never reads +The config is the server's own, closed, and must list exactly `B`. `consoles.B.channel_owner` +(optional, one word, default the profile) is the token Slice 5's actions claim the app's channel +with; it never reads `~/BDSPLab/consoles.json`. A Claude Code client adds it as an HTTP MCP server at `http://127.0.0.1:8765/mcp` with the header `Authorization: Bearer `. @@ -264,3 +271,88 @@ 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 5: leased actions + +Built so far: `stop_program`, the first tool that changes what the app does, and `cfr_batch` +([below](#cfr_batch)). `preflight_program` and `run_program` need app-side commands first; see the +list in the PR that added this section. + +**A leased action is a ticket.** `stop_program(console, request_id, lease_token)` returns its +request record at once: `pending` until the app reports the outcome, which arrives as a +`request_completed` / `request_failed` event (`next_events`) and in `request_status`. The tool +does not wait for the program to stop. `ControlPlane.begin_action` stores the call in one +transaction with the lease check: an exact retry gets the stored record and sends nothing; the +lease must be held by the token (an idle lease is renewed by the call); a program that is not +`running` completes at once with `outcome: not_running`; otherwise the record is `pending` and +remembers the app instance it was sent to (`requests.instance_id`, migration 2). + +**The channel request** (Lab.md "Requests", "Owner") is fixed text: + +``` +owner lab-B +request +owner claim lab-B +stop +``` + +The daemon claims the channel with `channel_owner` before each action rather than once at +attach, so it works across app restarts and beside `lab/scripts/lc.sh`, which uses the same +default token. The app puts `request_id` on `program.last_transition` and keeps it from +`stopping` to `stopped`. + +**What resolves the ticket.** The app's report, applied by `observe` on every read of +`console://B/state`, every `request_status`, and every poll of a waiting `next_events`: + +| The app shows | Ticket | +|---|---| +| `stopped`, `last_transition` `{stop, lab, }` | completed, `outcome: stopped` | +| `stopping` with that transition | still pending | +| `stopped` by `program` or `error` at or after the call | completed, `outcome: ended` (the run's own end) | +| a UI Start/Stop at or after the call | failed, `console_held_by_user`; the lease becomes `user` | +| another `instance.id` | failed, `app_unavailable`, `evidence.reason: instance_replaced` | +| (the stop line failed and nothing runs) | completed, `outcome: not_running` | +| (the stop line failed otherwise, e.g. `owned by `) | failed, `app_unavailable`, the journal in `evidence` | +| (no journal within 7 s and the request still in the inbox) | withdrawn; `refused`, `timeout`: nothing was sent | +| (no journal within 7 s and the app took the request) | still pending; the rows above resolve it | + +A stop by this lease holder ends `agent_running` as before (`lease_changed`, reason `run_ended`). +`begin_run` (Slice 3) is still entered only by tests: `run_program` will call it. + +### cfr_batch + +`cfr_batch(console, request_id, lease_token, lines)` is for debugging between runs: 1-200 lines of +the app's console commands (Lab.md "Console"), sent under the lease as one channel request after +the same `owner` / `request` / `owner claim` lines as `stop_program`. Raw writes to `Lab/inbox` +are still not exposed: `pa_lab/cfr.py` checks every line before anything is stored or sent. + +| Allowed | Bounds | +|---|---| +| `press BTN[+BTN] [hold] [release]` | buttons `A B X Y L R ZL ZR PLUS MINUS LCLICK RCLICK HOME` (no `CAPTURE`); hold, release 0-10000 ms | +| `dpad DIR [hold] [release] [BTN[+BTN]]`, `stick L\|R x y [hold] [release] [BTN[+BTN]]` | x, y -1..1 (3 decimals) | +| `wait ms` | 0-30000 | +| `taps DIR N [all] [hold] [release] [still]`, `walk x y [max] [still] [BTN[+BTN]]` | N 1-20; max 200-10000 | +| `shot LABEL`, `shots LABEL count [interval]` | label `A-Z a-z 0-9 _ -`, 1-64; count 1-10; interval 100-5000 | +| `detect D`, `wait_for D [timeout]`, `expect D [timeout]`, `game_open` | detector names only (no image path); timeout 0-30000 | + +Everything else is refused (`invalid_arguments`, `field` = `arguments.lines[i]`): channel +commands, `close_game`, `history`, `snapshot`, `state`, game-registered commands, comments, blank +lines and lines not in canonical form (single spaces). The sum of the lines' worst cases must fit +in 60 s (`field` = `arguments.lines`), so the call, which waits for the journal, is bounded. + +The call also refuses (stored, nothing sent) unless the program is `stopped` on a program panel, +the controller `ready` and the video `live`. Then it marks `console://B/save` stale (reason +`cfr_batch`, kept in the database across restarts) before sending: only a program-authored save +newer than the batch makes the fact `known` again. + +| The journal shows | Record | +|---|---| +| every line `ok` | completed, `outcome: done`, `journal` | +| a batch line failed (an `expect` timeout, a refused press) | completed, `outcome: line_failed`, `failed_line` (1-based), `error`, `journal` | +| the owner lines failed (`owned by `) | failed, `app_unavailable`; nothing ran | +| (nothing in time, request still in the inbox) | withdrawn; refused, `timeout` | +| (nothing in time, the app took it) | failed, `timeout`; it may have run in part | +| (the app restarted while it was pending) | failed, `app_unavailable`, `evidence.reason: instance_replaced` | + +An exact retry sends nothing; a retry of a ticket left `pending` (the daemon stopped while +waiting) collects its journal. diff --git a/lab/server/pa_lab/__main__.py b/lab/server/pa_lab/__main__.py index f12b07518d..f69307625c 100644 --- a/lab/server/pa_lab/__main__.py +++ b/lab/server/pa_lab/__main__.py @@ -94,7 +94,9 @@ def _serve(path: str) -> 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) + server = mcp_server.make_server(cfg.port, token, readers, control_plane=plane, + channel_owners={name: entry.channel_owner for name, entry in cfg.consoles.items() + if entry.channel_owner is not None}) logging.getLogger('pa_lab.server').info('serving %s on http://127.0.0.1:%d%s', ', '.join(sorted(readers)), server.server_address[1], mcp_server.ENDPOINT) diff --git a/lab/server/pa_lab/actions.py b/lab/server/pa_lab/actions.py new file mode 100644 index 0000000000..394a8e2407 --- /dev/null +++ b/lab/server/pa_lab/actions.py @@ -0,0 +1,260 @@ +"""Leased actions (Slice 5 of fork #131). First: `stop_program`. + +A leased action is a long operation: the tool stores a ticket, sends one fixed request into the +app's channel and returns; the app's own report in `Lab/state.json` completes it. Agents do not +park on the call: they read `request_status` or wait in `next_events` for the ticket's +`request_completed` / `request_failed` event. + +`stop_program(console, request_id, lease_token)`: + +1. Read `Lab/state.json` (the app is up; its instance) and apply it (`observe`), so a UI click + that already happened takes the console before this call is decided. +2. `ControlPlane.begin_action`: the lease must be held by the token; a program that is not + `running` completes at once (`outcome: not_running`); otherwise a `pending` ticket bound to + that app instance. An exact retry returns the stored record and sends nothing. +3. Send `owner T` / `request ` / `owner claim T` / `stop` (Lab.md "Requests", + "Owner"). `T` is the console's channel owner from the config; the app names `request_id` in + `program.last_transition` and keeps it from `stopping` to `stopped`. +4. Wait for the journal (the line itself is immediate; the program stops in the background): + - `ok`: read the state again; the ticket completes when the app reports `stopped` with this + request id, possibly already in this read (a terminal event before the response); + - a failed line: if the program is no longer running the stop is moot (`not_running`), + otherwise the ticket fails with the app's error; + - no journal in time: if the request is still in the inbox it is withdrawn and the ticket is + `refused` with `timeout` (nothing was sent); if the app took it, the ticket stays pending + and resolves from the state as above. + +No caller string reaches the inbox: the request id is a checked UUID and the rest is fixed text. + +`cfr_batch(console, request_id, lease_token, lines)` (5b) sends console lines (presses, waits, +screen reads) that `pa_lab/cfr.py` allows, and waits for their journal: + +1. As above, the app's state is read and applied first. +2. `begin_action` checks the lease; the batch is refused (stored) unless every line is allowed + and its worst case fits in `cfr.BATCH_MAX_MS`, the program is `stopped` on a program panel, + the controller is `ready` and the video `live`. +3. `console:///save` is marked stale (`cfr_batch`) before anything is sent: from here on the + game may differ from the last save fact, even if the batch never runs. +4. Send `owner T` / `request ` / `owner claim T` / the lines, and wait for the journal + for the batch's worst case plus the answer time: + - all `ok`: completed, `outcome: done`, with the journal; + - a batch line failed (an `expect` timed out, a press refused): completed, + `outcome: line_failed`, `failed_line` (1-based, as in `lines`), `error` and the journal: the + batch ran up to that line, which is an answer, not a server fault; + - the owner lines failed: failed, `app_unavailable`, nothing ran; + - no journal in time: `refused`, `timeout` if the request was still in the inbox (withdrawn, + nothing ran); otherwise `failed`, `timeout`: the batch may have run in part. +5. An exact retry sends nothing; if the stored ticket is still `pending` (the daemon stopped while + waiting), the retry collects the journal the same way. An app restart fails a pending batch + (`observe`). +""" + +from __future__ import annotations + +import os +import time +from pathlib import Path +from typing import Any, Callable, Dict, List, Optional + +import re + +from pa_lab import cfr, control, shot, timestamps +from pa_lab.lab_reader import ConsoleReader, Unavailable + +STOP_ANSWER_MS = 5000 +JOURNAL_POLL_S = 0.05 + +__all__ = ['stop_program', 'cfr_batch', 'ACTIONS', 'request_text'] + +JOURNAL_ERROR_RE = re.compile(r'^error ([0-9]+) ') +OWNER_LINES = 3 # owner, request, owner claim: a journal line number above this is a batch line + + +def request_text(owner: str, request_id: str, commands: List[str]) -> str: + """A channel request that claims the channel for `owner` and runs `commands` under it. + + `owner T` must be the first line and `request ` follows (Lab.md "Requests"); + `owner claim T` succeeds when the channel is free or already T's. + """ + return ''.join('{}\n'.format(line) for line in + ['owner ' + owner, 'request ' + request_id, 'owner claim ' + owner] + commands) + + +def _send(lab_dir: Path, name: str, text: str) -> Path: + part = lab_dir / 'outbox' / (name + '.part') + inbox = lab_dir / 'inbox' / (name + '.txt') + part.write_text(text, encoding='utf-8') + os.replace(part, inbox) + return inbox + + +def _journal(reader: ConsoleReader, sleep: Callable[[float], None], deadline: float, name: str) -> Optional[List[str]]: + path = reader.lab_dir / 'outbox' / (name + '.out') + while True: + if path.exists(): + lines = path.read_text(encoding='utf-8', errors='replace').splitlines() + if lines and lines[-1] == 'end': + return lines + if reader.now() >= deadline: + return None + sleep(JOURNAL_POLL_S) + + +def _withdrawn(inbox: Path) -> bool: + """True when the request was still in the inbox and is now gone: the app never saw it.""" + try: + os.remove(inbox) + return True + except FileNotFoundError: + return False + + +def _not_running(app: Dict[str, Any]) -> Dict[str, Any]: + program = app['program'] + return {'outcome': 'not_running', 'instance_id': app['instance']['id'], 'run_id': program['run_id'], + 'program_state': program['state']} + + +def stop_program(plane: control.ControlPlane, reader: ConsoleReader, client_id: str, request: Dict[str, Any], + owner: str, sleep: Callable[[float], None] = time.sleep) -> Dict[str, Any]: + """Runs one stop_program request; returns its request_record (pending, completed, refused or failed). + + Raises control.Refused for a request that cannot be keyed (bad console, request id or + arguments, or an id reused with other arguments); those are not stored. + """ + started = reader.now() + try: + app = reader.app_state() + except Unavailable as e: + app, unavailable = None, e + else: + plane.observe(reader.console, app) + + def decide(lease_row) -> Optional[Dict[str, Any]]: + if app is None: + refusal = unavailable.refusal() + raise control.Refused(refusal.pop('code'), refusal.pop('message'), **refusal) + if app['program']['state'] != 'running': + return _not_running(app) + return None + + record, send = plane.begin_action(client_id, request, None if app is None else app['instance']['id'], decide) + if not send: + return record + request_id = record['request_id'] + name = 'palab_stop_program_{}'.format(request_id.replace('-', '')) + inbox = _send(reader.lab_dir, name, request_text(owner, request_id, ['stop'])) + lines = _journal(reader, sleep, started + (STOP_ANSWER_MS + shot.ANSWER_GRACE_MS) / 1000.0, name) + if lines is None: + if _withdrawn(inbox): + return plane.resolve_ticket(client_id, 'stop_program', request_id, refusal={ + 'code': 'timeout', 'message': 'The app did not take the stop request in time; nothing was sent.', + 'evidence': {'request': name}}, acted=False) + return plane.record(client_id, 'stop_program', request_id) + errors = [line for line in lines if line.startswith('error ')] + if errors: + try: + now = reader.app_state() + except Unavailable: + now = None + if now is not None and now['instance']['id'] == app['instance']['id'] and \ + now['program']['state'] != 'running': + reader.console_state() + return plane.resolve_ticket(client_id, 'stop_program', request_id, result=_not_running(now)) + return plane.resolve_ticket(client_id, 'stop_program', request_id, refusal={ + 'code': 'app_unavailable', 'message': "The app refused the stop: {}".format(errors[0]), + 'evidence': {'journal': lines}}) + reader.console_state() # applies observe: the stop may already be reported + return plane.record(client_id, 'stop_program', request_id) + + +def _batch_refusal(app: Dict[str, Any]) -> Optional[control.Refused]: + """Why a batch cannot run on the app as it is now, or None. Stricter than the app, which only + refuses presses while a program runs: a batch needs a stopped program panel, a ready + controller and live video (so its shots and detectors see the console).""" + state = app['program']['state'] + panel = app['panel']['id'] + if state == 'no_program': + return control.Refused('panel_not_program', 'The selected panel is not a program; a batch needs its console.') + if state in ('running', 'stopping'): + return control.Refused('program_running', '{} is {}; stop it first.'.format(panel, state)) + if state != 'stopped': + return control.Refused('program_not_stopped', '{} is {}.'.format(panel, state.replace('_', ' '))) + if app['controller']['state'] != 'ready': + return control.Refused('controller_not_ready', 'The controller is {}.'.format( + app['controller']['state'].replace('_', ' '))) + if app['video']['state'] != 'live': + return control.Refused('video_stale', 'The video is {}.'.format(app['video']['state'])) + return None + + +def _batch_name(request_id: str) -> str: + return 'palab_cfr_batch_{}'.format(request_id.replace('-', '')) + + +def _batch_result(plane: control.ControlPlane, client_id: str, request_id: str, instance_id: str, + lines: List[str]) -> Dict[str, Any]: + errors = [JOURNAL_ERROR_RE.match(line) for line in lines] + failed = next(((m, line) for m, line in zip(errors, lines) if m is not None), None) + if failed is not None and int(failed[0].group(1)) <= OWNER_LINES: + return plane.resolve_ticket(client_id, 'cfr_batch', request_id, refusal={ + 'code': 'app_unavailable', 'message': 'The app refused the batch: {}'.format(failed[1]), + 'evidence': {'journal': lines}}) + result = {'outcome': 'done', 'instance_id': instance_id, 'journal': lines} + if failed is not None: + result.update(outcome='line_failed', failed_line=int(failed[0].group(1)) - OWNER_LINES, error=failed[1]) + return plane.resolve_ticket(client_id, 'cfr_batch', request_id, result=result) + + +def _collect(plane: control.ControlPlane, reader: ConsoleReader, client_id: str, request_id: str, + instance_id: str, deadline: float, sleep: Callable[[float], None]) -> Dict[str, Any]: + name = _batch_name(request_id) + lines = _journal(reader, sleep, deadline, name) + if lines is not None: + return _batch_result(plane, client_id, request_id, instance_id, lines) + if _withdrawn(reader.lab_dir / 'inbox' / (name + '.txt')): + return plane.resolve_ticket(client_id, 'cfr_batch', request_id, refusal={ + 'code': 'timeout', 'message': 'The app did not take the batch in time; nothing was sent.', + 'evidence': {'request': name}}, acted=False) + return plane.resolve_ticket(client_id, 'cfr_batch', request_id, refusal={ + 'code': 'timeout', 'message': 'The app took the batch but wrote no journal in time; it may have run in part.', + 'evidence': {'request': name}}) + + +def cfr_batch(plane: control.ControlPlane, reader: ConsoleReader, client_id: str, request: Dict[str, Any], + owner: str, sleep: Callable[[float], None] = time.sleep) -> Dict[str, Any]: + """Runs one cfr_batch request; returns its request_record (completed, refused or failed; pending + only when the daemon is stopped while waiting). Raises control.Refused as stop_program does.""" + started = reader.now() + try: + app = reader.app_state() + except Unavailable as e: + app, unavailable = None, e + else: + plane.observe(reader.console, app) + + def decide(lease_row) -> Optional[Dict[str, Any]]: + if app is None: + refusal = unavailable.refusal() + raise control.Refused(refusal.pop('code'), refusal.pop('message'), **refusal) + cfr.check(request['arguments']['lines']) + refused = _batch_refusal(app) + if refused is not None: + raise refused + return None + + record, send = plane.begin_action(client_id, request, None if app is None else app['instance']['id'], decide) + if record['status'] != 'pending': + return record + request_id = record['request_id'] + budget_s = (cfr.check(record['arguments']['lines']) + STOP_ANSWER_MS + shot.ANSWER_GRACE_MS) / 1000.0 + if not send: + deadline = timestamps.parse(record['created_at']) + budget_s + return _collect(plane, reader, client_id, request_id, app['instance']['id'] if app else None, + deadline, sleep) + plane.mark_save_stale(reader.console, 'cfr_batch') + _send(reader.lab_dir, _batch_name(request_id), request_text(owner, request_id, record['arguments']['lines'])) + return _collect(plane, reader, client_id, request_id, app['instance']['id'], started + budget_s, sleep) + + +ACTIONS = {'stop_program': stop_program, 'cfr_batch': cfr_batch} diff --git a/lab/server/pa_lab/cfr.py b/lab/server/pa_lab/cfr.py new file mode 100644 index 0000000000..b608a58bcf --- /dev/null +++ b/lab/server/pa_lab/cfr.py @@ -0,0 +1,214 @@ +"""The `cfr_batch` allowlist (Slice 5 of fork #131): which console lines a leased agent may send. + +A batch is 1-200 lines in the app's console-command syntax (Lab.md "Console"), each checked here +before anything is stored or sent. Only controller and screen-reading commands pass; every +number is bounded, and the batch's worst-case duration must fit in `BATCH_MAX_MS`, so the call +that waits for its journal is bounded too. Left out on purpose: + +- channel commands (`select`, `set`, `start`, `stop`, `owner`, `request`, `keepawake`, `popups`, + `snapshot`, `describe_program`, `state`, `help`): the server has its own tools for these; +- `close_game` (loses unsaved progress) and `history` (writes a recording); +- the `CAPTURE` button (writes to the console's album); +- the `image` argument of `detect` / `game_open`, which names a file; +- game-registered commands, comments (`#`) and blank lines; +- any line not in canonical form (single spaces, no leading or trailing space). + +`check(lines)` returns the batch's worst-case duration in ms or raises `control.Refused` +(`invalid_arguments`, `field` = `arguments.lines[i]`, or `arguments.lines` for the budget). +""" + +from __future__ import annotations + +import re +from typing import Callable, Dict, List, Optional + +from pa_lab import control + +BATCH_MAX_MS = 60000 +MAX_HOLD_MS = 10000 +MAX_WAIT_MS = 30000 +MAX_TAPS = 20 +MAX_SHOTS = 10 +LINE_OVERHEAD_MS = 200 # per line: the app's own bookkeeping +SCREEN_READ_MS = 1000 # shot, detect, game_open: one frame read and maybe a PNG write + +BUTTONS = ('A', 'B', 'X', 'Y', 'L', 'R', 'ZL', 'ZR', 'PLUS', 'MINUS', 'LCLICK', 'RCLICK', 'HOME') +DIRECTIONS = ('UP', 'DOWN', 'LEFT', 'RIGHT') +INT_RE = re.compile(r'^(0|[1-9][0-9]{0,5})$') +AXIS_RE = re.compile(r'^-?(0|1)(\.[0-9]{1,3})?$') +STILL_RE = re.compile(r'^(0|[1-9][0-9]{0,2})(\.[0-9]{1,2})?$') +LABEL_RE = re.compile(r'^[A-Za-z0-9_-]{1,64}$') +DETECTOR_RE = re.compile(r'^[a-z][a-z0-9_]{0,39}$') + +__all__ = ['check', 'BATCH_MAX_MS', 'COMMANDS'] + + +class _Bad(ValueError): + pass + + +def _int(word: str, name: str, minimum: int, maximum: int) -> int: + if not INT_RE.match(word) or not minimum <= int(word) <= maximum: + raise _Bad('{} must be an integer {}..{}, not {!r}'.format(name, minimum, maximum, word)) + return int(word) + + +def _axis(word: str, name: str) -> None: + if not AXIS_RE.match(word) or abs(float(word)) > 1: + raise _Bad('{} must be a number -1..1 with at most 3 decimals, not {!r}'.format(name, word)) + + +def _still(word: str) -> None: + if not STILL_RE.match(word): + raise _Bad('still must be a number 0..999 with at most 2 decimals, not {!r}'.format(word)) + + +def _buttons(word: str) -> None: + parts = word.split('+') + if any(part not in BUTTONS for part in parts) or len(set(parts)) != len(parts): + raise _Bad('buttons must be one or more of {} joined with +, not {!r}'.format(' '.join(BUTTONS), word)) + + +def _arity(args: List[str], least: int, most: int, usage: str) -> None: + if not least <= len(args) <= most: + raise _Bad('usage: ' + usage) + + +def _hold_release(args: List[str], hold: int, release: int) -> int: + if len(args) > 0: + hold = _int(args[0], 'hold', 0, MAX_HOLD_MS) + if len(args) > 1: + release = _int(args[1], 'release', 0, MAX_HOLD_MS) + return hold + release + + +def _press(args: List[str]) -> int: + _arity(args, 1, 3, 'press BTN[+BTN] [hold] [release]') + _buttons(args[0]) + return _hold_release(args[1:], 160, 160) + + +def _dpad(args: List[str]) -> int: + _arity(args, 1, 4, 'dpad UP|DOWN|LEFT|RIGHT [hold] [release] [BTN[+BTN]]') + if args[0] not in DIRECTIONS: + raise _Bad('direction must be one of {}'.format(' '.join(DIRECTIONS))) + if len(args) == 4: + _buttons(args[3]) + return _hold_release(args[1:3], 100, 200) + + +def _stick(args: List[str]) -> int: + _arity(args, 3, 6, 'stick L|R x y [hold] [release] [BTN[+BTN]]') + if args[0] not in ('L', 'R'): + raise _Bad('stick must be L or R') + _axis(args[1], 'x') + _axis(args[2], 'y') + if len(args) == 6: + _buttons(args[5]) + return _hold_release(args[3:5], 160, 160) + + +def _wait(args: List[str]) -> int: + _arity(args, 1, 1, 'wait ms') + return _int(args[0], 'ms', 0, MAX_WAIT_MS) + + +def _taps(args: List[str]) -> int: + _arity(args, 2, 6, 'taps UP|DOWN|LEFT|RIGHT N [all] [hold] [release] [still]') + if args[0] not in DIRECTIONS: + raise _Bad('direction must be one of {}'.format(' '.join(DIRECTIONS))) + count = _int(args[1], 'N', 1, MAX_TAPS) + rest = args[3:] if len(args) > 2 and args[2] == 'all' else args[2:] + if len(rest) > 3: + raise _Bad('usage: taps UP|DOWN|LEFT|RIGHT N [all] [hold] [release] [still]') + if len(rest) == 3: + _still(rest[2]) + return count * (_hold_release(rest[:2], 160, 640) + LINE_OVERHEAD_MS) + + +def _walk(args: List[str]) -> int: + _arity(args, 2, 5, 'walk x y [max] [still] [BTN[+BTN]]') + _axis(args[0], 'x') + _axis(args[1], 'y') + longest = _int(args[2], 'max', 200, MAX_HOLD_MS) if len(args) > 2 else 5000 + if len(args) > 3: + _still(args[3]) + if len(args) > 4: + _buttons(args[4]) + return longest + 2 * LINE_OVERHEAD_MS + + +def _shot(args: List[str]) -> int: + _arity(args, 1, 1, 'shot LABEL') + _label(args[0]) + return SCREEN_READ_MS + + +def _shots(args: List[str]) -> int: + _arity(args, 2, 3, 'shots LABEL count [interval]') + _label(args[0]) + count = _int(args[1], 'count', 1, MAX_SHOTS) + interval = _int(args[2], 'interval', 100, 5000) if len(args) > 2 else 500 + return count * (interval + SCREEN_READ_MS) + + +def _label(word: str) -> None: + if not LABEL_RE.match(word): + raise _Bad('label must be 1-64 of A-Z a-z 0-9 _ -') + + +def _detector(word: str) -> None: + if not DETECTOR_RE.match(word): + raise _Bad('detector must be a name of a-z 0-9 _ (no image path)') + + +def _detect(args: List[str]) -> int: + _arity(args, 1, 1, 'detect DETECTOR') + _detector(args[0]) + return SCREEN_READ_MS + + +def _wait_for(args: List[str]) -> int: + _arity(args, 1, 2, 'wait_for|expect DETECTOR [timeout]') + _detector(args[0]) + return (_int(args[1], 'timeout', 0, MAX_WAIT_MS) if len(args) > 1 else 5000) + SCREEN_READ_MS + + +def _game_open(args: List[str]) -> int: + _arity(args, 0, 0, 'game_open') + return SCREEN_READ_MS + + +COMMANDS: Dict[str, Callable[[List[str]], int]] = { + 'press': _press, 'dpad': _dpad, 'stick': _stick, 'wait': _wait, 'taps': _taps, 'walk': _walk, + 'shot': _shot, 'shots': _shots, 'detect': _detect, 'wait_for': _wait_for, 'expect': _wait_for, + 'game_open': _game_open, +} + + +def check_line(line: str) -> int: + """One line's worst-case duration in ms; raises ValueError with the reason it is not allowed.""" + if not isinstance(line, str) or line != ' '.join(line.split()) or not line: + raise _Bad('not in canonical form: one command, words separated by single spaces') + words = line.split(' ') + handler: Optional[Callable[[List[str]], int]] = COMMANDS.get(words[0]) + if handler is None: + raise _Bad('{!r} is not an allowed cfr_batch command; allowed: {}'.format( + words[0], ', '.join(sorted(COMMANDS)))) + return handler(words[1:]) + LINE_OVERHEAD_MS + + +def check(lines: List[str]) -> int: + """The batch's worst-case duration in ms, or control.Refused naming the first bad line.""" + total = 0 + for index, line in enumerate(lines): + try: + total += check_line(line) + except _Bad as e: + raise control.Refused('invalid_arguments', 'Line {} ({!r}): {}.'.format(index + 1, line, e), + field='arguments.lines[{}]'.format(index)) + if total > BATCH_MAX_MS: + raise control.Refused('invalid_arguments', 'The batch may take up to {} ms; the limit is {} ms. ' + 'Split it.'.format(total, BATCH_MAX_MS), field='arguments.lines', + evidence={'worst_case_ms': total, 'limit_ms': BATCH_MAX_MS}) + return total diff --git a/lab/server/pa_lab/config.py b/lab/server/pa_lab/config.py index d193e19e27..e0430e0ad8 100644 --- a/lab/server/pa_lab/config.py +++ b/lab/server/pa_lab/config.py @@ -1,5 +1,7 @@ """The daemon's own config (Slice 2 of fork #131): a one-entry allowlist (console B), the loopback port and the bearer token file. It never reads `~/BDSPLab/consoles.json`, which also lists A. +`channel_owner` (optional; default the profile name, which is what `lab/scripts/lc.sh` uses) is the +token the daemon claims the app's channel with before a leased action (Slice 5, Lab.md "Owner"). {"schema": 1, "host": "127.0.0.1", "port": 8765, "token_file": "~/.config/pa-lab/token", "db_file": "~/.local/state/pa-lab/control.sqlite", @@ -11,6 +13,7 @@ import json import os +import re from pathlib import Path import secrets import stat @@ -19,8 +22,9 @@ ALLOWED_CONSOLES = ('B',) LOOPBACK_HOSTS = ('127.0.0.1',) TOP_KEYS = ('schema', 'host', 'port', 'token_file', 'db_file', 'consoles') +OWNER_RE = re.compile(r'^[A-Za-z0-9_.-]{1,64}$') DEFAULT_DB_FILE = '~/.local/state/pa-lab/control.sqlite' -CONSOLE_KEYS = ('lab_dir', 'profile') +CONSOLE_KEYS = ('lab_dir', 'profile', 'channel_owner') class ConfigError(ValueError): @@ -28,9 +32,10 @@ class ConfigError(ValueError): class ConsoleConfig: - def __init__(self, lab_dir: Path, profile: Optional[str]): + def __init__(self, lab_dir: Path, profile: Optional[str], channel_owner: Optional[str] = None): self.lab_dir = lab_dir self.profile = profile + self.channel_owner = channel_owner if channel_owner is not None else profile class Config: @@ -85,7 +90,11 @@ def load(path: Path) -> Config: profile = entry.get('profile') if profile is not None and (not isinstance(profile, str) or not profile): raise ConfigError('{}.profile: expected a profile name'.format(field)) - out[name] = ConsoleConfig(_path(entry.get('lab_dir'), field + '.lab_dir'), profile) + owner = entry.get('channel_owner', profile) + if owner is not None and (not isinstance(owner, str) or not OWNER_RE.match(owner)): + raise ConfigError('{}.channel_owner: expected one word of A-Z a-z 0-9 _ . - (it defaults to the ' + 'profile)'.format(field)) + out[name] = ConsoleConfig(_path(entry.get('lab_dir'), field + '.lab_dir'), profile, owner) return Config(host, port, _path(doc.get('token_file'), 'token_file'), out, _path(doc.get('db_file', DEFAULT_DB_FILE), 'db_file')) diff --git a/lab/server/pa_lab/control.py b/lab/server/pa_lab/control.py index 60ea27fb8b..42172dfab4 100644 --- a/lab/server/pa_lab/control.py +++ b/lab/server/pa_lab/control.py @@ -17,6 +17,11 @@ - **Reconciliation.** `observe(app)` is applied whenever the daemon reads the app's state and once at start: it applies each new transition exactly once (UI takeover, `stopped` events) and ends a running lease whose app instance is gone. +- **Leased actions** (Slice 5). `begin_action` checks the lease and the action's own + precondition and stores the call once: refused, completed at once, or a `pending` ticket that + remembers the app instance it was sent to. `observe` resolves the ticket from what the app + reports (`_resolve_actions`): the app's terminal transition, not the tool's reply, is the + completion. """ from __future__ import annotations @@ -27,7 +32,7 @@ import sqlite3 import threading import time -from typing import Any, Dict, Optional, Sequence, Tuple +from typing import Any, Callable, Dict, Optional, Sequence, Tuple from pa_lab import contracts, timestamps from pa_lab.db import Database @@ -37,6 +42,8 @@ DEFAULT_PAGE = 100 MAX_PAGE = 500 POLL_S = 0.2 # another process's writes are seen by polling; this process's wake the waiters +ACTION_TOOLS = ('stop_program', 'cfr_batch') +SAVE_STALE_KEY = 'save_stale:{}' # meta row: the newest mutation that may have changed the game's save LEASE_COLUMNS = frozenset({ @@ -137,11 +144,13 @@ def request_status(self, client_id: str, console: Any, request_id: str) -> Dict[ return record def next_events(self, client_id: str, console: str, after_seq: Any, timeout_s: Any = 0, - limit: Any = DEFAULT_PAGE) -> Dict[str, Any]: + limit: Any = DEFAULT_PAGE, refresh: Optional[Callable[[], Any]] = None) -> Dict[str, Any]: """Events with seq > after_seq, oldest first, waiting up to timeout_s (<= 60) for one. `after_seq` is also the client's confirmed position: compaction keeps everything after it, so a client that lost a response asks again with the same cursor and loses nothing. + `refresh` (the server's read of the app, which applies `observe`) runs before each look, so + a run's end or a pending action's terminal transition becomes an event while a client waits. """ self._check_console(console) after_seq = self._int_arg('after_seq', after_seq, 0, None) @@ -166,6 +175,8 @@ def next_events(self, client_id: str, console: str, after_seq: Any, timeout_s: A (client_id, console, after_seq, self._stamp())) deadline = time.monotonic() + timeout_s while True: + if refresh is not None: + refresh() rows = self.db.read().execute( 'SELECT * FROM events WHERE console = ? AND seq > ? ORDER BY seq LIMIT ?', (console, after_seq, limit)).fetchall() @@ -224,24 +235,87 @@ def open_ticket(self, client_id: str, request: Dict[str, Any]) -> Dict[str, Any] return self._record(self._request_row(conn, client_id, req['tool'], req['request_id'])) def resolve_ticket(self, client_id: str, tool: str, request_id: str, result: Optional[Dict[str, Any]] = None, - refusal: Optional[Dict[str, Any]] = None) -> Dict[str, Any]: - """Completes (result) or fails (refusal) a pending ticket once; later calls return the record.""" + refusal: Optional[Dict[str, Any]] = None, acted: bool = True) -> Dict[str, Any]: + """Completes (result) or fails (refusal) a pending ticket once; later calls return the record. + + A refusal is `failed` (after acting) unless `acted` is False: then nothing reached the app + and the record is `refused`, as if it had been refused before acting. + """ if (result is None) == (refusal is None): raise ValueError('resolve_ticket needs exactly one of result and refusal') with self._writing() as conn: row = self._request_row(conn, client_id, tool, request_id) if row is None: raise Refused('invalid_arguments', 'No ticket {}.'.format(request_id), field='request_id') - if row['status'] != 'pending': - return self._record(row) - status = 'completed' if refusal is None else 'failed' - conn.execute('UPDATE requests SET status = ?, completed_at = ?, result = ?, refusal = ? ' - 'WHERE client_id = ? AND tool = ? AND request_id = ?', - (status, self._stamp(), None if result is None else _json(result), - None if refusal is None else _json(refusal), client_id, tool, request_id)) - record = self._record(self._request_row(conn, client_id, tool, request_id)) - self._request_event(conn, row['console'], request_id, tool, result, refusal) - return record + self._resolve(conn, row, result, refusal, acted) + return self._record(self._request_row(conn, client_id, tool, request_id)) + + def record(self, client_id: str, tool: str, request_id: str) -> Dict[str, Any]: + """One request record as stored (the lease token never is).""" + row = self.db.read().execute('SELECT * FROM requests WHERE client_id = ? AND tool = ? AND request_id = ?', + (client_id, tool, request_id)).fetchone() + if row is None: + raise Refused('invalid_arguments', 'No request {}.'.format(request_id), field='request_id') + return self._record(row) + + # ---- leased actions (Slice 5) -------------------------------------------------------------- + + def begin_action(self, client_id: str, request: Dict[str, Any], instance_id: str, + decide: Callable[[sqlite3.Row], Optional[Dict[str, Any]]]) -> Tuple[Dict[str, Any], bool]: + """Stores one leased action call once and says whether the caller must now send it. + + In one transaction: an exact retry gets its stored record (and is not sent again); the + lease must be held by the request's token (an idle lease is renewed by the call); then + `decide(lease_row)` raises Refused (stored `refused`), returns a result (stored `completed`: + nothing to do), or returns None: the record is a `pending` ticket bound to `instance_id`, + and the second value is True. Raises Refused only for a request that cannot be keyed. + """ + req, args, token_hash = self._parse_request(client_id, request) + if req['tool'] not in ACTION_TOOLS: + raise Refused('invalid_arguments', '{} is not served yet.'.format(req['tool']), field='tool') + console = req['console'] + with self._writing() as conn: + existing = self._existing(conn, req, args, token_hash) + if existing is not None: + return existing, False + self._expire_due(conn, console) + stamp = self._stamp() + try: + row = self._held(conn, console, token_hash) + if row['state'] == 'agent_idle': + conn.execute('UPDATE leases SET expires_at = ?, updated_at = ? WHERE console = ?', + (timestamps.format(self.now() + row['ttl_s']), stamp, console)) + result, refusal = decide(self._lease_row(conn, console)), None + except Refused as e: + result, refusal = None, e.refusal + status = 'refused' if refusal is not None else ('pending' if result is None else 'completed') + conn.execute('INSERT INTO requests (client_id, tool, request_id, console, token_hash, status, created_at, ' + 'completed_at, arguments, result, refusal, instance_id) ' + 'VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)', + (client_id, req['tool'], req['request_id'], console, token_hash, status, stamp, + None if status == 'pending' else stamp, _json(args), + None if result is None else _json(result), None if refusal is None else _json(refusal), + instance_id)) + if status != 'pending': + self._request_event(conn, console, req['request_id'], req['tool'], result, refusal) + return self._record(self._request_row(conn, client_id, req['tool'], req['request_id'])), \ + status == 'pending' + + def mark_save_stale(self, console: str, reason: str) -> str: + """Records that something outside a hooked program may have changed the game (a CFR batch): + `console:///save` is stale from now until a newer program-authored save fact. Returns the time.""" + self._check_console(console) + with self._writing() as conn: + stamp = self._stamp() + conn.execute('INSERT OR REPLACE INTO meta (key, value) VALUES (?, ?)', + (SAVE_STALE_KEY.format(console), _json({'reason': reason, 'at': stamp}))) + return stamp + + def save_stale_mark(self, console: str) -> Optional[Dict[str, Any]]: + """The newest mark_save_stale on `console` ({reason, at}), or None.""" + self._check_console(console) + value = self._meta(self.db.read(), SAVE_STALE_KEY.format(console), '') + return json.loads(value) if value else None # ---- runs and the operator ---------------------------------------------------------------- @@ -286,7 +360,8 @@ def observe(self, console: str, app: Dict[str, Any]) -> Dict[str, Any]: - a new UI transition revokes any agent lease and installs the user lease (no timeout); - a new stop transition is a `stopped` event with its source; - a running lease ends (back to agent_idle with a fresh TTL) when its run's stop is - reported or its app instance is gone. + reported or its app instance is gone; + - a pending leased action resolves from the app's terminal transition (`_resolve_actions`). """ self._check_console(console) instance = app['instance']['id'] @@ -310,6 +385,7 @@ def observe(self, console: str, app: Dict[str, Any]) -> Dict[str, Any]: instance_id=instance, request_id=transition['request_id'], at=transition['at']) if transition['source'] == 'ui': self._take_over(conn, console, transition['at'], 'ui_takeover', instance) + self._resolve_actions(conn, console, app) conn.execute('INSERT OR REPLACE INTO observations (console, instance_id, transition_key, program_state, ' 'observed_at) VALUES (?, ?, ?, ?, ?)', (console, instance, key if transition is not None else @@ -447,6 +523,62 @@ def _request_event(self, conn, console, request_id, tool, result, refusal) -> No self._append(conn, 'request_failed', console, {'request_id': request_id, 'tool': tool, 'refusal': refusal}, request_id=request_id) + def _resolve(self, conn, row: sqlite3.Row, result: Optional[Dict[str, Any]], refusal: Optional[Dict[str, Any]], + acted: bool = True) -> None: + """Completes or fails one pending record, once; a resolved record is left as it is.""" + if row['status'] != 'pending': + return + status = 'completed' if refusal is None else ('failed' if acted else 'refused') + conn.execute('UPDATE requests SET status = ?, completed_at = ?, result = ?, refusal = ? ' + 'WHERE client_id = ? AND tool = ? AND request_id = ?', + (status, self._stamp(), None if result is None else _json(result), + None if refusal is None else _json(refusal), row['client_id'], row['tool'], row['request_id'])) + self._request_event(conn, row['console'], row['request_id'], row['tool'], result, refusal) + + def _resolve_actions(self, conn, console: str, app: Dict[str, Any]) -> None: + """Resolves the console's pending stop_program tickets from what the app reports (and fails a + pending cfr_batch whose app instance is gone). + + - another app instance than the one the stop was sent to: failed, `instance_replaced`; + - a UI Start/Stop at or after the call: failed, the user holds the console; + - the stop transition carrying the ticket's request id, and the program `stopped`: + completed (`outcome: stopped`); while `stopping` the ticket stays pending; + - the program ended by itself (`program`/`error`) at or after the call: completed + (`outcome: ended`), since that is the run's terminal event. + Timestamps compare as strings: both are UTC with milliseconds and `Z`. + """ + rows = conn.execute("SELECT * FROM requests WHERE console = ? AND status = 'pending' AND tool IN (?, ?)", + (console,) + ACTION_TOOLS).fetchall() + instance = app['instance']['id'] + program = app['program'] + transition = program['last_transition'] + for row in rows: + if row['instance_id'] != instance: + self._resolve(conn, row, None, { + 'code': 'app_unavailable', 'message': 'The app restarted before the {} was confirmed.'.format( + 'stop' if row['tool'] == 'stop_program' else 'batch'), + 'evidence': {'reason': 'instance_replaced', 'instance_id': row['instance_id'], + 'new_instance_id': instance}}) + continue + if row['tool'] == 'cfr_batch': # its journal resolves it (pa_lab/actions.py), not a transition + continue + if transition is None or (transition['at'] < row['created_at'] and + transition['request_id'] != row['request_id']): + continue + done = {'outcome': 'stopped', 'instance_id': instance, 'run_id': program['run_id'], + 'source': transition['source'], 'stopped_at': transition['at'], 'program_state': program['state']} + if transition['source'] == 'ui': + self._resolve(conn, row, None, { + 'code': 'console_held_by_user', 'message': 'The user clicked {} in the app at {}.'.format( + transition['action'].capitalize(), _clock_time(transition['at'])), + 'evidence': {'since': transition['at']}}) + elif program['state'] != 'stopped' or transition['action'] != 'stop': + continue + elif transition['source'] == 'lab' and transition['request_id'] == row['request_id']: + self._resolve(conn, row, done, None) + elif transition['source'] in ('program', 'error'): + self._resolve(conn, row, dict(done, outcome='ended'), None) + # ---- lease rows @staticmethod diff --git a/lab/server/pa_lab/db.py b/lab/server/pa_lab/db.py index 6624b6e8bf..394ac71a74 100644 --- a/lab/server/pa_lab/db.py +++ b/lab/server/pa_lab/db.py @@ -86,6 +86,11 @@ )""", "CREATE TABLE meta (key TEXT PRIMARY KEY, value TEXT NOT NULL)", ], + # 2 (Slice 5): the app instance a leased action was sent to, so a pending ticket fails when that + # instance is gone rather than waiting for a transition that can no longer come. + [ + "ALTER TABLE requests ADD COLUMN instance_id TEXT", + ], ] SCHEMA_VERSION = len(MIGRATIONS) diff --git a/lab/server/pa_lab/lab_reader.py b/lab/server/pa_lab/lab_reader.py index 7c3cd14a3b..f2850b768a 100644 --- a/lab/server/pa_lab/lab_reader.py +++ b/lab/server/pa_lab/lab_reader.py @@ -182,9 +182,16 @@ def save_resource(self) -> Dict[str, Any]: except Unavailable: app = None transition = app['program']['last_transition'] if app is not None else None - if transition is not None and transition['source'] == 'ui' and \ - timestamps.parse(transition['at']) > timestamps.parse(fact['saved_at']): - doc.update(status='stale', reason='user_lease', since=transition['at']) + marks = [] # (at, reason): what happened after the fact that may have changed the game + if transition is not None and transition['source'] == 'ui': + marks.append((transition['at'], 'user_lease')) + mark = self.control.save_stale_mark(self.console) if self.control is not None else None + if mark is not None: + marks.append((mark['at'], mark['reason'])) + marks = [m for m in marks if timestamps.parse(m[0]) > timestamps.parse(fact['saved_at'])] + if marks: + at, reason = max(marks, key=lambda m: timestamps.parse(m[0])) + doc.update(status='stale', reason=reason, since=at) return contracts.validate('save_resource', doc).data diff --git a/lab/server/pa_lab/mcp_server.py b/lab/server/pa_lab/mcp_server.py index ac00a68b34..689c9c0f85 100644 --- a/lab/server/pa_lab/mcp_server.py +++ b/lab/server/pa_lab/mcp_server.py @@ -7,8 +7,9 @@ Resources: `console://B/state` (console_state), `console://B/save` (save_resource). Tools: `shot`, `ensure_game`, `describe_program`, `game_open`; with a control plane also `acquire_console`, -`renew_console`, `release_console`, `next_events` and `request_status`. Nothing here presses a -button or starts or stops a program: that is not served yet. +`renew_console`, `release_console`, `next_events`, `request_status` and the first leased action, +`stop_program` and the debug-only `cfr_batch` (Slice 5, pa_lab/actions.py, allowlist in pa_lab/cfr.py). +Nothing here starts a program yet. """ from __future__ import annotations @@ -23,9 +24,10 @@ import re import secrets import threading +import time from typing import Any, Callable, Dict, Optional, Tuple -from pa_lab import app_query, contracts, control, shot, tools +from pa_lab import actions, app_query, contracts, control, shot, tools from pa_lab.lab_reader import ConsoleReader, Unavailable LOG = logging.getLogger('pa_lab.server') @@ -49,7 +51,8 @@ 'Read-only view of lab console B. Read console://B/state before acting on the console and ' 'console://B/save for the last known save. shot returns a PNG newer than the call; ensure_game ' 'only verifies, it never navigates. describe_program gives the selected program\'s option contract; ' - 'game_open says whether a game is in front. Unknown observations are never success.') + 'game_open says whether a game is in front. Unknown observations are never success. ' + 'stop_program (with a lease) returns a ticket: follow it with request_status or next_events.') TOOL_LIST = [ { @@ -158,12 +161,31 @@ def _schema(properties: Dict[str, Any], required) -> Dict[str, Any]: 'limit': {'type': 'integer', 'minimum': 1, 'maximum': control.MAX_PAGE, 'default': control.DEFAULT_PAGE}}, ['after_seq']), 'annotations': _READ}, + {'name': 'stop_program', 'title': 'Stop the running program', + 'description': 'Asks the app to stop the running program, once, under your lease. Returns the request record: ' + 'pending until the app reports the program stopped by this request (completed, outcome ' + 'stopped), or the run ended by itself (outcome ended); completed at once with outcome ' + 'not_running when nothing runs. Follow it with request_status or next_events. Fails if ' + 'the user takes the console or the app restarts first.', + 'inputSchema': _schema({'request_id': _REQUEST_ID, 'lease_token': _LEASE_TOKEN}, + ['request_id', 'lease_token']), 'annotations': _MUTATING}, + {'name': 'cfr_batch', 'title': 'Run a short batch of console commands', + 'description': 'Debug only. Under your lease, with the program stopped, sends 1-200 console lines (press, dpad, ' + 'stick, wait, taps, walk, shot, shots, detect, wait_for, expect, game_open) and returns the ' + "app's journal: outcome done, or line_failed with failed_line. Every line is allowlisted and " + 'bounded; the batch must fit in 60 s. Marks console://B/save stale. Retry with the same ' + 'request_id to collect a batch still pending.', + 'inputSchema': _schema({'request_id': _REQUEST_ID, 'lease_token': _LEASE_TOKEN, + 'lines': {'type': 'array', 'items': {'type': 'string'}, 'minItems': 1, 'maxItems': 200}}, + ['request_id', 'lease_token', 'lines']), + 'annotations': {'readOnlyHint': False, 'destructiveHint': True, 'idempotentHint': True}}, {'name': 'request_status', 'title': 'Request or ticket status', 'description': "This client's request record: pending, completed, refused or failed.", 'inputSchema': _schema({'request_id': _REQUEST_ID}, ['request_id']), 'annotations': _READ}, ] LEASE_TOOLS = ('acquire_console', 'renew_console', 'release_console') +REQUEST_TOOLS = LEASE_TOOLS + control.ACTION_TOOLS # keyed by request_id; refusals echo it class RpcError(Exception): @@ -188,10 +210,14 @@ class LabMcp: def __init__(self, consoles: Dict[str, ConsoleReader], take_shot: Callable[..., Dict[str, Any]] = shot.take_shot, - control_plane: Optional[control.ControlPlane] = None): + control_plane: Optional[control.ControlPlane] = None, + channel_owners: Optional[Dict[str, str]] = None, + sleep: Callable[[float], None] = time.sleep): self.consoles = consoles self.take_shot = take_shot self.control = control_plane + self.channel_owners = channel_owners or {} + self.sleep = sleep def call(self, method: str, params: Dict[str, Any], client: str = 'unnamed') -> Dict[str, Any]: if method == 'ping': @@ -299,25 +325,56 @@ def _call_control(self, client: str, name: str, arguments: Any) -> Dict[str, Any if 'after_seq' not in args: raise control.Refused('invalid_arguments', 'required', field='after_seq') result = self.control.next_events(client, console, args['after_seq'], args.get('timeout_s', 0), - args.get('limit', control.DEFAULT_PAGE)) + args.get('limit', control.DEFAULT_PAGE), + refresh=self._refresher(console)) elif name == 'request_status': if set(args) != {'request_id'} or request_id is None: raise control.Refused('invalid_arguments', 'expects request_id', field='request_id') + self._refresher(console)() result = self.control.request_status(client, console, request_id) + elif name in control.ACTION_TOOLS: + reader = self._console(console) + owner = self.channel_owners.get(console) + if reader is None: + raise control.Refused('console_not_allowed', 'Console {!r} is not served; only {}.'.format( + console, ', '.join(sorted(self.consoles)))) + if owner is None: + raise control.Refused('app_unavailable', 'No channel owner is configured for console {}; ' + 'set consoles.{}.channel_owner or profile.'.format(console, console)) + record = actions.ACTIONS[name](self.control, reader, client, self._request(name, console, args), + owner, sleep=self.sleep) + if record['refusal'] is not None: + return self._refused(name, record['refusal'], record['request_id']) + result = record else: - request = {'schema': 1, 'request_id': args.pop('request_id', None), 'tool': name, - 'console': console, 'arguments': args} - if 'lease_token' in args: - request['lease_token'] = args.pop('lease_token') - record = self.control.execute(client, request) + record = self.control.execute(client, self._request(name, console, args)) if record['refusal'] is not None: return self._refused(name, record['refusal'], record['request_id']) result = record except control.Refused as e: - return self._refused(name, e.refusal, request_id if name in LEASE_TOOLS else None) + return self._refused(name, e.refusal, request_id if name in REQUEST_TOOLS else None) return {'content': [{'type': 'text', 'text': _json_text(result)}], 'structuredContent': result, 'isError': False} + @staticmethod + def _request(name: str, console: Any, args: Dict[str, Any]) -> Dict[str, Any]: + """The request document of a keyed call; the lease token goes beside the arguments.""" + args = dict(args) + request = {'schema': 1, 'request_id': args.pop('request_id', None), 'tool': name, 'console': console, + 'arguments': args} + if 'lease_token' in args: + request['lease_token'] = args.pop('lease_token') + return request + + def _refresher(self, console: Any) -> Callable[[], None]: + """Reads the console's state, which applies `observe` (run ends, pending action tickets).""" + reader = self._console(console) + + def refresh() -> None: + if reader is not None: + reader.console_state() + return refresh + @staticmethod def _refused(tool: str, refusal: Dict[str, Any], request_id: Optional[str] = None) -> Dict[str, Any]: try: diff --git a/lab/server/tests/fake_lab.py b/lab/server/tests/fake_lab.py index 060795fcf0..1a5e3ebff2 100644 --- a/lab/server/tests/fake_lab.py +++ b/lab/server/tests/fake_lab.py @@ -111,6 +111,16 @@ class FakeApp: `describe_program` and `game_open` (#504) are answered at once: `replies[command]` is the printed text (default below), `line_errors[command]` fails the line instead, and `restart_on` names a command whose answer comes from a new app instance. + + A request ending in `stop` (Slice 5's stop_program) is run as the channel does: the `owner` + first line must match a claimed `channel_owner` (or the channel is free), `owner claim T` + takes it, and `stop` is refused unless the program is `running`. Otherwise the program goes + `stopping` with `last_transition {stop, lab, }` and, at the next tick (or at once + with `stop_at_once`), `stopped`. `stop_silent` takes the request without writing a journal. + + A `palab_cfr_batch_*` request (Slice 5b's cfr_batch) claims the channel the same way, then runs + its lines in order: each is `ok` unless the program is not stopped or the line is in + `batch_errors` (line -> reason), which ends the batch. `batch_silent` takes it without a journal. """ def __init__(self, lab, clock): @@ -130,6 +140,11 @@ def __init__(self, lab, clock): } self.line_errors = {} self.restart_on = None + self.channel_owner = None + self.stop_at_once = False + self.stop_silent = False + self.batch_errors = {} + self.batch_silent = False self.requests = [] self.pending = [] clock.on_sleep.append(self.tick) @@ -142,6 +157,8 @@ def tick(self): changes['video.state'] = 'live' changes['video.captured_at'] = now self.lab.update_state(**changes) + if self.lab.state['program']['state'] == 'stopping': + self.lab.update_state(**{'program.state': 'stopped'}) for pending in list(self.pending): self.continue_snapshot(pending) if self.serve: @@ -154,6 +171,12 @@ def pick_up(self, request): self.requests.append(text) line = text.splitlines()[-1] words = line.split() + if request.stem.startswith('palab_cfr_batch_'): + self.batch(request.stem, text.splitlines()) + return + if words == ['stop']: + self.stop(request.stem, text.splitlines()) + return if words[0] in self.replies: self.answer(request.stem, line, words[0]) return @@ -176,6 +199,51 @@ def answer(self, name, line, command): else: self.finish(pending, self.replies[command]) + def stop(self, name, lines): + if self.stop_silent: + return + owner = lines[0].split()[1] + request_id = lines[1].split()[1] + out = (self.lab.dir / 'outbox' / (name + '.out')) + if self.channel_owner not in (None, owner): + out.write_text('error 3 (owner claim {}): owned by {}\nend\n'.format(owner, self.channel_owner), + encoding='utf-8') + return + self.channel_owner = owner + state = self.lab.state['program']['state'] + if state != 'running': + out.write_text('ok 3 owner claim {} @0-1ms\nerror 4 (stop): the program is {}, not RUNNING\nend\n'.format( + owner, state.upper()), encoding='utf-8') + return + self.lab.update_state(**{ + 'program.state': 'stopped' if self.stop_at_once else 'stopping', + 'program.last_transition': {'action': 'stop', 'source': 'lab', 'request_id': request_id, + 'at': timestamps.format(self.clock.now())}, + 'channel.owner_claimed': True}) + out.write_text('ok 3 owner claim {} @0-1ms\nok 4 stop @1-2ms\nend\n'.format(owner), encoding='utf-8') + + def batch(self, name, lines): + if self.batch_silent: + return + owner = lines[0].split()[1] + out = self.lab.dir / 'outbox' / (name + '.out') + if self.channel_owner not in (None, owner): + out.write_text('error 3 (owner claim {}): owned by {}\nend\n'.format(owner, self.channel_owner), + encoding='utf-8') + return + self.channel_owner = owner + journal = ['ok 3 owner claim {} @0-1ms'.format(owner)] + state = self.lab.state['program']['state'] + for number, line in enumerate(lines[3:], start=4): + reason = self.batch_errors.get(line) + if reason is None and state != 'stopped': + reason = 'the program is {}'.format(state.upper()) + if reason is not None: + journal.append('error {} ({}): {}'.format(number, line, reason)) + break + journal.append('ok {} {} @0-1ms'.format(number, line)) + out.write_text('\n'.join(journal + ['end']) + '\n', encoding='utf-8') + def continue_snapshot(self, pending): video = self.lab.state['video'] if video['frame_seq'] is not None and video['frame_seq'] > pending['after']: diff --git a/lab/server/tests/test_actions.py b/lab/server/tests/test_actions.py new file mode 100644 index 0000000000..30b0fccd2c --- /dev/null +++ b/lab/server/tests/test_actions.py @@ -0,0 +1,291 @@ +"""The first leased action, stop_program (Slice 5 of fork #131), against a fake app in a temp +`Lab/` folder: the ticket, the channel request it sends, and how the app's own report resolves +it, including the races the design names (duplicate requests, UI takeover, lease loss, app +restart, a terminal event before the response). No real profile or console is touched. + +Run from the repo root: python3 -m unittest discover -s lab/server/tests -t lab/server -v +""" + +import sqlite3 +import unittest + +from pa_lab import actions, control, db, lab_reader, mcp_server, timestamps +from tests.control_fixtures import START, acquire, app_state, clock, new_id, open_plane, temp_db_path, transition +from tests.fake_lab import FakeApp, FakeLab + +CLIENT = 'claude:frlg-lane' +OWNER = 'lab-B' +NEW_INSTANCE = '0b5e3f6c-9d2a-4e71-8c40-6f1a2b3c4d5e' + + +def stop_request(token, request_id=None): + request = {'schema': 1, 'request_id': request_id or new_id(), 'tool': 'stop_program', 'console': 'B', + 'arguments': {}} + if token is not None: + request['lease_token'] = token + return request + + +class ActionTest(unittest.TestCase): + def setUp(self): + self.clock = clock() + self.path = temp_db_path(self) + self.plane = open_plane(self, self.path, self.clock) + self.lab = FakeLab(self) + self.write_app(state='running', last=transition('start', 'lab', '2026-11-14T05:59:00.000Z', new_id())) + self.app = FakeApp(self.lab, self.clock) + self.reader = self.make_reader() + + def make_reader(self): + return lab_reader.ConsoleReader('B', self.lab.dir, profile='lab-B', now=self.clock.now, + pid_alive=lambda pid: True, control=self.plane) + + def write_app(self, state, last): + doc = app_state(last, state) + doc['written_at'] = START + doc['video']['captured_at'] = START + self.lab.write_state(doc) + + def acquired(self): + record = self.plane.execute(CLIENT, acquire()) + self.assertEqual(record['status'], 'completed', record) + return record['result']['lease_token'] + + def stop(self, token, request_id=None): + return actions.stop_program(self.plane, self.reader, CLIENT, stop_request(token, request_id), OWNER, + sleep=self.clock.sleep) + + def tick(self): + self.clock.sleep(0.5) + self.reader.console_state() + + def status(self, request_id): + return self.plane.request_status(CLIENT, 'B', request_id) + + def stop_requests(self): + return [text for text in self.app.requests if text.rstrip().endswith('stop')] + + def events(self): + return self.plane.next_events('reader', 'B', 0)['events'] + + +class StopTests(ActionTest): + def test_a_stop_is_pending_until_the_app_reports_it_stopped(self): + token = self.acquired() + request_id = new_id() + record = self.stop(token, request_id) + self.assertEqual(record['status'], 'pending') + self.assertEqual(self.lab.state['program']['state'], 'stopping') + self.tick() + record = self.status(request_id) + self.assertEqual(record['status'], 'completed') + self.assertEqual((record['result']['outcome'], record['result']['source']), ('stopped', 'lab')) + self.assertEqual(self.stop_requests(), ['owner lab-B\nrequest {}\nowner claim lab-B\nstop\n'.format(request_id)]) + last = self.events()[-1] + self.assertEqual((last['type'], last['payload']['tool'], last['request_id']), + ('request_completed', 'stop_program', request_id)) + + def test_the_stop_ends_a_running_lease(self): + token = self.acquired() + self.plane.begin_run('B', token, new_id(), self.lab.state['instance']['id']) + self.stop(token) + self.tick() + lease = self.plane.lease('B') + self.assertEqual(lease['state'], 'agent_idle') + reasons = [e['payload'].get('reason') for e in self.events() if e['type'] == 'lease_changed'] + self.assertEqual(reasons[-1], 'run_ended') + + def test_a_terminal_event_before_the_response_is_the_response(self): + self.app.stop_at_once = True + record = self.stop(self.acquired()) + self.assertEqual((record['status'], record['result']['outcome']), ('completed', 'stopped')) + + def test_an_exact_retry_sends_nothing_again(self): + token = self.acquired() + request_id = new_id() + first = self.stop(token, request_id) + again = self.stop(token, request_id) + self.assertEqual(again['status'], first['status']) + self.tick() + self.assertEqual(self.stop(token, request_id), self.status(request_id)) + self.assertEqual(len(self.stop_requests()), 1) + + def test_a_retry_after_a_daemon_restart_gets_the_same_record(self): + token = self.acquired() + request_id = new_id() + self.stop(token, request_id) + self.plane = open_plane(self, self.path, self.clock) + self.reader = self.make_reader() + self.tick() # the new daemon's first read resolves the ticket + self.assertEqual(self.stop(token, request_id)['status'], 'completed') + self.assertEqual(len(self.stop_requests()), 1) + + def test_nothing_running_completes_at_once_and_sends_nothing(self): + self.lab.update_state(**{'program.state': 'stopped'}) + record = self.stop(self.acquired()) + self.assertEqual((record['status'], record['result']['outcome']), ('completed', 'not_running')) + self.assertEqual(self.stop_requests(), []) + + def test_refused_before_acting_sends_nothing(self): + self.acquired() + cases = [ + dict(name='no lease token', input=None, expectation='invalid_arguments'), + dict(name='a token that does not hold the console', input='not-the-token', expectation='lease_invalid'), + ] + for case in cases: + with self.subTest(case['name']): + if case['input'] is None: + with self.assertRaises(control.Refused) as caught: + self.stop(None) + self.assertEqual(caught.exception.refusal['code'], case['expectation']) + else: + record = self.stop(case['input']) + self.assertEqual((record['status'], record['refusal']['code']), ('refused', case['expectation'])) + self.assertEqual(self.stop_requests(), []) + + def test_a_ui_click_before_the_call_takes_the_console(self): + token = self.acquired() + self.lab.update_state(**{'program.last_transition': transition('start', 'ui', START)}) + record = self.stop(token) + self.assertEqual((record['status'], record['refusal']['code']), ('refused', 'console_held_by_user')) + self.assertEqual(self.stop_requests(), []) + + def test_an_expired_lease_is_refused(self): + token = self.acquired() + self.clock.t += 1201 + self.lab.update_state(written_at=timestamps.format(self.clock.now())) + record = self.stop(token) + self.assertEqual(record['refusal']['code'], 'lease_expired') + + def test_an_unavailable_app_is_refused(self): + token = self.acquired() + self.clock.t += 60 # no heartbeat for a minute + record = self.stop(token) + self.assertEqual((record['status'], record['refusal']['code']), ('refused', 'app_unavailable')) + + +class RaceTests(ActionTest): + def test_a_ui_stop_after_the_request_fails_the_ticket_and_hands_over(self): + token = self.acquired() + request_id = new_id() + self.stop(token, request_id) + self.lab.update_state(**{'program.last_transition': transition( + 'stop', 'ui', timestamps.format(self.clock.now()))}) + self.tick() + record = self.status(request_id) + self.assertEqual((record['status'], record['refusal']['code']), ('failed', 'console_held_by_user')) + self.assertEqual(self.plane.lease('B')['state'], 'user') + + def test_an_app_restart_before_the_stop_is_confirmed_fails_the_ticket(self): + token = self.acquired() + request_id = new_id() + self.stop(token, request_id) + self.lab.update_state(**{'instance.id': NEW_INSTANCE, 'program.state': 'stopped', + 'program.last_transition': None}) + self.tick() + record = self.status(request_id) + self.assertEqual((record['status'], record['refusal']['evidence']['reason']), ('failed', 'instance_replaced')) + + def test_a_run_that_ends_by_itself_completes_the_ticket(self): + token = self.acquired() + self.app.stop_silent = True # the app took the request but has not answered yet + request_id = new_id() + self.assertEqual(self.stop(token, request_id)['status'], 'pending') + self.lab.update_state(**{'program.state': 'stopped', 'program.last_transition': transition( + 'stop', 'program', timestamps.format(self.clock.now()))}) + self.tick() + record = self.status(request_id) + self.assertEqual((record['status'], record['result']['outcome']), ('completed', 'ended')) + + def test_a_request_the_app_took_but_did_not_answer_stays_pending_until_reported(self): + token = self.acquired() + self.app.stop_silent = True + request_id = new_id() + self.assertEqual(self.stop(token, request_id)['status'], 'pending') + self.lab.update_state(**{'program.state': 'stopped', 'program.last_transition': transition( + 'stop', 'lab', timestamps.format(self.clock.now()), request_id)}) + self.tick() + self.assertEqual(self.status(request_id)['result']['outcome'], 'stopped') + + def test_a_busy_app_gets_the_request_withdrawn(self): + self.app.serve = False + record = self.stop(self.acquired()) + self.assertEqual((record['status'], record['refusal']['code']), ('refused', 'timeout')) + self.assertEqual(list((self.lab.dir / 'inbox').iterdir()), []) + + def test_a_channel_owned_by_another_script_fails_the_ticket(self): + self.app.channel_owner = 'someone-else' + record = self.stop(self.acquired()) + self.assertEqual((record['status'], record['refusal']['code']), ('failed', 'app_unavailable')) + self.assertIn('owned by someone-else', record['refusal']['message']) + + def test_a_run_that_ended_just_before_the_stop_line_is_its_end(self): + token = self.acquired() + original = self.app.stop + + def end_first(name, lines): + self.lab.update_state(**{'program.state': 'stopped', 'program.last_transition': transition( + 'stop', 'program', timestamps.format(self.clock.now()))}) + original(name, lines) + self.app.stop = end_first + record = self.stop(token) + self.assertEqual((record['status'], record['result']['outcome']), ('completed', 'ended')) + self.assertEqual(record['result']['source'], 'program') + + +class McpTests(ActionTest): + def setUp(self): + super().setUp() + self.mcp = mcp_server.LabMcp({'B': self.reader}, control_plane=self.plane, channel_owners={'B': OWNER}, + sleep=self.clock.sleep) + + def call(self, name, **arguments): + return self.mcp.call('tools/call', {'name': name, 'arguments': dict(arguments, console='B')}, client=CLIENT) + + def test_stop_program_then_wait_for_its_event(self): + token = self.acquired() + request_id = new_id() + reply = self.call('stop_program', request_id=request_id, lease_token=token) + self.assertFalse(reply['isError']) + self.assertEqual(reply['structuredContent']['status'], 'pending') + head = self.plane.next_events('reader', 'B', 0)['next_after_seq'] + self.clock.sleep(0.5) # the app reports stopped; the next read applies it + page = self.call('next_events', after_seq=head)['structuredContent'] + self.assertEqual([(e['type'], e['request_id']) for e in page['events'] if e['type'].startswith('request_')], + [('request_completed', request_id)]) + self.assertEqual(self.call('request_status', request_id=request_id)['structuredContent']['status'], + 'completed') + + def test_a_refusal_echoes_the_request_id(self): + request_id = new_id() + reply = self.call('stop_program', request_id=request_id, lease_token='nope') + self.assertTrue(reply['isError']) + self.assertEqual(reply['structuredContent']['request_id'], request_id) + self.assertEqual(reply['structuredContent']['refusal']['code'], 'lease_invalid') + + def test_no_channel_owner_is_refused(self): + self.mcp.channel_owners = {} + reply = self.call('stop_program', request_id=new_id(), lease_token=self.acquired()) + self.assertEqual(reply['structuredContent']['refusal']['code'], 'app_unavailable') + self.assertEqual(self.stop_requests(), []) + + +class MigrationTest(unittest.TestCase): + def test_a_version_1_file_gains_the_ticket_instance_column(self): + path = temp_db_path(self) + path.parent.mkdir(parents=True) + conn = sqlite3.connect(str(path)) + for statement in db.MIGRATIONS[0]: + conn.execute(statement) + conn.execute('PRAGMA user_version = 1') + conn.commit() + conn.close() + database = db.Database(path) + self.addCleanup(database.close) + columns = [row[1] for row in database.read().execute('PRAGMA table_info(requests)')] + self.assertIn('instance_id', columns) + self.assertEqual(database.found_version, 1) + + +if __name__ == '__main__': + unittest.main() diff --git a/lab/server/tests/test_cfr.py b/lab/server/tests/test_cfr.py new file mode 100644 index 0000000000..8f43eae7ae --- /dev/null +++ b/lab/server/tests/test_cfr.py @@ -0,0 +1,104 @@ +"""The cfr_batch allowlist (pa_lab/cfr.py): which lines pass, what each may cost, and the budget. + +Run from the repo root: python3 -m unittest discover -s lab/server/tests -t lab/server -v +""" + +import unittest + +from pa_lab import cfr, control + + +class AllowedLineTests(unittest.TestCase): + def test_allowed_lines_and_their_worst_case(self): + cases = [ + dict(name='press with defaults', input='press A', expectation=160 + 160 + 200), + dict(name='press two buttons, hold and release', input='press L+R 100 1500', expectation=1800), + dict(name='HOME is a button', input='press HOME 100 1000', expectation=1300), + dict(name='dpad with defaults', input='dpad DOWN', expectation=100 + 200 + 200), + dict(name='dpad holding B', input='dpad UP 160 400 B', expectation=760), + dict(name='stick with a button', input='stick L 0 1 1000 160 B', expectation=1360), + dict(name='stick with decimals', input='stick R -0.5 0.25', expectation=520), + dict(name='wait', input='wait 1500', expectation=1700), + dict(name='taps counts every tap', input='taps LEFT 3', expectation=3 * (160 + 640 + 200) + 200), + dict(name='taps all with timings', input='taps RIGHT 2 all 80 400 12.5', expectation=2 * 680 + 200), + dict(name='walk default max', input='walk 0 1', expectation=5000 + 400 + 200), + dict(name='walk with max, still and B', input='walk -1 0 2000 10 B', expectation=2600), + dict(name='shot', input='shot after_a', expectation=1200), + dict(name='shots', input='shots door 3 250', expectation=3 * 1250 + 200), + dict(name='detect', input='detect home', expectation=1200), + dict(name='wait_for default timeout', input='wait_for black', expectation=6200), + dict(name='expect with timeout', input='expect home 3000', expectation=4200), + dict(name='game_open', input='game_open', expectation=1200), + ] + for case in cases: + with self.subTest(case['name']): + self.assertEqual(cfr.check_line(case['input']), case['expectation']) + + +class RefusedLineTests(unittest.TestCase): + def test_lines_outside_the_allowlist(self): + cases = [ + dict(name='channel: start', input='start', expectation='not an allowed'), + dict(name='channel: select', input='select PokemonBDSP:AutoStory', expectation='not an allowed'), + dict(name='channel: set', input='set START_SEGMENT "0"', expectation='not an allowed'), + dict(name='channel: stop', input='stop', expectation='not an allowed'), + dict(name='channel: owner release', input='owner release', expectation='not an allowed'), + dict(name='channel: a second request id', input='request 3e8a6c21-7f90-4b2d-a1c4-6d0e9b5f8a73', + expectation='not an allowed'), + dict(name='channel: keepawake', input='keepawake off', expectation='not an allowed'), + dict(name='channel: popups', input='popups close', expectation='not an allowed'), + dict(name='close_game', input='close_game', expectation='not an allowed'), + dict(name='history', input='history run', expectation='not an allowed'), + dict(name='snapshot', input='snapshot frame 2000', expectation='not an allowed'), + dict(name='state', input='state', expectation='not an allowed'), + dict(name='a comment', input='# press A', expectation='not an allowed'), + dict(name='blank', input='', expectation='canonical'), + dict(name='two spaces', input='press A', expectation='canonical'), + dict(name='trailing space', input='press A ', expectation='canonical'), + dict(name='a tab', input='press\tA', expectation='canonical'), + dict(name='a newline smuggles a second command', input='press A\nstart', expectation='canonical'), + dict(name='CAPTURE button', input='press CAPTURE', expectation='buttons'), + dict(name='repeated button', input='press A+A', expectation='buttons'), + dict(name='lower-case button', input='press a', expectation='buttons'), + dict(name='hold too long', input='press A 10001', expectation='hold'), + dict(name='negative release', input='press A 100 -1', expectation='release'), + dict(name='leading zero', input='wait 0100', expectation='ms'), + dict(name='too many arguments', input='press A 1 2 3', expectation='usage'), + dict(name='bad direction', input='dpad NORTH', expectation='direction'), + dict(name='stick out of range', input='stick L 1.5 0', expectation='x must'), + dict(name='stick in exponent form', input='stick L 1e0 0', expectation='x must'), + dict(name='wait too long', input='wait 30001', expectation='ms'), + dict(name='too many taps', input='taps UP 21', expectation='N must'), + dict(name='walk max too long', input='walk 0 1 10001', expectation='max'), + dict(name='shot label with a slash', input='shot ../x', expectation='label'), + dict(name='too many shots', input='shots s 11', expectation='count'), + dict(name='detect on an image path', input='detect home /tmp/x.png', expectation='usage'), + dict(name='detector with a path', input='detect ../home', expectation='detector'), + dict(name='game_open on an image', input='game_open image', expectation='usage'), + ] + for case in cases: + with self.subTest(case['name']): + with self.assertRaises(ValueError) as caught: + cfr.check_line(case['input']) + self.assertIn(case['expectation'], str(caught.exception)) + + +class BatchTests(unittest.TestCase): + def test_the_first_bad_line_is_named(self): + with self.assertRaises(control.Refused) as caught: + cfr.check(['press A', 'start', 'stop']) + self.assertEqual(caught.exception.refusal['code'], 'invalid_arguments') + self.assertEqual(caught.exception.refusal['field'], 'arguments.lines[1]') + + def test_a_batch_over_the_budget_is_refused(self): + with self.assertRaises(control.Refused) as caught: + cfr.check(['wait 30000', 'wait 30000']) + self.assertEqual(caught.exception.refusal['field'], 'arguments.lines') + self.assertEqual(caught.exception.refusal['evidence']['limit_ms'], cfr.BATCH_MAX_MS) + + def test_a_batch_within_the_budget_returns_its_worst_case(self): + self.assertEqual(cfr.check(['shot before', 'press B 160 640', 'shot after']), 1200 + 1000 + 1200) + + +if __name__ == '__main__': + unittest.main() diff --git a/lab/server/tests/test_cfr_batch.py b/lab/server/tests/test_cfr_batch.py new file mode 100644 index 0000000000..cfc00355cd --- /dev/null +++ b/lab/server/tests/test_cfr_batch.py @@ -0,0 +1,244 @@ +"""The cfr_batch leased action (Slice 5b of fork #131) against a fake app in a temp `Lab/` folder: +the allowlist and state refusals, the request it sends, its journal as the result, the save fact +going stale, and the races (retry, daemon restart, busy app, app restart, foreign owner). No real +profile or console is touched. + +Run from the repo root: python3 -m unittest discover -s lab/server/tests -t lab/server -v +""" + +import unittest + +from pa_lab import actions, control, mcp_server, timestamps +from tests.control_fixtures import START, new_id, open_plane, transition +from tests.fake_lab import golden +from tests.test_actions import CLIENT, NEW_INSTANCE, OWNER, ActionTest + +BATCH = ['shot before', 'press B 160 640', 'shot after'] + + +def batch_request(token, lines=None, request_id=None): + request = {'schema': 1, 'request_id': request_id or new_id(), 'tool': 'cfr_batch', 'console': 'B', + 'arguments': {'lines': list(BATCH if lines is None else lines)}} + if token is not None: + request['lease_token'] = token + return request + + +class BatchTest(ActionTest): + def setUp(self): + super().setUp() + self.lab.update_state(**{'program.state': 'stopped', 'program.last_transition': transition( + 'stop', 'lab', '2026-11-14T05:59:30.000Z', new_id())}) + + def batch(self, token, lines=None, request_id=None): + return actions.cfr_batch(self.plane, self.reader, CLIENT, batch_request(token, lines, request_id), OWNER, + sleep=self.clock.sleep) + + def batch_requests(self): + return [text for text in self.app.requests if 'owner claim' in text and not text.endswith('\nstop\n')] + + +class BatchTests(BatchTest): + def test_a_batch_runs_and_returns_its_journal(self): + token = self.acquired() + request_id = new_id() + record = self.batch(token, request_id=request_id) + self.assertEqual((record['status'], record['result']['outcome']), ('completed', 'done')) + self.assertEqual(record['result']['journal'][-2:], ['ok 6 shot after @0-1ms', 'end']) + self.assertEqual(self.batch_requests(), ['owner lab-B\nrequest {}\nowner claim lab-B\nshot before\n' + 'press B 160 640\nshot after\n'.format(request_id)]) + last = self.events()[-1] + self.assertEqual((last['type'], last['payload']['tool'], last['request_id']), + ('request_completed', 'cfr_batch', request_id)) + + def test_a_failing_line_is_an_answer_with_its_line_number(self): + self.app.batch_errors = {'press B 160 640': 'timeout'} + record = self.batch(self.acquired()) + self.assertEqual((record['status'], record['result']['outcome']), ('completed', 'line_failed')) + self.assertEqual(record['result']['failed_line'], 2) + self.assertEqual(record['result']['error'], 'error 5 (press B 160 640): timeout') + + def test_an_exact_retry_sends_nothing_again(self): + token = self.acquired() + request_id = new_id() + first = self.batch(token, request_id=request_id) + self.assertEqual(self.batch(token, request_id=request_id), first) + self.assertEqual(len(self.batch_requests()), 1) + + def test_the_same_request_id_with_other_lines_is_refused(self): + token = self.acquired() + request_id = new_id() + self.batch(token, request_id=request_id) + with self.assertRaises(control.Refused) as caught: + self.batch(token, ['press A'], request_id=request_id) + self.assertEqual(caught.exception.refusal['code'], 'request_id_reused') + + +class RefusalTests(BatchTest): + def test_refused_before_acting_sends_nothing_and_keeps_the_save(self): + self.lab.write_save(golden('save_fact', 'frlg_checkpoint')) + cases = [ + dict(name='a token that does not hold the console', input=dict(token='not-the-token'), + expectation='lease_invalid'), + dict(name='a channel command', input=dict(lines=['press A', 'start']), expectation='invalid_arguments'), + dict(name='over the time budget', input=dict(lines=['wait 30000', 'wait 30000']), + expectation='invalid_arguments'), + dict(name='a running program', input=dict(state={'program.state': 'running'}), + expectation='program_running'), + dict(name='a loading panel', input=dict(state={'program.state': 'not_ready'}), + expectation='program_not_stopped'), + dict(name='the settings panel', input=dict(state={'program.state': 'no_program', 'panel.id': None, + 'panel.kind': 'other'}), + expectation='panel_not_program'), + dict(name='no controller', input=dict(state={'controller.state': 'not_connected'}), + expectation='controller_not_ready'), + dict(name='stale video', input=dict(state={'video.state': 'stale'}, frames=False), + expectation='video_stale'), + ] + token = self.acquired() + for case in cases: + with self.subTest(case['name']): + before = self.lab.state + self.app.frames = case['input'].get('frames', True) + self.lab.update_state(**case['input'].get('state', {})) + record = self.batch(case['input'].get('token', token), case['input'].get('lines')) + self.assertEqual((record['status'], record['refusal']['code']), ('refused', case['expectation']), + record['refusal']['message']) + self.lab.write_state(before) + self.app.frames = True + self.assertEqual(self.batch_requests(), []) + self.assertEqual(self.reader.save_resource()['status'], 'known') + + def test_the_bad_line_is_named_in_the_refusal(self): + record = self.batch(self.acquired(), ['press A', 'close_game']) + self.assertEqual(record['refusal']['field'], 'arguments.lines[1]') + + def test_a_ui_click_before_the_call_takes_the_console(self): + token = self.acquired() + self.lab.update_state(**{'program.last_transition': transition('stop', 'ui', START)}) + record = self.batch(token) + self.assertEqual((record['status'], record['refusal']['code']), ('refused', 'console_held_by_user')) + self.assertEqual(self.batch_requests(), []) + + def test_no_lease_token_cannot_be_keyed(self): + with self.assertRaises(control.Refused) as caught: + self.batch(None) + self.assertEqual(caught.exception.refusal['code'], 'invalid_arguments') + + +class SaveTests(BatchTest): + def test_a_sent_batch_marks_the_save_stale_until_a_newer_save(self): + fact = golden('save_fact', 'frlg_checkpoint') + fact['saved_at'] = '2026-11-14T05:00:00.000Z' + self.lab.write_save(fact) + self.assertEqual(self.reader.save_resource()['status'], 'known') + self.batch(self.acquired()) + save = self.reader.save_resource() + self.assertEqual((save['status'], save['reason']), ('stale', 'cfr_batch')) + fact['saved_at'] = timestamps.format(self.clock.now() + 1) + self.lab.write_save(fact) + self.assertEqual(self.reader.save_resource()['status'], 'known') + + def test_a_batch_the_app_never_took_still_marks_the_save_stale(self): + self.lab.write_save(golden('save_fact', 'frlg_checkpoint')) + self.app.serve = False + record = self.batch(self.acquired()) + self.assertEqual((record['status'], record['refusal']['code']), ('refused', 'timeout')) + self.assertEqual(self.reader.save_resource()['reason'], 'cfr_batch') + + def test_the_mark_survives_a_daemon_restart(self): + self.lab.write_save(golden('save_fact', 'frlg_checkpoint')) + self.batch(self.acquired()) + self.plane = open_plane(self, self.path, self.clock) + self.reader = self.make_reader() + self.assertEqual(self.reader.save_resource()['reason'], 'cfr_batch') + + +class RaceTests(BatchTest): + def test_a_busy_app_gets_the_batch_withdrawn(self): + self.app.serve = False + record = self.batch(self.acquired()) + self.assertEqual((record['status'], record['refusal']['code']), ('refused', 'timeout')) + self.assertEqual(list((self.lab.dir / 'inbox').iterdir()), []) + + def test_a_batch_taken_but_never_answered_fails_with_timeout(self): + self.app.batch_silent = True + record = self.batch(self.acquired()) + self.assertEqual((record['status'], record['refusal']['code']), ('failed', 'timeout')) + + def test_a_channel_owned_by_another_script_fails_and_nothing_runs(self): + self.app.channel_owner = 'someone-else' + record = self.batch(self.acquired()) + self.assertEqual((record['status'], record['refusal']['code']), ('failed', 'app_unavailable')) + self.assertIn('owned by someone-else', record['refusal']['message']) + + def test_a_program_started_before_the_batch_ran_fails_its_first_line(self): + token = self.acquired() + original = self.app.batch + + def started_first(name, lines): + self.lab.update_state(**{'program.state': 'running'}) + original(name, lines) + self.app.batch = started_first + record = self.batch(token) + self.assertEqual((record['result']['outcome'], record['result']['failed_line']), ('line_failed', 1)) + + def test_a_retry_after_a_daemon_restart_collects_the_journal(self): + token = self.acquired() + request_id = new_id() + stored = self.plane.begin_action(CLIENT, batch_request(token, request_id=request_id), + self.lab.state['instance']['id'], lambda row: None)[0] + self.assertEqual(stored['status'], 'pending') # the daemon stopped after storing the ticket + self.app.batch('palab_cfr_batch_' + request_id.replace('-', ''), + actions.request_text(OWNER, request_id, BATCH).splitlines()) + self.plane = open_plane(self, self.path, self.clock) + self.reader = self.make_reader() + record = self.batch(token, request_id=request_id) + self.assertEqual((record['status'], record['result']['outcome']), ('completed', 'done')) + self.assertEqual(self.batch_requests(), []) + + def test_an_app_restart_fails_a_pending_batch(self): + token = self.acquired() + request_id = new_id() + self.plane.begin_action(CLIENT, batch_request(token, request_id=request_id), + self.lab.state['instance']['id'], lambda row: None) + self.lab.update_state(**{'instance.id': NEW_INSTANCE, 'program.last_transition': None}) + self.tick() + record = self.status(request_id) + self.assertEqual((record['status'], record['refusal']['evidence']['reason']), ('failed', 'instance_replaced')) + + +class McpTests(BatchTest): + def setUp(self): + super().setUp() + self.mcp = mcp_server.LabMcp({'B': self.reader}, control_plane=self.plane, channel_owners={'B': OWNER}, + sleep=self.clock.sleep) + + def call(self, name, **arguments): + return self.mcp.call('tools/call', {'name': name, 'arguments': dict(arguments, console='B')}, client=CLIENT) + + def test_the_tool_is_listed_with_its_lines(self): + tools = {t['name']: t for t in self.mcp.call('tools/list', {})['tools']} + self.assertEqual(tools['cfr_batch']['inputSchema']['required'], ['console', 'request_id', 'lease_token', 'lines']) + + def test_cfr_batch_returns_the_journal(self): + reply = self.call('cfr_batch', request_id=new_id(), lease_token=self.acquired(), lines=BATCH) + self.assertFalse(reply['isError']) + self.assertEqual(reply['structuredContent']['result']['outcome'], 'done') + + def test_a_refusal_echoes_the_request_id_and_the_line(self): + request_id = new_id() + reply = self.call('cfr_batch', request_id=request_id, lease_token=self.acquired(), lines=['start']) + self.assertTrue(reply['isError']) + self.assertEqual(reply['structuredContent']['request_id'], request_id) + self.assertEqual(reply['structuredContent']['refusal']['field'], 'arguments.lines[0]') + + def test_no_channel_owner_is_refused(self): + self.mcp.channel_owners = {} + reply = self.call('cfr_batch', request_id=new_id(), lease_token=self.acquired(), lines=BATCH) + self.assertEqual(reply['structuredContent']['refusal']['code'], 'app_unavailable') + self.assertEqual(self.batch_requests(), []) + + +if __name__ == '__main__': + unittest.main() diff --git a/lab/server/tests/test_config.py b/lab/server/tests/test_config.py index e41e8b8293..81fd30b071 100644 --- a/lab/server/tests/test_config.py +++ b/lab/server/tests/test_config.py @@ -43,6 +43,11 @@ def test_refused_configs(self): dict(name='relative lab dir', input={'consoles.B': {'lab_dir': 'Lab'}}, expectation='consoles.B.lab_dir'), dict(name='unknown key', input={'mutations': True}, expectation='mutations'), dict(name='future schema', input={'schema': 2}, expectation='schema'), + dict(name='channel owner with a space', input={'consoles.B.channel_owner': 'lab B'}, + expectation='consoles.B.channel_owner'), + dict(name='profile unusable as the channel owner', + input={'consoles.B': {'lab_dir': '/x/Lab', 'profile': 'lab B'}}, + expectation='consoles.B.channel_owner'), ] for case in cases: with self.subTest(case['name']): @@ -57,6 +62,17 @@ def test_refused_configs(self): config.load(self.write(doc)) self.assertIn(case['expectation'], str(raised.exception)) + def test_the_channel_owner_defaults_to_the_profile(self): + cases = [ + dict(name='default', input={}, expectation='lab-B'), + dict(name='explicit', input={'channel_owner': 'pa-lab-daemon'}, expectation='pa-lab-daemon'), + ] + for case in cases: + with self.subTest(case['name']): + doc = self.good() + doc['consoles']['B'].update(case['input']) + self.assertEqual(config.load(self.write(doc)).consoles['B'].channel_owner, case['expectation']) + def test_token_file_is_owner_only(self): self.assertEqual(os.stat(self.token).st_mode & 0o777, 0o600) self.assertGreaterEqual(len(config.read_token(self.token)), 32) diff --git a/lab/server/tests/test_control_mcp.py b/lab/server/tests/test_control_mcp.py index edeeba05a3..1a8cfd1818 100644 --- a/lab/server/tests/test_control_mcp.py +++ b/lab/server/tests/test_control_mcp.py @@ -46,7 +46,7 @@ def test_the_control_tools_are_listed(self): _, body = self.client.rpc('tools/list') names = [t['name'] for t in body['result']['tools']] self.assertEqual(names, ['shot', 'ensure_game', 'describe_program', 'game_open', 'acquire_console', 'renew_console', 'release_console', - 'next_events', 'request_status']) + 'next_events', 'stop_program', 'cfr_batch', 'request_status']) def test_acquire_then_state_shows_the_lease_and_a_retry_matches(self): request_id = str(uuid.uuid4())