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: 27 additions & 0 deletions lab/server/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,8 @@ 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/status.py`, `pa_lab/stdio_server.py`, `smoke_readonly.py` | Read-only stdio mode for `.mcp.json`: `console_status` ([below](#read-only-stdio-mode-mcpjson)) |
| `tests/test_status_readonly.py` | `console_status` and the read-only gate against a fake profile |

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:
Expand Down Expand Up @@ -218,6 +220,31 @@ up to 5 s + 2 s for the journal, and reads `state.json` again. Arguments are clo
| a reply from another instance | `app_unavailable`, `evidence.reason` `instance_replaced` |
| no journal within 7 s | `timeout`; the request is withdrawn from the inbox |

## Read-only stdio mode (`.mcp.json`)

`python -m pa_lab serve-stdio --profile-dir <profile>` serves MCP over stdio for a Claude Code
`.mcp.json` entry: no port, token or daemon. It is read-only by construction (`LabMcp(read_only=True)`):
the `console://B/state` and `/save` resources and one tool, `console_status`
(`pa_lab/status.py`), which reports what `~/BDSPLab/checkin.sh` does: the app's pid and deployment,
the legacy `Lab/state` fields (owner token dropped), `console://B/state`, the last `Program State:`
and run lines, the last press, the last `keepawake.log` line, the newest failure frame and
screenshot paths and the last log lines. `shot`, `describe_program`, `game_open` (they write into
`Lab/inbox`) and every control tool are neither listed nor callable. `serve --read-only` gives the
same tool set over HTTP.

The project entry in `~/Projects/Arduino-Source/.mcp.json` (local, never committed):

```json
{"mcpServers": {"pa-lab": {"type": "stdio", "command": "/Users/difan/.venvs/lab-claude/bin/python",
"args": ["-m", "pa_lab", "serve-stdio",
"--profile-dir", "/Users/difan/Library/Application Support/SerialPrograms/Profiles/lab-B",
"--keepawake-log", "/Users/difan/BDSPLab/keepawake.log"],
"env": {"PYTHONPATH": "/Users/difan/Projects/Arduino-Source-agents/lab/server"}}}}
```

Smoke test (reads files only): `~/.venvs/lab-claude/bin/python lab/server/smoke_readonly.py [profile]`
starts the server as `.mcp.json` does and prints `console_status` once. Tests: `tests/test_status_readonly.py`.

## Slice 3: the durable control plane

SQLite (`db_file` in the config, default `~/.local/state/pa-lab/control.sqlite`, created `0600`)
Expand Down
30 changes: 26 additions & 4 deletions lab/server/pa_lab/__main__.py
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,8 @@
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
python3 -m pa_lab serve --config ~/.config/pa-lab/server.json [--read-only]
python3 -m pa_lab serve-stdio --profile-dir ~/Library/Application\\ Support/SerialPrograms/Profiles/lab-B
python3 -m pa_lab lease --config ~/.config/pa-lab/server.json show|claim-user|release-user

Run from lab/server (or with lab/server on PYTHONPATH). Exit 0 valid, 1 invalid, 2 usage.
Expand Down Expand Up @@ -32,6 +33,11 @@ def main(argv=None) -> int:
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)
serve.add_argument('--read-only', action='store_true',
help='serve only console_status and the resources: no inbox tools, no control plane')
stdio = sub.add_parser('serve-stdio', help='run the read-only MCP server on stdio (for .mcp.json)')
stdio.add_argument('--profile-dir', required=True, help="the console's SerialPrograms profile folder")
stdio.add_argument('--keepawake-log', default='~/BDSPLab/keepawake.log')
lease = sub.add_parser('lease', help="show console B's lease, or (operator) claim or release it for the user")
lease.add_argument('--config', required=True)
lease.add_argument('action', choices=('show', 'claim-user', 'release-user'))
Expand Down Expand Up @@ -71,14 +77,17 @@ def main(argv=None) -> int:
print('wrote {}'.format(args.path))
return 0
if args.command == 'serve':
return _serve(args.config)
return _serve(args.config, args.read_only)
if args.command == 'serve-stdio':
from pa_lab import stdio_server
return stdio_server.main(args.profile_dir, args.keepawake_log)
if args.command == 'lease':
return _lease(args.config, args.action, args.console)
parser.print_help()
return 2


def _serve(path: str) -> int:
def _serve(path: str, read_only: bool = False) -> int:
from pa_lab import lab_reader, mcp_server
try:
cfg = config.load(path)
Expand All @@ -87,6 +96,15 @@ def _serve(path: str) -> int:
print('error {}'.format(e))
return 1
logging.basicConfig(level=logging.INFO, format='%(asctime)s %(name)s %(message)s')
if read_only:
from pathlib import Path
from pa_lab import status
statuses = {name: status.ProfileStatus(name, Path(entry.lab_dir).parent,
keepawake_log=Path.home() / 'BDSPLab' / 'keepawake.log')
for name, entry in cfg.consoles.items()}
readers = {name: s.reader for name, s in statuses.items()}
server = mcp_server.make_server(cfg.port, token, readers, statuses=statuses, read_only=True)
return _serve_forever(server, readers, mcp_server.ENDPOINT)
from pa_lab import control, db
plane = control.ControlPlane(db.Database(cfg.db_file), sorted(cfg.consoles))
readers = {name: lab_reader.ConsoleReader(name, entry.lab_dir, profile=entry.profile, control=plane)
Expand All @@ -95,9 +113,13 @@ def _serve(path: str) -> int:
reader.console_state()
plane.compact()
server = mcp_server.make_server(cfg.port, token, readers, control_plane=plane)
return _serve_forever(server, readers, mcp_server.ENDPOINT)


def _serve_forever(server, readers, endpoint: str) -> int:
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)
endpoint)
try:
server.serve_forever()
except KeyboardInterrupt:
Expand Down
75 changes: 71 additions & 4 deletions lab/server/pa_lab/mcp_server.py
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,10 @@
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.

