@elizaos/plugin-screenshare 2.0.3-beta.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shaw Walters and elizaOS Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,79 @@
+# @elizaos/plugin-screenshare
+
+Screen Share plugin for elizaOS. Streams the local desktop and accepts authenticated remote mouse and keyboard control from any connected viewer.
+
+## What it does
+
+When loaded, the plugin:
+
+- Creates and manages **screen-share sessions** backed by the local machine's desktop.
+- Serves a **self-contained viewer** (`/api/apps/screenshare/viewer`) — a single HTML page that streams live screenshots and relays clicks, key presses, and scrolls back to the host.
+- Provides an **operator surface** inside the elizaOS dashboard (a React panel) where you can start, stop, copy, and open host sessions, and connect to a remote session by entering its server URL, session ID, and token.
+- Exposes a **TUI view** (`/screenshare/tui`) that renders session and capability state in a terminal-friendly layout.
+- All desktop capture and input dispatch is handled by `@elizaos/plugin-computeruse`, which supports macOS, Linux, and Windows.
+
+## Capabilities
+
+| Feature | Detail |
+|---------|--------|
+| Screen streaming | Polls live desktop screenshots at ~500 ms intervals; serves as PNG |
+| Mouse control | Click, double-click, right-click, move, scroll |
+| Keyboard control | Text input (up to 4096 chars), keypress combos (Enter, Escape, Tab, arrows, etc.) |
+| Window listing | Lists open desktop windows |
+| Session management | Create, list, and stop sessions; one active local session at a time |
+| Capability detection | Reports which desktop control features are available on the host platform |
+
+## Enabling the plugin
+
+Add `@elizaos/plugin-screenshare` to the agent's plugin list:
+
+```typescript
+import screensharePlugin from "@elizaos/plugin-screenshare";
+
+const agent = new AgentRuntime({
+  // ...
+  plugins: [screensharePlugin],
+});
+```
+
+The plugin is an elizaOS **app** (`kind: app`, `launchType: connect`). It is gated behind a valid app session — the viewer URL includes a session ID and a per-session bearer token that are generated at session creation time.
+
+## API overview
+
+All routes live under `/api/apps/screenshare/`:
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/capabilities` | Platform + desktop control capability flags |
+| GET | `/windows` | List open desktop windows |
+| GET | `/sessions` | All sessions (public fields; no tokens) |
+| POST | `/session` | Start a new session; returns `{ session, token, viewerUrl }` |
+| GET | `/session/:id` | Session state (requires token) |
+| GET | `/session/:id/frame` | Current desktop screenshot as PNG (requires token) |
+| POST | `/session/:id/input` | Send mouse/keyboard input (requires token) |
+| POST | `/session/:id/stop` | Stop the session (requires token) |
+| GET | `/viewer` | Self-contained viewer HTML |
+
+Token is passed via `?token=` query param, `X-Screenshare-Token` header, or `Authorization: Bearer <token>` header.
+
+## Security notes
+
+- Tokens are 24-byte cryptographically random base64url strings generated per session.
+- Session creation is rate-limited to 10 requests per IP per minute.
+- Keypress input is validated against an allowlist (`[A-Za-z0-9+_.,: -]`, max 128 chars).
+- Text input is capped at 4096 characters.
+- Sessions are in-memory only; they are lost on process restart.
+
+## Requirements
+
+Desktop capture and input control depend on the host platform. The `/capabilities` endpoint reports which features are available. For full functionality, the agent must run on a machine with a graphical display session (not headless).
+
+## Development
+
+```bash
+bun run --cwd plugins/plugin-screenshare build    # full build
+bun run --cwd plugins/plugin-screenshare test     # run tests
+bun run --cwd plugins/plugin-screenshare clean    # remove dist
+```
+
+See `CLAUDE.md` / `AGENTS.md` for the agent-oriented layout and extension guide.

package/assets/hero.svg

@@ -0,0 +1,31 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1024 1024" role="img" aria-labelledby="title desc">
+  <title id="title">Screen Share</title>
+  <desc id="desc">A desktop screen with a remote cursor and connection waves.</desc>
+  <defs>
+    <linearGradient id="bg" x1="128" y1="96" x2="896" y2="928" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#15181d"/>
+      <stop offset=".52" stop-color="#263229"/>
+      <stop offset="1" stop-color="#101418"/>
+    </linearGradient>
+    <linearGradient id="screen" x1="214" y1="258" x2="810" y2="678" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#f0f7f8"/>
+      <stop offset="1" stop-color="#88b9bd"/>
+    </linearGradient>
+    <linearGradient id="cursor" x1="514" y1="462" x2="708" y2="766" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#f8f2d8"/>
+      <stop offset="1" stop-color="#d2a84a"/>
+    </linearGradient>
+  </defs>
+  <rect width="1024" height="1024" rx="216" fill="url(#bg)"/>
+  <path d="M212 276c0-39.8 32.2-72 72-72h456c39.8 0 72 32.2 72 72v296c0 39.8-32.2 72-72 72H284c-39.8 0-72-32.2-72-72V276Z" fill="#06080a" opacity=".82"/>
+  <path d="M252 292c0-24.3 19.7-44 44-44h432c24.3 0 44 19.7 44 44v264c0 24.3-19.7 44-44 44H296c-24.3 0-44-19.7-44-44V292Z" fill="url(#screen)"/>
+  <path d="M302 530c80-90 143-94 226-16 60 57 124 56 194-2v56H302v-38Z" fill="#1d373f" opacity=".34"/>
+  <path d="M352 331h220" stroke="#203238" stroke-width="28" stroke-linecap="round" opacity=".35"/>
+  <path d="M352 390h312" stroke="#203238" stroke-width="20" stroke-linecap="round" opacity=".28"/>
+  <path d="M430 644h164l24 92h74c17.7 0 32 14.3 32 32s-14.3 32-32 32H332c-17.7 0-32-14.3-32-32s14.3-32 32-32h74l24-92Z" fill="#090c0f" opacity=".9"/>
+  <path d="M516 440 736 690l-118 12 59 123-76 36-58-122-82 86 55-385Z" fill="url(#cursor)" stroke="#15120a" stroke-width="22" stroke-linejoin="round"/>
+  <path d="M736 296c92 24 158 107 158 206" fill="none" stroke="#d7c06a" stroke-width="28" stroke-linecap="round" opacity=".92"/>
+  <path d="M752 392c38 23 62 64 62 110" fill="none" stroke="#d7c06a" stroke-width="24" stroke-linecap="round" opacity=".78"/>
+  <circle cx="220" cy="764" r="54" fill="#63c4b4" opacity=".94"/>
+  <path d="M199 765h42M220 744v42" stroke="#0b1516" stroke-width="18" stroke-linecap="round"/>
+</svg>

package/package.json

@@ -0,0 +1,96 @@
+{
+  "name": "@elizaos/plugin-screenshare",
+  "version": "2.0.3-beta.2",
+  "type": "module",
+  "description": "Screen Share app: authenticated desktop screen streaming and remote mouse/keyboard control for local, Linux, macOS, and Windows runtimes.",
+  "main": "./dist/index.js",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./*.css": "./dist/*.css",
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "import": "./dist/*.js",
+      "default": "./dist/*.js"
+    }
+  },
+  "dependencies": {
+    "@elizaos/agent": "2.0.3-beta.2",
+    "@elizaos/app-core": "2.0.3-beta.2",
+    "@elizaos/core": "2.0.3-beta.2",
+    "@elizaos/plugin-computeruse": "2.0.3-beta.2",
+    "@elizaos/shared": "2.0.3-beta.2",
+    "@elizaos/ui": "2.0.3-beta.2",
+    "lucide-react": "^1.0.0"
+  },
+  "peerDependencies": {
+    "react": "*",
+    "react-dom": "*"
+  },
+  "agentConfig": {
+    "pluginType": "elizaos:plugin:1.0.0",
+    "pluginParameters": {}
+  },
+  "elizaos": {
+    "kind": "app",
+    "app": {
+      "displayName": "Screen Share",
+      "category": "utility",
+      "heroImage": "assets/hero.png",
+      "launchType": "connect",
+      "launchUrl": "/api/apps/screenshare/viewer",
+      "capabilities": [
+        "screen-stream",
+        "mouse-control",
+        "keyboard-control",
+        "remote-support"
+      ],
+      "runtimePlugin": "@elizaos/plugin-screenshare",
+      "bridgeExport": "./dist/index.js",
+      "viewer": {
+        "url": "/api/apps/screenshare/viewer",
+        "sandbox": "allow-scripts allow-same-origin allow-forms allow-pointer-lock"
+      },
+      "session": {
+        "mode": "spectate-and-steer",
+        "features": [
+          "commands",
+          "telemetry",
+          "suggestions"
+        ]
+      }
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "bun run build:js && bun run build:views && bun run build:types",
+    "clean": "rm -rf dist",
+    "test": "vitest run --config vitest.config.ts",
+    "build:js": "tsup --config ../tsup.plugin-packages.shared.ts",
+    "build:views": "bunx --bun vite build --config vite.config.views.ts",
+    "build:types": "tsc --noCheck -p tsconfig.build.json"
+  },
+  "files": [
+    "assets",
+    "dist"
+  ],
+  "devDependencies": {
+    "@testing-library/react": "^16.3.2",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "jsdom": "^29.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tsup": "^8.5.1",
+    "vite": "^8.0.0",
+    "vitest": "^4.1.5"
+  },
+  "gitHead": "82fe0f44215954c2417328203f5bd6510985c1fc"
+}