Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 26 additions & 1 deletion lab/server/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,8 +19,10 @@ tickets and events in SQLite. Nothing presses a button yet: that is Slice 5.
| `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 |
| `pa_lab/app_query.py` | `describe_program` and `game_open`: one-line reads through the app's channel (#504) |
| `tests/fake_lab.py` | A fake `Lab/` folder and a fake app answering `snapshot`, `describe_program` and `game_open` requests, in temp dirs |
| `tests/test_{lab_reader,ensure_game,shot,config,mcp_server}.py` | Slice 2's fake-lab tests |
| `tests/test_app_query.py` | `describe_program` and `game_open` against the fake app |
| `pa_lab/db.py` | The SQLite file: migrations (`PRAGMA user_version`), owner-only file, `BEGIN IMMEDIATE` writes |
| `pa_lab/control.py` | Leases, idempotent requests, tickets, events, `next_events`, reconciliation, compaction |
| `tests/test_{db,control,control_concurrency,control_mcp}.py` | Slice 3's tests: restarts, threads and processes racing, kills mid-write |
Expand Down Expand Up @@ -189,6 +191,29 @@ or the saved frame is older than `max_age_ms`), `video_bad_signal`, `app_unavail
from another instance: `evidence.reason` `instance_replaced`; `panel_changed`, `app_closing`,
`save_failed` as `evidence.reason`; a line error or an incomplete PNG).

