sim-mirror 0.2.0__py3-none-any.whl

sim_mirror/__init__.py

@@ -0,0 +1,6 @@
+# SPDX-License-Identifier: Apache-2.0
+"""SimMirror: mirror and drive the iOS Simulator from AI agents and the browser."""
+
+from sim_mirror._version import __version__
+
+__all__ = ["__version__"]

sim_mirror/__main__.py

@@ -0,0 +1,7 @@
+# SPDX-License-Identifier: Apache-2.0
+"""``python -m sim_mirror``: the same as the ``sim-mirror`` command."""
+
+from sim_mirror.cli.main import main
+
+if __name__ == "__main__":  # pragma: no cover - run as a module
+    raise SystemExit(main())

sim_mirror/_version.py

@@ -0,0 +1,4 @@
+# SPDX-License-Identifier: Apache-2.0
+"""The package version, read by the build backend and by `sim-mirror version`."""
+
+__version__ = "0.2.0"

sim_mirror/api.py

@@ -0,0 +1,98 @@
+# SPDX-License-Identifier: Apache-2.0
+"""The surface a host application embeds SimMirror through.
+
+A host builds one `Runtime` from its seams -- where settings come from, where state lives, which device a scope
+remembers, what a scope may do, who is asking, and the words its messages use -- mounts the router factories under its
+own prefixes, and gives its agents the relay's command line. Everything a host needs is named here; anything else in
+the package may change between minor versions.
+
+What that promise is worth, and when it starts binding, is `docs/stability.md`: while SimMirror is 0.x these names
+can still change in a minor release, and from 1.0 they cannot. `tests/unit/test_api.py` writes the list down so one
+cannot leave it by accident.
+
+Three of these are here because a real host needed them and had to reach past this surface to get them:
+`InvalidScope`, which `Scope` raises; `JsonDeviceMemory`, so a host need not write a `DeviceMemory` of its own; and
+`claims_dir`, which is how every host on one Mac sees the same device claims and so refuses each other's devices
+rather than fighting over one.
+
+A host that lets a page change its settings mounts `create_settings_router` with a `SettingsStore`, a
+`SettingsAuthenticator` and, for the settings a page may not change alone, `Confirmations`. One that keeps its own
+settings screens mounts none of it.
+
+A host can also run no SimMirror of its own and share the local daemon with other hosts instead: `DaemonHost`, with a
+host token for its namespaces, answering `AgentAccess` for its agents and raising `DaemonRefused` or
+`DaemonUnavailable`.
+"""
+
+from __future__ import annotations
+
+from sim_mirror.config.model import SimConfig
+from sim_mirror.config.provenance import SettingOrigin
+from sim_mirror.core.devices import JsonDeviceMemory
+from sim_mirror.core.manager import SimulatorUnavailable
+from sim_mirror.core.runtime import Runtime
+from sim_mirror.host_copy import HostCopy
+from sim_mirror.hosting import AgentAccess, DaemonHost, DaemonRefused
+from sim_mirror.mcp.launcher import DaemonUnavailable
+from sim_mirror.mcp.relay import relay_command
+from sim_mirror.scope import InvalidScope, Scope
+from sim_mirror.seams import (
+    Admission,
+    Authenticator,
+    Caller,
+    ConfigSource,
+    Confirmations,
+    DeviceMemory,
+    HeldDevice,
+    Person,
+    Policy,
+    Refused,
+    SettingsAuthenticator,
+    SettingsEditor,
+    SettingsRefused,
+    SettingsStore,
+    StateStore,
+    UsageProbe,
+)
+from sim_mirror.server.agent_routes import create_agent_router
+from sim_mirror.server.http_routes import create_http_router
+from sim_mirror.server.settings_routes import create_settings_router
+from sim_mirror.server.socket_routes import create_socket_router
+from sim_mirror.storage.app_support import claims_dir
+
+__all__ = [
+    "Admission",
+    "AgentAccess",
+    "Authenticator",
+    "Caller",
+    "ConfigSource",
+    "Confirmations",
+    "DaemonHost",
+    "DaemonRefused",
+    "DaemonUnavailable",
+    "DeviceMemory",
+    "HeldDevice",
+    "HostCopy",
+    "InvalidScope",
+    "JsonDeviceMemory",
+    "Person",
+    "Policy",
+    "Refused",
+    "Runtime",
+    "Scope",
+    "SettingOrigin",
+    "SettingsAuthenticator",
+    "SettingsEditor",
+    "SettingsRefused",
+    "SettingsStore",
+    "SimConfig",
+    "SimulatorUnavailable",
+    "StateStore",
+    "UsageProbe",
+    "claims_dir",
+    "create_agent_router",
+    "create_http_router",
+    "create_settings_router",
+    "create_socket_router",
+    "relay_command",
+]

