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
55 changes: 53 additions & 2 deletions lab/server/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,9 @@

The local server designed in `docs/design/Agent-Integration.md` (fork #131, branch
`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.
Slice 2: the attach-only read server ([below](#slice-2-the-attach-only-read-server)). Slice 3: the
durable control plane ([below](#slice-3-the-durable-control-plane)): leases, request records,
tickets and events in SQLite. Nothing presses a button yet: that is Slice 5.

| Path | What |
|---|---|
Expand All @@ -20,6 +21,9 @@ lease store, no write path and no press: those are Slices 3 and 5.
| `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 |
| `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 |

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 @@ -184,3 +188,50 @@ journal names, and only when complete (signature and `IEND`). Refusals: `timeout
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).

## Slice 3: the durable control plane

SQLite (`db_file` in the config, default `~/.local/state/pa-lab/control.sqlite`, created `0600`)
is the source of truth; every change is one `BEGIN IMMEDIATE` transaction, so racing threads,
processes or a restarted daemon cannot both win, and a kill mid-write leaves nothing.

**Leases.** `acquire_console(console, request_id, owner, ttl_s=1200)` takes a `free` console and
returns an opaque `lease_token` (only its hash is in the lease row) and `expires_at`.
`renew_console` / `release_console` need the token. `agent_idle` expires after its TTL;
`agent_running` (entered by Slice 5's run start, `ControlPlane.begin_run`) never expires and ends
when the app reports the run's stop (back to `agent_idle` with a fresh TTL) or a new app instance.
A UI Start/Stop in `Lab/state.json` (`last_transition.source == 'ui'`) revokes any agent lease and
installs `user`, with no timeout; only the operator ends it:

```sh
python3 -m pa_lab lease --config ~/.config/pa-lab/server.json show|claim-user|release-user
```

A token whose lease ended is refused with the reason: `lease_expired`, `console_held_by_user`,
otherwise `lease_invalid`. `lease_changed` events carry `old`, `new` and a `reason` (`acquired`,
`released`, `expired`, `run_started`, `run_ended`, `app_restarted`, `ui_takeover`,
`operator_claim`, `operator_release`).

**Requests.** `(client_id, tool, request_id)` is unique; `client_id` is the MCP session's client
name. The record keeps the normalized arguments (defaults filled in) and the result or refusal.
An exact retry gets the stored record, refusals included, even after a restart; the same key with
other arguments is `request_id_reused`. `request_status(console, request_id)` reads the caller's
own record on that console (the newest, if one id was used for several tools); the lease token never appears in a status read or an event.

**Tickets** are request records with status `pending`: `open_ticket` / `resolve_ticket` are the
store side of Slice 5's long operations. They survive restarts and resolve once.

**Events.** `next_events(console, after_seq, timeout_s<=60, limit<=500)` returns the events after
the cursor and `next_after_seq`; it waits for one up to `timeout_s`. `after_seq` is also the
client's confirmed position: pass the last cursor you processed, so a lost response loses nothing.
`seq` comes from `AUTOINCREMENT` and is never reused.

**Reconciliation.** Every read of a live app (`console://B/state`) and the daemon's start apply
`observe`: each transition once (UI takeover, `stopped` with its source), a run's end, an app
restart. Expiries due during downtime apply on the next read, once.

**Retention.** `compact()` runs at start and every 500 events: it keeps the newest 10 000 events,
every event after an active cursor (one used in the last 7 days), every event of a pending ticket
and every pending record; finished records go after 7 days. A cursor behind the compacted range
is refused (`invalid_arguments`, field `after_seq`, `evidence.compacted_through`), never served
with a silent gap.
39 changes: 37 additions & 2 deletions lab/server/pa_lab/__main__.py
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
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 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 All @@ -31,6 +32,10 @@ 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)
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'))
lease.add_argument('--console', default='B')
args = parser.parse_args(argv)

if args.command == 'check':
Expand Down Expand Up @@ -67,6 +72,8 @@ def main(argv=None) -> int:
return 0
if args.command == 'serve':
return _serve(args.config)
if args.command == 'lease':
return _lease(args.config, args.action, args.console)
parser.print_help()
return 2

Expand All @@ -80,9 +87,14 @@ def _serve(path: str) -> int:
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)
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)
for name, entry in cfg.consoles.items()}
server = mcp_server.make_server(cfg.port, token, readers)
for reader in readers.values(): # restart reconciliation: apply what the app shows now
reader.console_state()
plane.compact()
server = mcp_server.make_server(cfg.port, token, readers, control_plane=plane)
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)
Expand All @@ -95,5 +107,28 @@ def _serve(path: str) -> int:
return 0


def _lease(path: str, action: str, console: str) -> int:
import json
from pa_lab import control, db
try:
cfg = config.load(path)
except config.ConfigError as e:
print('error {}'.format(e))
return 1
plane = control.ControlPlane(db.Database(cfg.db_file), sorted(cfg.consoles))
try:
if action == 'claim-user':
lease = plane.claim_user(console)
elif action == 'release-user':
lease = plane.release_user(console)
else:
lease = plane.lease(console)
except control.Refused as e:
print('error {}'.format(e.refusal['message']))
return 1
print(json.dumps(lease, indent=2))
return 0


if __name__ == '__main__':
sys.exit(main())
11 changes: 8 additions & 3 deletions lab/server/pa_lab/config.py
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@
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",
"db_file": "~/.local/state/pa-lab/control.sqlite",
"consoles": {"B": {"lab_dir": "~/Library/Application Support/SerialPrograms/Profiles/lab-B/Lab",
"profile": "lab-B"}}}
"""
Expand All @@ -17,7 +18,8 @@

ALLOWED_CONSOLES = ('B',)
LOOPBACK_HOSTS = ('127.0.0.1',)
TOP_KEYS = ('schema', 'host', 'port', 'token_file', 'consoles')
TOP_KEYS = ('schema', 'host', 'port', 'token_file', 'db_file', 'consoles')
DEFAULT_DB_FILE = '~/.local/state/pa-lab/control.sqlite'
CONSOLE_KEYS = ('lab_dir', 'profile')


Expand All @@ -32,11 +34,13 @@ def __init__(self, lab_dir: Path, profile: Optional[str]):


class Config:
def __init__(self, host: str, port: int, token_file: Path, consoles: Dict[str, ConsoleConfig]):
def __init__(self, host: str, port: int, token_file: Path, consoles: Dict[str, ConsoleConfig],
db_file: Optional[Path] = None):
self.host = host
self.port = port
self.token_file = token_file
self.consoles = consoles
self.db_file = db_file if db_file is not None else Path(os.path.expanduser(DEFAULT_DB_FILE))


def _path(value, field: str) -> Path:
Expand Down Expand Up @@ -82,7 +86,8 @@ def load(path: Path) -> Config:
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)
return Config(host, port, _path(doc.get('token_file'), 'token_file'), out,
_path(doc.get('db_file', DEFAULT_DB_FILE), 'db_file'))


def read_token(path: Path) -> str:
Expand Down
Loading
Loading