@taptapai/taptapai-openclaw 0.0.1

package/src/plugin.ts

@@ -0,0 +1,360 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import process from "process";
+
+import { DEFAULT_BACKEND_WS_URL, DEFAULT_RELAY_URL, PLUGIN_ID } from "./constants";
+import { shouldBeQuiet, silentLogger, isRunningInGatewayProcess } from "./logging";
+import { tryAcquireBridgeLock, releaseBridgeLock, type BridgeLockState } from "./bridgeLock";
+import { ensureSecureBackendWsUrl, ensureSecureRelayUrl } from "./urls";
+import { loadStoredSecret } from "./secrets";
+import { readOpenClawConfig, writeOpenClawConfig, migrateLegacyPluginEntryKey, isPluginEnabledInConfig } from "./openclawConfig";
+import { ensureDefaultBackendConfigInOpenClawConfig, runInitialSetupIfNeeded, logTerminalInstallGuide } from "./setup";
+import { emitPairingArtifactsIfRequested } from "./emitArtifacts";
+import { connectGatewayWs, type GatewayWsState } from "./gatewayWs";
+import { connectBackendWs, startBackendWatchdog, stopBackendWatchdog, type BackendWsState } from "./backendWs";
+import { runRelayFallback } from "./relayFallback";
+import { handleBackendRequest } from "./requestHandler";
+import { callGatewayHttp } from "./gatewayHttp";
+import { makeLeveledLogger } from "./loggerFilter";
+
+type PluginRuntime = any;
+
+type PluginState = {
+  aborted: boolean;
+  backgroundStarted: boolean;
+  abortController: AbortController;
+  bridgeLock: BridgeLockState;
+  backend: BackendWsState;
+  gateway: GatewayWsState;
+  shutdownHandlersInstalled: boolean;
+  globalErrorGuardsInstalled: boolean;
+};
+
+function createInitialState(): PluginState {
+  return {
+    aborted: false,
+    backgroundStarted: false,
+    abortController: new AbortController(),
+    bridgeLock: { held: false, path: "", skipLogged: false },
+    backend: {
+      ws: null,
+      connected: false,
+      connecting: false,
+      currentUrl: "",
+      currentTokenHash: "",
+      reconnectTimer: null,
+      reconnectAttempt: 0,
+      watchdogTimer: null,
+      pingTimer: null,
+    },
+    gateway: {
+      ws: null,
+      connected: false,
+      reconnectTimer: null,
+      reconnectAttempt: 0,
+      urlIndex: 0,
+      rpcId: 0,
+      pendingRequests: new Map(),
+      pendingChat: new Map(),
+    },
+    shutdownHandlersInstalled: false,
+    globalErrorGuardsInstalled: false,
+  };
+}
+
+function getActiveSecretToken(pluginConfig: any): string {
+  const stored = loadStoredSecret();
+  if (stored?.token) return stored.token;
+  return String(pluginConfig?.wsToken || pluginConfig?.token || "");
+}
+
+function installGlobalErrorGuards(params: { state: PluginState; logger: any; tryConnectBackendWs: (reason: string) => void }): void {
+  const { state, logger, tryConnectBackendWs } = params;
+  if (state.globalErrorGuardsInstalled) return;
+  state.globalErrorGuardsInstalled = true;
+
+  try {
+    process.on("unhandledRejection", (reason: any) => {
+      logger.error?.(`[taptapai] unhandledRejection: ${reason?.stack || reason}`);
+      // Attempt reconnect for WS-related rejections, but don't swallow others
+      tryConnectBackendWs("unhandledRejection");
+    });
+
+    process.on("uncaughtException", (error: any) => {
+      logger.error?.(`[taptapai] uncaughtException: ${error?.stack || error}`);
+      // Node.js docs warn: the process is in an undefined state after an
+      // uncaught exception. Log and exit cleanly instead of continuing.
+      try {
+        if (state.bridgeLock?.held) {
+          releaseBridgeLock(state.bridgeLock);
+        }
+      } catch {}
+      process.exit(1);
+    });
+  } catch (e: any) {
+    logger.warn?.(`[taptapai] Could not install global error guards: ${e?.message || e}`);
+  }
+}
+
+function installShutdownHandlers(params: { state: PluginState; logger: any; cleanup: (reason: string) => void }): void {
+  const { state, logger, cleanup } = params;
+  if (state.shutdownHandlersInstalled) return;
+  state.shutdownHandlersInstalled = true;
+
+  try {
+    process.once("exit", () => cleanup("exit"));
+    process.once("SIGINT", () => {
+      cleanup("SIGINT");
+      process.exit(0);
+    });
+    process.once("SIGTERM", () => {
+      cleanup("SIGTERM");
+      process.exit(0);
+    });
+  } catch (e: any) {
+    logger.warn?.(`[taptapai] Could not install shutdown handlers: ${e?.message || e}`);
+  }
+}
+
+export function createTapTapAiPlugin() {
+  const state = createInitialState();
+
+  const plugin = {
+    id: PLUGIN_ID,
+    name: "TapTapAI",
+    description: "Apple Watch & iOS voice assistant — WS gateway proxy + relay fallback",
+
+    register(api: OpenClawPluginApi) {
+      let runtime: PluginRuntime | null = null;
+      let pluginEntry: any = null;
+      let pluginConfig: any = null;
+      let logger: any = console;
+      const quiet = shouldBeQuiet();
+
+      try {
+        runtime = api.runtime as any;
+        pluginEntry = (api as any).pluginConfig;
+        pluginConfig = pluginEntry?.config || pluginEntry;
+        logger = (api as any).logger || console;
+
+        // Apply quiet + log level filtering early.
+        if (!quiet) {
+          logger = makeLeveledLogger(logger, { level: pluginConfig?.logLevel, quiet });
+        }
+
+        if (quiet) {
+          logger = silentLogger();
+          return;
+        }
+
+        logger.info?.("[taptapai] Registering plugin v3 (WS + relay bridge)...");
+
+        // Migration: move plugins.entries.taptapai -> plugins.entries.taptapai-openclaw
+        // Only do this in the gateway process.
+        if (isRunningInGatewayProcess()) {
+          const cfg = readOpenClawConfig(logger);
+          if (cfg && migrateLegacyPluginEntryKey(cfg)) {
+            writeOpenClawConfig(runtime as any, cfg, logger);
+          }
+        }
+
+        const enabled = () => {
+          return isPluginEnabledInConfig(pluginEntry?.enabled, logger);
+        };
+
+        if (!enabled()) {
+          logger.info?.("[taptapai] Plugin disabled in config — bridge not started");
+          return;
+        }
+
+        // Ensure default URLs are present so first-run config is minimal.
+        ensureDefaultBackendConfigInOpenClawConfig({ runtime, pluginConfig, logger, backendWsUrlDefault: DEFAULT_BACKEND_WS_URL, relayUrlDefault: DEFAULT_RELAY_URL });
+
+        const aborted = () => state.aborted;
+
+        const cleanup = (reason: string) => {
+          try {
+            logger.info?.(`[taptapai] Shutdown cleanup (${reason})`);
+          } catch {}
+          try {
+            state.abortController.abort();
+          } catch {}
+          try {
+            stopBackendWatchdog(state.backend);
+          } catch {}
+          try {
+            if (state.backend.pingTimer) {
+              clearInterval(state.backend.pingTimer);
+              state.backend.pingTimer = null;
+            }
+          } catch {}
+          try {
+            if (state.backend.reconnectTimer) {
+              clearTimeout(state.backend.reconnectTimer);
+              state.backend.reconnectTimer = null;
+            }
+          } catch {}
+          try {
+            if (state.gateway.reconnectTimer) {
+              clearTimeout(state.gateway.reconnectTimer);
+              state.gateway.reconnectTimer = null;
+            }
+          } catch {}
+          try {
+            state.backend.ws?.close();
+          } catch {}
+          try {
+            state.gateway.ws?.close();
+          } catch {}
+          state.backend.ws = null;
+          state.gateway.ws = null;
+          state.backend.connected = false;
+          state.gateway.connected = false;
+
+          // Fail any pending gateway waiters so we don't leak timers.
+          try {
+            for (const [id, pending] of state.gateway.pendingRequests) {
+              clearTimeout(pending.timer);
+              pending.reject(new Error("plugin shutdown"));
+              state.gateway.pendingRequests.delete(id);
+            }
+          } catch {}
+          try {
+            for (const [runId, pending] of state.gateway.pendingChat) {
+              clearTimeout(pending.timer);
+              pending.reject(new Error("plugin shutdown"));
+              state.gateway.pendingChat.delete(runId);
+            }
+          } catch {}
+
+          releaseBridgeLock(state.bridgeLock);
+        };
+
+        const tryConnectBackendWs = (reason: string) => {
+          try {
+            if (!state.bridgeLock.held) return;
+            if (state.backend.connected || state.backend.connecting) return;
+            const backendWsUrl = ensureSecureBackendWsUrl(pluginConfig?.backendWsUrl || DEFAULT_BACKEND_WS_URL, logger);
+            const token = getActiveSecretToken(pluginConfig);
+            if (!backendWsUrl || !token) return;
+            logger.info?.(`[taptapai] Backend WS reconnect requested (${reason})`);
+            connectBackendWs({
+              state: state.backend,
+              logger,
+              url: backendWsUrl,
+              token,
+              runtime,
+              aborted,
+              enabled: () => state.bridgeLock.held,
+              onRequest: async (req) => handleBackendRequest({ backendState: state.backend, gatewayState: state.gateway, runtime, pluginConfig, logger }, req),
+            });
+          } catch (e: any) {
+            logger.error?.(`[taptapai] Backend WS reconnect failed (${reason}): ${e?.message || e}`);
+          }
+        };
+
+        installGlobalErrorGuards({ state, logger, tryConnectBackendWs });
+        installShutdownHandlers({ state, logger, cleanup });
+
+        // First-run setup + bridge start.
+        void (async () => {
+          try {
+            await runInitialSetupIfNeeded({ runtime, pluginConfig, logger, quiet });
+
+            if (state.backgroundStarted) return;
+
+            const backendWsUrl = ensureSecureBackendWsUrl(
+              String(pluginConfig?.backendWsUrl || process.env.TAPTAPAI_BACKEND_WS_URL || DEFAULT_BACKEND_WS_URL).trim(),
+              logger,
+            );
+            const relayUrl = ensureSecureRelayUrl(
+              String(pluginConfig?.relayUrl || process.env.TAPTAPAI_RELAY_URL || DEFAULT_RELAY_URL).trim(),
+              logger,
+            );
+            const token = String(pluginConfig?.wsToken || pluginConfig?.token || getActiveSecretToken(pluginConfig) || "").trim();
+            const pollIntervalMs = Number(pluginConfig?.pollIntervalMs || 1000);
+
+            if (!token) {
+              logTerminalInstallGuide(logger, quiet);
+              return;
+            }
+
+            if (!tryAcquireBridgeLock(state.bridgeLock, logger, quiet)) return;
+            state.backgroundStarted = true;
+            state.aborted = false;
+
+            logger.info?.("[taptapai] Starting local gateway WS client for agent dispatch...");
+            connectGatewayWs({
+              state: state.gateway,
+              logger,
+              aborted,
+              enabled: () => state.bridgeLock.held,
+              readOpenClawConfig: () => readOpenClawConfig(logger),
+              runtime,
+              pluginConfig,
+            });
+
+            if (backendWsUrl) {
+              logger.info?.(`[taptapai] Starting backend WS connection to ${backendWsUrl}`);
+              connectBackendWs({
+                state: state.backend,
+                logger,
+                url: backendWsUrl,
+                token,
+                runtime,
+                aborted,
+                enabled: () => state.bridgeLock.held,
+                onRequest: async (req) => handleBackendRequest({ backendState: state.backend, gatewayState: state.gateway, runtime, pluginConfig, logger }, req),
+              });
+              startBackendWatchdog({
+                state: state.backend,
+                logger,
+                url: backendWsUrl,
+                token,
+                runtime,
+                aborted,
+                enabled: () => state.bridgeLock.held,
+                onRequest: async (req) => handleBackendRequest({ backendState: state.backend, gatewayState: state.gateway, runtime, pluginConfig, logger }, req),
+              });
+            } else {
+              logger.info?.("[taptapai] No backendWsUrl configured — WS mode disabled");
+            }
+
+            if (relayUrl) {
+              void runRelayFallback({
+                relayUrl,
+                token,
+                pollIntervalMs,
+                signal: state.abortController.signal,
+                isWsConnected: () => state.backend.connected,
+                callGatewayHttp: (text, sessionId) =>
+                  callGatewayHttp({ text, session: sessionId, runtime, pluginConfig, readOpenClawConfig: () => readOpenClawConfig(logger), logger }),
+                logger,
+              }).catch((e: any) => {
+                logger.error?.(`[taptapai] Relay fallback crashed: ${e?.message || e}`);
+                if (backendWsUrl) tryConnectBackendWs("relay-crash");
+              });
+            } else {
+              logger.info?.("[taptapai] No relayUrl configured — relay fallback disabled");
+            }
+
+            await emitPairingArtifactsIfRequested({ runtime, pluginConfig, logger, quiet, getActiveSecretToken: () => getActiveSecretToken(pluginConfig) });
+          } catch (e: any) {
+            // Never crash the gateway from background setup, but log the error.
+            logger.error?.(`[taptapai] Background setup error: ${e?.stack || e?.message || e}`);
+          }
+        })();
+
+        logger.info?.("[taptapai] Chat setup commands are disabled; use guided terminal installation (openclaw plugins enable + config set).");
+        logger.info?.("[taptapai] ✅ Plugin v3 registered");
+      } catch (e: any) {
+        try {
+          console.error?.(`[taptapai] Plugin registration failed: ${e?.stack || e?.message || e}`);
+          logger = silentLogger();
+        } catch {}
+        return;
+      }
+    },
+  };
+
+  return plugin;
+}