Read-only mode (`read_only=True`, `serve-stdio`): only `console_status` and the resources. Every tool
that writes into `Lab/inbox` (`shot`, `describe_program`, `game_open`) and every control tool is
neither listed nor callable.
"""

from __future__ import annotations
Expand All @@ -25,7 +29,7 @@
import threading
from typing import Any, Callable, Dict, Optional, Tuple

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

LOG = logging.getLogger('pa_lab.server')
Expand Down Expand Up @@ -119,6 +123,27 @@
},
]

CONSOLE_STATUS_TOOL = {
'name': 'console_status',
'title': 'Console status (check-in)',
'description': "What ~/BDSPLab/checkin.sh reports, read from the console's profile folder: the lab app's pid "
'and deployment, the Lab/state fields, console://B/state, the last Program State line, the last '
'run lines (checkpoint passed/failed, Starting Program), the last press time, the last '
'keepawake line, the newest failure frame and screenshot paths, and the last log lines. Reads '
'files only; sends nothing to the app.',
'inputSchema': {
'type': 'object',
'properties': {
'console': {'type': 'string', 'enum': ['B']},
'log_lines': {'type': 'integer', 'minimum': 0, 'maximum': status.MAX_LOG_LINES,
'default': status.DEFAULT_LOG_LINES},
},
'required': ['console'],
'additionalProperties': False,
},
'annotations': {'readOnlyHint': True, 'destructiveHint': False, 'idempotentHint': True},
}

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


Expand Down Expand Up @@ -184,14 +209,29 @@ def _json_text(value: Any) -> str:


class LabMcp:
"""JSON-RPC methods, without the transport. `consoles` is the allowlist: console id -> reader."""
"""JSON-RPC methods, without the transport. `consoles` is the allowlist: console id -> reader.

`statuses` (console id -> ProfileStatus) adds `console_status`. `read_only` serves only that tool
and the resources: no inbox tools, no control plane."""

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,
statuses: Optional[Dict[str, status.ProfileStatus]] = None,
read_only: bool = False):
if read_only and control_plane is not None:
raise ValueError('a read-only server has no control plane')
self.consoles = consoles
self.take_shot = take_shot
self.control = control_plane
self.statuses = statuses or {}
self.read_only = read_only

def tool_list(self):
status_tools = [CONSOLE_STATUS_TOOL] if self.statuses else []
if self.read_only:
return status_tools
return TOOL_LIST + status_tools + (CONTROL_TOOL_LIST if self.control is not None else [])

def call(self, method: str, params: Dict[str, Any], client: str = 'unnamed') -> Dict[str, Any]:
if method == 'ping':
Expand All @@ -203,8 +243,12 @@ def call(self, method: str, params: Dict[str, Any], client: str = 'unnamed') ->
if method == 'resources/read':
return self._read_resource(params.get('uri'))
if method == 'tools/list':
return {'tools': TOOL_LIST + (CONTROL_TOOL_LIST if self.control is not None else [])}
return {'tools': self.tool_list()}
if method == 'tools/call':
if params.get('name') not in [t['name'] for t in self.tool_list()]:
raise RpcError(INVALID_PARAMS, 'Unknown tool: {}'.format(params.get('name')))
if params.get('name') == 'console_status':
return self._call_status(params.get('arguments', {}))
if self.control is not None and params.get('name') in [t['name'] for t in CONTROL_TOOL_LIST]:
return self._call_control(client, params.get('name'), params.get('arguments', {}))
return self._call_tool(params.get('name'), params.get('arguments', {}))
Expand Down Expand Up @@ -284,6 +328,29 @@ def _call_tool(self, name: Any, arguments: Any) -> Dict[str, Any]:
{'type': 'text', 'text': _json_text(result)}],
'structuredContent': result, 'isError': False}

def _call_status(self, arguments: Any) -> Dict[str, Any]:
name = 'console_status'
if not isinstance(arguments, dict):
return self._refused(name, {'code': 'invalid_arguments', 'field': 'arguments',
'message': 'expected an object'})
unknown = sorted(set(arguments) - {'console', 'log_lines'})
if unknown:
return self._refused(name, {'code': 'invalid_arguments', 'field': unknown[0],
'message': 'unknown argument'})
reader = self.statuses.get(arguments.get('console')) if isinstance(arguments.get('console'), str) else None
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.statuses)))})
log_lines = arguments.get('log_lines', status.DEFAULT_LOG_LINES)
if isinstance(log_lines, bool) or not isinstance(log_lines, int) or \
not 0 <= log_lines <= status.MAX_LOG_LINES:
return self._refused(name, {'code': 'invalid_arguments', 'field': 'log_lines',
'message': 'expected 0..{}'.format(status.MAX_LOG_LINES)})
result = reader.console_status(log_lines)
return {'content': [{'type': 'text', 'text': _json_text(result)}], 'structuredContent': result,
'isError': False}

def _call_control(self, client: str, name: str, arguments: Any) -> Dict[str, Any]:
if not isinstance(arguments, dict):
return self._refused(name, {'code': 'invalid_arguments', 'field': 'arguments',
Expand Down
Loading
Loading