dsh-engineering-ui 0.0.0-stage → 1.5.0

package/engineering/tools/webots_mcp/runtime.py

@@ -0,0 +1,311 @@
+"""Single-instance scheduler. All ledger changes occur on the MCP event-loop thread."""
+import asyncio
+import json
+from datetime import datetime, timedelta, timezone
+import sqlite3
+import time
+from uuid import uuid4
+
+from .ledger import Ledger, now
+from .fault_resources import budget_check
+
+
+class Runtime:
+    def __init__(self,state,root,config,backend=None):
+        if backend is None:
+            from .transport import Transport
+            backend = Transport
+        self.backend = backend
+        self.state,self.root,self.config = state,root,config
+        if not {"process_count","wall_time_s","private_bytes"} <= set(config["limits"]):
+            raise ValueError("Explicit process, wall and private memory ceilings required")
+        budget_check({},config["limits"])
+        self.ledger = Ledger(state)
+        self.owner = self.live = self.monitor = None
+        self.jobs = {}
+        self.controls = {}
+        self.serial = asyncio.Lock()
+        self.cleanup = asyncio.Lock()
+        self.progress = dict(completed_steps=None,sim_time=None)
+        self.observed = None
+        self.sample_at = None
+        self.next_projection = 0.
+        self.poisoned = False
+        self.closing = False
+        self.last_error = None
+        try:
+            self.project("NEW")
+        except BaseException:
+            self.ledger.close()
+            raise
+
+    def project(self,state):
+        from .evidence import _atomic_write
+        owner = self.owner or (None,None,None,None)
+        stamp = datetime.now(timezone.utc)
+        ready = bool(self.live and self.live.connected and self.backend.provenance=="real-webots" and not self.poisoned)
+        snapshot = dict(schema_version=1,task_id=owner[0],room_id=owner[1],run_id=owner[2],
+            session_generation=owner[3],job_state=state,core_ready=ready,stale=not ready,
+            snapshot_at=stamp.isoformat(),valid_until=(stamp+timedelta(seconds=2)).isoformat(),
+            provenance=self.backend.provenance,diagnostic=self.last_error,**self.progress)
+        _atomic_write(self.state/"webots_state.json",json.dumps(snapshot,allow_nan=False).encode())
+
+    def fail(self,result,code,hint):
+        return dict(result,ok=False,error_code=code,hint=hint)
+
+    def owned(self,row,a):
+        return row and (row["task"],row["room"]) == (a["task_id"],a["room_id"])
+
+    def snapshot(self,row,request):
+        result = dict(json.loads(row["result"]),request_id=request)
+        live = (self.owner == (row["task"],row["room"],row["run"],row["gen"])
+                and self.live and self.live.connected and not self.poisoned)
+        result.update(core_ready=bool(live and self.backend.provenance == "real-webots"),
+                      stale=not bool(live))
+        if self.poisoned and row["phase"] == "dispatched":
+            result.update(ok=False,error_code="OUTCOME_UNKNOWN",execution_state="unknown",job_state="UNKNOWN",
+                          core_ready=False,stale=True,hint="Result commit unavailable. Do not replay.")
+        return result
+
+    async def dispatch(self,name,a,r,input_path=None):
+        r.update(provenance=self.backend.provenance,hint="Query sim_job by job/run/generation. Unknown actions must not be replayed.")
+        try:
+            return await self._dispatch(name,a,r,input_path)
+        except (sqlite3.Error,OSError) as err:
+            self.poisoned = True
+            return self.fail(r,"LEDGER_IO_ERROR",str(err)[:200])
+
+    async def _dispatch(self,name,a,r,input_path):
+        scope = (a["task_id"],a["room_id"])
+        if name == "sim_status":
+            visible = self.owner and self.owner[:2] == scope
+            ready = bool(visible and self.live and self.live.connected and not self.poisoned)
+            return dict(r,ok=True,core_ready=ready and self.backend.provenance == "real-webots",job_state="READY" if ready else "NEW",
+                        session_generation=self.owner[3] if visible else None,
+                        run_id=self.owner[2] if visible else None,stale=not ready,
+                        snapshot_at=(self.sample_at or self.observed) if visible else r["snapshot_at"],
+                        diagnostic=self.last_error if visible else None, **(self.progress if visible else {}))
+        if name == "sim_job":
+            row = self.ledger.lookup("job",a["job_id"])
+            if not self.owned(row,a) or (row["run"],row["gen"]) != (a["run_id"],a["session_generation"]):
+                return self.fail(r,"JOB_NOT_FOUND","No job in this scope")
+            return self.snapshot(row,a["request_id"])
+        op = a.get("operation_id")
+        digest = self.ledger.digest(name,a)
+        if op and (row := self.ledger.lookup("op",op)):
+            if not self.owned(row,a) or row["digest"] != digest:
+                return self.fail(r,"OPERATION_CONFLICT","Operation ID already bound")
+            return self.snapshot(row,a["request_id"])
+        if input_path is not None:
+            try:
+                for key,suffix in (("world_path",".wbt"),("urdf_path",".urdf")):
+                    if key in a:
+                        input_path(a[key],suffix)
+            except (ValueError,OSError) as error:
+                return self.fail(r,"INVALID_ARGUMENT",str(error)[:256])
+        if self.poisoned:
+            return self.fail(r,"LEDGER_IO_ERROR","Persistence failed; restart and reconcile")
+        if name == "sim_convert":
+            return self.fail(r,"UNSUPPORTED","Converter requires calibrated binding")
+        if name == "sim_launch":
+            if self.owner or self.closing:
+                return self.fail(r,"INSTANCE_BUSY","One active session per state root")
+            if a["world_path"] not in self.config["worlds"]:
+                return self.fail(r,"UNBOUND_WORLD","Explicit approved world hash and robot required")
+            run,gen = "run-"+uuid4().hex,1
+        else:
+            run,gen = a["run_id"],a["session_generation"]
+            if self.owner != (*scope,run,gen):
+                return self.fail(r,"STALE_SESSION","Run/generation is not live in this scope")
+        if name in ("sim_field","sim_scene","sim_devices"):
+            if not self.live or not self.live.connected or self.serial.locked() or self.jobs:
+                return self.fail(r,"WORKER_BUSY","Read only in an idle verified session")
+            async with self.serial:
+                try:
+                    data = await asyncio.wait_for(self.live.command(name,a,lambda *_:None),5)
+                    return dict(r,**data,ok=True,execution_state="completed",stale=False)
+                except Exception as err:
+                    await self.invalidate()
+                    return self.fail(r,"WORKER_DISCONNECTED",str(err))
+        if name == "sim_cancel":
+            target = self.ledger.lookup("job",a["job_id"])
+            if not self.owned(target,a) or (target["run"],target["gen"]) != (run,gen):
+                return self.fail(r,"JOB_NOT_FOUND","Target outside active session")
+        if (len(self.jobs)>=16 and name!="sim_cancel") or (len(self.controls)>=16 and name=="sim_cancel"):
+            return self.fail(r,"QUEUE_FULL","Session queue is bounded")
+        r.update(run_id=run,session_generation=gen,job_id="job-"+uuid4().hex,ok=True,
+                 job_state="QUEUED",execution_state="not_started",stale=False)
+        self.ledger.accept(a,digest,r)
+        if name == "sim_launch":
+            self.last_error = None
+            self.owner = (*scope,run,gen)
+            self.world_path = a["world_path"]
+            self.progress = dict(completed_steps=None,sim_time=None)
+            self.observed = now()
+            self.sample_at = None
+        if name == "sim_cancel":
+            self.ledger.finish(op,"dispatched",job_state="RUNNING",execution_state="running")
+            task = asyncio.create_task(self.cancel_target(op,target,scope,run,gen))
+            self.controls[op] = task
+            task.add_done_callback(lambda _:self.controls.pop(op,None))
+            return await asyncio.shield(task)
+        task = asyncio.create_task(self.execute(name,a,op,self.owner))
+        self.jobs[op] = task
+        task.add_done_callback(lambda _:self.jobs.pop(op,None))
+        return r
+
+    async def cancel_target(self,op,target,scope,run,gen):
+        try:
+            job = self.jobs.get(target["op"])
+            if job:
+                job.cancel()
+                await asyncio.gather(job,return_exceptions=True)
+                # Task may have been cancelled before its coroutine started.
+                if self.ledger.lookup("op",target["op"])["phase"] == "accepted":
+                    if self.live is None and self.owner == (*scope,run,gen):
+                        await self.invalidate()
+                    self.ledger.finish(target["op"],"rejected",ok=False,error_code="CANCELLED_BEFORE_DISPATCH",
+                                       job_state="CANCELLED",execution_state="not_started")
+            return self.ledger.finish(op,"done",job_state="COMPLETED",execution_state="completed",
+                                      data={"target_job":target["job"],"rollback_confirmed":False})
+        except (OSError,sqlite3.Error):
+            self.poisoned = True
+            return self.snapshot(self.ledger.lookup("op",op),None)
+
+    def observe(self,name,a,op,owner,out):
+        from .evidence import EvidenceStore
+        store = EvidenceStore(self.state,task_id=owner[0],room_id=owner[1])
+        identity = self.live.identity
+        data = out["data"]
+        generation = self.owner[3]
+        observation = dict(run_id=owner[2],generation=generation,world_sha256=identity["world_sha256"],
+            robot=identity["robot"],sim_time=out["sim_time"],step=out["completed_steps"],action=name,
+            operation_id=op,targets=[{"def":data["node_def"],"node_id":data["node_id"]}] if "node_def" in data else [],
+            measurement=data,model_sha256=identity["model_sha256"])
+        producer = dict(name="webots_mcp.controller_worker",version="A04",source_revision=None)
+        raw = json.dumps(observation,ensure_ascii=False,sort_keys=True,allow_nan=False).encode()
+        items = [store.save_snapshot(owner[2],"obs-"+op+".json",raw,kind="observation",
+                                     provenance="real-webots",producer=producer)]
+        if name == "sim_screenshot":
+            filename = "capture-"+op+".jpg"
+            image = (self.live.dir/filename).read_bytes()
+            import hashlib
+            if hashlib.sha256(image).hexdigest() != data["sha256"]:
+                raise ValueError("Screenshot bytes changed after capture")
+            items.append(store.save_snapshot(owner[2],filename,image,kind="screenshot",
+                                             provenance="real-webots",producer=producer))
+        if name == "sim_launch":
+            report = store.new_report("experiment_report",owner[2],provenance="real-webots",
+                data={"runtime_identity":identity,"model":{"sha256":identity["model_sha256"]}},
+                evidence=items,missing_information=["paired_trace","calibration","collision_coverage","physical_gate"])
+            store.write_report(report)
+        store.append_log(owner[2],json.dumps(dict(action=name,operation_id=op,generation=generation,
+            completed_steps=out["completed_steps"],sim_time=out["sim_time"],evidence=items),allow_nan=False)+"\n")
+        return items
+
+    async def execute(self,name,a,op,owner):
+        dispatched = False
+        try:
+            async with self.serial:
+                if self.owner != owner or self.closing or self.poisoned:
+                    raise RuntimeError("Session invalidated before dispatch")
+                self.ledger.finish(op,"dispatched",job_state="RUNNING",execution_state="running",**self.progress)
+                self.project("STARTING" if name in ("sim_launch","sim_reset") else "RUNNING")
+                dispatched = True
+                def progress(n,t):
+                    self.progress = dict(completed_steps=n,sim_time=t)
+                    self.observed = now()
+                    self.ledger.finish(op,"dispatched",**self.progress)
+                if name in ("sim_launch","sim_reset"):
+                    generation = owner[3]
+                    if name == "sim_reset":
+                        if self.monitor:
+                            self.monitor.cancel()
+                        await self.live.close()
+                        generation += 1
+                        self.owner = (*owner[:3],generation)
+                    if self.backend.provenance == "real-webots":
+                        from .evidence import EvidenceStore
+                        store = EvidenceStore(self.state,task_id=owner[0],room_id=owner[1])
+                        store._run(owner[2],claim=True)
+                    self.live = self.backend(self.state,self.root,self.config,owner[2],generation)
+                    self.monitor = asyncio.create_task(self.watch())
+                    call = self.live.launch(dict(a,world_path=self.world_path))
+                else:
+                    call = self.live.command(name,a,progress)
+                out = await asyncio.wait_for(call,30)
+                self.progress = {k:out[k] for k in ("completed_steps","sim_time")}
+                self.observed = now()
+                if name == "sim_reset":
+                    out["data"]["new_generation"] = generation
+                if self.backend.provenance == "real-webots":
+                    out["evidence"] = self.observe(name,a,op,owner,out)
+                if name == "sim_shutdown":
+                    await self.invalidate()
+                self.project("READY" if self.live else "COMPLETED")
+                self.ledger.finish(op,"done",job_state="COMPLETED",execution_state="completed",
+                                   core_ready=bool(self.live and self.live.connected and self.backend.provenance == "real-webots"),**out)
+        except (Exception,asyncio.CancelledError) as err:
+            try:
+                self.last_error = self.last_error or str(err) or "Cancellation requested"
+                if dispatched or (name == "sim_launch" and self.owner == owner):
+                    await self.invalidate()
+                self.ledger.finish(op,"unknown" if dispatched else "rejected",ok=False,
+                    error_code="OUTCOME_UNKNOWN" if dispatched else "NOT_DISPATCHED",
+                    execution_state="unknown" if dispatched else "not_started",
+                    job_state="UNKNOWN" if dispatched else "FAILED",stale=True,
+                    hint=(self.last_error or str(err) or "Cancellation; no rollback proof")[:256])
+            except Exception as failure:
+                self.last_error = str(failure)
+                self.poisoned = True
+            if isinstance(err,sqlite3.Error):
+                self.poisoned = True
+
+    async def watch(self):
+        try:
+            while self.live:
+                await asyncio.sleep(.25)
+                if not self.live:
+                    return
+                self.live.sample()
+                self.sample_at = now()
+                if self.live.connected and time.monotonic() >= self.next_projection:
+                    self.next_projection = time.monotonic()+1
+                    self.project("RUNNING" if self.serial.locked() else "READY")
+        except Exception as err:
+            self.last_error = str(err)[:256]
+            running = [op for op in self.jobs if self.ledger.lookup("op",op)["phase"] == "dispatched"]
+            for op in running:
+                self.jobs[op].cancel()
+            if not running:
+                await self.invalidate()
+
+    async def invalidate(self):
+        async with self.cleanup:
+            await self._invalidate()
+
+    async def _invalidate(self):
+        self.closing = True
+        self.owner = None
+        if self.monitor and self.monitor is not asyncio.current_task():
+            self.monitor.cancel()
+        if self.live:
+            try:
+                await self.live.close()
+            except Exception:
+                self.poisoned = True
+                raise
+        self.live = self.owner = None
+        self.project("UNKNOWN" if self.last_error else "COMPLETED")
+        self.closing = False
+        self.observed = now()
+
+    async def close(self):
+        tasks = list(self.jobs.values())
+        for task in tasks:
+            task.cancel()
+        await asyncio.gather(*tasks,*list(self.controls.values()),return_exceptions=True)
+        try:
+            await self.invalidate()
+        finally:
+            self.ledger.close()