package/src/qr.ts

@@ -0,0 +1,121 @@
+import * as fs from "fs";
+import QRCode from "qrcode";
+import type { LoggerLike, StoredSecret } from "./types";
+import { DEFAULT_RELAY_URL } from "./constants";
+import { getPairingArtifactsDir } from "./paths";
+
+export function qrPayloadForToken(token: string, relayUrl?: string): string {
+  // iOS expects: taptapai://link?host=X&port=Y&token=Z
+  const normalizedToken = String(token || "").trim();
+  if (!normalizedToken) return "";
+
+  let host = "";
+  let port = 443;
+  const relay = String(relayUrl || DEFAULT_RELAY_URL || "").trim();
+
+  if (!relay) {
+    return "";
+  }
+
+  try {
+    const u = new URL(relay);
+    host = u.hostname;
+    if (u.port) {
+      const p = Number(u.port);
+      if (Number.isFinite(p) && p > 0) port = p;
+    } else {
+      port = u.protocol === "http:" ? 80 : 443;
+    }
+  } catch {
+    return "";
+  }
+
+  if (!host) return "";
+  return `taptapai://link?host=${encodeURIComponent(host)}&port=${encodeURIComponent(String(port))}&token=${encodeURIComponent(normalizedToken)}`;
+}
+
+export async function renderQr(payload: string, logger?: LoggerLike): Promise<{ dataUrl: string; terminal: string }> {
+  let dataUrl = "";
+  let terminal = "";
+
+  try {
+    dataUrl = await QRCode.toDataURL(payload, { errorCorrectionLevel: "H", margin: 3, width: 512 });
+  } catch (e: any) {
+    logger?.warn?.(`[taptapai] QR data URL generation failed: ${e?.message || e}`);
+  }
+
+  try {
+    terminal = await QRCode.toString(payload, { type: "terminal", small: false, errorCorrectionLevel: "H", margin: 2 });
+  } catch (e: any) {
+    logger?.warn?.(`[taptapai] QR terminal generation failed: ${e?.message || e}`);
+  }
+
+  return { dataUrl, terminal };
+}
+
+export function ensurePairingArtifactsDir(): void {
+  fs.mkdirSync(getPairingArtifactsDir(), { recursive: true });
+}
+
+function writeTextFile0600(filePath: string, contents: string): void {
+  fs.writeFileSync(filePath, contents, { encoding: "utf8", mode: 0o600 });
+  try { fs.chmodSync(filePath, 0o600); } catch {}
+}
+
+function writeJsonFile0600(filePath: string, obj: any): void {
+  writeTextFile0600(filePath, JSON.stringify(obj, null, 2) + "\n");
+}
+
+export async function writePairingArtifacts(params: {
+  token: string;
+  secret?: StoredSecret | null;
+  backendWsUrl?: string;
+  relayUrl?: string;
+  logger?: LoggerLike;
+  quiet?: boolean;
+  includeDataUrl?: boolean;
+}): Promise<void> {
+  const token = String(params.token || "").trim();
+  if (!token) return;
+
+  ensurePairingArtifactsDir();
+  const createdAt = new Date().toISOString();
+  const payload = qrPayloadForToken(token, params.relayUrl);
+  const { dataUrl, terminal } = await renderQr(payload, params.logger);
+
+  const record = {
+    createdAt,
+    token,
+    qrPayload: payload,
+    uuidHex: params.secret?.uuidHex || null,
+    n: Number.isFinite(params.secret?.n as any) ? Number(params.secret?.n) : null,
+    backendWsUrl: params.backendWsUrl || null,
+    relayUrl: params.relayUrl || null,
+  };
+
+  writeJsonFile0600(`${getPairingArtifactsDir()}/pairing.latest.json`, record);
+  writeTextFile0600(`${getPairingArtifactsDir()}/pairing.token.txt`, `${token}\n`);
+  writeTextFile0600(`${getPairingArtifactsDir()}/pairing.qr.payload.txt`, `${payload}\n`);
+  if (terminal) writeTextFile0600(`${getPairingArtifactsDir()}/pairing.qr.terminal.txt`, `${terminal}\n`);
+
+  // Data URL is large and sensitive; only write it when explicitly requested.
+  if (params.includeDataUrl && dataUrl) {
+    writeTextFile0600(`${getPairingArtifactsDir()}/pairing.qr.dataurl.txt`, `${dataUrl}\n`);
+  } else {
+    try { fs.unlinkSync(`${getPairingArtifactsDir()}/pairing.qr.dataurl.txt`); } catch {}
+  }
+
+  // Best-effort PNG
+  try {
+    const q: any = QRCode as any;
+    if (typeof q.toFile === "function") {
+      await q.toFile(`${getPairingArtifactsDir()}/pairing.qr.png`, payload, { errorCorrectionLevel: "H", margin: 3, width: 512 });
+    }
+  } catch {}
+
+  if (!params.quiet) {
+    params.logger?.info?.(`[taptapai] Pairing artifacts written: ${getPairingArtifactsDir()}`);
+    params.logger?.info?.(`[taptapai] Pair token: ${token.substring(0, 16)}...`);
+    params.logger?.info?.(`[taptapai] QR payload: ${payload.substring(0, 40)}...`);
+  }
+}