sim_mirror/build/__init__.py

@@ -0,0 +1,2 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Building and testing an app for a scope's device, off unless ``build.tools`` is on."""

sim_mirror/build/destination.py

@@ -0,0 +1,82 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Another simulator a test run may use: `sim_test`'s ``destination``.
+
+A test run uses the scope's own device unless the call names another -- to run the tests on an older iOS, or on an
+iPad, without changing which device the scope shows. It is named the way a person names it, ``{"name": "iPhone 17"}``
+or ``{"udid": "…"}``, with ``"runtime": "iOS 26.5"`` to choose between simulators of one name, and must be one of the
+iOS simulators the scope's Xcode lists (`DeviceManager.devices`). A name that matches none, or several, is refused
+with the ones there are, so an agent can pick again rather than guess.
+
+Whether the device is someone else's to use is the provider's to ask (`build/provider.py`): this only reads the call.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import NoReturn
+
+from sim_mirror.build.xcodebuild import BuildRefused
+from sim_mirror.platform.simctl import is_udid
+from sim_mirror.protocol import DeviceChoice
+
+#: The keys a destination may have.
+KEYS = frozenset({"name", "udid", "runtime"})
+#: The longest name or runtime a destination may give.
+TEXT_MAX = 100
+#: The most simulators a refusal lists; the rest are counted.
+LISTED_MAX = 20
+
+USAGE = (
+    'destination is {"name": "iPhone 17"} or {"udid": "…"}, with "runtime": "iOS 26.5" to choose between '
+    "simulators of one name"
+)
+
+
+def _text(value: object) -> str | None:
+    if value is None:
+        return None
+    if not isinstance(value, str) or not value.strip() or len(value) > TEXT_MAX or not value.isprintable():
+        raise BuildRefused(USAGE)
+    return value.strip()
+
+
+def described(choice: DeviceChoice) -> str:
+    return f"{choice['name']} ({choice['runtime']})"
+
+
+def _listed(choices: Sequence[DeviceChoice]) -> str:
+    shown = ", ".join(described(choice) for choice in choices[:LISTED_MAX])
+    more = len(choices) - LISTED_MAX
+    return shown + (f" and {more} more" if more > 0 else "") if shown else "none"
+
+
+def choose_destination(choices: Sequence[DeviceChoice], value: object) -> DeviceChoice:
+    """The simulator a call's ``destination`` names, from the ones the scope could use. Raises `BuildRefused`."""
+    if not isinstance(value, dict) or not value.keys() <= KEYS or ("name" in value) == ("udid" in value):
+        raise BuildRefused(USAGE)
+    name, udid, runtime = _text(value.get("name")), _text(value.get("udid")), _text(value.get("runtime"))
+    if udid is not None and not is_udid(udid):
+        raise BuildRefused(f"{udid!r} is not a simulator's udid; {USAGE}")
+    found = [
+        choice
+        for choice in choices
+        if (udid is None or choice["udid"].upper() == udid.upper())
+        and (name is None or choice["name"] == name)
+        and (runtime is None or choice["runtime"] == runtime)
+    ]
+    if len(found) == 1:
+        return found[0]
+    if found:
+        _several(name or "", found)
+    wanted = udid or (f"{name} ({runtime})" if runtime else name)
+    raise BuildRefused(f"there is no simulator {wanted} on this Mac for this Xcode; there are {_listed(choices)}")
+
+
+def _several(name: str, found: Sequence[DeviceChoice]) -> NoReturn:
+    runtimes = sorted({choice["runtime"] for choice in found})
+    if len(runtimes) == len(found):
+        raise BuildRefused(f"several simulators are named {name}; add a runtime: {', '.join(runtimes)}")
+    raise BuildRefused(
+        f"several simulators are named {name} on one runtime; name one by udid: "
+        + ", ".join(f"{choice['udid']} ({choice['runtime']})" for choice in found[:LISTED_MAX])
+    )

