diff --git a/lab/server/README.md b/lab/server/README.md index 44dcbd5918..78ea12ccb5 100644 --- a/lab/server/README.md +++ b/lab/server/README.md @@ -1,8 +1,9 @@ # pa-lab console daemon (`lab/server`) The local server designed in `docs/design/Agent-Integration.md` (fork #131, branch -`design/agent-integration`). This directory is Slice 0 only: the version-1 contracts, golden -examples and a parser. There is no server, no network code and no app change here yet. +`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)). It has no +lease store, no write path and no press: those are Slices 3 and 5. | Path | What | |---|---| @@ -13,9 +14,15 @@ examples and a parser. There is no server, no network code and no app change her | `contracts/v1/legacy/*.state` | Legacy `Lab/state` twins of three `app_state` goldens (`stopped_ui` is the real lab-B file of 2026-11-14) | | `contracts/v1/invalid_cases.json` | Documents that must fail: name, kind, input, expected field path and message | | `tests/test_contracts.py` | Golden parse, round-trip, invalid-case and legacy-mapping tests | +| `pa_lab/config.py` | Server config: the one-entry allowlist (B), loopback port, owner-only token file | +| `pa_lab/lab_reader.py` | Strict reads of `Lab/state.json` and `Lab/save.json`; `console://B/state` and `/save` | +| `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 | +| `tests/fake_lab.py` | A fake `Lab/` folder and a fake app answering `snapshot` requests, in temp dirs | +| `tests/test_{lab_reader,ensure_game,shot,config,mcp_server}.py` | Slice 2's fake-lab tests | -Stdlib only (Python 3.8+), so no venv yet; Slice 2 adds `requirements.txt` and a venv -(`~/.venvs/pa-lab`) for the MCP server. Run the tests from the repo root: +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: ```sh python3 -m unittest discover -s lab/server/tests -t lab/server -v @@ -110,3 +117,70 @@ New in `state.json`: `written_at` (heartbeat), `instance.{id,pid,profile}`, `pan - Lower-case enums exactly as listed by `python3 -m pa_lab describe app_state`. - Checked by `python3 -m pa_lab check app_state ` and by a native serialization test against the goldens in `contracts/v1/app_state/`. + +## Slice 2: the attach-only read server + +```sh +python3 -m pa_lab init-token ~/.config/pa-lab/token # 0600; never overwritten +python3 -m pa_lab serve --config ~/.config/pa-lab/server.json +``` + +```json +{"schema": 1, "host": "127.0.0.1", "port": 8765, "token_file": "~/.config/pa-lab/token", + "consoles": {"B": {"lab_dir": "~/Library/Application Support/SerialPrograms/Profiles/lab-B/Lab", + "profile": "lab-B"}}} +``` + +The config is the server's own, closed, and must list exactly `B`; 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 `. + +**Transport.** One endpoint, `POST /mcp`, JSON-RPC answered as `application/json` (MCP +2025-06-18 or 2025-03-26). `GET` is 405 (nothing is pushed), `DELETE` ends a session. Each request +needs the bearer token (compared in constant time, never logged), a `Host` of +`127.0.0.1:` or `localhost:` (DNS rebinding), and no `Origin` but the server's own; +bodies over 1 MiB are refused. `initialize` opens an `Mcp-Session-Id` session and records the +client's name, which the log carries with each call. + +**Resources.** `console://B/state` is `console_state`: the app's `Lab/state.json` exactly as +parsed, availability, the reported lease and `blocked`. `console://B/save` is `save_resource`. +A console id is looked up in the allowlist, never turned into a path. + +| What the daemon finds | `console://B/state` | +|---|---| +| no `Lab/state.json` | `unavailable`, `no_state_file` | +| torn/partial file, duplicate key, `NaN`, > 1 MiB, a contract break, another profile's app | `unavailable`, `malformed` (the message names the field) | +| `schema` it does not read | `unavailable`, `unsupported_schema` | +| `instance.pid` not running | `unavailable`, `app_not_running` | +| `written_at` older than 10 s | `unavailable`, `stale_heartbeat` | + +The heartbeat limit is 10 s, not 1 s, because the app writes `state.json` between channel +requests and a long request (`walk`) holds it. A new `instance.id` is the new app: the resource +shows it with its own `frame_seq`; `shot` refuses a call that spans the restart. + +`save.json` missing is `unknown` / `no_fact`. A save fact is `known` / `hooked_save` until the +app shows a UI Start/Stop after `saved_at`, then `stale` / `user_lease`. A `save.json` that +exists but cannot be read is a JSON-RPC error (`-32001`, the refusal in `data`), not `unknown`. + +**Lease, reported only.** With no lease store yet, the lease comes from the app's last +transition: a UI Start/Stop means `user` (no timeout), otherwise `free`. A user lease is not +remembered across an app restart until Slice 3's store. + +**`ensure_game(console, expected, allowed_screens?, max_age_ms=5000)`** reads the app's +`observation.game` / `.screen` and returns them with their ages and `verified` with a `reason` +(`game_unknown`, `game_mismatch`, `screen_unknown`, `screen_not_allowed`, `observation_stale`). +`unknown` never verifies; until the app has detectors, every call says `game_unknown`. + +**`shot(console, max_age_ms=2000, timeout_ms=5000)`** returns the PNG (MCP image content), its +path and the exact `frame_seq` and `captured_at` of that frame. The daemon checks `state.json` +once (the app is up; its `instance.id`), then writes the fixed request `request ` / +`snapshot frame ` into `Lab/inbox` at once. The app's `snapshot` command (#481, +`Lab.md` "Snapshot") needs no owner token, program state or controller: it waits for the first +frame after the line starts, saves it and prints `snapshot saved instance=... frame_seq=... +captured_at=... after=... path=...`. The daemon opens only the path it chose, never the one the +journal names, and only when complete (signature and `IEND`). Refusals: `timeout` (the app's +`snapshot timeout`, evidence `{instance_id, frame_seq: after}`; or the app did not answer within +`timeout_ms` + 2 s, and the request is withdrawn from the inbox), `video_stale` (`reason=no_video`, +or the saved frame is older than `max_age_ms`), `video_bad_signal`, `app_unavailable` (a reply +from another instance: `evidence.reason` `instance_replaced`; `panel_changed`, `app_closing`, +`save_failed` as `evidence.reason`; a line error or an incomplete PNG). diff --git a/lab/server/pa_lab/__init__.py b/lab/server/pa_lab/__init__.py index 2d3734198a..40fcaafd67 100644 --- a/lab/server/pa_lab/__init__.py +++ b/lab/server/pa_lab/__init__.py @@ -1 +1 @@ -"""pa-lab console daemon (docs/design/Agent-Integration.md, fork #131). Slice 0: contracts only.""" +"""pa-lab console daemon (docs/design/Agent-Integration.md, fork #131). Slice 0: contracts; Slice 2: the read server.""" diff --git a/lab/server/pa_lab/__main__.py b/lab/server/pa_lab/__main__.py index d0949f877b..5187351d7f 100644 --- a/lab/server/pa_lab/__main__.py +++ b/lab/server/pa_lab/__main__.py @@ -1,8 +1,10 @@ -"""Check or describe version-1 lab contract documents. +"""Check or describe version-1 lab contract documents, or run the read-only lab server. python3 -m pa_lab check app_state ~/Library/Application\\ Support/SerialPrograms/Profiles/lab-B/Lab/state.json 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 Run from lab/server (or with lab/server on PYTHONPATH). Exit 0 valid, 1 invalid, 2 usage. """ @@ -10,9 +12,10 @@ from __future__ import annotations import argparse +import logging import sys -from pa_lab import contracts +from pa_lab import config, contracts def main(argv=None) -> int: @@ -24,6 +27,10 @@ def main(argv=None) -> int: describe = sub.add_parser('describe', help='print the fields of a kind') describe.add_argument('kind', choices=contracts.KINDS) sub.add_parser('kinds', help='list kinds and who writes them') + init_token = sub.add_parser('init-token', help='write a new owner-only bearer token file') + init_token.add_argument('path') + serve = sub.add_parser('serve', help='run the read-only MCP server (Streamable HTTP on 127.0.0.1)') + serve.add_argument('--config', required=True) args = parser.parse_args(argv) if args.command == 'check': @@ -50,9 +57,43 @@ def main(argv=None) -> int: for kind in contracts.KINDS: print('{:15} {}'.format(kind, contracts.AUTHORS[kind])) return 0 + if args.command == 'init-token': + try: + config.create_token(args.path) + except config.ConfigError as e: + print('error {}'.format(e)) + return 1 + print('wrote {}'.format(args.path)) + return 0 + if args.command == 'serve': + return _serve(args.config) parser.print_help() return 2 +def _serve(path: str) -> int: + from pa_lab import lab_reader, mcp_server + try: + cfg = config.load(path) + token = config.read_token(cfg.token_file) + except config.ConfigError as e: + print('error {}'.format(e)) + return 1 + logging.basicConfig(level=logging.INFO, format='%(asctime)s %(name)s %(message)s') + readers = {name: lab_reader.ConsoleReader(name, entry.lab_dir, profile=entry.profile) + for name, entry in cfg.consoles.items()} + server = mcp_server.make_server(cfg.port, token, readers) + 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) + try: + server.serve_forever() + except KeyboardInterrupt: + pass + finally: + server.server_close() + return 0 + + if __name__ == '__main__': sys.exit(main()) diff --git a/lab/server/pa_lab/config.py b/lab/server/pa_lab/config.py new file mode 100644 index 0000000000..ed7cf89d4f --- /dev/null +++ b/lab/server/pa_lab/config.py @@ -0,0 +1,111 @@ +"""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. + + {"schema": 1, "host": "127.0.0.1", "port": 8765, "token_file": "~/.config/pa-lab/token", + "consoles": {"B": {"lab_dir": "~/Library/Application Support/SerialPrograms/Profiles/lab-B/Lab", + "profile": "lab-B"}}} +""" + +from __future__ import annotations + +import json +import os +from pathlib import Path +import secrets +import stat +from typing import Dict, Optional + +ALLOWED_CONSOLES = ('B',) +LOOPBACK_HOSTS = ('127.0.0.1',) +TOP_KEYS = ('schema', 'host', 'port', 'token_file', 'consoles') +CONSOLE_KEYS = ('lab_dir', 'profile') + + +class ConfigError(ValueError): + pass + + +class ConsoleConfig: + def __init__(self, lab_dir: Path, profile: Optional[str]): + self.lab_dir = lab_dir + self.profile = profile + + +class Config: + def __init__(self, host: str, port: int, token_file: Path, consoles: Dict[str, ConsoleConfig]): + self.host = host + self.port = port + self.token_file = token_file + self.consoles = consoles + + +def _path(value, field: str) -> Path: + if not isinstance(value, str) or not value: + raise ConfigError('{}: expected a path'.format(field)) + path = Path(os.path.expanduser(value)) + if not path.is_absolute(): + raise ConfigError('{}: {!r} is not an absolute path'.format(field, value)) + return path + + +def load(path: Path) -> Config: + try: + doc = json.loads(Path(path).read_text(encoding='utf-8')) + except (OSError, ValueError) as e: + raise ConfigError('{}: {}'.format(path, e)) + if not isinstance(doc, dict): + raise ConfigError('$: expected an object') + for key in doc: + if key not in TOP_KEYS: + raise ConfigError('{}: unknown key (the config is closed)'.format(key)) + if doc.get('schema') != 1: + raise ConfigError('schema: expected 1, got {!r}'.format(doc.get('schema'))) + host = doc.get('host', '127.0.0.1') + if host not in LOOPBACK_HOSTS: + raise ConfigError('host: {!r} is not loopback; the daemon binds only to 127.0.0.1'.format(host)) + port = doc.get('port') + if isinstance(port, bool) or not isinstance(port, int) or not 0 <= port <= 65535: + raise ConfigError('port: expected 0..65535, got {!r}'.format(port)) + consoles = doc.get('consoles') + if not isinstance(consoles, dict) or sorted(consoles) != sorted(ALLOWED_CONSOLES): + raise ConfigError('consoles: must list exactly {} (console A is never exposed), got {}'.format( + ', '.join(ALLOWED_CONSOLES), sorted(consoles) if isinstance(consoles, dict) else consoles)) + out = {} + for name, entry in consoles.items(): + field = 'consoles.' + name + if not isinstance(entry, dict): + raise ConfigError('{}: expected an object'.format(field)) + for key in entry: + if key not in CONSOLE_KEYS: + raise ConfigError('{}.{}: unknown key'.format(field, key)) + 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) + return Config(host, port, _path(doc.get('token_file'), 'token_file'), out) + + +def read_token(path: Path) -> str: + """The bearer token; refused unless only the owner can read the file.""" + try: + mode = stat.S_IMODE(os.stat(path).st_mode) + token = Path(path).read_text(encoding='utf-8').strip() + except OSError as e: + raise ConfigError('token_file: {}'.format(e)) + if mode & 0o077: + raise ConfigError('token_file: {} has mode {:04o}; it must be owner-only (0600)'.format(path, mode)) + if len(token) < 32: + raise ConfigError('token_file: the token is shorter than 32 characters') + return token + + +def create_token(path: Path) -> None: + """Writes a new random token readable only by the owner. Never overwrites.""" + path = Path(path) + path.parent.mkdir(parents=True, exist_ok=True) + try: + fd = os.open(str(path), os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600) + except FileExistsError: + raise ConfigError('token_file: {} already exists'.format(path)) + with os.fdopen(fd, 'w') as f: + f.write(secrets.token_urlsafe(32) + '\n') diff --git a/lab/server/pa_lab/contracts.py b/lab/server/pa_lab/contracts.py index cca4e74fe7..eaa7362747 100644 --- a/lab/server/pa_lab/contracts.py +++ b/lab/server/pa_lab/contracts.py @@ -699,6 +699,15 @@ def _page_order(obj, path, ctx): # ---- entry points -------------------------------------------------------------------------------- +def check_object(spec: Spec, value: Any) -> Any: + """Checks `value` against one spec; returns it as checked or raises ContractError.""" + ctx = _Ctx() + out = spec.check(value, '', ctx) + if ctx.errors: + raise ContractError('object', ctx.errors) + return out + + def validate(kind: str, value: Any) -> Parsed: if kind not in _SPECS: raise ValueError('unknown kind {!r}; kinds: {}'.format(kind, ', '.join(KINDS))) diff --git a/lab/server/pa_lab/lab_reader.py b/lab/server/pa_lab/lab_reader.py new file mode 100644 index 0000000000..0ec55ec185 --- /dev/null +++ b/lab/server/pa_lab/lab_reader.py @@ -0,0 +1,232 @@ +"""Read-only view of one console's `Lab/` folder: `console://B/state` and `console://B/save`. + +Slice 2 of docs/design/Agent-Integration.md (fork #131). The app writes `Lab/state.json` (and a +program that saved writes `Lab/save.json`); this module parses them strictly and builds the +daemon's resources around them, never editing the app's document. Anything it cannot trust +(no file, a torn or malformed file, an unsupported schema, another profile's app, a dead pid, a +stale heartbeat) is an explicit `unavailable` state with the reason, never a guess. + +Slice 2 has no lease store (that is Slice 3), so the lease is only reported: the app's last +transition from a UI Start/Stop means the user holds the console, with no timeout. +""" + +from __future__ import annotations + +import json +import os +from pathlib import Path +from typing import Any, Callable, Dict, List, Optional + +from pa_lab import contracts, timestamps + +MAX_FILE_BYTES = 1 << 20 + +# The app rewrites state.json every 500 ms, but not while it runs a channel request (a `walk` +# can take 5 s), so the heartbeat is judged against a generous limit. +HEARTBEAT_TIMEOUT_S = 10.0 + +BAD_SIGNALS = ('black', 'colour_bars') + + +class Unavailable(Exception): + """A file the daemon cannot use. `reason` is a console_state availability.reason.""" + + def __init__(self, reason: str, message: str, evidence: Optional[Dict[str, Any]] = None): + super().__init__(message) + self.reason = reason + self.message = message + self.evidence = evidence + + def refusal(self) -> Dict[str, Any]: + out = {'code': 'unsupported_schema' if self.reason == 'unsupported_schema' else 'app_unavailable', + 'message': self.message} + if self.evidence is not None: + out['evidence'] = self.evidence + return out + + +def _no_duplicate_keys(pairs): + out = {} + for key, value in pairs: + if key in out: + raise ValueError('duplicate key {!r}'.format(key)) + out[key] = value + return out + + +def _no_constants(name): + raise ValueError('{} is not JSON'.format(name)) + + +def load_strict(path: Path, kind: str) -> Dict[str, Any]: + """One read of a whole file, parsed strictly and checked against the version-1 contract. + + Raises Unavailable with reason no_state_file, malformed or unsupported_schema. + """ + name = 'Lab/' + path.name + try: + with open(path, 'rb') as f: + data = f.read(MAX_FILE_BYTES + 1) + except FileNotFoundError: + raise Unavailable('no_state_file', '{} does not exist.'.format(name)) + except OSError as e: + raise Unavailable('malformed', '{} cannot be read: {}.'.format(name, e.strerror)) + if len(data) > MAX_FILE_BYTES: + raise Unavailable('malformed', '{} is larger than {} bytes.'.format(name, MAX_FILE_BYTES)) + try: + value = json.loads(data.decode('utf-8'), object_pairs_hook=_no_duplicate_keys, + parse_constant=_no_constants) + except (UnicodeDecodeError, ValueError) as e: + raise Unavailable('malformed', '{} is not complete JSON (a partial write?): {}.'.format(name, e)) + if isinstance(value, dict) and 'schema' in value and value['schema'] not in contracts.SUPPORTED_VERSIONS \ + and isinstance(value['schema'], int) and not isinstance(value['schema'], bool): + raise Unavailable('unsupported_schema', '{} has schema {}; this daemon reads {}.'.format( + name, value['schema'], ', '.join(str(v) for v in contracts.SUPPORTED_VERSIONS)), + {'schema': value['schema']}) + try: + return contracts.validate(kind, value).data + except contracts.ContractError as e: + raise Unavailable('malformed', '{} breaks the {} contract: {}.'.format( + name, kind, '; '.join(str(err) for err in e.errors)), {'fields': e.paths()}) + + +def pid_alive(pid: int) -> bool: + try: + os.kill(pid, 0) + except ProcessLookupError: + return False + except PermissionError: + return True + return True + + +def _clock_time(at: str) -> str: + return at[11:16] + + +class ConsoleReader: + """Reads one allowlisted console's `Lab/` folder. Safe to share between threads: it keeps no + state between calls except the last app instance it saw.""" + + def __init__(self, console: str, lab_dir: Path, profile: Optional[str] = None, + now: Callable[[], float] = timestamps.wall_clock, + pid_alive: Callable[[int], bool] = pid_alive, + heartbeat_timeout_s: float = HEARTBEAT_TIMEOUT_S): + self.console = console + self.lab_dir = Path(lab_dir) + self.profile = profile + self.now = now + self.pid_alive = pid_alive + self.heartbeat_timeout_s = heartbeat_timeout_s + + @property + def state_path(self) -> Path: + return self.lab_dir / 'state.json' + + @property + def save_path(self) -> Path: + return self.lab_dir / 'save.json' + + def app_state(self) -> Dict[str, Any]: + """The parsed `Lab/state.json` of a live app, or Unavailable.""" + app = load_strict(self.state_path, 'app_state') + profile = app['instance'].get('profile') + if self.profile is not None and profile is not None and profile != self.profile: + raise Unavailable('malformed', 'Lab/state.json is from profile {!r}, not {!r}.'.format( + profile, self.profile), {'profile': profile}) + pid = app['instance']['pid'] + if not self.pid_alive(pid): + raise Unavailable('app_not_running', 'The app that wrote Lab/state.json (pid {}) is not running.'.format( + pid), {'pid': pid, 'instance_id': app['instance']['id']}) + age = self.now() - timestamps.parse(app['written_at']) + if age > self.heartbeat_timeout_s: + raise Unavailable('stale_heartbeat', 'Lab/state.json was last written {:.1f} s ago (limit {:g} s).'.format( + age, self.heartbeat_timeout_s), {'written_at': app['written_at'], + 'instance_id': app['instance']['id']}) + return app + + def console_state(self) -> Dict[str, Any]: + observed_at = timestamps.format(self.now()) + try: + app = self.app_state() + except Unavailable as e: + doc = {'schema': 1, 'console': self.console, 'observed_at': observed_at, + 'availability': {'state': 'unavailable', 'reason': e.reason}, + 'app': None, 'lease': free_lease(), 'blocked': [_app_unavailable(e)]} + return contracts.validate('console_state', doc).data + lease = reported_lease(app) + doc = {'schema': 1, 'console': self.console, 'observed_at': observed_at, + 'availability': {'state': 'available', 'reason': None}, + 'app': app, 'lease': lease, 'blocked': blocked(self.console, app, lease)} + return contracts.validate('console_state', doc).data + + def save_resource(self) -> Dict[str, Any]: + """`console://B/save`: the last program-authored save fact and whether it still holds. + + A save.json that exists but cannot be read raises Unavailable: it is not "no fact". + """ + if not self.save_path.exists(): + doc = {'schema': 1, 'console': self.console, 'status': 'unknown', 'reason': 'no_fact', + 'since': None, 'fact': None} + return contracts.validate('save_resource', doc).data + fact = load_strict(self.save_path, 'save_fact') + doc = {'schema': 1, 'console': self.console, 'status': 'known', 'reason': 'hooked_save', + 'since': fact['saved_at'], 'fact': fact} + try: + app = self.app_state() + 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']) + return contracts.validate('save_resource', doc).data + + +def _app_unavailable(e: Unavailable) -> Dict[str, Any]: + out = {'code': 'app_unavailable', 'message': e.message} + if e.evidence is not None: + out['evidence'] = e.evidence + return out + + +def free_lease() -> Dict[str, Any]: + return {'state': 'free', 'owner': None, 'acquired_at': None, 'expires_at': None} + + +def reported_lease(app: Dict[str, Any]) -> Dict[str, Any]: + """The lease as far as this instance's state shows it: a UI Start/Stop hands the console to + the user, with no timeout. Without the Slice 3 store a user lease from before an app restart + is not remembered.""" + transition = app['program']['last_transition'] + if transition is not None and transition['source'] == 'ui': + return {'state': 'user', 'owner': 'user', 'acquired_at': transition['at'], 'expires_at': None} + return free_lease() + + +def blocked(console: str, app: Dict[str, Any], lease: Dict[str, Any]) -> List[Dict[str, Any]]: + """The refusals a leased run_program would get right now, in the order it would check them.""" + out = [] + if lease['state'] == 'user': + transition = app['program']['last_transition'] + out.append({'code': 'console_held_by_user', 'message': + 'The user clicked {} in the app at {}; console {} is theirs until they release it.'.format( + transition['action'].capitalize(), _clock_time(transition['at']), console)}) + state = app['program']['state'] + panel = app['panel']['id'] + if state == 'no_program': + out.append({'code': 'panel_not_program', 'message': 'The selected panel is not a program.'}) + elif state in ('running', 'stopping'): + out.append({'code': 'program_running', 'message': '{} is {}.'.format(panel, state)}) + elif state == 'not_ready': + out.append({'code': 'program_not_stopped', 'message': '{} is still loading.'.format(panel)}) + if app['controller']['state'] != 'ready' and state != 'no_program': + out.append({'code': 'controller_not_ready', 'message': 'The controller is {}.'.format( + app['controller']['state'].replace('_', ' '))}) + video = app['video'] + if video['state'] != 'live': + out.append({'code': 'video_stale', 'message': 'The video is {}.'.format(video['state'])}) + elif video['signal'] in BAD_SIGNALS: + out.append({'code': 'video_bad_signal', 'message': 'The video shows {}.'.format( + video['signal'].replace('_', ' '))}) + return out diff --git a/lab/server/pa_lab/mcp_server.py b/lab/server/pa_lab/mcp_server.py new file mode 100644 index 0000000000..40b4d98d9b --- /dev/null +++ b/lab/server/pa_lab/mcp_server.py @@ -0,0 +1,397 @@ +"""The attach-only read server: MCP over Streamable HTTP on 127.0.0.1 (Slice 2 of fork #131). + +One POST endpoint, `/mcp`, answering JSON-RPC with `application/json` (no SSE stream: nothing +here pushes). Every request must carry `Authorization: Bearer `, a loopback `Host`, and no +`Origin` other than this server's own; bodies are capped. Sessions follow the spec's +`Mcp-Session-Id`. The bearer token is never logged or returned. + +Resources: `console://B/state` (console_state), `console://B/save` (save_resource). +Tools: `shot`, `ensure_game`. Nothing here presses a button, starts or stops a program, or +holds a lease: those arrive in Slices 3 and 5. +""" + +from __future__ import annotations + +import base64 +from collections import OrderedDict +import hmac +import socketserver +from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer +import json +import logging +import re +import secrets +import threading +from typing import Any, Callable, Dict, Optional, Tuple + +from pa_lab import contracts, shot, tools +from pa_lab.lab_reader import ConsoleReader, Unavailable + +LOG = logging.getLogger('pa_lab.server') + +ENDPOINT = '/mcp' +MAX_BODY_BYTES = 1 << 20 +MAX_SESSIONS = 64 +PROTOCOL_VERSIONS = ('2025-06-18', '2025-03-26') +SERVER_INFO = {'name': 'pa-lab', 'version': '0.2.0'} +RESOURCE_URI_RE = re.compile(r'^console://([A-Za-z0-9]{1,8})/(state|save)$') + +# JSON-RPC error codes +PARSE_ERROR = -32700 +INVALID_REQUEST = -32600 +METHOD_NOT_FOUND = -32601 +INVALID_PARAMS = -32602 +RESOURCE_UNAVAILABLE = -32001 +RESOURCE_NOT_FOUND = -32002 + +INSTRUCTIONS = ( + '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. Unknown observations are never success.') + +TOOL_LIST = [ + { + 'name': 'shot', + 'title': 'Console screenshot', + 'description': 'The first console frame after this call starts, with its frame_seq. Read-only; needs no lease. ' + 'Refuses on timeout, stale video or a classified bad signal.', + 'inputSchema': { + 'type': 'object', + 'properties': { + 'console': {'type': 'string', 'enum': ['B']}, + 'max_age_ms': {'type': 'integer', 'minimum': 100, 'maximum': 60000, 'default': 2000}, + 'timeout_ms': {'type': 'integer', 'minimum': 100, 'maximum': 60000, 'default': 5000}, + }, + 'required': ['console'], + 'additionalProperties': False, + }, + 'annotations': {'readOnlyHint': True, 'destructiveHint': False, 'idempotentHint': False}, + }, + { + 'name': 'ensure_game', + 'title': 'Verify the game in front', + 'description': "Checks the app's game (and screen) observations against what is expected and " + 'returns them with their age. Verification only: it never goes HOME or launches ' + 'a title. An unknown observation does not verify.', + 'inputSchema': { + 'type': 'object', + 'properties': { + 'console': {'type': 'string', 'enum': ['B']}, + 'expected': {'type': 'string', 'description': "game id, e.g. 'PokemonFRLG'"}, + 'allowed_screens': {'type': 'array', 'items': {'type': 'string'}, 'minItems': 1}, + 'max_age_ms': {'type': 'integer', 'minimum': 100, 'maximum': 600000, 'default': 5000}, + }, + 'required': ['console', 'expected'], + 'additionalProperties': False, + }, + 'annotations': {'readOnlyHint': True, 'destructiveHint': False, 'idempotentHint': True}, + }, +] + + +class RpcError(Exception): + def __init__(self, code: int, message: str, data: Any = None): + super().__init__(message) + self.code = code + self.message = message + self.data = data + + +def refusal_doc(tool: str, refusal: Dict[str, Any]) -> Dict[str, Any]: + return contracts.validate('refusal', {'schema': 1, 'request_id': None, 'tool': tool, + 'refusal': refusal}).data + + +def _json_text(value: Any) -> str: + return json.dumps(value, indent=2, ensure_ascii=False) + + +class LabMcp: + """JSON-RPC methods, without the transport. `consoles` is the allowlist: console id -> reader.""" + + def __init__(self, consoles: Dict[str, ConsoleReader], + take_shot: Callable[..., Dict[str, Any]] = shot.take_shot): + self.consoles = consoles + self.take_shot = take_shot + + def call(self, method: str, params: Dict[str, Any]) -> Dict[str, Any]: + if method == 'ping': + return {} + if method == 'resources/list': + return {'resources': [r for c in sorted(self.consoles) for r in self._resources(c)]} + if method == 'resources/templates/list': + return {'resourceTemplates': []} + if method == 'resources/read': + return self._read_resource(params.get('uri')) + if method == 'tools/list': + return {'tools': TOOL_LIST} + if method == 'tools/call': + return self._call_tool(params.get('name'), params.get('arguments', {})) + raise RpcError(METHOD_NOT_FOUND, 'method not found: {}'.format(method)) + + @staticmethod + def initialize_result(params: Dict[str, Any]) -> Dict[str, Any]: + asked = params.get('protocolVersion') + version = asked if asked in PROTOCOL_VERSIONS else PROTOCOL_VERSIONS[0] + return {'protocolVersion': version, 'capabilities': {'resources': {}, 'tools': {}}, + 'serverInfo': SERVER_INFO, 'instructions': INSTRUCTIONS} + + @staticmethod + def _resources(console: str): + return [ + {'uri': 'console://{}/state'.format(console), 'name': 'console-{}-state'.format(console), + 'title': 'Console {} state'.format(console), 'mimeType': 'application/json', + 'description': "The app's Lab/state.json with availability, the reported lease and what " + 'blocks a run.'}, + {'uri': 'console://{}/save'.format(console), 'name': 'console-{}-save'.format(console), + 'title': 'Console {} save'.format(console), 'mimeType': 'application/json', + 'description': 'The last program-authored save fact: known, stale or unknown.'}, + ] + + def _console(self, console: Any) -> Optional[ConsoleReader]: + # An id is looked up in the allowlist, never turned into a path. + return self.consoles.get(console) if isinstance(console, str) else None + + def _read_resource(self, uri: Any) -> Dict[str, Any]: + match = RESOURCE_URI_RE.match(uri) if isinstance(uri, str) else None + if match is None: + raise RpcError(RESOURCE_NOT_FOUND, 'Resource not found', {'uri': uri}) + reader = self._console(match.group(1)) + if reader is None: + raise RpcError(RESOURCE_NOT_FOUND, 'Resource not found', { + 'uri': uri, 'refusal': {'code': 'console_not_allowed', + 'message': 'Console {} is not served.'.format(match.group(1))}}) + if match.group(2) == 'state': + doc = reader.console_state() + else: + try: + doc = reader.save_resource() + except Unavailable as e: + raise RpcError(RESOURCE_UNAVAILABLE, e.message, {'uri': uri, 'refusal': e.refusal()}) + return {'contents': [{'uri': uri, 'mimeType': 'application/json', 'text': _json_text(doc)}]} + + def _call_tool(self, name: Any, arguments: Any) -> Dict[str, Any]: + if name not in ('shot', 'ensure_game'): + raise RpcError(INVALID_PARAMS, 'Unknown tool: {}'.format(name)) + if not isinstance(arguments, dict): + return self._refused(name, {'code': 'invalid_arguments', 'field': 'arguments', + 'message': 'expected an object'}) + reader = self._console(arguments.get('console')) + if reader is None: + return self._refused(name, {'code': 'console_not_allowed', 'message': + 'Console {!r} is not served; only {}.'.format( + arguments.get('console'), ', '.join(sorted(self.consoles)))}) + try: + if name == 'ensure_game': + result = tools.ensure_game(reader, arguments) + return {'content': [{'type': 'text', 'text': _json_text(result)}], + 'structuredContent': result, 'isError': not result['verified']} + result = self.take_shot(reader, arguments) + except tools.InvalidArguments as e: + return self._refused(name, e.refusal()) + except Unavailable as e: + return self._refused(name, e.refusal()) + except shot.Refused as e: + return self._refused(name, e.refusal) + png = result.pop('png') + return {'content': [{'type': 'image', 'data': base64.b64encode(png).decode('ascii'), + 'mimeType': 'image/png'}, + {'type': 'text', 'text': _json_text(result)}], + 'structuredContent': result, 'isError': False} + + @staticmethod + def _refused(tool: str, refusal: Dict[str, Any]) -> Dict[str, Any]: + doc = refusal_doc(tool, refusal) + return {'content': [{'type': 'text', 'text': _json_text(doc)}], 'structuredContent': doc, + 'isError': True} + + +class Sessions: + def __init__(self): + self._lock = threading.Lock() + self._clients: 'OrderedDict[str, str]' = OrderedDict() + + def open(self, client: str) -> str: + session = secrets.token_hex(16) + with self._lock: + self._clients[session] = client + while len(self._clients) > MAX_SESSIONS: + self._clients.popitem(last=False) + return session + + def client(self, session: str) -> Optional[str]: + with self._lock: + return self._clients.get(session) + + def close(self, session: str) -> bool: + with self._lock: + return self._clients.pop(session, None) is not None + + +class LabHttpServer(ThreadingHTTPServer): + daemon_threads = True + + def __init__(self, address: Tuple[str, int], token: str, mcp: LabMcp): + super().__init__(address, _Handler) + self.token = token + self.mcp = mcp + self.sessions = Sessions() + + def server_bind(self): + # HTTPServer.server_bind looks up the host's FQDN, a reverse DNS call that can hang for + # half a minute on macOS; the name is never used here. + socketserver.TCPServer.server_bind(self) + self.server_name, self.server_port = self.server_address[:2] + + def allowed_authorities(self): + port = self.server_address[1] + return ('127.0.0.1:{}'.format(port), 'localhost:{}'.format(port)) + + +class _Handler(BaseHTTPRequestHandler): + server: LabHttpServer + protocol_version = 'HTTP/1.1' + + def log_message(self, format, *args): # the default writes every request to stderr + LOG.debug('%s %s', self.address_string(), format % args) + + # ---- responses + + def _send(self, status: int, body: Optional[Dict[str, Any]] = None, + headers: Optional[Dict[str, str]] = None) -> None: + data = json.dumps(body).encode('utf-8') if body is not None else b'' + self.send_response(status) + for key, value in (headers or {}).items(): + self.send_header(key, value) + if body is not None: + self.send_header('Content-Type', 'application/json') + self.send_header('Content-Length', str(len(data))) + self.end_headers() + self.wfile.write(data) + + def _http_error(self, status: int, message: str, headers: Optional[Dict[str, str]] = None) -> None: + self._send(status, {'jsonrpc': '2.0', 'id': None, 'error': {'code': INVALID_REQUEST, 'message': message}}, + headers) + + # ---- checks every method shares + + def _gate(self) -> bool: + if self.path != ENDPOINT: + self._http_error(404, 'Not found; the endpoint is {}'.format(ENDPOINT)) + return False + authorities = self.server.allowed_authorities() + if self.headers.get('Host') not in authorities: + self._http_error(403, 'Host must be a loopback address of this server') + return False + origin = self.headers.get('Origin') + if origin is not None and origin not in ['http://' + a for a in authorities]: + self._http_error(403, 'Origin not allowed') + return False + auth = self.headers.get('Authorization', '') + given = auth[len('Bearer '):] if auth.startswith('Bearer ') else '' + if not hmac.compare_digest(given.encode('utf-8'), self.server.token.encode('utf-8')): + self._http_error(401, 'Missing or wrong bearer token', {'WWW-Authenticate': 'Bearer'}) + return False + version = self.headers.get('MCP-Protocol-Version') + if version is not None and version not in PROTOCOL_VERSIONS: + self._http_error(400, 'Unsupported MCP-Protocol-Version {}'.format(version)) + return False + return True + + def _session(self) -> Optional[Tuple[str, str]]: + session = self.headers.get('Mcp-Session-Id') + if session is None: + self._http_error(400, 'Missing Mcp-Session-Id; send initialize first') + return None + client = self.server.sessions.client(session) + if client is None: + self._http_error(404, 'Unknown or ended session') + return None + return session, client + + # ---- methods + + def do_GET(self): + if self._gate(): + self._send(405, None, {'Allow': 'POST, DELETE'}) + + def do_DELETE(self): + if not self._gate(): + return + found = self._session() + if found is not None: + self.server.sessions.close(found[0]) + self._send(200) + + def do_POST(self): + if not self._gate(): + self.close_connection = True # the body is unread; it must not parse as the next request + return + length = self.headers.get('Content-Length') + if length is None or not length.isdigit(): + self.close_connection = True + self._http_error(411, 'Content-Length required') + return + if int(length) > MAX_BODY_BYTES: + self.close_connection = True + self._http_error(413, 'Body larger than {} bytes'.format(MAX_BODY_BYTES)) + return + raw = self.rfile.read(int(length)) + if not self.headers.get('Content-Type', '').startswith('application/json'): + self._http_error(415, 'Content-Type must be application/json') + return + try: + message = json.loads(raw.decode('utf-8')) + except (UnicodeDecodeError, ValueError): + self._send(400, {'jsonrpc': '2.0', 'id': None, 'error': {'code': PARSE_ERROR, 'message': 'Parse error'}}) + return + if not isinstance(message, dict) or message.get('jsonrpc') != '2.0': + self._http_error(400, 'Expected one JSON-RPC 2.0 message (batches are not supported)') + return + if 'method' not in message: # a response from the client: nothing asked for one + self._send(202) + return + method = message['method'] + params = message.get('params') or {} + if method == 'initialize': + self._initialize(message, params) + return + found = self._session() + if found is None: + return + if 'id' not in message: # notifications (notifications/initialized, cancelled) + self._send(202) + return + if not isinstance(params, dict): + self._send(200, {'jsonrpc': '2.0', 'id': message['id'], + 'error': {'code': INVALID_PARAMS, 'message': 'params must be an object'}}) + return + LOG.info('client=%s method=%s tool=%s', found[1], method, + params.get('name') if method == 'tools/call' else '-') + try: + reply = {'jsonrpc': '2.0', 'id': message['id'], 'result': self.server.mcp.call(method, params)} + except RpcError as e: + error = {'code': e.code, 'message': e.message} + if e.data is not None: + error['data'] = e.data + reply = {'jsonrpc': '2.0', 'id': message['id'], 'error': error} + except Exception: + LOG.exception('method %s failed', method) + reply = {'jsonrpc': '2.0', 'id': message['id'], 'error': {'code': -32603, 'message': 'Internal error'}} + self._send(200, reply) + + def _initialize(self, message: Dict[str, Any], params: Any) -> None: + if 'id' not in message or not isinstance(params, dict): + self._http_error(400, 'initialize must be a request with params') + return + info = params.get('clientInfo') if isinstance(params.get('clientInfo'), dict) else {} + client = str(info.get('name') or 'unnamed')[:64] + session = self.server.sessions.open(client) + LOG.info('client=%s initialize', client) + self._send(200, {'jsonrpc': '2.0', 'id': message['id'], 'result': LabMcp.initialize_result(params)}, + {'Mcp-Session-Id': session}) + + +def make_server(port: int, token: str, consoles: Dict[str, ConsoleReader], **mcp_options) -> LabHttpServer: + """Binds 127.0.0.1 only; port 0 picks a free one (tests).""" + return LabHttpServer(('127.0.0.1', port), token, LabMcp(consoles, **mcp_options)) diff --git a/lab/server/pa_lab/shot.py b/lab/server/pa_lab/shot.py new file mode 100644 index 0000000000..c5c8c8c9db --- /dev/null +++ b/lab/server/pa_lab/shot.py @@ -0,0 +1,199 @@ +"""`shot`: the console's first frame after the call starts (Slice 2 of fork #131). + +The app's channel command `snapshot LABEL TIMEOUT_MS` (#481, Lab.md "Snapshot") waits for the +first video frame that arrives after the line starts, saves it and names it with the same +`instance.id` and `frame_seq` that `Lab/state.json` uses. It needs no owner token, program state +or controller. So: + +1. Read `Lab/state.json` at call start: the app must be up (fresh heartbeat), and its + `instance.id` is the one the reply must name. +2. Write the request `request ` / `snapshot frame ` into `Lab/inbox` at once. +3. Read the journal: `snapshot saved ...` gives the exact `frame_seq` and `captured_at`; + `snapshot timeout` and `snapshot unavailable` map to refusals. +4. Open only the PNG this call asked for, never a path read from the journal, check it is + complete, and return it. + +The request is fixed text; no caller input but the checked `timeout_ms` reaches the inbox. +""" + +from __future__ import annotations + +import os +import re +import time +import uuid +from pathlib import Path +from typing import Any, Callable, Dict, List, Optional + +from pa_lab import timestamps +from pa_lab.lab_reader import BAD_SIGNALS, ConsoleReader, Unavailable +from pa_lab.tools import InvalidArguments, check_arguments + +DEFAULT_MAX_AGE_MS = 2000 +DEFAULT_TIMEOUT_MS = 5000 +# The app reads its inbox every 500 ms and its own wait starts when the line does; the journal +# may come this long after the caller's timeout. +ANSWER_GRACE_MS = 2000 +POLL_S = 0.05 +MAX_PNG_BYTES = 32 << 20 +LABEL = 'frame' +PNG_SIGNATURE = b'\x89PNG\r\n\x1a\n' +PNG_END = b'\x00\x00\x00\x00IEND\xaeB`\x82' +JOURNAL_ERROR_RE = re.compile(r'^error \d+ \([^)]*\): (.*)$') +JOURNAL_OK_RE = re.compile(r'^ok \d+ snapshot ' + LABEL + r'\b') +SAVED_RE = re.compile(r'^snapshot saved instance=(\S+) frame_seq=(\d+) captured_at=(\S+) after=(\d+) path=(.+)$') +TIMEOUT_RE = re.compile(r'^snapshot timeout instance=(\S+) after=(\d+) timeout_ms=(\d+)$') +UNAVAILABLE_RE = re.compile(r'^snapshot unavailable instance=(\S+) reason=(\S+)$') +# `snapshot unavailable` reasons the app has no frame for; the rest mean the app could not serve. +APP_REASONS = ('panel_changed', 'app_closing', 'save_failed') + +__all__ = ['take_shot', 'Refused', 'InvalidArguments'] + + +class Refused(Exception): + def __init__(self, code: str, message: str, evidence: Optional[Dict[str, Any]] = None): + super().__init__(message) + self.refusal: Dict[str, Any] = {'code': code, 'message': message} + if evidence is not None: + self.refusal['evidence'] = evidence + + +def _check_start(app: Dict[str, Any]) -> None: + signal = app['video']['signal'] + if signal in BAD_SIGNALS: + raise Refused('video_bad_signal', 'The video shows {}.'.format(signal.replace('_', ' '))) + + +def _write_request(lab_dir: Path, name: str, request_id: str, timeout_ms: int) -> Path: + part = lab_dir / 'outbox' / (name + '.part') + inbox = lab_dir / 'inbox' / (name + '.txt') + part.write_text('request {}\nsnapshot {} {}\n'.format(request_id, LABEL, timeout_ms), encoding='utf-8') + os.replace(part, inbox) + return inbox + + +def _withdraw(inbox: Path) -> None: + try: + os.remove(inbox) + except FileNotFoundError: + pass + + +def _wait_for_journal(console: ConsoleReader, sleep: Callable[[float], None], deadline: float, + lab_dir: Path, name: str, inbox: Path) -> List[str]: + journal = lab_dir / 'outbox' / (name + '.out') + while True: + if journal.exists(): + lines = journal.read_text(encoding='utf-8', errors='replace').splitlines() + if lines and lines[-1] == 'end': # the app may still be writing it + return lines + if console.now() >= deadline: + break + sleep(POLL_S) + _withdraw(inbox) + raise Refused('timeout', 'The app did not answer the snapshot request in time (busy with another ' + 'request?).', {'request': name}) + + +def _check_instance(reply_instance: str, instance_id: str) -> None: + if reply_instance != instance_id: + raise Refused('app_unavailable', 'The app restarted during the call; its frames are not ' + 'comparable with the old instance.', { + 'reason': 'instance_replaced', 'instance_id': instance_id, + 'new_instance_id': reply_instance}) + + +def _refuse_failed_reply(lines: List[str], instance_id: str) -> None: + """Raises the refusal for a `snapshot timeout` or `snapshot unavailable` line, if any.""" + for line in lines: + match = TIMEOUT_RE.match(line) + if match: + _check_instance(match.group(1), instance_id) + after = int(match.group(2)) + raise Refused('timeout', 'No frame newer than seq {} within {} ms.'.format(after, match.group(3)), + {'instance_id': instance_id, 'frame_seq': after}) + match = UNAVAILABLE_RE.match(line) + if match: + _check_instance(match.group(1), instance_id) + reason = match.group(2) + if reason == 'no_video': + raise Refused('video_stale', 'The selected panel has no video.', + {'instance_id': instance_id, 'reason': reason}) + if reason in APP_REASONS: + raise Refused('app_unavailable', 'The app could not save a frame ({}).'.format( + reason.replace('_', ' ')), {'instance_id': instance_id, 'reason': reason}) + raise Refused('app_unavailable', 'The app gave an unknown snapshot reason {!r}.'.format(reason), + {'instance_id': instance_id, 'reason': 'unknown', 'journal': lines}) + + +def _parse_saved(lines: List[str], instance_id: str, expected: Path) -> Dict[str, Any]: + _refuse_failed_reply(lines, instance_id) + for line in lines: + match = JOURNAL_ERROR_RE.match(line) + if match: + raise Refused('app_unavailable', "The app's snapshot line failed: {}".format(match.group(1)), + {'journal': lines}) + saved = [m for m in (SAVED_RE.match(line) for line in lines) if m] + if len(saved) != 1 or not any(JOURNAL_OK_RE.match(line) for line in lines): + raise Refused('app_unavailable', 'The snapshot journal has no single saved line and ok line.', + {'journal': lines}) + match = saved[0] + _check_instance(match.group(1), instance_id) + frame_seq, after = int(match.group(2)), int(match.group(4)) + try: + timestamps.parse(match.group(3)) + except ValueError: + raise Refused('app_unavailable', 'The snapshot names a bad capture time.', {'journal': lines}) + # The journal's path is compared by name only; the file opened is the one this call asked for. + if frame_seq <= after or Path(match.group(5)).name != expected.name: + raise Refused('app_unavailable', 'The snapshot line does not match this request.', {'journal': lines}) + return {'frame_seq': frame_seq, 'captured_at': match.group(3)} + + +def _read_png(path: Path) -> bytes: + try: + with open(path, 'rb') as f: + data = f.read(MAX_PNG_BYTES + 1) + except OSError as e: + raise Refused('app_unavailable', 'The saved snapshot cannot be read: {}.'.format(e.strerror)) + if len(data) > MAX_PNG_BYTES or not data.startswith(PNG_SIGNATURE) or not data.endswith(PNG_END): + raise Refused('app_unavailable', 'The saved snapshot is not a complete PNG ({} bytes).'.format(len(data))) + return data + + +def take_shot(console: ConsoleReader, arguments: Dict[str, Any], + sleep: Callable[[float], None] = time.sleep, + new_uuid: Callable[[], uuid.UUID] = uuid.uuid4) -> Dict[str, Any]: + """Raises InvalidArguments or Refused (with a contract refusal object).""" + args = check_arguments('shot', arguments) + max_age_ms = args.get('max_age_ms', DEFAULT_MAX_AGE_MS) + timeout_ms = args.get('timeout_ms', DEFAULT_TIMEOUT_MS) + started = console.now() + try: + app = console.app_state() + except Unavailable as e: + raise Refused(e.refusal()['code'], e.message, e.evidence) + _check_start(app) + instance_id = app['instance']['id'] + + request_id = str(new_uuid()) + name = 'palab_shot_' + request_id.replace('-', '') + inbox = _write_request(console.lab_dir, name, request_id, timeout_ms) + deadline = started + (timeout_ms + ANSWER_GRACE_MS) / 1000.0 + lines = _wait_for_journal(console, sleep, deadline, console.lab_dir, name, inbox) + png_path = console.lab_dir / 'outbox' / '{}_{}.png'.format(name, LABEL) + frame = _parse_saved(lines, instance_id, png_path) + age_ms = int(round((console.now() - timestamps.parse(frame['captured_at'])) * 1000)) + if age_ms > max_age_ms: + raise Refused('video_stale', 'The saved frame is {} ms old (max_age_ms {}).'.format(age_ms, max_age_ms), + dict(frame, instance_id=instance_id)) + return { + 'console': console.console, + 'path': str(png_path), + 'png': _read_png(png_path), + 'instance_id': instance_id, + 'frame_seq': frame['frame_seq'], + 'captured_at': frame['captured_at'], + 'call_started_at': timestamps.format(started), + 'request': name, + } diff --git a/lab/server/pa_lab/timestamps.py b/lab/server/pa_lab/timestamps.py new file mode 100644 index 0000000000..700af55176 --- /dev/null +++ b/lab/server/pa_lab/timestamps.py @@ -0,0 +1,24 @@ +"""The contract's UTC timestamps (`2026-11-14T06:10:12.124Z`) to and from epoch seconds.""" + +from __future__ import annotations + +import calendar +import datetime +import time + +FORMAT = '%Y-%m-%dT%H:%M:%S.%fZ' + + +def parse(text: str) -> float: + moment = datetime.datetime.strptime(text, FORMAT) + return calendar.timegm(moment.timetuple()) + moment.microsecond / 1e6 + + +def format(epoch: float) -> str: + millis = int(round(epoch * 1000)) + moment = datetime.datetime.utcfromtimestamp(millis // 1000) + return moment.strftime('%Y-%m-%dT%H:%M:%S') + '.{:03d}Z'.format(millis % 1000) + + +def wall_clock() -> float: + return time.time() diff --git a/lab/server/pa_lab/tools.py b/lab/server/pa_lab/tools.py new file mode 100644 index 0000000000..21c81f22f5 --- /dev/null +++ b/lab/server/pa_lab/tools.py @@ -0,0 +1,98 @@ +"""The read-only tools of Slice 2 (fork #131): argument checks and `ensure_game`. + +`shot` lives in pa_lab/shot.py. No tool here presses a button, starts or stops a program, or +changes what the app shows; mutating tools arrive with leases (Slices 3 and 5). +""" + +from __future__ import annotations + +from typing import Any, Dict, Optional + +from pa_lab import contracts, timestamps +from pa_lab.contracts import F, Int, ListOf, Obj, Str +from pa_lab.lab_reader import ConsoleReader + +ENSURE_GAME_DEFAULT_MAX_AGE_MS = 5000 + +ARGUMENTS: Dict[str, Obj] = { + 'shot': Obj([ + F('console', Str()), + F('max_age_ms', Int(minimum=100, maximum=60000), required=False, doc='default 2000'), + F('timeout_ms', Int(minimum=100, maximum=60000), required=False, doc='default 5000'), + ], open=False), + 'ensure_game': Obj([ + F('console', Str()), + F('expected', Str(contracts.GAME_ID_RE, 'game id'), doc="e.g. 'PokemonFRLG'"), + F('allowed_screens', ListOf(Str(contracts.GAME_ID_RE, 'screen id'), min_items=1, max_items=32), + required=False), + F('max_age_ms', Int(minimum=100, maximum=600000), required=False, doc='default 5000'), + ], open=False), +} + + +class InvalidArguments(Exception): + def __init__(self, field: str, message: str): + super().__init__('{}: {}'.format(field, message)) + self.field = field + self.message = message + + def refusal(self) -> Dict[str, Any]: + return {'code': 'invalid_arguments', 'field': self.field, 'message': self.message} + + +def check_arguments(tool: str, arguments: Any) -> Dict[str, Any]: + """Closed argument objects: an unknown key is refused, as for every request (README).""" + if not isinstance(arguments, dict): + raise InvalidArguments('arguments', 'expected an object') + try: + return contracts.check_object(ARGUMENTS[tool], arguments) + except contracts.ContractError as e: + first = e.errors[0] + raise InvalidArguments(first.path, first.message) from None + + +def _age_ms(observation: Dict[str, Any], now: float) -> Optional[int]: + if observation['observed_at'] is None: + return None + return int(round((now - timestamps.parse(observation['observed_at'])) * 1000)) + + +def ensure_game(console: ConsoleReader, arguments: Dict[str, Any]) -> Dict[str, Any]: + """Verifies, from the app's own observations, that the expected game (and one of the allowed + screens) is in front. Never navigates HOME or launches a title. `unknown` never verifies. + + Raises InvalidArguments, or lab_reader.Unavailable when the app state cannot be trusted. + """ + args = check_arguments('ensure_game', dict(arguments, console=arguments.get('console', console.console))) + max_age_ms = args.get('max_age_ms', ENSURE_GAME_DEFAULT_MAX_AGE_MS) + app = console.app_state() + now = console.now() + game = app['observation']['game'] + screen = app['observation']['screen'] + game_age = _age_ms(game, now) + reason = None + if game['value'] == contracts.UNKNOWN: + reason = 'game_unknown' + elif game_age > max_age_ms: + reason = 'observation_stale' + elif game['value'] != args['expected']: + reason = 'game_mismatch' + elif 'allowed_screens' in args: + screen_age = _age_ms(screen, now) + if screen['value'] == contracts.UNKNOWN: + reason = 'screen_unknown' + elif screen_age > max_age_ms: + reason = 'observation_stale' + elif screen['value'] not in args['allowed_screens']: + reason = 'screen_not_allowed' + return { + 'console': console.console, + 'verified': reason is None, + 'reason': reason, + 'expected': args['expected'], + 'instance_id': app['instance']['id'], + 'game': game, + 'game_age_ms': game_age, + 'screen': screen, + 'screen_age_ms': _age_ms(screen, now), + } diff --git a/lab/server/tests/fake_lab.py b/lab/server/tests/fake_lab.py new file mode 100644 index 0000000000..72c72ea900 --- /dev/null +++ b/lab/server/tests/fake_lab.py @@ -0,0 +1,168 @@ +"""A fake lab-B profile folder for the Slice 2 tests: what the app writes into `Lab/`, by hand. + +Everything lives in a temp dir; nothing here touches a real profile or console. +""" + +import copy +import json +import os +from pathlib import Path +import tempfile + +from pa_lab import timestamps + +FIXTURES = Path(__file__).resolve().parent.parent / 'contracts' / 'v1' + + +def golden(kind, name): + return json.loads((FIXTURES / kind / (name + '.json')).read_text(encoding='utf-8')) + + +class FakeClock: + """Epoch seconds the test moves by hand; `sleep` advances it instead of waiting.""" + + def __init__(self, at): + self.t = timestamps.parse(at) + self.on_sleep = [] + + def now(self): + return self.t + + def sleep(self, seconds): + self.t += seconds + for hook in list(self.on_sleep): + hook() + + +class FakeLab: + def __init__(self, test): + self._tmp = tempfile.TemporaryDirectory(prefix='pa-lab-test-') + test.addCleanup(self._tmp.cleanup) + self.dir = Path(self._tmp.name) / 'Lab' + for sub in ('inbox', 'outbox', 'done'): + (self.dir / sub).mkdir(parents=True) + self.state = None + + @property + def state_path(self): + return self.dir / 'state.json' + + @property + def save_path(self): + return self.dir / 'save.json' + + def write_state(self, doc): + """Atomic, as the app does: write beside, then rename.""" + self.state = copy.deepcopy(doc) + self._atomic(self.state_path, json.dumps(doc, indent=2) + '\n') + + def write_save(self, doc): + self._atomic(self.save_path, json.dumps(doc, indent=2) + '\n') + + def write_raw(self, path, text): + """A torn or hand-made file: written in place, not atomically.""" + Path(path).write_text(text, encoding='utf-8') + + def update_state(self, **changes): + """Rewrite state.json with dotted-path changes: update_state(**{'video.frame_seq': 5}).""" + doc = copy.deepcopy(self.state) + for dotted, value in changes.items(): + node = doc + keys = dotted.split('.') + for key in keys[:-1]: + node = node[key] + node[keys[-1]] = value + self.write_state(doc) + + @staticmethod + def _atomic(path, text): + tmp = path.with_name(path.name + '.tmp') + tmp.write_text(text, encoding='utf-8') + os.replace(tmp, path) + + +PNG = b'\x89PNG\r\n\x1a\n' + b'\x00\x00\x00\rIHDR' + b'\x00' * 17 + b'\x00\x00\x00\x00IEND\xaeB`\x82' + + +class FakeApp: + """The app's side of the channel, run on each FakeClock.sleep: a new frame per tick, a fresh + heartbeat, and the inbox's `snapshot LABEL TIMEOUT_MS` requests answered as LabChannel does + (Lab.md "Snapshot"): the request moves to done/, and the first frame newer than the line's + start is saved as `_