package/engineering/tools/webots_mcp/server.py

@@ -0,0 +1,217 @@
+"""Official MCP SDK stdio transport with explicit unavailable/fake execution."""
+import argparse
+import asyncio
+from datetime import datetime, timezone
+import json
+import logging
+import os
+from pathlib import Path
+import re
+import sys
+
+from jsonschema import Draft202012Validator
+from mcp import types
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+
+from . import __version__
+from .fake_worker import FakeWorker
+
+INSTRUCTIONS = "Bounded Webots runtime and evidence inspection. Execution requires an explicitly pinned local runtime. Native CAD export and repair require calibration. Fake fixtures never prove readiness or physics. Unknown outcomes must not be replayed."
+CAPABILITIES = ["stored_reports", "bounded_evidence", "attribution", "pinned_runtime", "durable_operations"]
+BLOCKED_NATIVE = ["native_mesh_frame", "complete_global_mate_state", "native_identity_calibration",
+                  "converter_physical_precision", "calibrated_collision_feedback", "authorized_native_repair"]
+ID = {"type": "string", "pattern": r"^[A-Za-z0-9][A-Za-z0-9_-]{0,95}(?![\s\S])"}
+TEXT = {"type": "string", "minLength": 1, "maxLength": 256}
+CONTEXT = {key: ID for key in ("task_id", "room_id", "request_id")}
+SESSION = {"run_id": ID, "session_generation": {"type": "integer", "minimum": 1}}
+MUTATIONS = {"sim_launch", "sim_shutdown", "sim_step", "sim_reset", "sim_screenshot",
+             "sim_contacts", "sim_convert", "sim_motor", "sim_sensor", "sim_cancel"}
+
+
+def tool(name, description, properties=None, *, scoped=True, optional=()):
+    fields = {**CONTEXT, **(SESSION if scoped else {}), **(properties or {})}
+    if name in MUTATIONS:
+        fields["operation_id"] = ID
+    return types.Tool(name=name, description=description, inputSchema={
+        "type": "object", "properties": fields,
+        "required": [key for key in fields if key not in optional], "additionalProperties": False})
+
+
+TOOLS = [
+    tool("sim_status", "Cached availability; never starts Webots.", scoped=False),
+    tool("sim_launch", "Submit a pinned world job when a runtime is configured.", {"world_path": TEXT}, scoped=False),
+    tool("sim_shutdown", "Request owned-session shutdown and confirm exit."),
+    tool("sim_step", "Submit bounded steps.", {"steps": {"type": "integer", "minimum": 1, "maximum": 1000}}),
+    tool("sim_reset", "Cold-reset a pinned world into a new generation."),
+    tool("sim_scene", "Read scene snapshot."),
+    tool("sim_field", "Read one node field.", {"node": TEXT, "field": TEXT}),
+    tool("sim_screenshot", "Request an on-demand view."),
+    tool("sim_contacts", "Request contact observation; no physical verdict.", {"node": TEXT}),
+    tool("sim_convert", "Conversion requires a calibrated converter binding.", {"urdf_path": TEXT}, scoped=False),
+    tool("sim_devices", "Discover devices of the owned robot."),
+    tool("sim_motor", "Submit one motor command.", {"device": TEXT, "velocity": {"type": "number"},
+         "position": {"type": "number"}}, optional=("position",)),
+    tool("sim_sensor", "Request one sensor sample.", {"device": TEXT}),
+    tool("sim_job", "Read job snapshot; unknown must not be replayed.", {"job_id": ID}),
+    tool("sim_cancel", "Request cancellation; acknowledgement is not rollback.", {"job_id": ID}),
+    tool("sim_report", "Read an owned stored report.", {"run_id": ID, "report_type": {
+         "enum": ["model_manifest", "conversion_report", "experiment_report"]}}, scoped=False),
+    tool("sim_attribute", "Inspect one owned issue; retain all candidates and evidence levels. Never writes CAD.",
+         {"run_id": ID, "issue_id": ID}, scoped=False),
+    tool("sim_evidence", "Read an owned bounded log page.", {"run_id": ID, "name": ID,
+         "offset": {"type": "integer", "minimum": 0},
+         "limit": {"type": "integer", "minimum": 4, "maximum": 16384},
+         "expected_sha256": {"type": "string", "pattern": r"^[a-f0-9]{64}(?![\s\S])"}},
+         scoped=False, optional=("name", "offset", "limit", "expected_sha256")),
+]
+TOOL_INDEX = {item.name: item for item in TOOLS}
+
+
+class PeripheralServer:
+    def __init__(self, state_dir, *, input_root, fake_worker=None, runtime_config=None):
+        self.state_dir = Path(state_dir).resolve(strict=True)
+        self.input_root = Path(input_root).resolve(strict=True)
+        if not self.state_dir.is_dir() or not self.input_root.is_dir():
+            raise ValueError("State and input roots must be existing directories")
+        self.runtime = None
+        if runtime_config is not None:
+            if fake_worker:
+                raise ValueError("Select exactly one worker backend")
+            from .runtime import Runtime
+            self.runtime = Runtime(self.state_dir,self.input_root,runtime_config)
+        self.worker = FakeWorker(fake_worker) if fake_worker else None
+
+    def envelope(self, args):
+        result = {key: args.get(key) for key in (
+            "run_id", "job_id", "request_id", "operation_id", "session_generation", "task_id", "room_id")}
+        for key, value in result.items():
+            valid = (type(value) is int and value >= 1) if key == "session_generation" else (
+                isinstance(value, str) and re.fullmatch(ID["pattern"], value))
+            if not valid:
+                result[key] = None
+        result.update(schema_version=1, ok=False, error_code=None, execution_state="not_started",
+                      sim_time=None, completed_steps=None, evidence=[], core_ready=False,
+                      provenance="fake" if self.worker else "unavailable", job_state="NEW",
+                      snapshot_at=datetime.now(timezone.utc).isoformat(), stale=True,
+                      capabilities=CAPABILITIES, blocked_native=BLOCKED_NATIVE,
+                      hint="Runtime is opt-in; native CAD export and repair await measured calibration.")
+        return result
+
+    def input_path(self, value, suffix):
+        relative = Path(value)
+        if relative.is_absolute() or ".." in relative.parts or ":" in value or "\\" in value:
+            raise ValueError("Input must be a relative path inside input_root")
+        path = (self.input_root / relative).resolve(strict=True)
+        if not path.is_relative_to(self.input_root) or not path.is_file() or path.suffix.lower() != suffix:
+            raise ValueError("Input path escapes root or has an unsupported file type")
+        return path
+
+    async def dispatch(self, name, args):
+        result = self.envelope(args if isinstance(args, dict) else {})
+        if name not in TOOL_INDEX:
+            result["error_code"] = "UNKNOWN_TOOL"
+            return result
+        try:
+            json.dumps(args, allow_nan=False)
+            errors = list(Draft202012Validator(TOOL_INDEX[name].inputSchema).iter_errors(args))
+            if errors:
+                raise ValueError(errors[0].message)
+            for key, suffix in (("world_path", ".wbt"), ("urdf_path", ".urdf")):
+                if key in args and not self.runtime:
+                    self.input_path(args[key], suffix)
+        except (ValueError, TypeError, OSError) as error:
+            result.update(error_code="INVALID_ARGUMENT", hint=str(error)[:256])
+            return result
+        if name in ("sim_report", "sim_evidence", "sim_attribute"):
+            try:
+                from .evidence import EvidenceStore
+                store = EvidenceStore(self.state_dir, task_id=args["task_id"], room_id=args["room_id"])
+                if name == "sim_report":
+                    data = store.read_report(args["run_id"], args["report_type"])
+                elif name == "sim_attribute":
+                    from .repair import attribute
+                    data = attribute(store, args["run_id"], args["issue_id"])
+                else:
+                    page_args = {key: args[key] for key in ("name", "offset", "limit", "expected_sha256") if key in args}
+                    data = store.read_log(args["run_id"], **page_args)
+                result.update(ok=True, execution_state="completed", data=data)
+            except ImportError:
+                result["error_code"] = "EVIDENCE_UNAVAILABLE"
+            except PermissionError:
+                result["error_code"] = "OWNERSHIP_MISMATCH"
+            except FileNotFoundError:
+                result["error_code"] = "EVIDENCE_NOT_FOUND"
+            except (ValueError, TypeError, KeyError, AttributeError) as error:
+                result.update(error_code="EVIDENCE_INVALID", hint=str(error)[:256])
+            except OSError as error:
+                result.update(error_code="EVIDENCE_IO_ERROR", hint=str(error)[:256])
+            return result
+        if name == "sim_convert" and not self.worker:
+            result.update(error_code="CALIBRATION_REQUIRED",
+                          hint="Native export/conversion is blocked: measured mesh frame, complete mates and converter precision are unverified.")
+            return result
+        if self.runtime:
+            return await self.runtime.dispatch(name,args,result,self.input_path)
+        if self.worker:
+            return self.worker.dispatch(name, args, result)
+        if name == "sim_status":
+            result.update(ok=True, unsupported=["unconfigured_runtime", "native_export", "native_repair"],
+                          state_dir=str(self.state_dir))
+        else:
+            result["error_code"] = "CORE_NOT_IMPLEMENTED"
+        return result
+
+    def sdk_server(self):
+        server = Server("webots", version=__version__, instructions=INSTRUCTIONS)
+
+        @server.list_tools()
+        async def list_tools():
+            return TOOLS
+
+        @server.call_tool(validate_input=False)
+        async def call_tool(name, arguments):
+            result = await self.dispatch(name, arguments)
+            return types.CallToolResult(
+                content=[types.TextContent(type="text", text=json.dumps(result, ensure_ascii=False, allow_nan=False))],
+                structuredContent=result, isError=not result["ok"])
+
+        return server
+
+
+async def serve(peripheral):
+    server = peripheral.sdk_server()
+    async with stdio_server() as (read_stream, write_stream):
+        await server.run(read_stream, write_stream, server.create_initialization_options())
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--input-root", required=True)
+    parser.add_argument("--fake-worker", choices=("complete", "error", "timeout", "unknown"))
+    parser.add_argument("--runtime-config", type=Path, help="Trusted A04 pinned local runtime configuration")
+    args = parser.parse_args()
+    logging.basicConfig(stream=sys.stderr, level=logging.INFO)
+    declared = os.environ.get("DSH_STATE_DIR")
+    if not declared or not Path(declared).is_dir():
+        parser.error("DSH_STATE_DIR must explicitly name an existing isolated state directory")
+    from _store import state_dir
+    resolved = Path(state_dir()).resolve(strict=True)
+    if resolved != Path(declared).resolve(strict=True):
+        parser.error("Resolved state_dir does not match DSH_STATE_DIR")
+    logging.info("webots state_dir=%s core_ready=false backend=%s", resolved,
+                 "configured" if args.runtime_config else ("fake" if args.fake_worker else "unavailable"))
+    config = json.loads(args.runtime_config.read_text(encoding="utf-8")) if args.runtime_config else None
+    peripheral = PeripheralServer(resolved, input_root=args.input_root, fake_worker=args.fake_worker,runtime_config=config)
+    async def run():
+        try:
+            await serve(peripheral)
+        finally:
+            if peripheral.runtime:
+                await peripheral.runtime.close()
+    asyncio.run(run())
+
+
+if __name__ == "__main__":
+    main()
+