@ambient-os/openclaw-channel 0.0.2

package/clawdbot.plugin.json

@@ -0,0 +1,19 @@
+{
+  "id": "openclaw-channel",
+  "name": "Ambient",
+  "version": "1.0.0",
+  "configSchema": {
+    "type": "object",
+    "properties": {
+      "pushEndpoint": { "type": "string" },
+      "pushApiKey": { "type": "string" },
+      "relayUrl": { "type": "string" },
+      "gatewayId": { "type": "string" },
+      "tunnelSecret": { "type": "string" }
+    }
+  },
+  "uiHints": {
+    "pushApiKey": { "label": "Push API Key", "sensitive": true },
+    "tunnelSecret": { "label": "Tunnel Secret", "sensitive": true }
+  }
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export default function register(api: any): void;

package/dist/index.js

@@ -0,0 +1,195 @@
+import { generatePairingToken, validatePairingToken } from "./pairing";
+import { sendPushNotification } from "./push";
+import { ensureRelayRegistration } from "./relay-registration";
+import { TunnelClient } from "./tunnel";
+const plugin = {
+    id: "ambient",
+    meta: {
+        id: "ambient",
+        label: "Ambient",
+        selectionLabel: "Ambient iOS App",
+        docsPath: "/channels/ambient",
+        blurb: "Voice, display, and messaging via Ambient.",
+        aliases: ["amb"],
+    },
+    capabilities: {
+        chatTypes: ["direct"],
+        media: {
+            send: { image: true, audio: true, video: true },
+            receive: { image: true, audio: true, video: true },
+        },
+    },
+    config: {
+        listAccountIds: (cfg) => {
+            const ambient = cfg.channels?.ambient;
+            return Object.keys(ambient?.accounts ?? {});
+        },
+        resolveAccount: (cfg, accountId) => {
+            const ambient = cfg.channels?.ambient;
+            const accounts = ambient?.accounts ?? {};
+            return accounts[accountId ?? "default"];
+        },
+    },
+    outbound: {
+        deliveryMode: "direct",
+        sendText: async (ctx) => {
+            const { text, account, config } = ctx;
+            const ambient = config.channels?.ambient;
+            if (!account.pushToken) {
+                return { ok: false, error: "No push token for this device" };
+            }
+            try {
+                await sendPushNotification({
+                    endpoint: ambient?.pushEndpoint ?? "https://api.ambient.app/push",
+                    apiKey: ambient?.pushApiKey ?? "",
+                    deviceToken: account.pushToken,
+                    payload: {
+                        type: "message",
+                        text,
+                        timestamp: Date.now(),
+                    },
+                });
+                return { ok: true };
+            }
+            catch (err) {
+                return { ok: false, error: String(err) };
+            }
+        },
+        sendMedia: async (ctx) => {
+            const { media, caption, account, config } = ctx;
+            const ambient = config.channels?.ambient;
+            if (!account.pushToken) {
+                return { ok: false, error: "No push token for this device" };
+            }
+            try {
+                await sendPushNotification({
+                    endpoint: ambient?.pushEndpoint ?? "https://api.ambient.app/push",
+                    apiKey: ambient?.pushApiKey ?? "",
+                    deviceToken: account.pushToken,
+                    payload: {
+                        type: "media",
+                        url: media.url,
+                        mimeType: media.mimeType,
+                        caption,
+                        timestamp: Date.now(),
+                    },
+                });
+                return { ok: true };
+            }
+            catch (err) {
+                return { ok: false, error: String(err) };
+            }
+        },
+    },
+};
+export default function register(api) {
+    api.registerChannel({ plugin });
+    // Set up relay tunnel if configured
+    let tunnelClient = null;
+    let relayNodeUrl = null;
+    (async () => {
+        try {
+            const relay = await ensureRelayRegistration(api);
+            if (relay) {
+                relayNodeUrl = relay.nodeUrl;
+                const localGatewayUrl = `ws://localhost:${api.getConfig?.()?.gateway?.port ?? 18789}`;
+                tunnelClient = new TunnelClient({
+                    tunnelUrl: relay.tunnelUrl,
+                    localGatewayUrl,
+                });
+                tunnelClient.connect();
+                console.log(`[Ambient] Relay tunnel active, node URL: ${relay.nodeUrl}`);
+            }
+        }
+        catch (err) {
+            console.error("[Ambient] Failed to set up relay tunnel:", err);
+        }
+    })();
+    // Register the /ambient pairing command
+    api.registerCommand({
+        name: "ambient",
+        description: "Connect your Ambient iOS app",
+        acceptsArgs: true,
+        requireAuth: true,
+        handler: async (ctx) => {
+            const pairingToken = await generatePairingToken({
+                senderId: ctx.senderId,
+                channel: ctx.channel,
+                expiresIn: 300_000, // 5 minutes
+            });
+            // Use relay URL if available, otherwise fall back to direct connection
+            let gatewayUrl;
+            if (relayNodeUrl) {
+                gatewayUrl = relayNodeUrl;
+            }
+            else {
+                const gatewayHost = ctx.config.gateway?.publicHost ?? "localhost";
+                const gatewayPort = ctx.config.gateway?.port ?? 18789;
+                const useTls = ctx.config.gateway?.tls?.enabled ?? false;
+                const protocol = useTls ? "wss" : "ws";
+                gatewayUrl = `${protocol}://${gatewayHost}:${gatewayPort}`;
+            }
+            const params = new URLSearchParams({
+                token: pairingToken,
+                gateway: gatewayUrl,
+            });
+            const deepLink = `ambient://pair?${params.toString()}`;
+            return {
+                text: `**Connect Ambient**\n\nTap the link below on your iPhone to pair your Ambient app:\n\n${deepLink}\n\n_Link expires in 5 minutes._`,
+            };
+        },
+    });
+    // Register gateway RPC method for completing pairing
+    api.registerGatewayMethod("ambient.pair.complete", async (ctx) => {
+        const { params, respond } = ctx;
+        try {
+            const pairingData = await validatePairingToken(params.pairingToken);
+            if (!pairingData) {
+                respond(false, { error: "Invalid or expired pairing token" });
+                return;
+            }
+            const deviceToken = crypto.randomUUID();
+            const account = {
+                deviceId: params.deviceId,
+                deviceToken,
+                pushToken: params.pushToken,
+                displayName: params.displayName,
+                enabled: true,
+                pairedAt: Date.now(),
+            };
+            // Store the account in gateway config
+            // api.patchConfig({ channels: { ambient: { accounts: { [params.deviceId]: account }}}});
+            respond(true, {
+                deviceToken,
+                accountId: params.deviceId,
+                message: "Paired successfully",
+            });
+        }
+        catch (err) {
+            respond(false, { error: String(err) });
+        }
+    });
+    // Register push token update handler
+    api.registerGatewayMethod("ambient.pushToken.update", async (ctx) => {
+        const { params, respond } = ctx;
+        // Update the push token for this device in config
+        // api.patchConfig({ channels: { ambient: { accounts: { [params.deviceId]: { pushToken: params.pushToken } }}}});
+        respond(true, { ok: true });
+    });
+    // Register inbound webhook (for future HTTP-based inbound if needed)
+    api.registerHttpHandler({
+        method: "POST",
+        path: "/webhooks/ambient/inbound",
+        handler: async (req, res) => {
+            const { deviceId, message } = req.body;
+            const authHeader = req.headers.authorization;
+            if (!authHeader?.startsWith("Bearer ")) {
+                res.status(401).json({ error: "Unauthorized" });
+                return;
+            }
+            // Route to the agent session
+            // api.routeInbound({ channel: "ambient", accountId: deviceId, text: message });
+            res.json({ ok: true });
+        },
+    });
+}

package/dist/pairing.d.ts

@@ -0,0 +1,13 @@
+interface PairingData {
+    senderId: string;
+    channel: string;
+    createdAt: number;
+    expiresAt: number;
+}
+export declare function generatePairingToken(opts: {
+    senderId: string;
+    channel: string;
+    expiresIn: number;
+}): Promise<string>;
+export declare function validatePairingToken(token: string): Promise<PairingData | null>;
+export {};

package/dist/pairing.js

@@ -0,0 +1,25 @@
+import * as crypto from "crypto";
+// In production, use Redis or a proper store
+const pairingTokens = new Map();
+export async function generatePairingToken(opts) {
+    const token = crypto.randomBytes(32).toString("base64url");
+    pairingTokens.set(token, {
+        senderId: opts.senderId,
+        channel: opts.channel,
+        createdAt: Date.now(),
+        expiresAt: Date.now() + opts.expiresIn,
+    });
+    return token;
+}
+export async function validatePairingToken(token) {
+    const data = pairingTokens.get(token);
+    if (!data)
+        return null;
+    if (Date.now() > data.expiresAt) {
+        pairingTokens.delete(token);
+        return null;
+    }
+    // Consume the token (one-time use)
+    pairingTokens.delete(token);
+    return data;
+}

package/dist/push.d.ts

@@ -0,0 +1,6 @@
+export declare function sendPushNotification(opts: {
+    endpoint: string;
+    apiKey: string;
+    deviceToken: string;
+    payload: any;
+}): Promise<void>;

package/dist/push.js

@@ -0,0 +1,16 @@
+export async function sendPushNotification(opts) {
+    const response = await fetch(opts.endpoint, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${opts.apiKey}`,
+        },
+        body: JSON.stringify({
+            deviceToken: opts.deviceToken,
+            payload: opts.payload,
+        }),
+    });
+    if (!response.ok) {
+        throw new Error(`Push failed: ${response.status} ${response.statusText}`);
+    }
+}

package/dist/relay-registration.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Ensures this gateway is registered with the relay service.
+ * If already registered (gatewayId + tunnelSecret in config), returns existing values.
+ * Otherwise, generates a gatewayId, calls POST /v1/register, and stores the result.
+ */
+export declare function ensureRelayRegistration(api: any): Promise<{
+    gatewayId: string;
+    tunnelSecret: string;
+    tunnelUrl: string;
+    nodeUrl: string;
+    relayUrl: string;
+} | null>;

package/dist/relay-registration.js

@@ -0,0 +1,69 @@
+/**
+ * Ensures this gateway is registered with the relay service.
+ * If already registered (gatewayId + tunnelSecret in config), returns existing values.
+ * Otherwise, generates a gatewayId, calls POST /v1/register, and stores the result.
+ */
+export async function ensureRelayRegistration(api) {
+    const config = api.getConfig?.() ?? {};
+    const ambient = config.channels?.ambient;
+    const relayUrl = ambient?.relayUrl ?? "https://ambient-relay.sunnya97.workers.dev";
+    // Already registered?
+    if (ambient?.gatewayId && ambient?.tunnelSecret) {
+        const baseWss = relayUrl
+            .replace("https://", "wss://")
+            .replace("http://", "ws://");
+        return {
+            gatewayId: ambient.gatewayId,
+            tunnelSecret: ambient.tunnelSecret,
+            tunnelUrl: `${baseWss}/gateway/${ambient.gatewayId}/tunnel?secret=${ambient.tunnelSecret}`,
+            nodeUrl: `${baseWss}/gateway/${ambient.gatewayId}/node`,
+            relayUrl,
+        };
+    }
+    // Generate a new gatewayId
+    const gatewayId = "gw_" + randomHex(16);
+    try {
+        const response = await fetch(`${relayUrl}/v1/register`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({ gatewayId }),
+        });
+        if (!response.ok) {
+            console.error(`[Relay] Registration failed: ${response.status} ${response.statusText}`);
+            return null;
+        }
+        const result = (await response.json());
+        // Store credentials in config
+        if (api.patchConfig) {
+            api.patchConfig({
+                channels: {
+                    ambient: {
+                        gatewayId: result.gatewayId,
+                        tunnelSecret: result.tunnelSecret,
+                    },
+                },
+            });
+        }
+        console.log(`[Relay] Registered gateway: ${result.gatewayId}`);
+        return {
+            gatewayId: result.gatewayId,
+            tunnelSecret: result.tunnelSecret,
+            tunnelUrl: result.tunnelUrl,
+            nodeUrl: result.nodeUrl,
+            relayUrl,
+        };
+    }
+    catch (err) {
+        console.error("[Relay] Registration error:", err);
+        return null;
+    }
+}
+function randomHex(bytes) {
+    const buf = new Uint8Array(bytes);
+    crypto.getRandomValues(buf);
+    return Array.from(buf)
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+}

package/dist/tunnel.d.ts

@@ -0,0 +1,30 @@
+interface TunnelClientOptions {
+    tunnelUrl: string;
+    localGatewayUrl: string;
+    onStatusChange?: (connected: boolean) => void;
+}
+/**
+ * TunnelClient maintains a persistent WebSocket to the relay service
+ * and bridges incoming node connections to the local gateway.
+ */
+export declare class TunnelClient {
+    private tunnelUrl;
+    private localGatewayUrl;
+    private onStatusChange?;
+    private tunnelWs;
+    private localConnections;
+    private reconnectDelay;
+    private maxReconnectDelay;
+    private reconnectTimer;
+    private closed;
+    constructor(options: TunnelClientOptions);
+    connect(): void;
+    disconnect(): void;
+    private scheduleReconnect;
+    private handleTunnelMessage;
+    private handleNodeConnect;
+    private handleNodeFrame;
+    private handleNodeDisconnect;
+    private sendToRelay;
+}
+export {};

package/dist/tunnel.js

@@ -0,0 +1,151 @@
+import WebSocket from "ws";
+/**
+ * TunnelClient maintains a persistent WebSocket to the relay service
+ * and bridges incoming node connections to the local gateway.
+ */
+export class TunnelClient {
+    tunnelUrl;
+    localGatewayUrl;
+    onStatusChange;
+    tunnelWs = null;
+    localConnections = new Map();
+    reconnectDelay = 1000;
+    maxReconnectDelay = 30000;
+    reconnectTimer = null;
+    closed = false;
+    constructor(options) {
+        this.tunnelUrl = options.tunnelUrl;
+        this.localGatewayUrl = options.localGatewayUrl;
+        this.onStatusChange = options.onStatusChange;
+    }
+    connect() {
+        if (this.closed)
+            return;
+        this.tunnelWs = new WebSocket(this.tunnelUrl);
+        this.tunnelWs.on("open", () => {
+            console.log("[Tunnel] Connected to relay");
+            this.reconnectDelay = 1000;
+            this.onStatusChange?.(true);
+        });
+        this.tunnelWs.on("message", (data) => {
+            const raw = typeof data === "string" ? data : data.toString();
+            this.handleTunnelMessage(raw);
+        });
+        this.tunnelWs.on("close", () => {
+            console.log("[Tunnel] Disconnected from relay");
+            this.onStatusChange?.(false);
+            this.scheduleReconnect();
+        });
+        this.tunnelWs.on("error", (err) => {
+            console.error("[Tunnel] Error:", err.message);
+            // 'close' event will fire after error, triggering reconnect
+        });
+    }
+    disconnect() {
+        this.closed = true;
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        this.tunnelWs?.close();
+        this.tunnelWs = null;
+        // Close all local connections
+        for (const [nodeId, ws] of this.localConnections) {
+            ws.close();
+        }
+        this.localConnections.clear();
+    }
+    scheduleReconnect() {
+        if (this.closed)
+            return;
+        console.log(`[Tunnel] Reconnecting in ${this.reconnectDelay}ms`);
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            this.connect();
+        }, this.reconnectDelay);
+        this.reconnectDelay = Math.min(this.reconnectDelay * 2, this.maxReconnectDelay);
+    }
+    handleTunnelMessage(raw) {
+        let msg;
+        try {
+            msg = JSON.parse(raw);
+        }
+        catch {
+            console.error("[Tunnel] Invalid message:", raw);
+            return;
+        }
+        switch (msg.type) {
+            case "tunnel.nodeConnect":
+                if (msg.nodeId)
+                    this.handleNodeConnect(msg.nodeId);
+                break;
+            case "tunnel.frame":
+                if (msg.nodeId && msg.frame)
+                    this.handleNodeFrame(msg.nodeId, msg.frame);
+                break;
+            case "tunnel.nodeDisconnect":
+                if (msg.nodeId)
+                    this.handleNodeDisconnect(msg.nodeId);
+                break;
+            case "tunnel.ping":
+                this.sendToRelay({
+                    type: "tunnel.pong",
+                    ts: msg.ts ?? Date.now(),
+                });
+                break;
+        }
+    }
+    handleNodeConnect(nodeId) {
+        // Close existing connection for this nodeId if any
+        const existing = this.localConnections.get(nodeId);
+        if (existing) {
+            existing.close();
+            this.localConnections.delete(nodeId);
+        }
+        console.log(`[Tunnel] Node ${nodeId} connected, opening local WS`);
+        const localWs = new WebSocket(this.localGatewayUrl);
+        localWs.on("open", () => {
+            console.log(`[Tunnel] Local WS for node ${nodeId} connected`);
+        });
+        localWs.on("message", (data) => {
+            // Forward local gateway response back through the tunnel
+            const frame = typeof data === "string" ? data : data.toString();
+            this.sendToRelay({
+                type: "tunnel.frame",
+                nodeId,
+                frame,
+            });
+        });
+        localWs.on("close", () => {
+            console.log(`[Tunnel] Local WS for node ${nodeId} closed`);
+            this.localConnections.delete(nodeId);
+            // Notify relay that this node's local connection is gone
+            this.sendToRelay({
+                type: "tunnel.nodeDisconnect",
+                nodeId,
+            });
+        });
+        localWs.on("error", (err) => {
+            console.error(`[Tunnel] Local WS error for node ${nodeId}:`, err.message);
+        });
+        this.localConnections.set(nodeId, localWs);
+    }
+    handleNodeFrame(nodeId, frame) {
+        const localWs = this.localConnections.get(nodeId);
+        if (localWs && localWs.readyState === WebSocket.OPEN) {
+            localWs.send(frame);
+        }
+    }
+    handleNodeDisconnect(nodeId) {
+        const localWs = this.localConnections.get(nodeId);
+        if (localWs) {
+            localWs.close();
+            this.localConnections.delete(nodeId);
+        }
+    }
+    sendToRelay(msg) {
+        if (this.tunnelWs && this.tunnelWs.readyState === WebSocket.OPEN) {
+            this.tunnelWs.send(JSON.stringify(msg));
+        }
+    }
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@ambient-os/openclaw-channel",
+  "version": "0.0.2",
+  "description": "OpenClaw channel plugin for Ambient iOS app — messaging, pairing, and push notifications",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "clawdbot.plugin.json"
+  ],
+  "clawdbot": {
+    "extensions": [
+      "./dist/index.js"
+    ],
+    "channel": {
+      "id": "ambient",
+      "label": "Ambient",
+      "selectionLabel": "Ambient iOS App",
+      "docsPath": "/channels/ambient",
+      "blurb": "Connect your Ambient iOS app for voice, display, and messaging.",
+      "order": 50,
+      "aliases": [
+        "amb"
+      ]
+    },
+    "install": {
+      "npmSpec": "@ambient-os/openclaw-channel"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.3",
+    "@types/ws": "^8.5.13",
+    "typescript": "^5.3.0"
+  }
+}