package/src/relayFallback.ts

@@ -0,0 +1,103 @@
+import type { LoggerLike, RelayMessage } from "./types";
+
+export async function runRelayFallback(params: {
+  relayUrl: string;
+  token: string;
+  pollIntervalMs: number;
+  signal: AbortSignal;
+  isWsConnected: () => boolean;
+  callGatewayHttp: (text: string, sessionId: string) => Promise<string>;
+  logger: LoggerLike;
+}): Promise<void> {
+  const { relayUrl, token, pollIntervalMs, signal, isWsConnected, callGatewayHttp, logger } = params;
+  logger.info?.(`[taptapai] Starting HTTP relay fallback: ${relayUrl}`);
+
+  async function pollForMessages(): Promise<RelayMessage[]> {
+    try {
+      const res = await fetch(`${relayUrl}/relay/poll?limit=10`, {
+        method: "GET",
+        headers: {
+          Accept: "application/json",
+          "ngrok-skip-browser-warning": "true",
+          Authorization: `Bearer ${token}`,
+        },
+      });
+      if (!res.ok) return [];
+      const data = await res.json();
+      return (data as any).messages || [];
+    } catch (e: any) {
+      logger.debug?.(`[taptapai] Relay poll error: ${e?.message || e}`);
+      return [];
+    }
+  }
+
+  async function sendToRelay(messageId: string, sessionId: string, text: string): Promise<boolean> {
+    try {
+      const res = await fetch(`${relayUrl}/relay/responses`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "ngrok-skip-browser-warning": "true",
+          Authorization: `Bearer ${token}`,
+        },
+        body: JSON.stringify({ message_id: messageId, session_id: sessionId, text }),
+      });
+      return res.ok;
+    } catch (e: any) {
+      logger.debug?.(`[taptapai] Relay send error: ${e?.message || e}`);
+      return false;
+    }
+  }
+
+  let pollCount = 0;
+  let consecutiveFailures = 0;
+  const MAX_BACKOFF_MS = 30_000;
+
+  while (!signal.aborted) {
+    pollCount++;
+    if (pollCount % 120 === 0) {
+      logger.info?.(`[taptapai] Relay fallback heartbeat #${pollCount}`);
+    }
+
+    if (!isWsConnected()) {
+      try {
+        const messages = await pollForMessages();
+        if (messages.length > 0) consecutiveFailures = 0; // Reset on success
+        for (const msg of messages) {
+          if (signal.aborted) break;
+          logger.info?.(`[taptapai] Relay message: "${msg.text.slice(0, 60)}..."`);
+          try {
+            const responseText = await callGatewayHttp(msg.text, msg.session_id);
+            await sendToRelay(msg.id, msg.session_id, responseText);
+          } catch (e: any) {
+            await sendToRelay(msg.id, msg.session_id, `Error: ${e?.message || e}`);
+          }
+        }
+      } catch (e: any) {
+        consecutiveFailures++;
+        logger.debug?.(`[taptapai] Relay poll error (failures=${consecutiveFailures}): ${e?.message || e}`);
+      }
+    } else {
+      consecutiveFailures = 0;
+    }
+
+    // Exponential backoff on consecutive failures
+    const backoffMs = consecutiveFailures > 0
+      ? Math.min(pollIntervalMs * Math.pow(2, consecutiveFailures - 1), MAX_BACKOFF_MS)
+      : pollIntervalMs;
+
+    await new Promise<void>((resolve) => {
+      const timer = setTimeout(resolve, backoffMs);
+      signal.addEventListener(
+        "abort",
+        () => {
+          clearTimeout(timer);
+          resolve();
+        },
+        { once: true },
+      );
+    });
+  }
+
+  logger.info?.("[taptapai] Relay fallback stopped");
+}