sim_mirror/build/provider.py

@@ -0,0 +1,176 @@
+# SPDX-License-Identifier: Apache-2.0
+"""The build tools -- `sim_build_run` and `sim_test` -- listed while a scope's ``build.tools`` is on.
+
+A build runs xcodebuild, which is running commands: the tools are refused on every call unless the host also lets the
+scope run commands (`Policy.shells_allowed`). A build that succeeded is installed and launched on the scope's device,
+drawn for anyone watching; while tests run the device takes no agent gestures, and every screen watching is told why.
+
+A test run may be sent to another simulator on this Mac instead (`destination`). Not to one that is somebody else's:
+another scope's running device, one another scope's tests are running on, or one another process on the Mac has
+claimed. xcodebuild boots it if it has to, and it is left running, as Xcode leaves it.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from sim_mirror.build.destination import choose_destination, described
+from sim_mirror.build.xcodebuild import Build, BuildRefused, BuildRunner
+from sim_mirror.config.model import SimConfig
+from sim_mirror.connectors.base import Capability
+from sim_mirror.core.actions import ActionError
+from sim_mirror.core.instance import DeviceInstance
+from sim_mirror.core.manager import DeviceManager, SimulatorUnavailable
+from sim_mirror.platform.simctl import SimctlError
+from sim_mirror.tools.context import Tool, ToolContext, flag_arg, make_tool, ready_device, whole_arg
+from sim_mirror.tools.results import Result, ToolRefused, text
+from sim_mirror.tools.schemas import (
+    BUILD_INSTRUCTIONS,
+    BUILD_WAIT_BOUNDS,
+    BUILD_WAIT_S,
+    SHELL_INSTRUCTIONS,
+    TEST_RETRIES_BOUNDS,
+)
+
+NEEDS = (Capability.LIFECYCLE, Capability.APP_INSTALL, Capability.APP_LAUNCH)
+
+
+def _builds(ctx: ToolContext) -> tuple[BuildRunner, Path]:
+    """The build runner and the build folder -- or why this scope builds nothing now."""
+    if not ctx.config.build_tools:
+        raise ToolRefused(ctx.copy.build_tools_off())
+    if not ctx.shells_allowed:
+        raise ToolRefused(ctx.copy.shells_not_allowed())
+    if ctx.builds is None:
+        raise ToolRefused("The build runner is not running.")
+    if ctx.folder is None:
+        raise ToolRefused(ctx.copy.no_build_folder())
+    return ctx.builds, ctx.folder
+
+
+async def _install_and_launch(build: Build, instance: DeviceInstance, ctx: ToolContext) -> list[str]:
+    """Put a build that succeeded on the device and open it, drawn for anyone watching."""
+    if build.app is None or build.bundle_id is None:
+        others = [name for name in build.schemes if name != build.scheme]
+        there = f"; the other schemes are {', '.join(others)}" if others else ""
+        raise BuildRefused(
+            f"{build.scheme} builds no app to install -- a framework or a test bundle, say -- so there is nothing to "
+            f"launch; name a scheme that builds an iOS app{there}"
+        )
+    simctl = ctx.manager.simctl(instance)
+    try:
+        installing = simctl.install(instance.udid, str(build.app))
+        await ctx.actions.announced(instance, ctx.caller, "app", f"install {build.app.name}", installing)
+        launching = simctl.launch(instance.udid, build.bundle_id)
+        pid = await ctx.actions.announced(instance, ctx.caller, "app", f"launch {build.bundle_id}", launching)
+    except (SimctlError, ActionError) as exc:
+        raise BuildRefused(str(exc)) from exc
+    if pid is not None:
+        instance.launched[build.bundle_id] = pid
+    return [f"installed {build.app.name}", f"launched {build.bundle_id}" + (f" (pid {pid})" if pid else "")]
+
+
+def _keep_busy(manager: DeviceManager, instance: DeviceInstance, build: Build) -> None:
+    """Tests drive the device themselves: an agent's gestures would land in the middle of them.
+
+    Every screen watching is told what the device is busy with, so a person can see why it is not theirs to touch.
+    """
+    busy = f"running tests ({build.id})"
+    instance.busy = busy
+    manager.publish_status(instance)
+
+    def free(_: object) -> None:
+        if instance.busy == busy:
+            instance.busy = None
+            manager.publish_status(instance)
+
+    assert build.task is not None
+    build.task.add_done_callback(free)
+
+
+async def _elsewhere(ctx: ToolContext, runner: BuildRunner, value: object) -> tuple[str, str] | None:
+    """The simulator a test run's ``destination`` names, and how its answer names it -- None for the scope's own
+    device -- or why it is not this scope's to use."""
+    try:
+        choices = await ctx.manager.devices(ctx.scope)
+    except SimulatorUnavailable as exc:
+        raise ToolRefused(str(exc)) from exc
+    choice = choose_destination(choices, value)
+    udid, named = choice["udid"], described(choice)
+    own = ctx.manager.instance(ctx.scope)
+    if own is not None and own.udid == udid:
+        return None
+    noun = ctx.copy.scope_noun
+    if any(instance.udid == udid for instance in ctx.manager.instances()):
+        raise BuildRefused(f"{named} is another {noun}'s simulator here; name one nobody is using")
+    if any(build.udid == udid and build.scope.id != ctx.scope.id for build in runner.runs()):
+        raise BuildRefused(f"another {noun}'s tests are running on {named}; name another simulator")
+    claim = await ctx.manager.holder(udid)
+    if claim is not None:
+        raise BuildRefused(ctx.copy.claimed(claim.owner, claim.pid))
+    return udid, named
+
+
+async def _run(args: dict[str, Any], ctx: ToolContext, kind: str) -> Result:
+    runner, folder = _builds(ctx)
+    wait_s = whole_arg(args.get("wait_s"), BUILD_WAIT_S, BUILD_WAIT_BOUNDS, "wait_s")
+    if args.get("build_id") is not None:
+        return text(await runner.result(ctx.scope.id, args["build_id"], wait_s))
+    if kind == "build" and args.get("destination") is not None:
+        raise ToolRefused("destination is for sim_test: a build is installed and launched on your own simulator")
+    elsewhere = await _elsewhere(ctx, runner, args["destination"]) if args.get("destination") is not None else None
+    instance: DeviceInstance | None = None
+    if elsewhere is not None:
+        udid, device = elsewhere
+    else:
+        instance = await ready_device(ctx)
+        udid, device = instance.udid, ""
+
+    async def after(build: Build) -> list[str]:
+        assert instance is not None
+        return await _install_and_launch(build, instance, ctx)
+
+    build = await runner.start(
+        ctx.scope,
+        kind=kind,
+        folder=folder,
+        udid=udid,
+        developer_dir=instance.developer_dir if instance else ctx.config.developer_dir,
+        device=device,
+        configuration=args.get("configuration") or ctx.config.build_configuration,
+        timeout_s=ctx.config.build_timeout_minutes * 60,
+        scheme=args.get("scheme"),
+        project=args.get("project"),
+        workspace=args.get("workspace"),
+        only_testing=args.get("only_testing"),
+        skip_testing=args.get("skip_testing"),
+        test_plan=args.get("test_plan"),
+        retries=whole_arg(args.get("retries"), 0, TEST_RETRIES_BOUNDS, "retries"),
+        warnings=flag_arg(args.get("warnings"), "warnings"),
+        test_diagnostics=ctx.config.build_test_diagnostics,
+        after=after if kind == "build" else None,
+    )
+    if kind == "test" and instance is not None:
+        _keep_busy(ctx.manager, instance, build)
+    return text(await runner.result(ctx.scope.id, build.id, wait_s))
+
+
+async def _build_run(args: dict[str, Any], ctx: ToolContext) -> Result:
+    return await _run(args, ctx, "build")
+
+
+async def _test(args: dict[str, Any], ctx: ToolContext) -> Result:
+    return await _run(args, ctx, "test")
+
+
+class BuildToolProvider:
+    """The build tools: listed while ``build.tools`` is on; otherwise the agent is told to build from its shell."""
+
+    tools: tuple[Tool, ...] = (make_tool("sim_build_run", NEEDS, _build_run), make_tool("sim_test", NEEDS, _test))
+
+    def offered(self, config: SimConfig) -> bool:
+        return config.build_tools
+
+    def instructions(self, config: SimConfig) -> str:
+        return BUILD_INSTRUCTIONS if config.build_tools else SHELL_INSTRUCTIONS