@ycodium-ai/plugin-devices 0.0.0-stage → 0.2.2808

package/README.md

@@ -1,3 +1,93 @@
-# Temporary Holding Version
+# @ycodium-ai/plugin-devices
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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.
+
+## 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.
+
+## Agent tools
+
+On MCP the tools are prefixed with the plugin id (`devices_device_list`, …).
+
+- **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.
+
+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 card
+
+- **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.
+
+## Tool updates
+
+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.
+
+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.
+
+## Requirements
+
+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`.

package/assets/icon.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" fill="none">
+  <rect x="4" y="4" width="14" height="24" rx="3" stroke="#3B82F6" stroke-width="2"/>
+  <path d="M9 24h4" stroke="#3B82F6" stroke-width="2" stroke-linecap="round"/>
+  <rect x="21" y="10" width="8" height="14" rx="2" stroke="#3B82F6" stroke-width="2"/>
+</svg>