#!/usr/bin/env python3 # SPDX-License-Identifier: GPL-3.0-or-later """Exercise a built stdio helper against a disposable host, without emulator or model access.""" import argparse import base64 import hashlib import json import os from pathlib import Path import select import socketserver import subprocess import struct import zlib import tempfile import threading import time class Client: def __init__(self, helper, grant): self.proc = subprocess.Popen([helper, "--grant", str(grant)], stdin=subprocess.PIPE, stdout=subprocess.PIPE, bufsize=0) def __enter__(self): return self def __exit__(self, *exc): self.proc.stdin.close() try: self.proc.wait(timeout=5) finally: self.proc.kill() self.proc.wait() self.proc.stdout.close() def send(self, obj): self.raw(json.dumps(obj).encode()) def raw(self, data): self.proc.stdin.write(data + b"\n") self.proc.stdin.flush() def response(self): assert select.select([self.proc.stdout], [], [], 7)[0], "Timed out waiting for stdio reply" line = self.proc.stdout.readline() assert line, f"Helper exited with {self.proc.poll()}" return json.loads(line) def request(self, method, params=None, rid=1): obj = {"jsonrpc": "2.0", "id": rid, "method": method} if params is not None: obj["params"] = params self.send(obj) reply = self.response() assert reply["id"] == rid return reply def handshake(self, protocol): params = {"protocolVersion": protocol, "capabilities": {}, "clientInfo": {"name": "fixture", "version": "1"}} offer = self.request("initialize", params)["result"]["protocolVersion"] assert self.request("tools/list")["error"]["code"] == -32002 self.send({"jsonrpc": "2.0", "method": "notifications/initialized"}) return offer def call(self, name, **arguments): return self.request("tools/call", {"name": name, "arguments": arguments}) def check(helper): with tempfile.TemporaryDirectory(dir="/tmp", prefix="vcc-mcp-check-") as work: socket_path = str(Path(work) / "host") grant_file = Path(work) / "access" grant = {"version": 1, "token": "first-grant", "socket": socket_path} def write_grant(**extra): grant_file.write_text(json.dumps({**grant, **extra})) grant_file.chmod(0o600) write_grant() active = {"token": grant["token"], "requests": []} class MockHost(socketserver.StreamRequestHandler): def handle(self): request = json.loads(self.rfile.readline(48 * 1024)) active["requests"].append(request) result = {"result": {"document_id": "selected-draft"}} if request["tool"] == "get_capabilities" and "project_capabilities" in active: result = {"result": active["project_capabilities"]} if request["tool"] == "capture_playtest" and "playtest_capture" in active: result = {"result": active["playtest_capture"]} if request["tool"] == "capture_playtest_graphics" and "playtest_graphics" in active: result = {"result": active["playtest_graphics"]} if request["tool"] == "capture_playtest_audio" and "playtest_audio" in active: result = {"result": active["playtest_audio"]} if request["tool"] == "get_build_log" and "build_log" in active: result = {"result": active["build_log"]} if request["tool"] == "get_debug_snapshot" and "debug_snapshot" in active: result = {"result": active["debug_snapshot"]} if request["tool"] == "get_call_context" and "call_context" in active: result = {"result": active["call_context"]} if request["tool"] == "list_playtest_disks" and "retained_disks" in active: result = {"result": active["retained_disks"]} if request["tool"] == "list_playtest_media" and "playtest_media" in active: result = {"result": active["playtest_media"]} if request["tool"] == "exchange_playtest_media" and "media_exchange" in active: if active.get("slow_media_retention"): time.sleep(5.15) result = active["media_exchange"] if request["tool"] in ("refresh_project", "get_project_refresh", "read_project_inputs") and "refresh_reply" in active: result = active["refresh_reply"] if request["tool"] in ("start_playtest", "get_run", "stop_playtest") and "startup_receipt" in active: result = {"result": active["startup_receipt"]} if request["token"] != active["token"]: result = {"error": "access_denied"} if request["arguments"].get("query") == "mixed-envelope": result["error"] = 42 if request["arguments"].get("query") == "truncated-reply": self.wfile.write(b'{"result":{}') return if request["arguments"].get("query") == "delayed-reply": # Exercise the real bounded five-second host deadline, # without changing production timeout settings for tests. time.sleep(5.15) return self.wfile.write(json.dumps(result).encode() + b"\n") with socketserver.UnixStreamServer(socket_path, MockHost) as host: thread = threading.Thread(target=host.serve_forever, daemon=True) thread.start() try: with Client(helper, grant_file) as c: assert c.request("tools/list")["error"]["code"] == -32002 assert c.request("initialize", {})["error"]["code"] == -32602 assert c.handshake("2099-01-01") == "2025-11-25" assert c.request("initialize", {})["error"]["code"] == -32600 for bad in (b"{", b'{"bad":"\xff"}', '{"jsonrpc":"2.0","id":2,"method":"ping"}'.encode("utf-16")): c.raw(bad) assert c.response()["error"]["code"] == -32700 c.raw(b"x" * (64 * 1024 + 1)) assert c.response()["error"]["code"] == -32600 c.send([{"jsonrpc": "2.0", "method": "ping", "id": 1}]) assert c.response()["error"]["code"] == -32600 c.send({"jsonrpc": "2.0", "id": 7, "result": {}}) c.send({"jsonrpc": "2.0", "method": "notifications/ignored"}) assert c.request("ping", rid="after-silent-messages")["result"] == {} assert c.request("unknown")["error"]["code"] == -32601 assert c.request(42, rid="malformed")["error"]["code"] == -32600 listed = {t["name"] for t in c.request("tools/list")["result"]["tools"]} assert listed == {"get_capabilities", "search_help", "read_source", "read_topic"} assert c.call("propose_listing")["error"]["code"] == -32602 assert c.request("tools/call", {"name":"read_source", "arguments":[]})["error"]["code"] == -32602 for args in ({"document_id": []}, {"other": "x"}, {"document_id": ""}, {"document_id":"x","extra":1}): assert c.call("read_source", **args)["result"]["isError"] assert not active["requests"] assert c.call("get_capabilities")["result"]["structuredContent"]["document_id"] == "selected-draft" for query in ("truncated-reply", "mixed-envelope"): result = c.call("search_help", query=query)["result"] assert result["isError"] and result["content"][0]["text"] == "invalid_or_incomplete_host_reply" delayed = c.call("search_help", query="delayed-reply")["result"] assert delayed["isError"] and delayed["content"][0]["text"] == "transport_timeout" assert c.call("get_capabilities")["result"]["structuredContent"]["document_id"] == "selected-draft" active["token"] = "second-grant" write_grant(token=active["token"]) denied = c.call("get_capabilities")["result"] assert denied["isError"] and denied["content"][0]["text"] == "access_denied" write_grant(token=active["token"], canPropose=True) with Client(helper, grant_file) as c: assert c.handshake("2025-11-25") == "2025-11-25" tools = {t["name"]: t for t in c.request("tools/list")["result"]["tools"]} assert {"propose_edit", "propose_listing", "send_keys"} <= tools.keys() args = {"document_id":"draft", "revision":0, "request_id":"once", "source":"10 ?" + "A" * (12288-4)} assert c.call("propose_listing", **args)["result"]["structuredContent"] assert active["requests"][-1]["arguments"] == args count = len(active["requests"]) for update in ({"source": args["source"]+"x"}, {"revision": True}, {"revision": -1}, {"request_id":"x"*129}): assert c.call("propose_listing", **{**args, **update})["result"]["isError"] assert c.call("send_keys", run_id="r", request_id="i", keys="RUN")["result"]["isError"] assert len(active["requests"]) == count for kind, limit in (("cmoc", 128), ("assembly", 64)): write_grant(kind=kind, token=active["token"]) with Client(helper, grant_file) as c: c.handshake("2025-11-25") listed = {t["name"]:t for t in c.request("tools/list")["result"]["tools"]} assert len(listed) == 9 and {"build_project", "search_help", "read_topic"} <= listed.keys() assert c.call("search_help", query="WIDTH")["result"]["structuredContent"] assert c.call("read_topic", topic_id="reference")["result"]["structuredContent"] fields = listed["propose_fix"]["inputSchema"]["properties"] assert fields["request_id"]["maxLength"] == limit args = dict(project_id="project", revision=0, request_id="q"*(limit+1)) assert c.call("build_project", **args)["result"]["isError"] for kind, toolset, custom, supported in (("cmoc", 3, True, False), ("cmoc", 4, False, False), ("cmoc", 4, "yes", False), ("assembly", 4, True, False), ("cmoc", 4, True, True)): write_grant(kind=kind, toolset=toolset, customMake=custom, token=active["token"]) with Client(helper, grant_file) as c: c.handshake("2025-11-25") listed = {t["name"]: t for t in c.request("tools/list")["result"]["tools"]} schema = listed["build_project"]["inputSchema"] assert set(schema["required"]) == {"project_id", "revision", "request_id"} assert ("action" in schema["properties"]) == supported assert ("configuration" in schema["properties"]) == supported args = dict(project_id="project", revision=7, request_id="custom-build") assert c.call("build_project", **args)["result"]["structuredContent"] assert active["requests"][-1]["arguments"] == args count = len(active["requests"]) selection = dict(action="disk", configuration="Release") result = c.call("build_project", **args, **selection)["result"] assert ("structuredContent" in result) == supported if not supported: assert len(active["requests"]) == count continue assert active["requests"][-1]["arguments"] == {**args, **selection} for action in ("build", "disk"): for configuration in ("Debug", "Release"): chosen = {**args, "action": action, "configuration": configuration} assert c.call("build_project", **chosen)["result"]["structuredContent"] assert active["requests"][-1]["arguments"] == chosen count = len(active["requests"]) for invalid in ({"action": "clean"}, {"action": "custom-target"}, {"action": 1}, {"configuration": ""}, {"configuration": "x" * 129}, {"configuration": ["Debug"]}, {"target": "disk"}, {"make_arguments": "-f other.mk"}): assert c.call("build_project", **{**args, **invalid})["result"]["isError"] assert len(active["requests"]) == count capabilities = dict(project_id="project", revision=7, build_recipe="approved_make", build_actions=["build", "disk"], configurations=["Debug", "Release"], configuration="Debug", targets={"build": "build", "disk": "disk"}, recipe_id="observed-recipe") active["project_capabilities"] = capabilities assert c.call("get_capabilities")["result"]["structuredContent"] == capabilities del active["project_capabilities"] refresh_tools = {"refresh_project", "get_project_refresh", "read_project_inputs"} for kind, toolset, permission in (("cmoc", 5, True), ("cmoc", 6, False), ("cmoc", 6, "yes"), ("assembly", 6, True), ("cmoc", 6, True)): write_grant(kind=kind, toolset=toolset, projectRefresh=permission, token=active["token"]) with Client(helper, grant_file) as c: c.handshake("2025-11-25") listed = {t["name"]: t for t in c.request("tools/list")["result"]["tools"]} supported = kind == "cmoc" and toolset >= 6 and permission is True assert bool(refresh_tools & listed.keys()) == supported if not supported: continue assert refresh_tools <= listed.keys() for status in ("pending", "approved", "rejected", "unchanged"): payload = dict(project_id="project", refresh_id="refresh", status=status, revision=8) active["refresh_reply"] = {"result": payload} for tool, arguments in (("refresh_project", dict(project_id="project", request_id="refresh", revision=7)), ("get_project_refresh", dict(project_id="project", refresh_id="refresh")), ("read_project_inputs", dict(project_id="project", offset=0, limit=256))): assert c.call(tool, **arguments)["result"]["structuredContent"] == payload assert active["requests"][-1]["arguments"] == arguments count = len(active["requests"]) for invalid in ({"offset": -1}, {"limit": 0}, {"limit": 257}, {"path": "secret"}): assert c.call("read_project_inputs", project_id="project", **invalid)["result"]["isError"] assert len(active["requests"]) == count details = dict(error="stale_revision", expected_revision=7, current_revision=8, expected_artifact_id="old", current_artifact_id=None, changed_input_paths=["src/game.c"]) active["refresh_reply"] = {"error": "stale_revision", "error_details": details} failure = c.call("refresh_project", project_id="project", request_id="stale", revision=7)["result"] assert failure["isError"] and failure["structuredContent"] == details del active["refresh_reply"] # A new helper must not expand an old/forged grant. The one # discovery list also controls dispatch before contacting host. for kind, toolset, playtest, permission in ( ("cmoc", None, True, True), ("cmoc", 5, True, True), ("cmoc", 9, True, True), ("cmoc", 10, False, True), ("cmoc", 10, None, True), ("cmoc", 10, 1, True), ("cmoc", 10, True, None), ("cmoc", 10, True, False), ("cmoc", 10, True, "yes"), ("cmoc", 10, True, 1), ("cmoc", 10, True, []), ("cmoc", 10, True, {}), ("cmoc", 10, True, "missing"), ("cmoc", 10.0, True, True), ("cmoc", True, True, True), ("cmoc", "10", True, True), ("cmoc", [], True, True), ("cmoc", {}, True, True), ("basic", 10, True, True), ("assembly", 10, True, True), ("archive", 10, True, True), ("cmoc", 10, True, True), ("cmoc", 11, True, True)): options = dict(kind=kind, version=2 if kind == "archive" else 1, toolset=toolset, playtest=playtest, playtestCallContext=permission, token=active["token"]) if permission == "missing": del options["playtestCallContext"] write_grant(**options) with Client(helper, grant_file) as c: c.handshake("2025-11-25") catalog = {t["name"]: t for t in c.request("tools/list")["result"]["tools"]} enabled = kind == "cmoc" and type(toolset) is int and toolset >= 10 and playtest is True and permission is True assert ("get_call_context" in catalog) == enabled, (kind, toolset, playtest, permission) count = len(active["requests"]) args = dict(run_id="owned-run", snapshot_id="current-snapshot") if not enabled: assert c.call("get_call_context", **args)["error"]["code"] == -32602 assert len(active["requests"]) == count continue tool = catalog["get_call_context"]; schema = tool["inputSchema"] assert schema["type"] == "object" and schema["additionalProperties"] is False assert set(schema["properties"]) == set(schema["required"]) == {"run_id", "snapshot_id"} assert all(value == dict(type="string", minLength=1, maxLength=64) for value in schema["properties"].values()) assert tool["annotations"] == dict(readOnlyHint=True, openWorldHint=False) for payload in (dict(run_id="owned-run", snapshot_id="current-snapshot", status="unavailable", reason="unverified_frame"), dict(run_id="owned-run", snapshot_id="current-snapshot", status="verified", frames=[])): active["call_context"] = payload assert c.call("get_call_context", **args)["result"]["structuredContent"] == payload assert active["requests"][-1]["tool"] == "get_call_context" assert active["requests"][-1]["arguments"] == args del active["call_context"] count = len(active["requests"]) invalid = ({}, {"run_id":"owned-run"}, {"snapshot_id":"current-snapshot"}, dict(args, run_id=""), dict(args, snapshot_id="x"*65), dict(args, run_id=True), dict(args, snapshot_id=[]), dict(args, address=0), dict(args, offset=0), dict(args, count=1), dict(args, registers={}), dict(args, memory=[]), dict(args, caller="guess"), dict(args, max_frames=1), dict(args, request_id="read")) for arguments in invalid: assert c.call("get_call_context", **arguments)["result"]["isError"], arguments assert len(active["requests"]) == count # Media exchange is a separate, strict Boolean opt-in on fresh # reviewed grants. Older grants never acquire it on restart. media_tools = {"list_playtest_media", "exchange_playtest_media"} for kind, toolset, playtest, permission in ( ("cmoc", None, True, True), ("cmoc", 10, True, True), ("cmoc", 11.0, True, True), ("cmoc", True, True, True), ("cmoc", "11", True, True), ("cmoc", [], True, True), ("cmoc", {}, True, True), ("cmoc", 11, False, True), ("cmoc", 11, 1, True), ("cmoc", 11, "yes", True), ("cmoc", 11, None, True), ("cmoc", 11, True, False), ("cmoc", 11, True, 1), ("cmoc", 11, True, "yes"), ("cmoc", 11, True, []), ("cmoc", 11, True, {}), ("cmoc", 11, True, None), ("cmoc", 11, True, "missing"), ("basic", 11, True, True), ("assembly", 11, True, True), ("archive", 11, True, True), ("cmoc", 11, True, True), ("cmoc", 12, True, True)): options = dict(kind=kind, version=2 if kind == "archive" else 1, toolset=toolset, playtest=playtest, playtestMedia=permission, token=active["token"]) if permission == "missing": del options["playtestMedia"] write_grant(**options) with Client(helper, grant_file) as c: c.handshake("2025-11-25") catalog = {t["name"]:t for t in c.request("tools/list")["result"]["tools"]} enabled = kind == "cmoc" and type(toolset) is int and toolset >= 11 and playtest is True and permission is True assert (media_tools & set(catalog)) == (media_tools if enabled else set()), options listing = dict(project_id="project", revision=3, artifact_id="artifact") insert = dict(run_id="run", request_id="swap-1", action="insert", media_id="opaque-media-1", media_sha256="0123456789abcdef"*4) eject = dict(run_id="run", request_id="swap-2", action="eject") count = len(active["requests"]) if not enabled: assert c.call("list_playtest_media", **listing)["error"]["code"] == -32602 assert c.call("exchange_playtest_media", **insert)["error"]["code"] == -32602 if "start_playtest" in catalog: assert "retained_media" not in catalog["start_playtest"]["inputSchema"]["properties"] assert c.call("start_playtest", project_id="project", revision=3, artifact_id="artifact", request_id="start", retained_media=[])["result"]["isError"] assert len(active["requests"]) == count continue assert catalog["list_playtest_media"]["annotations"] == dict(readOnlyHint=True, openWorldHint=False) assert catalog["exchange_playtest_media"]["annotations"] == dict(readOnlyHint=False, idempotentHint=True, openWorldHint=False) schema = catalog["exchange_playtest_media"]["inputSchema"] assert schema["properties"]["action"]["enum"] == ["insert", "eject"] assert len(schema["oneOf"]) == 2 assert all(branch["additionalProperties"] is False for branch in schema["oneOf"]) assert schema["oneOf"][0]["required"] == ["run_id", "request_id", "action", "media_id", "media_sha256"] assert set(schema["oneOf"][1]["properties"]) == {"run_id", "request_id", "action"} assert schema["properties"]["media_sha256"]["pattern"] == "^[0-9a-f]{64}$" assert schema["properties"]["media_id"]["pattern"] == "^[A-Za-z0-9_-]{1,64}$" resume_schema = catalog["start_playtest"]["inputSchema"]["properties"]["retained_media"] assert resume_schema["minItems"] == 1 and resume_schema["maxItems"] == 8 and resume_schema["uniqueItems"] is True assert set(resume_schema["items"]["properties"]) == {"media_id", "retained_disk_id", "retained_disk_sha256"} resume_disk = dict(media_id="opaque-media-1", retained_disk_id="00000000-0000-4000-8000-000000000001", retained_disk_sha256="a"*64) resume = dict(project_id="project", revision=3, artifact_id="artifact", request_id="resume-media", retained_media=[resume_disk]) assert c.call("start_playtest", **resume)["result"]["structuredContent"] assert active["requests"][-1]["arguments"] == resume count = len(active["requests"]) for invalid in ([], [resume_disk]*2, [dict(resume_disk, media_id="m"+str(i)) for i in range(9)], [dict(resume_disk, media_id="/tmp/world.dsk")], [dict(resume_disk, media_id="")], [dict(resume_disk, retained_disk_sha256="A"*64)], [{k:v for k,v in resume_disk.items() if k != "retained_disk_id"}], [dict(resume_disk, path="world.dsk")], "media", None): assert c.call("start_playtest", **dict(resume, retained_media=invalid))["result"]["isError"], invalid assert len(active["requests"]) == count, "Invalid additional media resume selections reached the host" payload = dict(project_id="project", revision=3, artifact_id="artifact", media=[dict(media_id="opaque-media-1", media_sha256=insert["media_sha256"])]) active["playtest_media"] = payload for args in (listing, dict(listing, run_id="run")): assert c.call("list_playtest_media", **args)["result"]["structuredContent"] == payload assert active["requests"][-1]["arguments"] == args del active["playtest_media"] # Preserve the exact request plan on retry. A changed # selection reaches the host, whose ownership ledger # decides conflicts; this adapter invents no media state. receipt = dict(run_id="run", old_media_id="home", media_id="opaque-media-1", fields=42) active["media_exchange"] = {"result": receipt} for args in (insert, dict(insert), dict(insert, media_sha256="a"*64), eject): assert c.call("exchange_playtest_media", **args)["result"]["structuredContent"] == receipt assert active["requests"][-1]["arguments"] == args if toolset == 11: # Durable retention gets the bounded playtest # deadline, not the five-second metadata deadline. active["slow_media_retention"] = True try: assert c.call("exchange_playtest_media", **insert)["result"]["structuredContent"] == receipt finally: del active["slow_media_retention"] active["media_exchange"] = {"error":"request_id_conflict"} declined = c.call("exchange_playtest_media", **insert)["result"] assert declined["isError"] and declined["content"][0]["text"] == "request_id_conflict" del active["media_exchange"] count = len(active["requests"]) for args in ({}, {"project_id":"project"}, dict(listing, revision=True), dict(listing, revision=-1), dict(listing, revision=1.5), dict(listing, run_id=""), dict(listing, artifact_id=[]), dict(listing, project_id="p"*65), dict(listing, path="/tmp/world.dsk"), dict(listing, run_id="r"*65), dict(listing, request_id="listing")): assert c.call("list_playtest_media", **args)["result"]["isError"], args for args in ({}, {k:v for k,v in insert.items() if k != "media_id"}, {k:v for k,v in insert.items() if k != "media_sha256"}, dict(eject, media_id="opaque-media-1"), dict(eject, media_sha256="a"*64), dict(insert, action="eject"), dict(insert, action="replace"), dict(insert, action=True), dict(insert, media_sha256="A"*64), dict(insert, media_sha256="a"*63), dict(insert, media_sha256="a"*65), dict(insert, media_sha256="a"*63+"\n"), dict(insert, media_sha256=True), dict(insert, media_sha256=None), dict(insert, media_id=""), dict(insert, media_id="m"*65), dict(insert, media_id="../world.dsk"), dict(insert, media_id="/tmp/world.dsk"), dict(insert, media_id=[]), dict(insert, request_id="r"*65), dict(insert, run_id=""), dict(insert, path="world.dsk"), dict(insert, drive=0), dict(insert, fields=1), dict(eject, media_id=None), dict(eject, media_sha256=None)): assert c.call("exchange_playtest_media", **args)["result"]["isError"], args assert len(active["requests"]) == count, "Invalid media selections reached the host" write_grant(kind="cmoc", toolset=11, playtest=True, customMake=True, projectRefresh=True, projectDiagnostics=True, playtestAudio=True, playtestProcessors=True, playtestJoysticks=True, playtestCallContext=True, playtestMedia=True, token=active["token"]) with Client(helper, grant_file) as c: c.handshake("2025-11-25") catalog = {t["name"]:t for t in c.request("tools/list")["result"]["tools"]} assert len(catalog) == 32 and media_tools <= set(catalog) assert "single letter, digit or space" in catalog["send_keys"]["description"] or "one letter, digit or space" in catalog["send_keys"]["description"] # CPU selection is opt-in; legacy exported schemas retain the # 6809-only contract even when handled by this newer helper. for toolset, permission in ((5,True),(7,True),(8,False),(8,"yes"),(8,True)): write_grant(kind="cmoc",toolset=toolset,playtest=True,playtestProcessors=permission,token=active["token"]) with Client(helper,grant_file) as c: c.handshake("2025-11-25") catalog={t["name"]:t for t in c.request("tools/list")["result"]["tools"]} schema=catalog["start_playtest"]["inputSchema"] enabled=toolset>=8 and permission is True assert ("processor" in schema["properties"])==enabled args=dict(project_id="project",revision=1,artifact_id="artifact",request_id="start") c.call("start_playtest",**args) assert "processor" not in active["requests"][-1]["arguments"] if enabled: assert schema["properties"]["processor"]["enum"]==["MC6809","HD6309"] assert schema["properties"]["processor"]["default"]=="MC6809" assert "processor" not in schema["required"] for processor in ("MC6809","HD6309"): c.call("start_playtest",**args,processor=processor) assert active["requests"][-1]["arguments"]["processor"]==processor count=len(active["requests"]) for processor in (["6809","6309","hd6309","",None,True,9,[],{}] if enabled else ["HD6309"]): assert c.call("start_playtest",**args,processor=processor)["result"]["isError"] assert c.call("start_playtest",**args,cpu="6309")["result"]["isError"] assert len(active["requests"])==count # Standard analog ports are an explicit fresh-grant capability. for toolset, permission in ((8, True), (9, False), (9, "yes"), (9, 1), (9, None), (9, True)): write_grant(kind="cmoc", toolset=toolset, playtest=True, playtestProcessors=True, playtestJoysticks=permission, token=active["token"]) with Client(helper, grant_file) as c: c.handshake("2025-11-25") catalog = {t["name"]: t for t in c.request("tools/list")["result"]["tools"]} step = catalog["playtest_input"]["inputSchema"]["properties"]["steps"]["items"] enabled = toolset >= 9 and permission is True assert ("joysticks" in step["properties"]) == enabled assert ("get_playtest_input" in catalog) == enabled assert step["required"] == ["keys", "fields"] joystick = {"port": "right", "x": 0, "y": 8191, "buttons": ["fire1"]} plan = dict(run_id="run", request_id="joy", steps=[dict(keys=[], fields=6, joysticks=[joystick])]) count = len(active["requests"]) if enabled: assert catalog["get_playtest_input"]["annotations"]["readOnlyHint"] c.call("get_playtest_input", run_id="run") c.call("playtest_input", **plan) assert active["requests"][-1]["arguments"] == plan count = len(active["requests"]) for bad in (dict(joystick, x=True), dict(joystick, x=-1), dict(joystick, y=16384), dict(joystick, x=1.5), dict(joystick, port="0"), dict(joystick, buttons=["fire3"]), dict(joystick, buttons=["fire1", "fire1"]), dict(joystick, interface="standard")): invalid = dict(plan, steps=[dict(keys=[], fields=6, joysticks=[bad])]) assert c.call("playtest_input", **invalid)["result"]["isError"], bad assert len(active["requests"]) == count else: assert c.call("playtest_input", **plan)["result"]["isError"] assert c.call("get_playtest_input", run_id="run")["error"]["code"] == -32602 assert len(active["requests"]) == count playtest_tools = {"start_playtest", "list_playtest_disks", "playtest_input", "playtest_debug", "capture_playtest", "capture_playtest_graphics", "restart_playtest", "stop_playtest"} for kind, toolset, permission in (("cmoc", 4, True), ("cmoc", 5, False), ("cmoc", 5, "yes"), ("assembly", 5, True)): write_grant(kind=kind, toolset=toolset, playtest=permission, token=active["token"]) with Client(helper, grant_file) as c: c.handshake("2025-11-25") listed = {t["name"] for t in c.request("tools/list")["result"]["tools"]} assert not playtest_tools & listed count = len(active["requests"]) assert c.call("playtest_input", run_id="r", request_id="i", steps=[])["error"]["code"] == -32602 assert c.call("start_playtest", project_id="p", revision=1, artifact_id="a", request_id="entry", stop_function="render_frame", stop_kind="function_entry")["error"]["code"] == -32602 assert c.call("list_playtest_disks", project_id="project")["error"]["code"] == -32602 assert c.call("capture_playtest_graphics", run_id="r")["error"]["code"] == -32602 assert len(active["requests"]) == count write_grant(kind="cmoc", toolset=5, playtest=True, customMake=True, token=active["token"]) with Client(helper, grant_file) as c: c.handshake("2025-11-25") listed = {t["name"] for t in c.request("tools/list")["result"]["tools"]} assert playtest_tools <= listed and len(listed) == 23 assert {"get_capabilities", "build_project", "get_build", "get_debug_snapshot", "read_debug_memory"} <= listed detailed = {t["name"]:t for t in c.request("tools/list")["result"]["tools"]} key_schema = detailed["playtest_input"]["inputSchema"]["properties"]["steps"]["items"]["properties"]["keys"] assert {"period", "backspace", "shift"} <= set(key_schema["items"]["enum"]) assert "." not in key_schema["items"]["enum"] graphics_schema = detailed["capture_playtest_graphics"]["inputSchema"] assert "poll get_run" in detailed["start_playtest"]["description"] assert "reserved run_id" in detailed["stop_playtest"]["description"] assert detailed["capture_playtest_graphics"]["annotations"]["readOnlyHint"] is True assert graphics_schema["required"] == ["run_id"] assert set(graphics_schema["properties"]) == {"run_id", "buffer_id"} assert graphics_schema["properties"]["buffer_id"]["pattern"] == "^[A-Za-z0-9_-]{1,64}$" for name in ("start_playtest", "playtest_debug"): schema = detailed[name]["inputSchema"] assert "stop_kind" not in schema["required"] assert schema["properties"]["stop_kind"]["enum"] == ["c_line", "function_entry"] assert schema["properties"]["stop_kind"]["default"] == "c_line" field = "stop_function" if name == "start_playtest" else "function" assert schema["properties"][field]["maxLength"] == 1023 assert schema["properties"]["request_id"]["maxLength"] == 64 starts = dict(project_id="project", revision=1, artifact_id="artifact", request_id="entry", stop_function="render_frame") # Startup is accepted before preparation/boot finishes. # Preserve polling/cancellation receipts exactly, without # synthesizing a ready run or hiding the failed phase. pending = dict(project_id="project", revision=1, artifact_id="artifact", request_id="entry", run_id="reserved", owned_playtest=True, status="starting", phase="preparing_debug_metadata", busy=True, poll_tool="get_run") active["startup_receipt"] = pending assert c.call("start_playtest", **starts)["result"]["structuredContent"] == pending assert c.call("start_playtest", **starts)["result"]["structuredContent"] == pending assert c.call("get_run", project_id="project", revision=1)["result"]["structuredContent"] == pending for state in ({**pending, "status":"cancelling", "phase":"booting"}, {**pending, "status":"cancelled", "phase":"booting", "busy":False}, {**pending, "status":"failed", "phase":"reading_artifact", "busy":False, "error":"artifact_disk_changed"}): active["startup_receipt"] = state assert c.call("get_run", project_id="project", revision=1)["result"]["structuredContent"] == state active["startup_receipt"] = {**pending, "status":"cancelling", "phase":"booting"} assert c.call("stop_playtest", run_id="reserved", request_id="cancel-start")["result"]["structuredContent"]["status"] == "cancelling" assert active["requests"][-1]["arguments"] == {"run_id":"reserved", "request_id":"cancel-start"} del active["startup_receipt"] stops = dict(run_id="owned", request_id="entry-stop", action="stop_at", function="render_frame") for tool, arguments in (("start_playtest", starts), ("playtest_debug", stops)): for index, selection in enumerate(({}, {"stop_kind":"c_line"}, {"stop_kind":"function_entry"})): expected = {**arguments, **selection, "request_id":arguments["request_id"] + "-" + str(index)} assert c.call(tool, **expected)["result"]["structuredContent"] assert active["requests"][-1]["arguments"] == expected count = len(active["requests"]) for invalid_kind in ("assembly", "", "FUNCTION_ENTRY", True, 1, None, [], {}): assert c.call(tool, **arguments, stop_kind=invalid_kind)["result"]["isError"] assert len(active["requests"]) == count, "Invalid stop kinds reached the host" name_field = "stop_function" if tool == "start_playtest" else "function" # Function identifiers have the same supported size as # verified compiler metadata, independently of run IDs. for length in (65, 1023): expected = {**arguments, name_field:"f"*length, "stop_kind":"function_entry", "request_id":arguments["request_id"] + "-long-" + str(length)} assert c.call(tool, **expected)["result"]["structuredContent"] assert active["requests"][-1]["arguments"] == expected count = len(active["requests"]) too_long = {**arguments, name_field:"f"*1024, "stop_kind":"function_entry"} assert c.call(tool, **too_long)["result"]["isError"] long_id = {**arguments, name_field:"f"*65, "request_id":"r"*65} assert c.call(tool, **long_id)["result"]["isError"] assert len(active["requests"]) == count, "Oversized names or IDs reached the host" # Resuming a saved test disk carries an opaque record ID # and the exact receipt hash, never an arbitrary host path. disk_id = "00000000-0000-4000-8000-000000000001" digest = "0123456789abcdef"*4 schema = detailed["start_playtest"]["inputSchema"] assert not {"retained_disk_id", "retained_disk_sha256"} & set(schema["required"]) assert schema["properties"]["retained_disk_sha256"]["pattern"] == "^[0-9a-f]{64}$" resumed = {**starts, "request_id":"resume", "retained_disk_id":disk_id, "retained_disk_sha256":digest} assert c.call("start_playtest", **resumed)["result"]["structuredContent"] assert active["requests"][-1]["arguments"] == resumed count = len(active["requests"]) for update in ({"retained_disk_id":[]}, {"retained_disk_id":True}, {"retained_disk_id":None}, {"retained_disk_id":""}, {"retained_disk_id":"x"*65}, {"retained_disk_sha256":[]}, {"retained_disk_sha256":64}, {"retained_disk_sha256":True}, {"retained_disk_sha256":None}, {"retained_disk_sha256":"a"*63}, {"retained_disk_sha256":"a"*65}, {"retained_disk_sha256":"A"*64}, {"retained_disk_sha256":"g"*64}, {"retained_disk_sha256":"a"*63+"\n"}, {"disk_path":"/tmp/not-an-authorized-disk.dsk"}): assert c.call("start_playtest", **{**resumed, **update})["result"]["isError"], update assert len(active["requests"]) == count, "Invalid retained disk fields reached the host" assert detailed["list_playtest_disks"]["annotations"]["readOnlyHint"] is True records = dict(project_id="project", disks=[dict(retained_disk_id=disk_id, sha256=digest, provenance="project_record")]) active["retained_disks"] = records listed_disks = c.call("list_playtest_disks", project_id="project")["result"]["structuredContent"] assert listed_disks == records assert active["requests"][-1]["arguments"] == {"project_id":"project"} count = len(active["requests"]) for invalid in ({}, {"project_id":[]}, {"project_id":""}, {"project_id":"project", "path":"/tmp"}): assert c.call("list_playtest_disks", **invalid)["result"]["isError"] assert len(active["requests"]) == count del active["retained_disks"] # An assembly entry observation is distinct from a C line. # The public adapter preserves that distinction exactly. snapshot = dict(run_id="owned", snapshot_id="assembly-stop", source_stop=None, function_stop=dict(name="render_frame", kind="function_entry", address=0x4000, module_id="render-overlay", physical_address=12*8192), registers={"PC":0x4000}, watches=[], memory_ranges=[]) active["debug_snapshot"] = snapshot observed = c.call("get_debug_snapshot", run_id="owned")["result"] assert observed["structuredContent"] == snapshot assert json.loads(observed["content"][0]["text"]) == snapshot assert observed["structuredContent"]["source_stop"] is None assert "line" not in observed["structuredContent"]["function_stop"] del active["debug_snapshot"] # Nested scalar arrays and an empty release chord are both # valid. Forward the plan byte-for-byte in JSON semantics. plan = dict(run_id="owned", request_id="held-keys", steps=[ {"keys":["right", "x", "z"], "fields":60}, {"keys":[], "fields":1}]) assert c.call("playtest_input", **plan)["result"]["structuredContent"] assert active["requests"][-1]["arguments"] == plan for step in ({"keys":["left"], "fields":600}, {"keys":[], "fields":1}, {"keys":["period"], "fields":1}, {"keys":["shift", "period"], "fields":1}, {"keys":["backspace"], "fields":1}, {"keys":["shift", "backspace"], "fields":1}): args = {**plan, "steps":[step]} assert c.call("playtest_input", **args)["result"]["structuredContent"] assert active["requests"][-1]["arguments"] == args count = len(active["requests"]) invalid_steps = [ {}, "right", {"keys":"right", "fields":1}, {"keys":[{}], "fields":1}, {"keys":[1], "fields":1}, {"keys":[True], "fields":1}, {"keys":[["right"]], "fields":1}, {"keys":["right","right"], "fields":1}, {"keys":["unknown"], "fields":1}, {"keys":["."], "fields":1}, {"keys":["PERIOD"], "fields":1}, {"keys":["period", "period"], "fields":1}, {"keys":["right"], "fields":True}, {"keys":["right"], "fields":1.5}, {"keys":["right"], "fields":0}, {"keys":["right"], "fields":601}, {"keys":["right"], "fields":1, "extra":True}, {"keys":list("abcdefghi"), "fields":1}, {"keys":[], "fields":None}, ] for step in invalid_steps: assert c.call("playtest_input", **{**plan, "steps":[step]})["result"]["isError"], step for steps in ([], [{}]*65, "right", [None]): assert c.call("playtest_input", **{**plan, "steps":steps})["result"]["isError"] assert len(active["requests"]) == count, "Invalid nested arguments reached the host" # The transport returns a standard image block, keeping # base64 out of both human-readable and structured metadata. def png_chunk(kind, payload): return (struct.pack(">I", len(payload)) + kind + payload + struct.pack(">I", zlib.crc32(kind + payload) & 0xffffffff)) authored_png = (b"\x89PNG\r\n\x1a\n" + png_chunk(b"IHDR", struct.pack(">2I5B", 1, 1, 8, 2, 0, 0, 0)) + png_chunk(b"IDAT", zlib.compress(b"\0\0\0\0")) + png_chunk(b"IEND", b"")) png = base64.b64encode(authored_png).decode() active["playtest_capture"] = dict(run_id="owned", field_clock=61, width=1, height=1, png_base64=png) result = c.call("capture_playtest", run_id="owned")["result"] image = [item for item in result["content"] if item["type"] == "image"] assert len(image) == 1 and image[0]["mimeType"] == "image/png" and image[0]["data"] == png assert base64.b64decode(image[0]["data"]).startswith(b"\x89PNG\r\n\x1a\n") metadata = json.loads(result["content"][0]["text"]) assert metadata == result["structuredContent"] assert metadata["field_clock"] == 61 and metadata["image_content"] is True assert "png_base64" not in metadata and png not in result["content"][0]["text"] del active["playtest_capture"] # Paired read-only previews share one paused observation. # Preserve image order and all physical identity metadata, # with image bytes occurring only in MCP image blocks. second_png_bytes = (b"\x89PNG\r\n\x1a\n" + png_chunk(b"IHDR", struct.pack(">2I5B", 1, 1, 8, 2, 0, 0, 0)) + png_chunk(b"IDAT", zlib.compress(b"\0\xff\0\0")) + png_chunk(b"IEND", b"")) second_png = base64.b64encode(second_png_bytes).decode() displayed = dict(role="display", physical_address=0x60000, width=1, height=1, png_base64=png) declared = dict(role="declared", buffer_id="page_B-2", physical_address=0x62000, width=1, height=1, png_base64=second_png) for args, rows in (({"run_id":"owned"}, [displayed]), ({"run_id":"owned", "buffer_id":"page_B-2"}, [displayed, declared]), ({"run_id":"owned", "buffer_id":"A"*64}, [displayed, declared])): payload = dict(run_id="owned", snapshot_id="paused-graphics", field_clock=61, paused=True, buffers=rows) active["playtest_graphics"] = payload result = c.call("capture_playtest_graphics", **args)["result"] assert active["requests"][-1]["arguments"] == args images = [item for item in result["content"] if item["type"] == "image"] assert [item["data"] for item in images] == [row["png_base64"] for row in rows] assert all(item["mimeType"] == "image/png" for item in images) expected_rows = [{**{k:v for k,v in row.items() if k != "png_base64"}, "image_content":True} for row in rows] expected = {**payload, "buffers":expected_rows} assert result["structuredContent"] == expected assert json.loads(result["content"][0]["text"]) == expected metadata_text = json.dumps(result["structuredContent"]) assert "png_base64" not in metadata_text and png not in metadata_text and second_png not in metadata_text assert png not in result["content"][0]["text"] and second_png not in result["content"][0]["text"] count = len(active["requests"]) for args in ({}, {"run_id":[]}, {"run_id":"owned", "buffer_id":True}, {"run_id":"owned", "buffer_id":[]}, {"run_id":"owned", "buffer_id":None}, {"run_id":"owned", "buffer_id":""}, {"run_id":"owned", "buffer_id":"A"*65}, {"run_id":"owned", "buffer_id":"page\n"}, {"run_id":"owned", "buffer_id":"../page"}, {"run_id":"owned", "buffer_id":"/tmp/page"}, {"run_id":"owned", "buffer_id":"page.bin"}, {"run_id":"owned", "address":0x60000}, {"run_id":"owned", "path":"/tmp/page"}): assert c.call("capture_playtest_graphics", **args)["result"]["isError"], args assert len(active["requests"]) == count, "Invalid graphics selections reached the host" too_large_png = base64.b64encode(b"\x89PNG\r\n\x1a\n" + b"x"*(350001-8)).decode() malformed = [None, {}, [], [displayed]*3, [None], ["image"], [{}], [{"png_base64":None}], [{"png_base64":[]}], [{"png_base64":True}], [{"png_base64":"not base64!"}], [{"png_base64":base64.b64encode(b"not a PNG").decode()}], [{"png_base64":base64.b64encode(b"\x89PNG\r\n\x1a").decode()}], [{"png_base64":too_large_png}], [displayed, {"png_base64":"!"}]] for rows in malformed: active["playtest_graphics"] = dict(run_id="owned", buffers=rows) result = c.call("capture_playtest_graphics", run_id="owned")["result"] assert result["isError"], rows if not isinstance(rows, list) else len(rows) assert not any(item["type"] == "image" for item in result["content"]) assert "structuredContent" not in result active["playtest_graphics"] = dict(run_id="owned") assert c.call("capture_playtest_graphics", run_id="owned")["result"]["isError"] del active["playtest_graphics"] # New diagnostics/audio grants opt in without changing older # discovery. Audio is execution, not a read-only observation. for kind, toolset, play, audio, diagnostic in ( ("cmoc", 6, True, True, True), ("assembly", 7, True, True, True), ("cmoc", 7, False, True, True), ("cmoc", 7, True, "yes", False), ("cmoc", 7, True, True, True)): write_grant(kind=kind, toolset=toolset, playtest=play, playtestAudio=audio, projectDiagnostics=diagnostic, projectRefresh=True, customMake=True, token=active["token"]) with Client(helper, grant_file) as c: c.handshake("2025-11-25") catalog = {t["name"]: t for t in c.request("tools/list")["result"]["tools"]} has_audio = kind == "cmoc" and toolset >= 7 and play is True and audio is True has_log = kind == "cmoc" and toolset >= 7 and diagnostic is True assert ("capture_playtest_audio" in catalog) == has_audio assert ("get_build_log" in catalog) == has_log if has_log: active["build_log"] = dict(build_id="build", text="warning: first\nerror: actual failure\n", offset=0, next_offset=None, process_output_truncated=False) assert c.call("get_build_log", build_id="build", offset=0, limit=32768)["result"]["structuredContent"] == active["build_log"] count = len(active["requests"]) for args in ({"build_id":"build", "limit":32769}, {"build_id":"build", "limit":0}, {"build_id":"build", "offset":-1}, {"build_id":"build", "path":"/tmp/private"}): assert c.call("get_build_log", **args)["result"]["isError"] assert count == len(active["requests"]) del active["build_log"] if not has_audio: continue assert catalog["capture_playtest_audio"]["annotations"]["readOnlyHint"] is False payload = struct.pack("<8h", 0,0,100,100,-100,-100,0,0) wav = (b"RIFF" + struct.pack("