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
82 changes: 78 additions & 4 deletions lab/server/README.md
Original file line number Diff line number Diff line change
@@ -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 |
|---|---|
Expand All @@ -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
Expand Down Expand Up @@ -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 <file>` 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 <token>`.

**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:<port>` or `localhost:<port>` (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 <uuid>` /
`snapshot frame <timeout_ms>` 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).
2 changes: 1 addition & 1 deletion lab/server/pa_lab/__init__.py
Original file line number Diff line number Diff line change
@@ -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."""
45 changes: 43 additions & 2 deletions lab/server/pa_lab/__main__.py
Original file line number Diff line number Diff line change
@@ -1,18 +1,21 @@
"""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.
"""

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:
Expand All @@ -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':
Expand All @@ -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())
111 changes: 111 additions & 0 deletions lab/server/pa_lab/config.py
Original file line number Diff line number Diff line change
@@ -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')
9 changes: 9 additions & 0 deletions lab/server/pa_lab/contracts.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)))
Expand Down
Loading
Loading