@ycodium-ai/plugin-devices 0.2.3510 → 0.2.3576

package/README.md

@@ -1,103 +1,129 @@
 # @ycodium-ai/plugin-devices
 
-Lets agents drive the iOS Simulators and Android Emulators on a Ycodium machine:
-list them, boot one, take screenshots, and operate it with the `agent-device`
-command line. The plugin is off by default; turning it on is the single switch
-for device support.
+Lets agents list, open, screenshot and operate iOS Simulators and Android Emulators
+on the connected Ycodium machine. The plugin is off by default. Turn it on under
+Settings → Plugins, then open the Devices panel in a conversation.
 
 ## What it does
 
-Nothing is installed or started when the plugin is turned on. The first time an
-agent or a person actually uses a device (listing or opening one), the plugin:
-
-1. Checks which platforms this machine can run. iOS needs macOS with `xcrun`;
-   Android needs an SDK with `adb` and `emulator`. A machine that can run
-   neither installs nothing.
-2. Installs the two device tools at pinned versions into the plugin data
-   directory (`<dataDir>/tools/<package>/<version>`): `expo-device-hub` for the
-   device screens and `agent-device` for driving devices. It downloads its own
-   copy of npm, checks it against a pinned sha512 integrity, and runs it with the
-   Node the Ycodium server runs on. It never uses `npx` or the `node` on `PATH`.
-3. Starts the device hub on `127.0.0.1` and hands it to Ycodium's plugin network
-   proxy as the service `hub`, so a paired client can reach only the routes listed
-   in this package's manifest. The `agent-device` daemon starts the same way.
-
-Turning the plugin off stops both processes.
-
-On Windows the hub and its ordinary children are owned by a kill-on-close Job.
-Android Emulators started through its `emulator.exe` shim belong to the user and
-continue running when the hub stops. This requires the shipped Windows launcher.
-The launcher uses managed mode when its executable stem is `ycodium-job-launcher`
-(case-insensitive). Any other name selects breakaway mode and looks for a same-named
-`.exe` on PATH outside its own directory; Devices copies it as `emulator.exe`.
-The shim depends on `agent-device` finding emulator through `PATH`; an absolute
-SDK path bypasses it and the emulator then stops with the hub. The plugin logs a
-warning when a launch cannot be matched to the shim's process record.
+Device helpers are delivered with Ycodium at pinned versions, including their
+dependencies. Listing or opening a device starts the helpers when needed; it does
+not install npm packages or download a Node interpreter. The helpers run through
+Ycodium's managed Node, rather than the `node` on the machine's PATH.
+
+The device hub listens on loopback. Paired clients reach its declared routes through
+Ycodium's plugin network proxy, including when the machine is remote. The device
+panel is shared by web, desktop and the mobile plugin view.
+
+Turning the plugin off stops its helper processes and any active component download
+or Apple installation process. Prepared environments, downloaded archives and
+virtual device data remain on disk. Simulators themselves belong to the user and
+are not shut down as part of disabling the plugin.
+
+On Windows, keeping an emulator running after its hub stops requires Ycodium's
+shipped process launcher. The emulator breakaway shim depends on the device helper
+finding `emulator.exe` through PATH. An absolute SDK executable path bypasses the
+shim; the plugin logs unmatched launches because those emulators can stop with the
+hub.
+
+## Prepare a simulator
+
+In the Devices panel, expand **Prepare simulator environment** and choose Android
+or iOS. **Check prerequisites and storage** reads the machine's current setup,
+download estimate, private storage location and free space. Enter an absolute
+directory to use another disk on that machine. A remote machine's path is not a
+path on the client computer.
+
+For Android, the plugin detects and validates an existing SDK with runnable `adb`
+and `emulator`. Existing virtual devices can be reused without installing
+`avdmanager` or changing the SDK. Running an existing virtual device still writes
+to that device's data. An incompatible running ADB server is reported without
+stopping or restarting it.
+
+If a private environment is needed, accept the Android SDK license and choose
+**Download and prepare**. The plugin downloads fixed official Google archives for
+Platform-Tools, Emulator and an Android 15 AOSP system image, checks their recorded
+sizes and official checksums, and creates a private virtual device. SDK files,
+Android preferences, emulator configuration, AVD data and controlled temporary files
+use the selected private storage. Global environment variables and shell files are
+not changed. The plugin does not install an application build toolchain or Java.
+An explicitly configured SDK location in Settings takes precedence over the newly
+prepared private environment.
+
+Android preparation checks hardware virtualization before downloading. Windows
+needs an enabled hypervisor, Linux needs accessible KVM, and macOS needs
+Hypervisor.framework. Missing system support produces official setup guidance;
+Ycodium does not elevate privileges, install drivers or enable Windows features.
+The pinned emulator supports Windows x64, Linux x64 and macOS x64/arm64. Other
+targets receive an unsupported-platform explanation.
+
+The bundled iOS native helpers must load successfully on the machine. Missing or
+incompatible helpers produce an explicit readiness error. For iOS, install and
+initialize Xcode yourself using Apple's instructions. Ycodium
+checks the selected full Xcode and first-launch status; it does not select,
+initialize or upgrade Xcode. To add a simulator runtime, enter an exact iOS version
+supported by that Xcode, read the storage estimate, accept the applicable agreement
+and confirm installation into Apple's shared simulator environment. Ycodium uses
+Apple's `xcodebuild -downloadPlatform` export and `-importPlatform` mechanism.
+Download archives are private; installed runtimes are managed by Apple and shared
+with other applications. Existing runtimes are retained. Apple determines the
+actual download size and can require additional space or user action in Xcode.
+
+Preparation continues if the panel closes. Open the panel again to read its current
+progress. After completion, refresh the device list and open the simulator to check
+its actual startup on the machine.
+
+## Cleanup and retention
+
+Disabling or removing the plugin preserves environments and data. The preparation
+panel shows separate sizes and cleanup actions for private download cache and
+Android virtual device data. Deleting a private virtual device requires a separate
+confirmation because its installed apps and data are permanently removed. Power it
+off first; cleanup refuses active device lock files. The SDK is retained so a
+private device can be recreated without downloading the components again.
+
+Cleanup never removes external SDKs, external virtual devices or Apple shared
+simulator runtimes. Manage Apple's runtimes in Xcode. Each private directory has an
+ownership record; the plugin refuses to claim a nonempty unrelated directory.
 
 ## Agent tools
 
