@pinclaw/pinclaw-plugin 0.1.24

package/index.mjs

@@ -0,0 +1,1945 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import process from "node:process";
+
+const require = createRequire(import.meta.url);
+const relayCapabilities = ["host-enrollment", "desktop-binding", "relay-session"];
+const relayEvents = ["chat", "agent", "presence", "health"];
+const defaultHostHeartbeatIntervalMs = 10_000;
+const pinClawChannelId = "pinclaw";
+const defaultPinClawAccountId = "default";
+const emptyPluginConfigSchema = {
+  type: "object",
+  properties: {},
+  additionalProperties: false,
+};
+const pinClawChannelConfigSchema = {
+  schema: {
+    type: "object",
+    properties: {
+      enabled: {
+        type: "boolean",
+      },
+      name: {
+        type: "string",
+      },
+    },
+    additionalProperties: false,
+  },
+};
+const pinClawChannelMeta = {
+  id: pinClawChannelId,
+  label: "PinClaw",
+  selectionLabel: "PinClaw Relay",
+  detailLabel: "PinClaw Host Relay",
+  docsPath: "/channels/pinclaw",
+  docsLabel: "pinclaw",
+  blurb: "Relay-hosted desktop access channel for PinClaw.",
+  systemImage: "desktopcomputer",
+};
+const openClawLookupPaths = [
+  process.cwd(),
+  "/opt/homebrew/lib/node_modules",
+  "/usr/lib/node_modules",
+  "/usr/local/lib/node_modules",
+];
+let replyRuntimePromise;
+const activePinClawChannelAccounts = new Map();
+
+export function createRelayServiceSnapshot() {
+  return {
+    serviceId: "pinclaw.relay",
+    name: "PinClaw Relay Service",
+    capabilities: relayCapabilities,
+    hostEnrollment: {
+      activeEnrollmentId: "enr-active-8246",
+      activeToken: "pct_enr_8246",
+      relayEndpoint: "wss://relay-manager.example/ws/hosts/host_mac_mini",
+      expiresAt: "2026-03-26T10:30:00.000Z",
+      consumedEnrollmentIds: ["enr-consumed-7001"],
+    },
+    desktopBinding: {
+      activePairingCode: "PC-8X4N",
+      activeDesktopId: "desktop_macbook_pro",
+      replacedDesktopIds: ["desktop_ipad_mini"],
+      pendingDesktopIds: ["desktop_windows_dev"],
+    },
+    relaySession: {
+      transport: "websocket",
+      gatewayUrl: "wss://relay-manager.example/ws/hosts/host_mac_mini",
+      heartbeatIntervalMs: defaultHostHeartbeatIntervalMs,
+      idleTimeoutMs: 30_000,
+      hostId: "host_mac_mini",
+      activeDesktopSessionId: "desktop_macbook_pro",
+      replacedDesktopSessionIds: ["desktop_ipad_mini"],
+    },
+  };
+}
+
+export function createDesktopSessionRouter() {
+  const activeDesktopByHost = new Map();
+  const replacedDesktopByHost = new Map();
+
+  return {
+    activateDesktopSession({ hostId, desktopId }) {
+      const previousDesktopId = activeDesktopByHost.get(hostId);
+
+      activeDesktopByHost.set(hostId, desktopId);
+
+      if (previousDesktopId !== undefined && previousDesktopId !== desktopId) {
+        const replaced = replacedDesktopByHost.get(hostId) ?? [];
+        replacedDesktopByHost.set(hostId, [...replaced, previousDesktopId]);
+      }
+
+      return {
+        hostId,
+        activeDesktopId: desktopId,
+        replacedDesktopId:
+          previousDesktopId !== desktopId ? previousDesktopId : undefined,
+      };
+    },
+    routeDesktopRequest({ hostId, desktopId }) {
+      return {
+        accepted: activeDesktopByHost.get(hostId) === desktopId,
+        reason:
+          activeDesktopByHost.get(hostId) === desktopId
+            ? "accepted"
+            : "desktop-session-replaced",
+      };
+    },
+    getSnapshot(hostId) {
+      return {
+        hostId,
+        activeDesktopId: activeDesktopByHost.get(hostId),
+        replacedDesktopIds: replacedDesktopByHost.get(hostId) ?? [],
+      };
+    },
+  };
+}
+
+export function createHostTunnelRuntime({ transport, onDesktopRequest }) {
+  const router = createDesktopSessionRouter();
+  let connection;
+
+  return {
+    connect({ relayUrl, hostId, credentialSecret }) {
+      connection = {
+        hostId,
+        credentialSecret,
+        websocketUrl: relayUrl.replace(/^http/u, "ws").replace(
+          /\/?$/u,
+          `/ws/hosts/${hostId}`,
+        ),
+      };
+      transport.send({
+        type: "host.hello",
+        hostId,
+        authorization: `Bearer ${credentialSecret}`,
+        websocketUrl: connection.websocketUrl,
+      });
+    },
+    receivePlatformMessage(message) {
+      if (message.type === "desktop-session.current") {
+        router.activateDesktopSession({
+          hostId: message.hostId,
+          desktopId: message.desktopId,
+        });
+        return;
+      }
+
+      if (message.type === "desktop-request") {
+        const decision = router.routeDesktopRequest({
+          hostId: message.hostId,
+          desktopId: message.desktopId,
+        });
+
+        if (decision.accepted) {
+          onDesktopRequest(message);
+        }
+      }
+    },
+    flushHeartbeat() {
+      if (connection === undefined) {
+        return;
+      }
+
+      transport.send({
+        type: "host.heartbeat",
+        hostId: connection.hostId,
+        activeDesktopId: router.getSnapshot(connection.hostId).activeDesktopId,
+      });
+    },
+  };
+}
+
+export function createManagedHostRelayService(options) {
+  const heartbeatIntervalMs =
+    options.heartbeatIntervalMs ?? defaultHostHeartbeatIntervalMs;
+  const reconnectIntervalMs = options.reconnectIntervalMs ?? 3_000;
+  const router = createDesktopSessionRouter();
+  const cleanupHandlers = [];
+  let activeDesktopId;
+  let heartbeatTimer;
+  let reconnectTimer;
+  let relayConnected = false;
+  let relayConnectPromise;
+  let started = false;
+  let lastRelayError = null;
+
+  const publishRelayState = () => {
+    options.onRelayStateChange?.({
+      connected: relayConnected,
+      activeDesktopId,
+      errorMessage: lastRelayError,
+      at: Date.now(),
+    });
+  };
+
+  const sendHeartbeat = () => {
+    if (!relayConnected) {
+      return;
+    }
+
+    options.relayTransport.send({
+      type: "host.heartbeat",
+      hostId: options.config.hostId,
+      activeDesktopId,
+    });
+  };
+
+  const scheduleRelayReconnect = () => {
+    if (!started || relayConnected || reconnectTimer !== undefined) {
+      return;
+    }
+
+    reconnectTimer = globalThis.setTimeout(() => {
+      reconnectTimer = undefined;
+      void ensureRelayConnected();
+    }, reconnectIntervalMs);
+    reconnectTimer.unref?.();
+  };
+
+  const ensureRelayConnected = async () => {
+    if (!started || relayConnected) {
+      return;
+    }
+
+    if (relayConnectPromise !== undefined) {
+      return relayConnectPromise;
+    }
+
+    relayConnectPromise = (async () => {
+      try {
+        await options.relayTransport.connect();
+        relayConnected = true;
+        lastRelayError = null;
+        publishRelayState();
+        options.relayTransport.send({
+          type: "host.hello",
+          hostId: options.config.hostId,
+        });
+      } catch (error) {
+        relayConnected = false;
+        lastRelayError = normalizeErrorMessage(error);
+        publishRelayState();
+        scheduleRelayReconnect();
+      } finally {
+        relayConnectPromise = undefined;
+      }
+    })();
+
+    return relayConnectPromise;
+  };
+
+  const handleRelayClose = () => {
+    if (!started) {
+      return;
+    }
+
+    relayConnected = false;
+    activeDesktopId = undefined;
+    lastRelayError = "relay connection closed";
+    publishRelayState();
+    scheduleRelayReconnect();
+  };
+
+  const handleRelayMessage = async (message) => {
+    if (message?.type === "desktop-session.current" && message.hostId === options.config.hostId) {
+      activeDesktopId = message.desktopId;
+      router.activateDesktopSession({
+        hostId: message.hostId,
+        desktopId: message.desktopId,
+      });
+      publishRelayState();
+      return;
+    }
+
+    if (message?.type !== "desktop-request" || message.hostId !== options.config.hostId) {
+      return;
+    }
+
+    const decision = router.routeDesktopRequest({
+      hostId: message.hostId,
+      desktopId: message.desktopId,
+    });
+
+    if (!decision.accepted) {
+      return;
+    }
+
+    try {
+      const payload = await options.gatewayClient.call(
+        message.request.method,
+        message.request.params,
+      );
+      options.relayTransport.send({
+        type: "desktop-response",
+        hostId: options.config.hostId,
+        desktopId: message.desktopId,
+        requestId: message.request.id,
+        ok: true,
+        payload,
+      });
+    } catch (error) {
+      options.relayTransport.send({
+        type: "desktop-response",
+        hostId: options.config.hostId,
+        desktopId: message.desktopId,
+        requestId: message.request.id,
+        ok: false,
+        error: {
+          message: normalizeErrorMessage(error),
+        },
+      });
+    }
+  };
+
+  return {
+    async start() {
+      if (started) {
+        return;
+      }
+
+      started = true;
+      publishRelayState();
+      await options.gatewayClient.connect();
+      options.relayTransport.onMessage(handleRelayMessage);
+      options.relayTransport.onClose?.(handleRelayClose);
+      await ensureRelayConnected();
+
+      for (const eventName of relayEvents) {
+        cleanupHandlers.push(options.gatewayClient.subscribe(eventName, (payload) => {
+          if (!activeDesktopId || !relayConnected) {
+            return;
+          }
+
+          options.relayTransport.send({
+            type: "desktop-event",
+            hostId: options.config.hostId,
+            desktopId: activeDesktopId,
+            event: eventName,
+            payload,
+          });
+        }));
+      }
+
+      heartbeatTimer = globalThis.setInterval(sendHeartbeat, heartbeatIntervalMs);
+    },
+    async stop() {
+      if (!started) {
+        return;
+      }
+
+      started = false;
+
+      if (heartbeatTimer !== undefined) {
+        globalThis.clearInterval(heartbeatTimer);
+        heartbeatTimer = undefined;
+      }
+
+      if (reconnectTimer !== undefined) {
+        globalThis.clearTimeout(reconnectTimer);
+        reconnectTimer = undefined;
+      }
+
+      while (cleanupHandlers.length > 0) {
+        cleanupHandlers.pop()?.();
+      }
+
+      relayConnected = false;
+      lastRelayError = null;
+      await options.relayTransport.close();
+      await options.gatewayClient.close();
+      publishRelayState();
+    },
+  };
+}
+
+export function createWebSocketRelayTransport({ websocketUrl, authorization, hostId }) {
+  let socket;
+  let messageHandler = () => {};
+  let closeHandler = () => {};
+  let closing = false;
+
+  return {
+    async connect() {
+      const WebSocketCtor = await loadNodeWebSocket();
+
+      closing = false;
+      socket = new WebSocketCtor(websocketUrl, {
+        headers: {
+          authorization: `Bearer ${authorization}`,
+          "x-pinclaw-host-id": hostId,
+        },
+      });
+
+      await new Promise((resolvePromise, rejectPromise) => {
+        socket.once("open", resolvePromise);
+        socket.once("error", rejectPromise);
+      });
+
+      socket.on("message", (payload) => {
+        try {
+          messageHandler(JSON.parse(payload.toString("utf8")));
+        } catch {
+          // Ignore malformed relay frames.
+        }
+      });
+      socket.on("close", () => {
+        const wasClosing = closing;
+        socket = undefined;
+
+        if (!wasClosing) {
+          closeHandler();
+        }
+      });
+    },
+    send(frame) {
+      if (socket === undefined || socket.readyState !== 1) {
+        return;
+      }
+
+      socket.send(JSON.stringify(frame));
+    },
+    onMessage(handler) {
+      messageHandler = handler;
+    },
+    onClose(handler) {
+      closeHandler = handler;
+    },
+    async close() {
+      if (socket === undefined || socket.readyState === 3) {
+        return;
+      }
+
+      closing = true;
+      await new Promise((resolvePromise) => {
+        socket.once("close", resolvePromise);
+        socket.close(1000, "disconnect");
+      });
+      socket = undefined;
+    },
+  };
+}
+
+export function createOpenClawRuntimeBridge({ runtime, logger }) {
+  const emitter = createRuntimeEventEmitter();
+  const activeRuns = new Map();
+  const agentRunToClientRun = new Map();
+  const lastRunBySession = new Map();
+  const cleanupHandlers = [];
+  let connected = false;
+
+  const cleanupRun = (clientRunId) => {
+    const runState = activeRuns.get(clientRunId);
+
+    if (runState === undefined || runState.cleaned) {
+      return;
+    }
+
+    runState.cleaned = true;
+
+    if (runState.agentRunId !== undefined) {
+      agentRunToClientRun.delete(runState.agentRunId);
+    }
+
+    activeRuns.delete(clientRunId);
+  };
+
+  const rememberSessionAlias = (sessionKey, clientRunId) => {
+    if (typeof sessionKey !== "string" || sessionKey.trim().length === 0) {
+      return;
+    }
+
+    lastRunBySession.set(sessionKey, clientRunId);
+  };
+
+  const findRunIdBySession = (sessionKey) => {
+    if (typeof sessionKey !== "string" || sessionKey.trim().length === 0) {
+      return undefined;
+    }
+
+    if (lastRunBySession.has(sessionKey)) {
+      return lastRunBySession.get(sessionKey);
+    }
+
+    for (const [candidateSessionKey, candidateRunId] of lastRunBySession.entries()) {
+      if (
+        candidateSessionKey === sessionKey
+        || candidateSessionKey.endsWith(`:${sessionKey}`)
+        || sessionKey.endsWith(`:${candidateSessionKey}`)
+      ) {
+        return candidateRunId;
+      }
+    }
+
+    return undefined;
+  };
+
+  const emitStatusEvents = () => {
+    emitter.emit("presence", {
+      connected,
+      mode: "relay-only",
+    });
+    emitter.emit("health", {
+      status: connected ? "ok" : "offline",
+      mode: "relay-only",
+    });
+  };
+
+  const emitChatDelta = (runState, text) => {
+    if (text.trim().length === 0) {
+      return;
+    }
+
+    emitter.emit("chat", {
+      runId: runState.clientRunId,
+      sessionKey: runState.sessionKey,
+      state: "delta",
+      message: createChatMessage("assistant", text),
+    });
+  };
+
+  const emitChatFinal = (runState) => {
+    if (runState.completed) {
+      return;
+    }
+
+    runState.completed = true;
+
+    emitter.emit("chat", {
+      runId: runState.clientRunId,
+      sessionKey: runState.sessionKey,
+      state: "final",
+      ...(runState.buffer.trim().length > 0
+        ? { message: createChatMessage("assistant", runState.buffer) }
+        : {}),
+    });
+  };
+
+  const emitChatError = (runState, error) => {
+    if (runState.completed) {
+      return;
+    }
+
+    runState.completed = true;
+    emitter.emit("chat", {
+      runId: runState.clientRunId,
+      sessionKey: runState.sessionKey,
+      state: "error",
+      errorMessage: normalizeErrorMessage(error),
+    });
+  };
+
+  const handleTranscriptUpdate = (update) => {
+    const sessionKey =
+      typeof update?.sessionKey === "string" ? update.sessionKey.trim() : "";
+
+    if (sessionKey.length === 0) {
+      return;
+    }
+
+    const clientRunId = findRunIdBySession(sessionKey);
+    const runState = clientRunId === undefined ? undefined : activeRuns.get(clientRunId);
+
+    if (
+      runState === undefined
+      || runState.completed
+      || runState.aborted
+      || runState.sawAssistantEvent
+    ) {
+      return;
+    }
+
+    const message = normalizeTranscriptUpdateMessage(update.message);
+
+    if (message?.role !== "assistant") {
+      return;
+    }
+
+    const text = extractMessageText(message.content);
+
+    if (text.trim().length === 0) {
+      return;
+    }
+
+    runState.sessionKey = sessionKey;
+    runState.buffer = text;
+    rememberSessionAlias(sessionKey, runState.clientRunId);
+    emitChatFinal(runState);
+    cleanupRun(runState.clientRunId);
+  };
+
+  const handleAgentEvent = (event) => {
+    const clientRunId = agentRunToClientRun.get(event.runId) ?? event.runId;
+    const runState = activeRuns.get(clientRunId);
+    const sessionKey = resolveEventSessionKey(runState, event);
+    const desktopEvent = sessionKey === undefined
+      ? {
+        ...event,
+        runId: clientRunId,
+      }
+      : {
+        ...event,
+        runId: clientRunId,
+        sessionKey,
+      };
+
+    emitter.emit("agent", desktopEvent);
+
+    if (runState === undefined || sessionKey === undefined) {
+      return;
+    }
+
+    runState.sessionKey = sessionKey;
+    rememberSessionAlias(sessionKey, clientRunId);
+
+    if (runState.aborted) {
+      if (isLifecycleTerminal(event)) {
+        cleanupRun(clientRunId);
+      }
+      return;
+    }
+
+    if (event.stream === "assistant") {
+      const nextText = readAgentTextField(event.data, "text");
+      const nextDelta = readAgentTextField(event.data, "delta");
+      const mergedText = resolveMergedAssistantText(
+        runState.buffer,
+        nextText,
+        nextDelta,
+      );
+
+      if (mergedText !== runState.buffer) {
+        runState.buffer = mergedText;
+        runState.sawAssistantEvent = true;
+        emitChatDelta(runState, mergedText);
+      }
+
+      return;
+    }
+
+    if (event.stream !== "lifecycle") {
+      return;
+    }
+
+    const phase = readAgentTextField(event.data, "phase");
+
+    if (phase === "end") {
+      emitChatFinal(runState);
+      cleanupRun(clientRunId);
+      return;
+    }
+
+    if (phase === "error") {
+      emitChatError(
+        runState,
+        readAgentTextField(event.data, "error") || "OpenClaw runtime error",
+      );
+      cleanupRun(clientRunId);
+    }
+  };
+
+  const listSessions = async (params = {}) => {
+    const sessionKey = typeof params.sessionKey === "string" ? params.sessionKey : undefined;
+    const storeContext = await loadRuntimeStoreContext(runtime, sessionKey);
+    const sessions = Object.entries(storeContext.store)
+      .sort((left, right) => (right[1]?.updatedAt ?? 0) - (left[1]?.updatedAt ?? 0))
+      .map(([key, entry]) => ({
+        key,
+        sessionKey: key,
+        sessionId: entry.sessionId,
+        updatedAt: entry.updatedAt,
+        label: resolveSessionLabel(entry, key),
+        displayName: resolveSessionLabel(entry, key),
+      }));
+
+    return {
+      sessions,
+      ts: Date.now(),
+    };
+  };
+
+  const readHistory = async (params = {}) => {
+    const sessionKey = normalizeSessionKey(params.sessionKey);
+    const storeContext = await loadRuntimeStoreContext(runtime, sessionKey);
+    const resolvedEntry = resolveStoreEntry(storeContext.store, sessionKey, storeContext.agentId);
+
+    if (resolvedEntry === undefined) {
+      return {
+        sessionKey,
+        sessionId: sessionKey,
+        messages: [],
+      };
+    }
+
+    const sessionFile = runtime.agent.session.resolveSessionFilePath(
+      resolvedEntry.entry.sessionId,
+      resolvedEntry.entry,
+      {
+        agentId: storeContext.agentId,
+      },
+    );
+    const messages = readTranscriptMessages(sessionFile);
+
+    return {
+      sessionKey: resolvedEntry.key,
+      sessionId: resolvedEntry.entry.sessionId,
+      messages,
+    };
+  };
+
+  const sendChat = async (params = {}) => {
+    const sessionKey = normalizeSessionKey(params.sessionKey);
+    const message = normalizeChatMessage(params.message);
+    const clientRunId = normalizeRunId(params.idempotencyKey);
+    const { createReplyDispatcher, dispatchInboundMessage } = await loadReplyRuntime();
+    const cfg = await runtime.config.loadConfig();
+    const abortController = new globalThis.AbortController();
+    const runState = {
+      clientRunId,
+      sessionKey,
+      agentRunId: undefined,
+      abortController,
+      buffer: "",
+      sawAssistantEvent: false,
+      completed: false,
+      aborted: false,
+      cleaned: false,
+    };
+
+    activeRuns.set(clientRunId, runState);
+    rememberSessionAlias(sessionKey, clientRunId);
+
+    const dispatcher = createReplyDispatcher({
+      deliver: async (payload) => {
+        const nextText = typeof payload?.text === "string" ? payload.text : "";
+
+        if (nextText.trim().length === 0) {
+          return;
+        }
+
+        runState.buffer = resolveMergedAssistantText(
+          runState.buffer,
+          nextText,
+          nextText,
+        );
+      },
+      onError: (error) => {
+        logger.warn(`PinClaw relay reply dispatch failed: ${normalizeErrorMessage(error)}`);
+      },
+    });
+
+    void dispatchInboundMessage({
+      ctx: createInboundContext({
+        sessionKey,
+        message,
+        clientRunId,
+      }),
+      cfg,
+      dispatcher,
+      replyOptions: {
+        runId: clientRunId,
+        abortSignal: abortController.signal,
+        onAgentRunStart: (agentRunId) => {
+          runState.agentRunId = agentRunId;
+          agentRunToClientRun.set(agentRunId, clientRunId);
+        },
+      },
+    }).then(() => {
+      if (runState.aborted) {
+        cleanupRun(clientRunId);
+        return;
+      }
+
+      if (!runState.completed) {
+        emitChatFinal(runState);
+      }
+
+      cleanupRun(clientRunId);
+    }).catch((error) => {
+      if (runState.aborted) {
+        cleanupRun(clientRunId);
+        return;
+      }
+
+      emitChatError(runState, error);
+      cleanupRun(clientRunId);
+    });
+
+    return {
+      runId: clientRunId,
+      status: "started",
+    };
+  };
+
+  const abortChat = async (params = {}) => {
+    const requestedSessionKey =
+      typeof params.sessionKey === "string" ? params.sessionKey.trim() : "";
+    const requestedRunId = typeof params.runId === "string" ? params.runId.trim() : "";
+    const clientRunId = requestedRunId || findRunIdBySession(requestedSessionKey);
+    const runState = clientRunId === undefined ? undefined : activeRuns.get(clientRunId);
+
+    if (runState === undefined) {
+      return {
+        ok: true,
+        aborted: false,
+        runIds: [],
+      };
+    }
+
+    runState.aborted = true;
+    runState.abortController.abort();
+    emitter.emit("chat", {
+      runId: runState.clientRunId,
+      sessionKey: runState.sessionKey,
+      state: "aborted",
+    });
+
+    if (runState.agentRunId === undefined) {
+      cleanupRun(runState.clientRunId);
+    }
+
+    return {
+      ok: true,
+      aborted: true,
+      runIds: [runState.clientRunId],
+    };
+  };
+
+  const getChannelsStatus = async () => ({
+    ok: true,
+    mode: "relay-only",
+    connected,
+  });
+
+  return {
+    async connect() {
+      if (connected) {
+        return;
+      }
+
+      connected = true;
+      cleanupHandlers.push(runtime.events.onAgentEvent(handleAgentEvent));
+      cleanupHandlers.push(runtime.events.onSessionTranscriptUpdate(handleTranscriptUpdate));
+      emitStatusEvents();
+    },
+    async close() {
+      connected = false;
+
+      while (cleanupHandlers.length > 0) {
+        cleanupHandlers.pop()?.();
+      }
+
+      for (const runState of activeRuns.values()) {
+        runState.aborted = true;
+        runState.abortController.abort();
+      }
+
+      activeRuns.clear();
+      agentRunToClientRun.clear();
+      emitStatusEvents();
+    },
+    async call(method, params) {
+      switch (method) {
+        case "sessions.list":
+          return listSessions(params);
+        case "chat.history":
+          return readHistory(params);
+        case "chat.send":
+          return sendChat(params);
+        case "chat.abort":
+          return abortChat(params);
+        case "channels.status":
+          return getChannelsStatus();
+        default:
+          throw new Error(`unsupported OpenClaw runtime method: ${String(method)}`);
+      }
+    },
+    subscribe(eventName, handler) {
+      return emitter.subscribe(eventName, handler);
+    },
+  };
+}
+
+export const pinclawRelayChannelPlugin = createPinClawRelayChannelPlugin();
+
+export default defineChannelPluginEntry({
+  id: "pinclaw",
+  name: "PinClaw Relay Plugin",
+  description: "PinClaw relay channel plugin for OpenClaw",
+  plugin: pinclawRelayChannelPlugin,
+});
+
+function createPinClawRelayChannelPlugin() {
+  return {
+    id: "pinclaw",
+    meta: pinClawChannelMeta,
+    reload: {
+      configPrefixes: [`channels.${pinClawChannelId}`],
+    },
+    capabilities: {
+      chatTypes: ["direct"],
+      polls: false,
+      reactions: false,
+      edit: false,
+      unsend: false,
+      reply: true,
+      groupManagement: false,
+      threads: false,
+      media: false,
+      nativeCommands: false,
+    },
+    configSchema: pinClawChannelConfigSchema,
+    config: {
+      listAccountIds(cfg) {
+        return listPinClawAccountIds(cfg);
+      },
+      resolveAccount(cfg, accountId) {
+        return resolvePinClawAccount(cfg, accountId);
+      },
+      inspectAccount(cfg, accountId) {
+        const account = resolvePinClawAccount(cfg, accountId);
+
+        return buildPinClawAccountSnapshot(account);
+      },
+      defaultAccountId() {
+        return defaultPinClawAccountId;
+      },
+      setAccountEnabled({ cfg, accountId, enabled }) {
+        return updatePinClawChannelConfig(cfg, accountId, (current) => ({
+          ...current,
+          enabled,
+        }));
+      },
+      deleteAccount({ cfg, accountId }) {
+        return deletePinClawChannelAccount(cfg, accountId);
+      },
+      isEnabled(account) {
+        return account.enabled;
+      },
+      disabledReason(account) {
+        return account.enabled ? undefined : "PinClaw channel disabled in OpenClaw config.";
+      },
+      isConfigured(account) {
+        return account.configured;
+      },
+      unconfiguredReason(account) {
+        return account.configured
+          ? undefined
+          : "Waiting for @pinclaw/host-connect to write pinclaw-relay-host.json.";
+      },
+      describeAccount(account) {
+        return buildPinClawAccountSnapshot(account);
+      },
+    },
+    setup: {
+      resolveAccountId({ accountId }) {
+        return normalizePinClawAccountId(accountId);
+      },
+      applyAccountConfig({ cfg, accountId, input }) {
+        return updatePinClawChannelConfig(cfg, accountId, (current) => ({
+          ...current,
+          enabled: true,
+          ...(typeof input?.name === "string" && input.name.trim().length > 0
+            ? { name: input.name.trim() }
+            : {}),
+        }));
+      },
+      applyAccountName({ cfg, accountId, name }) {
+        return updatePinClawChannelConfig(cfg, accountId, (current) => ({
+          ...current,
+          ...(typeof name === "string" && name.trim().length > 0
+            ? { name: name.trim() }
+            : {}),
+        }));
+      },
+      validateInput() {
+        return null;
+      },
+    },
+    status: {
+      defaultRuntime: createPinClawRuntimeSnapshot(defaultPinClawAccountId),
+      buildAccountSnapshot({ account, runtime }) {
+        return buildPinClawAccountSnapshot(account, runtime);
+      },
+      collectStatusIssues(accounts) {
+        return accounts.flatMap((account) => {
+          if (!account.enabled) {
+            return [];
+          }
+
+          if (!account.configured) {
+            return [{
+              channel: pinClawChannelId,
+              accountId: account.accountId,
+              kind: "config",
+              message: "Missing pinclaw-relay-host.json host runtime config.",
+              fix: "Run npx @pinclaw/host-connect to write the relay credential and enable the channel.",
+            }];
+          }
+
+          if (!account.connected) {
+            return [{
+              channel: pinClawChannelId,
+              accountId: account.accountId,
+              kind: "runtime",
+              message: "PinClaw relay tunnel is not connected.",
+              fix: "Check the relay URL, credential secret, and outbound websocket connectivity.",
+            }];
+          }
+
+          return [];
+        });
+      },
+    },
+    gateway: {
+      async startAccount(ctx) {
+        await startPinClawRelayChannelAccount(ctx);
+      },
+      async stopAccount(ctx) {
+        await stopPinClawRelayChannelAccount(ctx.accountId, {
+          account: ctx.account,
+          getStatus: ctx.getStatus,
+          setStatus: ctx.setStatus,
+        });
+      },
+    },
+  };
+}
+
+async function startPinClawRelayChannelAccount(ctx) {
+  const account = ctx.account ?? resolvePinClawAccount(ctx.cfg, ctx.accountId);
+  let currentAccount = account;
+  const updateStatus = (patch = {}, nextAccount = currentAccount) => {
+    currentAccount = nextAccount;
+    const currentStatus = ctx.getStatus?.() ?? createPinClawRuntimeSnapshot(currentAccount.accountId);
+    ctx.setStatus(buildPinClawAccountSnapshot(currentAccount, {
+      ...currentStatus,
+      ...patch,
+    }));
+  };
+
+  await stopPinClawRelayChannelAccount(account.accountId);
+  updateStatus({
+    running: false,
+    connected: false,
+    lastError: null,
+    healthState: account.enabled
+      ? account.configured
+        ? "connecting"
+        : "unconfigured"
+      : "disabled",
+  });
+
+  if (!account.enabled) {
+    ctx.log?.info?.("PinClaw relay channel disabled by OpenClaw config.");
+    return;
+  }
+
+  if (account.runtimeConfig === undefined) {
+    ctx.log?.info?.("PinClaw relay host config missing, skip realtime host tunnel.");
+    return;
+  }
+
+  const logger = createPluginLogger(ctx.log);
+  const createManagedService = (nextAccount) => createManagedHostRelayService({
+    config: nextAccount.runtimeConfig,
+    relayTransport: createWebSocketRelayTransport({
+      websocketUrl: nextAccount.runtimeConfig.websocketUrl,
+      authorization: nextAccount.runtimeConfig.credentialSecret,
+      hostId: nextAccount.runtimeConfig.hostId,
+    }),
+    gatewayClient: createOpenClawRuntimeBridge({
+      runtime: ctx.runtime,
+      logger,
+    }),
+    onRelayStateChange({ connected, errorMessage, at }) {
+      const currentStatus = ctx.getStatus?.() ?? createPinClawRuntimeSnapshot(nextAccount.accountId);
+
+      updateStatus({
+        ...currentStatus,
+        running: true,
+        connected,
+        lastEventAt: at,
+        lastConnectedAt: connected
+          ? at
+          : currentStatus.lastConnectedAt ?? null,
+        lastDisconnect: connected
+          ? null
+          : {
+            at,
+            ...(typeof errorMessage === "string" && errorMessage.trim().length > 0
+              ? { error: errorMessage }
+              : {}),
+          },
+        lastError:
+          typeof errorMessage === "string" && errorMessage.trim().length > 0
+            ? errorMessage
+            : null,
+        healthState: connected ? "connected" : "reconnecting",
+      }, nextAccount);
+    },
+  });
+  const managedService = createManagedService(account);
+  const accountHandle = createPinClawChannelAccountHandle({
+    account,
+    managedService,
+    createManagedService,
+    loadAccount: () => resolvePinClawAccount(ctx.cfg, ctx.accountId),
+    updateStatus,
+    abortSignal: ctx.abortSignal,
+  });
+
+  activePinClawChannelAccounts.set(account.accountId, accountHandle);
+
+  try {
+    updateStatus({
+      running: true,
+      connected: false,
+      lastStartAt: Date.now(),
+      healthState: "starting",
+    });
+    await managedService.start();
+    ctx.log?.info?.(`PinClaw relay channel started: ${account.runtimeConfig.hostId}`);
+
+    if (ctx.abortSignal.aborted) {
+      await accountHandle.stop();
+    }
+  } catch (error) {
+    activePinClawChannelAccounts.delete(account.accountId);
+    accountHandle.cleanupAbortListener();
+    updateStatus({
+      running: false,
+      connected: false,
+      healthState: "error",
+      lastError: normalizeErrorMessage(error),
+      lastDisconnect: {
+        at: Date.now(),
+        error: normalizeErrorMessage(error),
+      },
+      lastStopAt: Date.now(),
+    });
+    throw error;
+  }
+}
+
+export function createPinClawChannelAccountHandle({
+  account,
+  managedService,
+  createManagedService,
+  loadAccount,
+  updateStatus,
+  abortSignal,
+  configPollIntervalMs = 2_000,
+}) {
+  let stopped = false;
+  let currentAccount = account;
+  let currentManagedService = managedService;
+  let runtimeConfigSignature = serializeHostRelayRuntimeConfig(account.runtimeConfig);
+  let refreshPromise = Promise.resolve();
+  const abortHandler = () => {
+    void handle.stop();
+  };
+  const refreshManagedServiceForRuntimeConfigChange = async () => {
+    if (
+      stopped
+      || typeof createManagedService !== "function"
+      || typeof loadAccount !== "function"
+    ) {
+      return;
+    }
+
+    const nextAccount = loadAccount();
+    const nextRuntimeConfigSignature = serializeHostRelayRuntimeConfig(nextAccount.runtimeConfig);
+
+    if (nextRuntimeConfigSignature === runtimeConfigSignature) {
+      return;
+    }
+
+    runtimeConfigSignature = nextRuntimeConfigSignature;
+    currentAccount = nextAccount;
+
+    await currentManagedService.stop();
+
+    if (!nextAccount.enabled || nextAccount.runtimeConfig === undefined) {
+      updateStatus({
+        running: false,
+        connected: false,
+        healthState: nextAccount.configured ? "offline" : "unconfigured",
+        lastError: null,
+        lastStopAt: Date.now(),
+      }, nextAccount);
+      currentManagedService = createNoopManagedService();
+      return;
+    }
+
+    currentManagedService = createManagedService(nextAccount);
+    updateStatus({
+      running: true,
+      connected: false,
+      healthState: "starting",
+      lastError: null,
+      lastDisconnect: null,
+      lastStartAt: Date.now(),
+    }, nextAccount);
+    await currentManagedService.start();
+  };
+  const configPollTimer =
+    typeof createManagedService === "function" && typeof loadAccount === "function"
+      ? globalThis.setInterval(() => {
+        refreshPromise = refreshPromise
+          .then(() => refreshManagedServiceForRuntimeConfigChange())
+          .catch((error) => {
+            updateStatus({
+              running: false,
+              connected: false,
+              healthState: "error",
+              lastError: normalizeErrorMessage(error),
+              lastDisconnect: {
+                at: Date.now(),
+                error: normalizeErrorMessage(error),
+              },
+              lastStopAt: Date.now(),
+            }, currentAccount);
+          });
+      }, configPollIntervalMs)
+      : undefined;
+
+  configPollTimer?.unref?.();
+  const handle = {
+    cleanupAbortListener() {
+      abortSignal.removeEventListener("abort", abortHandler);
+
+      if (configPollTimer !== undefined) {
+        globalThis.clearInterval(configPollTimer);
+      }
+    },
+    async stop() {
+      if (stopped) {
+        return;
+      }
+
+      stopped = true;
+      activePinClawChannelAccounts.delete(account.accountId);
+      handle.cleanupAbortListener();
+      await refreshPromise;
+      await currentManagedService.stop();
+      updateStatus({
+        running: false,
+        connected: false,
+        healthState: currentAccount.configured ? "offline" : "unconfigured",
+        lastStopAt: Date.now(),
+      }, currentAccount);
+    },
+  };
+
+  abortSignal.addEventListener("abort", abortHandler, {
+    once: true,
+  });
+
+  return handle;
+}
+
+async function stopPinClawRelayChannelAccount(accountId, statusContext) {
+  const normalizedAccountId = normalizePinClawAccountId(accountId);
+  const accountHandle = activePinClawChannelAccounts.get(normalizedAccountId);
+
+  if (accountHandle !== undefined) {
+    await accountHandle.stop();
+    return;
+  }
+
+  if (statusContext?.setStatus) {
+    const account =
+      statusContext.account
+      ?? resolvePinClawAccount({}, normalizedAccountId);
+    const currentStatus =
+      statusContext.getStatus?.()
+      ?? createPinClawRuntimeSnapshot(normalizedAccountId);
+
+    statusContext.setStatus(buildPinClawAccountSnapshot(account, {
+      ...currentStatus,
+      running: false,
+      connected: false,
+      healthState: account.configured ? "offline" : "unconfigured",
+      lastStopAt: Date.now(),
+    }));
+  }
+}
+
+function listPinClawAccountIds(cfg) {
+  const configAccountIds = resolvePinClawConfigAccountIds(cfg);
+
+  if (configAccountIds.length > 0) {
+    return configAccountIds;
+  }
+
+  return loadHostRelayRuntimeConfig() === undefined ? [] : [defaultPinClawAccountId];
+}
+
+function resolvePinClawAccount(cfg, accountId) {
+  const normalizedAccountId = normalizePinClawAccountId(accountId);
+  const configSection = resolvePinClawAccountSection(cfg, normalizedAccountId);
+  const runtimeConfig = loadHostRelayRuntimeConfig();
+  const accountName =
+    typeof configSection?.name === "string" && configSection.name.trim().length > 0
+      ? configSection.name.trim()
+      : "PinClaw Host";
+
+  return {
+    accountId: normalizedAccountId,
+    name: accountName,
+    enabled: configSection?.enabled !== false,
+    configured: runtimeConfig !== undefined,
+    runtimeConfig,
+  };
+}
+
+function buildPinClawAccountSnapshot(account, runtimeSnapshot = {}) {
+  const snapshot = isRecord(runtimeSnapshot)
+    ? runtimeSnapshot
+    : createPinClawRuntimeSnapshot(account.accountId);
+
+  return {
+    ...createPinClawRuntimeSnapshot(account.accountId),
+    ...snapshot,
+    accountId: account.accountId,
+    name: account.name,
+    enabled: account.enabled,
+    configured: account.configured,
+    linked: account.configured,
+    baseUrl: account.runtimeConfig?.relayUrl,
+    credentialSource: account.configured ? "pinclaw-relay-host.json" : "missing",
+    mode: "relay-channel",
+  };
+}
+
+function createPinClawRuntimeSnapshot(accountId) {
+  return {
+    accountId: normalizePinClawAccountId(accountId),
+    enabled: true,
+    configured: false,
+    linked: false,
+    running: false,
+    connected: false,
+    healthState: "offline",
+    lastConnectedAt: null,
+    lastDisconnect: null,
+    lastError: null,
+    lastEventAt: null,
+    lastStartAt: null,
+    lastStopAt: null,
+    mode: "relay-channel",
+  };
+}
+
+function normalizePinClawAccountId(accountId) {
+  return typeof accountId === "string" && accountId.trim().length > 0
+    ? accountId.trim()
+    : defaultPinClawAccountId;
+}
+
+function createNoopManagedService() {
+  return {
+    async start() {},
+    async stop() {},
+  };
+}
+
+function serializeHostRelayRuntimeConfig(runtimeConfig) {
+  if (!isRecord(runtimeConfig)) {
+    return "";
+  }
+
+  return JSON.stringify({
+    relayUrl: runtimeConfig.relayUrl,
+    websocketUrl: runtimeConfig.websocketUrl,
+    hostId: runtimeConfig.hostId,
+    credentialId: runtimeConfig.credentialId,
+    credentialSecret: runtimeConfig.credentialSecret,
+  });
+}
+
+function resolvePinClawConfigAccountIds(cfg) {
+  const channelSection = resolvePinClawChannelSection(cfg);
+
+  if (channelSection === undefined) {
+    return [];
+  }
+
+  if (!isRecord(channelSection.accounts)) {
+    return [defaultPinClawAccountId];
+  }
+
+  return Object.keys(channelSection.accounts)
+    .map((accountId) => normalizePinClawAccountId(accountId))
+    .filter((accountId, index, accountIds) => accountIds.indexOf(accountId) === index);
+}
+
+function resolvePinClawChannelSection(cfg) {
+  if (!isRecord(cfg) || !isRecord(cfg.channels)) {
+    return undefined;
+  }
+
+  const channelSection = cfg.channels[pinClawChannelId];
+
+  return isRecord(channelSection) ? channelSection : undefined;
+}
+
+function resolvePinClawAccountSection(cfg, accountId) {
+  const channelSection = resolvePinClawChannelSection(cfg);
+
+  if (channelSection === undefined) {
+    return undefined;
+  }
+
+  if (!isRecord(channelSection.accounts)) {
+    return channelSection;
+  }
+
+  const accountSection = channelSection.accounts[normalizePinClawAccountId(accountId)];
+
+  return isRecord(accountSection) ? accountSection : undefined;
+}
+
+function updatePinClawChannelConfig(cfg, accountId, mutateAccount) {
+  const normalizedAccountId = normalizePinClawAccountId(accountId);
+  const nextConfig = isRecord(cfg) ? { ...cfg } : {};
+  const nextChannels = isRecord(nextConfig.channels) ? { ...nextConfig.channels } : {};
+  const currentChannelSection = resolvePinClawChannelSection(nextConfig) ?? {};
+
+  if (normalizedAccountId === defaultPinClawAccountId && !isRecord(currentChannelSection.accounts)) {
+    nextChannels[pinClawChannelId] = mutateAccount({
+      ...currentChannelSection,
+    });
+    nextConfig.channels = nextChannels;
+    return nextConfig;
+  }
+
+  const nextChannelSection = {
+    ...currentChannelSection,
+    accounts: isRecord(currentChannelSection.accounts)
+      ? { ...currentChannelSection.accounts }
+      : {},
+  };
+  const currentAccountSection = isRecord(nextChannelSection.accounts[normalizedAccountId])
+    ? {
+      ...nextChannelSection.accounts[normalizedAccountId],
+    }
+    : {};
+
+  nextChannelSection.accounts[normalizedAccountId] = mutateAccount(currentAccountSection);
+  nextChannels[pinClawChannelId] = nextChannelSection;
+  nextConfig.channels = nextChannels;
+
+  return nextConfig;
+}
+
+function deletePinClawChannelAccount(cfg, accountId) {
+  const normalizedAccountId = normalizePinClawAccountId(accountId);
+
+  if (!isRecord(cfg)) {
+    return {};
+  }
+
+  if (!isRecord(cfg.channels)) {
+    return {
+      ...cfg,
+    };
+  }
+
+  const nextConfig = {
+    ...cfg,
+    channels: {
+      ...cfg.channels,
+    },
+  };
+  const channelSection = resolvePinClawChannelSection(cfg);
+
+  if (channelSection === undefined) {
+    return nextConfig;
+  }
+
+  if (normalizedAccountId === defaultPinClawAccountId && !isRecord(channelSection.accounts)) {
+    delete nextConfig.channels[pinClawChannelId];
+    return nextConfig;
+  }
+
+  if (!isRecord(channelSection.accounts)) {
+    delete nextConfig.channels[pinClawChannelId];
+    return nextConfig;
+  }
+
+  const nextAccounts = {
+    ...channelSection.accounts,
+  };
+
+  delete nextAccounts[normalizedAccountId];
+
+  nextConfig.channels[pinClawChannelId] = Object.keys(nextAccounts).length === 0
+    ? {
+      ...channelSection,
+      accounts: {},
+    }
+    : {
+      ...channelSection,
+      accounts: nextAccounts,
+    };
+
+  return nextConfig;
+}
+
+function loadHostRelayRuntimeConfig(homeDirectory = homedir()) {
+  const configPath = join(homeDirectory, ".openclaw", "pinclaw-relay-host.json");
+
+  if (!existsSync(configPath)) {
+    return undefined;
+  }
+
+  return JSON.parse(readFileSync(configPath, "utf8"));
+}
+
+function createRuntimeEventEmitter() {
+  const handlersByEvent = new Map(
+    relayEvents.map((eventName) => [eventName, new Set()]),
+  );
+
+  return {
+    emit(eventName, payload) {
+      handlersByEvent.get(eventName)?.forEach((handler) => {
+        handler(payload);
+      });
+    },
+    subscribe(eventName, handler) {
+      const handlers = handlersByEvent.get(eventName);
+
+      if (handlers === undefined) {
+        throw new Error(`unsupported runtime event: ${String(eventName)}`);
+      }
+
+      handlers.add(handler);
+
+      return () => {
+        handlers.delete(handler);
+      };
+    },
+  };
+}
+
+function resolveEventSessionKey(runState, event) {
+  if (typeof event?.sessionKey === "string" && event.sessionKey.trim().length > 0) {
+    return event.sessionKey;
+  }
+
+  if (runState?.sessionKey) {
+    return runState.sessionKey;
+  }
+
+  return undefined;
+}
+
+function isLifecycleTerminal(event) {
+  if (event?.stream !== "lifecycle" || event.data === null || typeof event.data !== "object") {
+    return false;
+  }
+
+  const phase = event.data.phase;
+
+  return phase === "end" || phase === "error";
+}
+
+function readAgentTextField(data, key) {
+  if (data === null || typeof data !== "object") {
+    return "";
+  }
+
+  const value = data[key];
+
+  return typeof value === "string" ? value : "";
+}
+
+async function loadRuntimeStoreContext(runtime, sessionKey) {
+  const cfg = await runtime.config.loadConfig();
+  const agentId = resolveAgentIdFromSessionKey(sessionKey);
+  const storePath = runtime.agent.session.resolveStorePath(cfg.session?.store, {
+    agentId,
+  });
+  const store = runtime.agent.session.loadSessionStore(storePath);
+
+  return {
+    cfg,
+    agentId,
+    storePath,
+    store,
+  };
+}
+
+function resolveAgentIdFromSessionKey(sessionKey) {
+  if (typeof sessionKey !== "string") {
+    return "main";
+  }
+
+  const normalized = sessionKey.trim();
+
+  if (!normalized.startsWith("agent:")) {
+    return "main";
+  }
+
+  const parts = normalized.split(":");
+
+  return parts[1] && parts[1].trim().length > 0 ? parts[1] : "main";
+}
+
+function resolveStoreEntry(store, sessionKey, agentId) {
+  const candidates = new Set([sessionKey]);
+
+  if (!sessionKey.startsWith("agent:")) {
+    candidates.add(`agent:${agentId}:${sessionKey}`);
+  }
+
+  for (const candidate of candidates) {
+    if (store[candidate] !== undefined) {
+      return {
+        key: candidate,
+        entry: store[candidate],
+      };
+    }
+  }
+
+  for (const [key, entry] of Object.entries(store)) {
+    if (key === sessionKey || key.endsWith(`:${sessionKey}`)) {
+      return {
+        key,
+        entry,
+      };
+    }
+  }
+
+  return undefined;
+}
+
+function readTranscriptMessages(sessionFilePath) {
+  if (!existsSync(sessionFilePath)) {
+    return [];
+  }
+
+  return readFileSync(sessionFilePath, "utf8")
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => {
+      try {
+        return JSON.parse(line);
+      } catch {
+        return null;
+      }
+    })
+    .flatMap((record, index) => {
+      const message = normalizeTranscriptRecord(record, index);
+
+      return message === null ? [] : [message];
+    });
+}
+
+function normalizeTranscriptRecord(record, index) {
+  if (record === null || typeof record !== "object") {
+    return null;
+  }
+
+  const message =
+    record.type === "message" && record.message !== null && typeof record.message === "object"
+      ? record.message
+      : record;
+  const role = typeof message.role === "string" ? message.role : "";
+
+  if (role !== "user" && role !== "assistant" && role !== "system") {
+    return null;
+  }
+
+  return {
+    id: resolveTranscriptMessageId(message, index),
+    role,
+    content: createTextContent(extractMessageText(message.content)),
+    timestamp: typeof message.timestamp === "number" ? message.timestamp : Date.now(),
+  };
+}
+
+function normalizeTranscriptUpdateMessage(message) {
+  if (message === null || typeof message !== "object") {
+    return null;
+  }
+
+  const role = typeof message.role === "string" ? message.role : "";
+
+  if (role !== "assistant" && role !== "user" && role !== "system") {
+    return null;
+  }
+
+  return {
+    role,
+    content: message.content,
+    timestamp: typeof message.timestamp === "number" ? message.timestamp : Date.now(),
+  };
+}
+
+function resolveTranscriptMessageId(message, index) {
+  if (typeof message.id === "string" && message.id.trim().length > 0) {
+    return message.id;
+  }
+
+  if (typeof message.messageId === "string" && message.messageId.trim().length > 0) {
+    return message.messageId;
+  }
+
+  return `transcript-${index}`;
+}
+
+function extractMessageText(content) {
+  if (typeof content === "string") {
+    return content;
+  }
+
+  if (!Array.isArray(content)) {
+    return "";
+  }
+
+  return content
+    .flatMap((item) => {
+      if (item === null || typeof item !== "object") {
+        return [];
+      }
+
+      if (item.type !== "text" || typeof item.text !== "string") {
+        return [];
+      }
+
+      return [item.text];
+    })
+    .join("\n");
+}
+
+function resolveMergedAssistantText(previousText, nextText, nextDelta) {
+  const normalizedText = typeof nextText === "string" ? nextText : "";
+  const normalizedDelta = typeof nextDelta === "string" ? nextDelta : "";
+
+  if (normalizedText.length > 0) {
+    if (normalizedText.startsWith(previousText)) {
+      return normalizedText;
+    }
+
+    if (
+      normalizedDelta.length > 0
+      && normalizedText === `${previousText}${normalizedDelta}`
+    ) {
+      return normalizedText;
+    }
+
+    if (normalizedDelta.length > 0) {
+      return `${previousText}${normalizedDelta}`;
+    }
+
+    return normalizedText;
+  }
+
+  if (normalizedDelta.length > 0) {
+    return `${previousText}${normalizedDelta}`;
+  }
+
+  return previousText;
+}
+
+function createChatMessage(role, text) {
+  return {
+    role,
+    content: createTextContent(text),
+    timestamp: Date.now(),
+  };
+}
+
+function createTextContent(text) {
+  return [
+    {
+      type: "text",
+      text,
+    },
+  ];
+}
+
+function createInboundContext({ sessionKey, message, clientRunId }) {
+  const timestamp = Date.now();
+
+  return {
+    Body: message,
+    BodyForAgent: message,
+    BodyForCommands: message,
+    RawBody: message,
+    CommandBody: message,
+    SessionKey: sessionKey,
+    Provider: "webchat",
+    Surface: "webchat",
+    ChatType: "direct",
+    CommandAuthorized: true,
+    MessageSid: clientRunId,
+    Timestamp: timestamp,
+  };
+}
+
+function resolveSessionLabel(entry, fallbackKey) {
+  for (const candidate of [entry?.displayName, entry?.label, entry?.subject, fallbackKey]) {
+    if (typeof candidate === "string" && candidate.trim().length > 0) {
+      return candidate;
+    }
+  }
+
+  return fallbackKey;
+}
+
+function normalizeSessionKey(sessionKey) {
+  if (typeof sessionKey !== "string" || sessionKey.trim().length === 0) {
+    throw new Error("chat.send 需要 sessionKey。");
+  }
+
+  return sessionKey.trim();
+}
+
+function normalizeChatMessage(message) {
+  if (typeof message !== "string" || message.trim().length === 0) {
+    throw new Error("chat.send 需要 message。");
+  }
+
+  return message.trim();
+}
+
+function normalizeRunId(idempotencyKey) {
+  return typeof idempotencyKey === "string" && idempotencyKey.trim().length > 0
+    ? idempotencyKey.trim()
+    : randomUUID();
+}
+
+function normalizeErrorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function resolvePluginConfigSchema(configSchema = emptyPluginConfigSchema) {
+  return typeof configSchema === "function" ? configSchema() : configSchema;
+}
+
+function defineChannelPluginEntry({
+  id,
+  name,
+  description,
+  plugin,
+  configSchema,
+  setRuntime,
+  registerFull,
+}) {
+  return {
+    id,
+    name,
+    description,
+    configSchema: resolvePluginConfigSchema(configSchema),
+    register(api) {
+      setRuntime?.(api.runtime);
+      api.registerChannel({ plugin });
+
+      if (api.registrationMode === "setup-only") {
+        return;
+      }
+
+      registerFull?.(api);
+    },
+  };
+}
+
+function createPluginLogger(logSink = {}) {
+  return {
+    info(message) {
+      logSink.info?.(message);
+    },
+    warn(message) {
+      logSink.warn?.(message);
+    },
+    error(message) {
+      logSink.error?.(message);
+    },
+    debug(message) {
+      logSink.debug?.(message);
+    },
+  };
+}
+
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+async function loadReplyRuntime() {
+  if (replyRuntimePromise === undefined) {
+    replyRuntimePromise = importOpenClawModule("openclaw/plugin-sdk/reply-runtime");
+  }
+
+  return replyRuntimePromise;
+}
+
+async function importOpenClawModule(specifier) {
+  try {
+    return await import(specifier);
+  } catch (error) {
+    const modulePath = resolveOpenClawModulePath(specifier);
+
+    if (modulePath === undefined) {
+      throw error;
+    }
+
+    return import(modulePath);
+  }
+}
+
+function resolveOpenClawModulePath(specifier) {
+  try {
+    return require.resolve(specifier);
+  } catch (error) {
+    void error;
+  }
+
+  for (const lookupPath of openClawLookupPaths) {
+    try {
+      return require.resolve(specifier, {
+        paths: [lookupPath],
+      });
+    } catch (error) {
+      void error;
+    }
+  }
+
+  return undefined;
+}
+
+async function loadNodeWebSocket() {
+  const module = await import("ws");
+
+  return module.default;
+}