**`describe_program(console)`** and **`game_open(console)`** send the app's channel commands of
the same names (#504, `Lab.md` "Describe program" and "Screen"); both read only and need no
lease, owner token or program state. Each reads `state.json` (the app is up; its `instance.id`),
writes the fixed request `request <uuid>` / `<command>` into `Lab/inbox` as `shot` does, waits
up to 5 s + 2 s for the journal, and reads `state.json` again. Arguments are closed: only
`console` (no `game_open image`).

- `describe_program` parses `describe_program <JSON>` and returns it as `program`:
`{"id", "options", "prechecks", "schema": 1}` (the option entries as the app prints them) with
`prechecks_supported`. `prechecks` is the string `unsupported` until the program declares a
list (#485); that is a valid reply, not an error. A list is passed through.
- `game_open` parses `game_open yes` / `game_open no REASON` and returns `open` and `reason`
(`null`, `home`, `user_select`, `black` or `no_video`). `open: false` is an answer, not a tool
error; it does not tell one game from another (`ensure_game` does).

| What the daemon finds | Refusal |
|---|---|
| `describe_program: the selected panel is not a program.` | `panel_not_program` |
| `schema` other than 1 | `unsupported_schema` |
| a failed line, no single reply line and `ok` line, bad JSON, a missing `id`/`options`/`prechecks`, an unknown `game_open` reason | `app_unavailable` (the journal in `evidence`) |
| a reply from another instance | `app_unavailable`, `evidence.reason` `instance_replaced` |
| no journal within 7 s | `timeout`; the request is withdrawn from the inbox |

## Slice 3: the durable control plane

SQLite (`db_file` in the config, default `~/.local/state/pa-lab/control.sqlite`, created `0600`)
Expand Down
156 changes: 156 additions & 0 deletions lab/server/pa_lab/app_query.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,156 @@
"""`describe_program` and `game_open`: one-line reads through the app's channel (Slice 4, fork #131).

Both are app commands from #504 (Lab.md "Describe program" and "Screen") that need no owner
token, no program state and no lease:

- `describe_program` prints `describe_program <JSON>`, the selected program's id and the static
contract of its options: `{"id", "options", "prechecks", "schema": 1}`. `prechecks` is the
string `unsupported` until the program declares a precheck list (#485); a list after that.
- `game_open` prints `game_open yes`, or `game_open no REASON` with REASON `home`,
`user_select`, `black` or `no_video`. It never fails the line and does not tell one game from
another.

Each call reads `Lab/state.json` (the app is up; its `instance.id`), writes a fixed request into
`Lab/inbox` the way `shot` does, reads the journal, and reads `state.json` again: a reply that
spans an app restart is refused. No caller input reaches the inbox.
"""

from __future__ import annotations

import json
import re
import time
import uuid
from typing import Any, Callable, Dict, List

from pa_lab import shot
from pa_lab.lab_reader import ConsoleReader, Unavailable
from pa_lab.shot import Refused
from pa_lab.tools import check_arguments

QUERY_TIMEOUT_MS = 5000
GAME_OPEN_REASONS = ('home', 'user_select', 'black', 'no_video')
PROGRAM_SCHEMA = 1
PRECHECKS_UNSUPPORTED = 'unsupported'
NOT_A_PROGRAM = 'the selected panel is not a program'

JOURNAL_ERROR_RE = re.compile(r'^error \d+ \([^)]*\): (.*)$')
DESCRIBE_RE = re.compile(r'^describe_program (\{.*\})$')
GAME_OPEN_RE = re.compile(r'^game_open (yes|no(?: (\S+))?)$')

__all__ = ['describe_program', 'game_open', 'Refused']


def _instance_id(console: ConsoleReader) -> str:
try:
return console.app_state()['instance']['id']
except Unavailable as e:
raise Refused(e.refusal()['code'], e.message, e.evidence)


def _ask(console: ConsoleReader, command: str, sleep: Callable[[float], None],
new_uuid: Callable[[], uuid.UUID]) -> Dict[str, Any]:
"""Sends `command` (fixed text) and returns the journal's lines, the instance and the request."""
started = console.now()
instance_id = _instance_id(console)
request_id = str(new_uuid())
name = 'palab_{}_{}'.format(command, request_id.replace('-', ''))
inbox = shot.write_request(console.lab_dir, name, request_id, command)
deadline = started + (QUERY_TIMEOUT_MS + shot.ANSWER_GRACE_MS) / 1000.0
lines = shot.wait_for_journal(console, sleep, deadline, console.lab_dir, name, inbox, command)
after = _instance_id(console)
if after != instance_id:
raise Refused('app_unavailable', 'The app restarted during the call.', {
'reason': 'instance_replaced', 'instance_id': instance_id, 'new_instance_id': after})
return {'lines': lines, 'instance_id': instance_id, 'request': name}


def _line_error(lines: List[str]):
for line in lines:
match = JOURNAL_ERROR_RE.match(line)
if match:
return match.group(1)
return None


def _one_reply(lines: List[str], pattern: 're.Pattern[str]', command: str):
"""The single printed reply line, after an `ok N <command>` line."""
ok_re = re.compile(r'^ok \d+ ' + command + r'\b')
replies = [m for m in (pattern.match(line) for line in lines) if m]
if len(replies) != 1 or not any(ok_re.match(line) for line in lines):
raise Refused('app_unavailable', 'The {} journal has no single reply line and ok line.'.format(command),
{'journal': lines})
return replies[0]


def _check_contract(doc: Any, lines: List[str]) -> Dict[str, Any]:
if not isinstance(doc, dict):
raise Refused('app_unavailable', 'describe_program did not print a JSON object.', {'journal': lines})
if doc.get('schema') != PROGRAM_SCHEMA:
raise Refused('unsupported_schema', 'describe_program schema {!r}; this daemon reads {}.'.format(
doc.get('schema'), PROGRAM_SCHEMA), {'schema': doc.get('schema')})
problems = []
if not isinstance(doc.get('id'), str) or not doc['id']:
problems.append('id')
if not isinstance(doc.get('options'), list) or not all(isinstance(o, dict) for o in doc['options']):
problems.append('options')
prechecks = doc.get('prechecks')
if prechecks != PRECHECKS_UNSUPPORTED and not isinstance(prechecks, list):
problems.append('prechecks')
if problems:
raise Refused('app_unavailable', 'describe_program printed a bad {}.'.format(', '.join(problems)),
{'journal': lines})
return doc


def describe_program(console: ConsoleReader, arguments: Dict[str, Any],
sleep: Callable[[float], None] = time.sleep,
new_uuid: Callable[[], uuid.UUID] = uuid.uuid4) -> Dict[str, Any]:
"""The selected program's id and option contract. Raises InvalidArguments or Refused."""
check_arguments('describe_program', arguments)
reply = _ask(console, 'describe_program', sleep, new_uuid)
lines = reply['lines']
error = _line_error(lines)
if error is not None:
if NOT_A_PROGRAM in error:
raise Refused('panel_not_program', 'The selected panel is not a program.', {'journal': lines})
raise Refused('app_unavailable', "The app's describe_program line failed: {}".format(error),
{'journal': lines})
match = _one_reply(lines, DESCRIBE_RE, 'describe_program')
try:
doc = json.loads(match.group(1))
except ValueError:
raise Refused('app_unavailable', 'describe_program printed invalid JSON.', {'journal': lines}) from None
program = _check_contract(doc, lines)
return {
'console': console.console,
'instance_id': reply['instance_id'],
'program': program,
'prechecks_supported': program['prechecks'] != PRECHECKS_UNSUPPORTED,
'request': reply['request'],
}


def game_open(console: ConsoleReader, arguments: Dict[str, Any],
sleep: Callable[[float], None] = time.sleep,
new_uuid: Callable[[], uuid.UUID] = uuid.uuid4) -> Dict[str, Any]:
"""Whether a game is in front (`open`), and why not (`reason`). Raises InvalidArguments or Refused."""
check_arguments('game_open', arguments)
reply = _ask(console, 'game_open', sleep, new_uuid)
lines = reply['lines']
error = _line_error(lines)
if error is not None:
raise Refused('app_unavailable', "The app's game_open line failed: {}".format(error), {'journal': lines})
match = _one_reply(lines, GAME_OPEN_RE, 'game_open')
is_open = match.group(1) == 'yes'
reason = match.group(2)
if not is_open and reason not in GAME_OPEN_REASONS:
raise Refused('app_unavailable', 'The app gave an unknown game_open reason {!r}.'.format(reason),
{'journal': lines})
return {
'console': console.console,
'instance_id': reply['instance_id'],
'open': is_open,
'reason': reason,
'request': reply['request'],
}
44 changes: 40 additions & 4 deletions lab/server/pa_lab/mcp_server.py
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
`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`; with a control plane also `acquire_console`,
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.
"""
Expand All @@ -25,7 +25,7 @@
import threading
from typing import Any, Callable, Dict, Optional, Tuple

from pa_lab import contracts, control, shot, tools
from pa_lab import app_query, contracts, control, shot, tools
from pa_lab.lab_reader import ConsoleReader, Unavailable

LOG = logging.getLogger('pa_lab.server')
Expand All @@ -48,7 +48,8 @@
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.')
'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.')

TOOL_LIST = [
{
Expand Down Expand Up @@ -87,8 +88,39 @@
},
'annotations': {'readOnlyHint': True, 'destructiveHint': False, 'idempotentHint': True},
},
{
'name': 'describe_program',
'title': "The selected program's option contract",
'description': "The selected program's id and the static contract of its options (keys, types, "
'defaults, bounds, enum entries) and its prechecks (the string "unsupported" until the '
'program declares them). Read-only; needs no lease. Refuses when the selected panel is '
'not a program.',
'inputSchema': {
'type': 'object',
'properties': {'console': {'type': 'string', 'enum': ['B']}},
'required': ['console'],
'additionalProperties': False,
},
'annotations': {'readOnlyHint': True, 'destructiveHint': False, 'idempotentHint': True},
},
{
'name': 'game_open',
'title': 'Is a game in front',
'description': 'Whether a game is in front of the console now: open true, or open false with reason '
'home, user_select, black (loading or no signal) or no_video. It does not tell one game '
'from another; use ensure_game for that. Read-only; needs no lease.',
'inputSchema': {
'type': 'object',
'properties': {'console': {'type': 'string', 'enum': ['B']}},
'required': ['console'],
'additionalProperties': False,
},
'annotations': {'readOnlyHint': True, 'destructiveHint': False, 'idempotentHint': False},
},
]

APP_QUERIES = {'describe_program': app_query.describe_program, 'game_open': app_query.game_open}


_REQUEST_ID = {'type': 'string', 'description': 'client-generated lower-case UUID; a retry reuses it'}
_LEASE_TOKEN = {'type': 'string', 'description': 'the token acquire_console returned'}
Expand Down Expand Up @@ -220,7 +252,7 @@ def _read_resource(self, uri: Any) -> Dict[str, Any]:
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'):
if name not in ('shot', 'ensure_game') and name not in APP_QUERIES:
raise RpcError(INVALID_PARAMS, 'Unknown tool: {}'.format(name))
if not isinstance(arguments, dict):
return self._refused(name, {'code': 'invalid_arguments', 'field': 'arguments',
Expand All @@ -235,6 +267,10 @@ def _call_tool(self, name: Any, arguments: Any) -> Dict[str, Any]:
result = tools.ensure_game(reader, arguments)
return {'content': [{'type': 'text', 'text': _json_text(result)}],
'structuredContent': result, 'isError': not result['verified']}
if name in APP_QUERIES:
result = APP_QUERIES[name](reader, arguments)
return {'content': [{'type': 'text', 'text': _json_text(result)}],
'structuredContent': result, 'isError': False}
result = self.take_shot(reader, arguments)
except tools.InvalidArguments as e:
return self._refused(name, e.refusal())
Expand Down
17 changes: 9 additions & 8 deletions lab/server/pa_lab/shot.py
Original file line number Diff line number Diff line change
Expand Up @@ -68,10 +68,11 @@ def _check_start(app: Dict[str, Any]) -> None:
# app writes after its next 500 ms poll. A local socket is the likely replacement if poll latency
# or missed events become a measured problem; the alternatives are in lab/tooling's
# docs/design/Agent-Integration.md, "Transport: now and later".
def _write_request(lab_dir: Path, name: str, request_id: str, timeout_ms: int) -> Path:
def write_request(lab_dir: Path, name: str, request_id: str, line: str) -> Path:
"""`line` is fixed text built by the daemon; no caller string reaches the inbox."""
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')
part.write_text('request {}\n{}\n'.format(request_id, line), encoding='utf-8')
os.replace(part, inbox)
return inbox

Expand All @@ -83,8 +84,8 @@ def _withdraw(inbox: Path) -> None:
pass


def _wait_for_journal(console: ConsoleReader, sleep: Callable[[float], None], deadline: float,
lab_dir: Path, name: str, inbox: Path) -> List[str]:
def wait_for_journal(console: ConsoleReader, sleep: Callable[[float], None], deadline: float,
lab_dir: Path, name: str, inbox: Path, command: str = 'snapshot') -> List[str]:
journal = lab_dir / 'outbox' / (name + '.out')
while True:
if journal.exists():
Expand All @@ -95,8 +96,8 @@ def _wait_for_journal(console: ConsoleReader, sleep: Callable[[float], None], de
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})
raise Refused('timeout', 'The app did not answer the {} request in time (busy with another '
'request?).'.format(command), {'request': name})


def _check_instance(reply_instance: str, instance_id: str) -> None:
Expand Down Expand Up @@ -182,9 +183,9 @@ def take_shot(console: ConsoleReader, arguments: Dict[str, Any],

request_id = str(new_uuid())
name = 'palab_shot_' + request_id.replace('-', '')
inbox = _write_request(console.lab_dir, name, request_id, timeout_ms)
inbox = write_request(console.lab_dir, name, request_id, 'snapshot {} {}'.format(LABEL, timeout_ms))
deadline = started + (timeout_ms + ANSWER_GRACE_MS) / 1000.0
lines = _wait_for_journal(console, sleep, deadline, console.lab_dir, name, inbox)
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))
Expand Down
4 changes: 3 additions & 1 deletion lab/server/pa_lab/tools.py
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
"""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
`shot` lives in pa_lab/shot.py; `describe_program` and `game_open` in pa_lab/app_query.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).
"""

Expand All @@ -27,6 +27,8 @@
required=False),
F('max_age_ms', Int(minimum=100, maximum=600000), required=False, doc='default 5000'),
], open=False),
'describe_program': Obj([F('console', Str())], open=False),
'game_open': Obj([F('console', Str())], open=False),
}


Expand Down
Loading
Loading