-On MCP the tools are prefixed with the plugin id (`devices_device_list`, …).
+`device_list`, `device_open`, `device_screenshot` and `device_close` are exposed
+through the plugin toolkit. MCP prefixes them with `devices_`.
 
-- **device_list** lists simulators and emulators with their state.
-- **device_open** boots a device if needed and returns the `agent-device`
-  command to drive it: the launcher's absolute path plus `--config <file>
---session <id>`, which pin the command to this device and this conversation.
-  On Windows the launcher is a `.cmd` file, elsewhere a shell script.
-- **device_screenshot** returns the current screen as a PNG image.
-- **device_close** closes one device or every device in the conversation, and
-  can also power it off.
+`device_open` returns a launcher path and `--config` / `--session` arguments pinned
+to the chosen device and conversation. Use that command for tapping, typing,
+installing existing APKs and reading logs. The launcher uses the same managed Node
+and SDK environment as the hub. It rejects device operations without the returned
+configuration and session arguments.
 
-Tapping, typing, installing apps and reading logs all go through the
-`agent-device` command line rather than more MCP tools. It carries its own
-semantic snapshots and versions, and forwarding its dozens of tools would weigh
-down every conversation's tool list.
+## Settings and updates
 
-## Settings card
+**Android SDK location** overrides automatic detection. **Check tool versions**
+reads the bundled and running helper versions. **Verify bundled tools** checks the
+pinned components without downloading or starting anything. Missing or incomplete
+helper artifacts require repairing or updating Ycodium on that machine.
 
-- **Android SDK location**: leave it empty to use `ANDROID_HOME` or Android
-  Studio's default location.
-- **Check tool versions** reads the installed and running versions without
-  installing or starting anything.
-- **Install or update tools** installs the pinned versions. Running tools switch
-  over the next time they start.
+## Requirements and verification limits
 
-## Tool updates
+A Ycodium host supporting `host:node`, plugin network services and the plugin UI is
+required. Preparing Android components needs outbound HTTPS to Google's official
+download service. Preparing iOS runtimes requires macOS, initialized Xcode and
+access to Apple's component service.
 
-Each plugin version pins one version of `expo-device-hub` and one of
-`agent-device`; the plugin never follows the registry's latest release. When a
-newer plugin pins newer tools, they install automatically the next time a device
-is used, and the panel shows "Updating Device hub from 0.11.0 to 0.12.0…".
-Installing needs network access. The plugin never falls back to an older install
-it finds on disk: if the required version cannot be installed, the panel shows
-the failure with a Retry button, and the installed files stay as they were.
+Private archive extraction, integrity failures, directory ownership, retention,
+cleanup, ADB coexistence and Apple command selection have isolated automated
+coverage. A successful component check does not prove a virtual device boots.
+Actual Android startup, iOS installation/startup on macOS, screen streaming over
+Relay and the mobile application require their respective machines and integration
+checks.
 
-The panel's **Tool versions** popover shows the required, installed and running
-version of each tool. **Check versions** only reads the install directory and
-installs or starts nothing; **Update to …** appears when the required version is
-missing and installs it without starting anything. After a tool starts, older
-installs are removed, keeping the previous one and any install a running process
-still uses.
+## Developing
 
-## Requirements
+Run `vp run test`, `vp run typecheck` and `vp run build` from this package. Update the
+runtime lock together with helper version pins and verify the hub route allowlist
+when changing helper versions. Runtime artifacts retain dependency licenses and
+include an inventory of delivered files.
 
-A Ycodium server with plugin API version 3, including `process.spawn` for
-`host:node` (at most eight processes at once) and `network.serve` for the `hub`
-service. The first install needs outbound HTTPS to `registry.npmjs.org`.
-
-To move to another tool version, change `DEVICE_HUB_VERSION` or
-`AGENT_DEVICE_VERSION` in `src/toolchain.ts` and check the `hub` route allowlist
-in `package.json` against the new hub, since the allowlist and the screen
-protocol are written for the pinned versions.
-
-## Not yet verified on real hardware
-
-The plugin is covered by unit tests with fake processes and a fake hub. The
-following have not been run end to end yet: Android Emulators, iOS Simulators,
-screen streaming over Relay, and the mobile app.
-
-## Install
-
-Bundled with Ycodium and off by default. Turn it on under Settings → Plugins.
-
-Third-party license notices for `expo-device-hub` and `agent-device` are in the
-repository's `THIRD_PARTY_NOTICES.md`.
+Third-party notices are included in Ycodium's `THIRD_PARTY_NOTICES.md` and the
+delivered dependency artifacts. This first-party package is `UNLICENSED`.