@egoai/platform 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ego AI and 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,111 @@
+# @egoai/platform
+
+[![npm](https://img.shields.io/npm/v/@egoai/platform)](https://www.npmjs.com/package/@egoai/platform)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+An OpenClaw channel plugin that connects an OpenClaw agent to SideClaw for real-time AI voice conversations.
+
+## Install
+
+### From npm
+
+```bash
+openclaw plugins install @egoai/platform
+```
+
+### From source
+
+```bash
+git clone https://github.com/egotv/sideclaw-plugin.git
+cd character-platform-plugin
+npm install
+openclaw plugins install .
+```
+
+## Configuration
+
+Add the following to your `openclaw.json` under `channels.sideclaw`:
+
+```jsonc
+{
+  "channels": {
+    "sideclaw": {
+      "enabled": true,
+      "platformUrl": "ws://sideclaw-host:19999",
+      "platformKey": "sk_pair_YOUR_TOKEN_HERE"
+    }
+  }
+}
+```
+
+Or use the CLI:
+
+```bash
+openclaw config set channels.sideclaw.enabled true
+openclaw config set channels.sideclaw.platformUrl "ws://sideclaw-host:19999"
+openclaw config set channels.sideclaw.platformKey "sk_pair_YOUR_TOKEN_HERE"
+```
+
+### Config fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `enabled` | boolean | Yes | Enable or disable the channel |
+| `platformUrl` | string | Yes | WebSocket URL of the SideClaw server (ws:// or wss://) |
+| `platformKey` | string | Yes | Pairing token generated from the SideClaw onboarding UI |
+
+### Environment variables
+
+| Variable | Description |
+|----------|-------------|
+| `OPENCLAW_GATEWAY_TOKEN` | Gateway authentication token. Takes priority over any value stored in config. |
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/sideclaw-pair` | Show step-by-step pairing instructions (register on SideClaw, add OpenClaw, get pairing token) |
+| `/sideclaw-status` | Show current connection state and configured values (`platformUrl`, `platformKey` presence, `enabled`) |
+| `/sideclaw-reconnect` | Skip the pending retry delay and reconnect immediately (no-op if already connected) |
+
+## How It Works
+
+OpenClaw gateways typically run on a user's local machine behind NAT, so SideClaw cannot reach the gateway directly. This plugin uses a reverse connection pattern: it dials out from the gateway to SideClaw rather than waiting to be dialed. On startup, the plugin connects to the local gateway WebSocket first and buffers the `connect.challenge` message before opening a second connection to SideClaw. The buffered challenge is forwarded to SideClaw immediately after the connection opens, which prevents the gateway from timing out while waiting for a handshake response. Once both sides complete the handshake, the plugin becomes a bidirectional frame relay for the lifetime of the session. If either side disconnects, the gateway's ChannelManager restarts `startAccount()` with backoff.
+
+### Workspace file reading
+
+The relay intercepts `workspace.read` RPC requests from the SideClaw server. Instead of forwarding these to the gateway (which can't serve files back over NAT), the relay reads files directly from the local filesystem using the workspace path from the gateway config (`agents.defaults.workspace`). A fast string pre-check avoids JSON parsing overhead on non-matching frames.
+
+## Security
+
+- **URL validation**: Only `ws://` and `wss://` URLs are accepted for `platformUrl`. Any other scheme is rejected to prevent SSRF.
+- **Plaintext token warning**: If `platformKey` is transmitted over an unencrypted `ws://` connection, the plugin logs a security warning. Use `wss://` in production.
+- **Secret priority**: `OPENCLAW_GATEWAY_TOKEN` in the environment always takes precedence over the value in `openclaw.json`. Prefer environment variables for secrets rather than storing them in config files.
+
+## Development
+
+After cloning and installing (see "From source" above):
+
+```bash
+npm run type-check   # TypeScript check
+npm test             # Run tests (vitest)
+```
+
+The package ships raw TypeScript with no runtime dependencies. TypeScript and vitest are the only dev-time requirements.
+
+### File structure
+
+| File | Purpose |
+|------|---------|
+| `src/index.ts` | Plugin entry — `register(api)` |
+| `src/channel.ts` | ChannelPlugin shape — id, meta, capabilities, config |
+| `src/monitor.ts` | `startAccount()` — buffered handshake + relay with `workspace.read` interception |
+| `src/config.ts` | `SideClawAccount` type, `resolveGatewayToken/Url` |
+| `src/types.ts` | RPC frame types (`RpcRequest`, `RpcResponse`, `WorkspaceReadParams`, `FileEntry`) |
+| `src/workspace.ts` | Local workspace file reading — `handleWorkspaceRead()`, `resolveWorkspace()`, `collectFiles()` |
+| `tests/workspace.test.ts` | Workspace module tests (file reading, path traversal, resolution) |
+| `tests/intercept.test.ts` | RPC interception flow tests |
+
+## License
+
+MIT

package/openclaw.plugin.json

@@ -0,0 +1,39 @@
+{
+  "id": "platform",
+  "kind": "channel",
+  "channels": ["platform"],
+  "version": "0.1.0",
+  "description": "Connect OpenClaw to platform for real-time AI voice conversations with embodied agents.",
+  "name": "platform",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "platform": {
+        "type": "object",
+        "properties": {
+          "enabled": { "type": "boolean", "default": false },
+          "platformUrl": {
+            "type": "string",
+            "description": "WebSocket URL of the platform server, e.g. ws://platform-host:19999"
+          },
+          "platformKey": {
+            "type": "string",
+            "description": "Pairing token from platform onboarding UI"
+          }
+        }
+      }
+    }
+  },
+  "uiHints": {
+    "platformUrl": {
+      "label": "platform URL",
+      "placeholder": "ws://platform-host:19999"
+    },
+    "platformKey": {
+      "label": "Platform Key",
+      "placeholder": "Key from platform onboarding",
+      "sensitive": true
+    }
+  }
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@egoai/platform",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "OpenClaw channel plugin character platform",
+  "main": "./src/index.ts",
+  "license": "MIT",
+  "author": "Ego AI <dev@ego.live>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/egotv/character-platform-plugin.git"
+  },
+  "homepage": "https://github.com/egotv/character-platform-plugin",
+  "bugs": {
+    "url": "https://github.com/egotv/character-platform-plugin/issues"
+  },
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "character-platform",
+    "voice",
+    "webrtc",
+    "channel"
+  ],
+  "engines": {
+    "node": ">= 20"
+  },
+  "files": [
+    "src/",
+    "openclaw.plugin.json"
+  ],
+  "openclaw": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "openclaw": ">= 2026.3"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "type-check": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.18.1",
+    "openclaw": "^2026.3.24",
+    "typescript": "^5.7.0",
+    "undici": "^8.0.2",
+    "vitest": "^4.1.1",
+    "ws": "^8.20.0"
+  }
+}