@hywkp/test-openclaw-sider 1.0.2

package/src/remote-browser-support.ts

@@ -0,0 +1,64 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import {
+  SIDER_CHANNEL_ID,
+  SIDER_REMOTE_BROWSER_ENABLE_ENV,
+  readSiderRemoteBrowserEnableEnv,
+} from "./config.js";
+
+export { SIDER_REMOTE_BROWSER_ENABLE_ENV } from "./config.js";
+
+const SIDER_REMOTE_BROWSER_PREPEND_CONTEXT = [
+  "Sider remote-browser mode is enabled.",
+  `When the active channel is \`${SIDER_CHANNEL_ID}\` and the user requests browser work, you must use the bundled \`remote-browser\` skill and the \`mcporter remote-browser\` MCP server.`,
+  "Do not fall back to built-in browser tools. If `remote-browser` is unavailable, stop and tell the user how to repair the local MCP setup.",
+].join("\n");
+
+const SIDER_REMOTE_BROWSER_PREPEND_SYSTEM_CONTEXT = [
+  `Browser operations for \`channel=${SIDER_CHANNEL_ID}\` must go through \`remote-browser\`.`,
+  "Use the user's real browser via MCPorter, not the built-in browser tool.",
+].join("\n");
+
+const SIDER_REMOTE_BROWSER_APPEND_SYSTEM_CONTEXT =
+  "If the request is not a browser task, continue normally. If it is a browser task and `remote-browser` is unavailable, report that clearly instead of improvising a fallback.";
+
+type RemoteBrowserPromptInjection = {
+  prependContext: string;
+  prependSystemContext: string;
+  appendSystemContext: string;
+};
+
+function isTruthyEnv(value: string | undefined): boolean {
+  if (!value) {
+    return false;
+  }
+  return ["1", "true", "yes", "on"].includes(value.trim().toLowerCase());
+}
+
+function isRemoteBrowserSupportEnabled(): boolean {
+  return isTruthyEnv(readSiderRemoteBrowserEnableEnv());
+}
+
+function buildRemoteBrowserPromptInjection(): RemoteBrowserPromptInjection {
+  return {
+    prependContext: SIDER_REMOTE_BROWSER_PREPEND_CONTEXT,
+    prependSystemContext: SIDER_REMOTE_BROWSER_PREPEND_SYSTEM_CONTEXT,
+    appendSystemContext: SIDER_REMOTE_BROWSER_APPEND_SYSTEM_CONTEXT,
+  };
+}
+
+export function registerSiderRemoteBrowserSupport(api: OpenClawPluginApi): void {
+  if (!isRemoteBrowserSupportEnabled()) {
+    return;
+  }
+
+  api.on("before_prompt_build", async (_event, ctx) => {
+    if (ctx.channelId !== SIDER_CHANNEL_ID) {
+      return;
+    }
+    // Preserve newer prompt-injection fields for hosts that support them while
+    // remaining compatible with the older SDK type surface.
+    return buildRemoteBrowserPromptInjection() as unknown as {
+      prependContext: string;
+    };
+  });
+}

package/src/setup-core.ts

@@ -0,0 +1,431 @@
+import {
+  DEFAULT_ACCOUNT_ID,
+  normalizeAccountId,
+  type ChannelSetupAdapter,
+  type ChannelSetupInput,
+  type OpenClawConfig,
+} from "openclaw/plugin-sdk/setup";
+import {
+  cloneOpenClawConfig,
+  formatAuthorizationHeader,
+  resolveSiderApiUrl,
+  resolveWritableSiderAccountConfig,
+} from "./auth.js";
+import { SIDER_CHANNEL_ID } from "./config.js";
+import { SIDER_USER_AGENT } from "./user-agent.js";
+
+export const SIDER_PAIR_REQUEST_API_PATH = "/v1/claws/pair/request";
+export const SIDER_PAIR_STATUS_API_PATH = "/v1/claws/pair/status";
+export const SIDER_EXTENSION_INSTALL_URL = "https://chromewebstore.google.com/detail/sider-chat-with-all-ai-gp/difoiogjjojoaoomphldepapgpbgkhkb?utm_source=openclaw";
+const DEFAULT_POLL_INTERVAL_MS = 5_000;
+const DEFAULT_PENDING_UPDATE_INTERVAL_MS = 30_000;
+const ANSI_ESCAPE = "\u001B";
+const ANSI_RESET = `${ANSI_ESCAPE}[0m`;
+const ANSI_BOLD = `${ANSI_ESCAPE}[1m`;
+const ANSI_CODE_COLOR = `${ANSI_ESCAPE}[38;5;214m`;
+
+type SiderPairRequestResponse = {
+  pairing_code: string;
+  pairing_token: string;
+  expires_at: number;
+  poll_interval?: number;
+};
+
+type SiderPairStatusResponse =
+  | {
+      status: "pending";
+    }
+  | {
+      status: "paired";
+      claw_id: string;
+      token: string;
+    };
+
+export type SiderPairingSession = {
+  pairingCode: string;
+  pairingToken: string;
+  expiresAt: number;
+  pollIntervalMs: number;
+};
+
+export type SiderPairingResult = {
+  clawId: string;
+  token: string;
+};
+
+export class SiderPairingExpiredError extends Error {
+  constructor(message = "Sider pairing code expired") {
+    super(message);
+    this.name = "SiderPairingExpiredError";
+  }
+}
+
+export class SiderPairingTransientError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "SiderPairingTransientError";
+  }
+}
+
+function trimMaybe(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function readJsonObject(payload: unknown, errorMessage: string): Record<string, unknown> {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+    throw new Error(errorMessage);
+  }
+  return payload as Record<string, unknown>;
+}
+
+function parsePairRequestResponse(payload: unknown): SiderPairRequestResponse {
+  const data = readJsonObject(payload, "selfclaw pairing response is not a JSON object");
+  const pairingCode = trimMaybe(data.pairing_code);
+  const pairingToken = trimMaybe(data.pairing_token);
+  const expiresAt =
+    typeof data.expires_at === "number" && Number.isFinite(data.expires_at) ? data.expires_at : 0;
+  const pollInterval =
+    typeof data.poll_interval === "number" && Number.isFinite(data.poll_interval)
+      ? Math.floor(data.poll_interval)
+      : undefined;
+  if (!pairingCode || !pairingToken || expiresAt <= 0) {
+    throw new Error("selfclaw pairing response missing pairing_code/pairing_token/expires_at");
+  }
+  return {
+    pairing_code: pairingCode,
+    pairing_token: pairingToken,
+    expires_at: expiresAt,
+    poll_interval: pollInterval,
+  };
+}
+
+function parsePairStatusResponse(payload: unknown): SiderPairStatusResponse {
+  const data = readJsonObject(payload, "selfclaw pairing status is not a JSON object");
+  const status = trimMaybe(data.status);
+  if (status === "pending") {
+    return { status: "pending" };
+  }
+  if (status === "paired") {
+    const clawId = trimMaybe(data.claw_id);
+    const token = trimMaybe(data.token);
+    if (!clawId || !token) {
+      throw new Error("selfclaw pairing status missing claw_id/token");
+    }
+    return {
+      status: "paired",
+      claw_id: clawId,
+      token,
+    };
+  }
+  throw new Error("selfclaw pairing status missing valid status");
+}
+
+async function parseErrorDetail(response: Response): Promise<string> {
+  try {
+    const text = (await response.text()).trim();
+    return text ? `: ${text}` : "";
+  } catch {
+    return "";
+  }
+}
+
+async function readJsonResponse(response: Response): Promise<unknown> {
+  try {
+    return await response.json();
+  } catch {
+    return null;
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function describeUnknownError(error: unknown): string {
+  if (error instanceof Error && error.message) {
+    return error.message;
+  }
+  return String(error);
+}
+
+function isRetryableFetchError(error: unknown): boolean {
+  if (!(error instanceof Error)) {
+    return false;
+  }
+  if (error.name === "TypeError" && /fetch failed/i.test(error.message)) {
+    return true;
+  }
+
+  const cause = "cause" in error ? error.cause : undefined;
+  const causeCode =
+    cause && typeof cause === "object" && "code" in cause && typeof cause.code === "string"
+      ? cause.code
+      : undefined;
+  return Boolean(
+    causeCode &&
+      [
+        "ECONNRESET",
+        "ECONNREFUSED",
+        "EHOSTUNREACH",
+        "ENETUNREACH",
+        "ENOTFOUND",
+        "ETIMEDOUT",
+        "UND_ERR_CONNECT_TIMEOUT",
+        "UND_ERR_HEADERS_TIMEOUT",
+        "UND_ERR_BODY_TIMEOUT",
+        "UND_ERR_SOCKET",
+      ].includes(causeCode),
+  );
+}
+
+function supportsTerminalFormatting(): boolean {
+  return Boolean(process.stdout.isTTY);
+}
+
+function stripAnsiEscapes(value: string): string {
+  return value.replaceAll(ANSI_ESCAPE, "");
+}
+
+function formatTerminalLink(url: string, label = url): string {
+  const safeUrl = stripAnsiEscapes(url);
+  const safeLabel = stripAnsiEscapes(label);
+  if (!supportsTerminalFormatting()) {
+    return safeUrl;
+  }
+  return `\u001b]8;;${safeUrl}\u0007${safeLabel}\u001b]8;;\u0007`;
+}
+
+function formatHighlightedPairingCode(pairingCode: string): string {
+  const safePairingCode = stripAnsiEscapes(pairingCode);
+  if (!supportsTerminalFormatting()) {
+    return safePairingCode;
+  }
+  return `${ANSI_BOLD}${ANSI_CODE_COLOR}${safePairingCode}${ANSI_RESET}`;
+}
+
+function formatSiderExtensionInstallLink(): string {
+  return formatTerminalLink(SIDER_EXTENSION_INSTALL_URL);
+}
+
+export function formatSiderPairingTtl(remainingMs: number): string {
+  const totalSeconds = Math.max(0, Math.ceil(remainingMs / 1000));
+  const minutes = Math.floor(totalSeconds / 60);
+  const seconds = totalSeconds % 60;
+  return `${minutes}:${String(seconds).padStart(2, "0")}`;
+}
+
+export function formatSiderPairingPendingMessage(params: {
+  pairingCode: string;
+  remainingMs: number;
+}): string {
+  return `Waiting for connection... Pairing code: ${formatHighlightedPairingCode(params.pairingCode)}. Pairing code expires in ${formatSiderPairingTtl(params.remainingMs)}.`;
+}
+
+export function formatSiderPairingRetryMessage(params: {
+  pairingCode: string;
+  remainingMs: number;
+  retryAfterMs: number;
+  detail: string;
+}): string {
+  return `Temporary connection issue while checking pairing status (${params.detail}). Retrying in ${formatSiderPairingTtl(params.retryAfterMs)}. Pairing code: ${formatHighlightedPairingCode(params.pairingCode)}. Pairing code expires in ${formatSiderPairingTtl(params.remainingMs)}.`;
+}
+
+export function createSiderPairingPendingUpdateReporter(params: {
+  pairingCode: string;
+  report: (message: string) => void | Promise<void>;
+  intervalMs?: number;
+}): (state: { remainingMs: number; pollIntervalMs: number }) => void | Promise<void> {
+  const intervalMs = Math.max(1_000, Math.floor(params.intervalMs ?? DEFAULT_PENDING_UPDATE_INTERVAL_MS));
+  let lastReportedAt = Date.now();
+  let hasReported = false;
+
+  return async ({ remainingMs }) => {
+    const now = Date.now();
+    const shouldReport = hasReported
+      ? now - lastReportedAt >= intervalMs
+      : now - lastReportedAt >= intervalMs || remainingMs <= intervalMs;
+    if (!shouldReport) {
+      return;
+    }
+    hasReported = true;
+    lastReportedAt = now;
+    await params.report(
+      formatSiderPairingPendingMessage({
+        pairingCode: params.pairingCode,
+        remainingMs,
+      }),
+    );
+  };
+}
+
+export function applySiderSetupAccountConfig(params: {
+  cfg: OpenClawConfig;
+  accountId: string;
+  input: Pick<ChannelSetupInput, "name" | "token">;
+}): OpenClawConfig {
+  const next = cloneOpenClawConfig(params.cfg);
+  const accountCfg = resolveWritableSiderAccountConfig(next, params.accountId);
+  const token = trimMaybe(params.input.token);
+  const name = trimMaybe(params.input.name);
+
+  if (name) {
+    accountCfg.name = name;
+  }
+  if (token) {
+    accountCfg.token = token;
+  }
+  delete accountCfg.setupToken;
+  accountCfg.enabled = true;
+
+  return next;
+}
+
+export const siderSetupAdapter: ChannelSetupAdapter = {
+  resolveAccountId: ({ accountId }) => normalizeAccountId(accountId) ?? DEFAULT_ACCOUNT_ID,
+  validateInput: ({ input }) => {
+    if (input.useEnv) {
+      return "Sider setup does not support --use-env.";
+    }
+    return null;
+  },
+  applyAccountConfig: ({ cfg, accountId, input }) =>
+    applySiderSetupAccountConfig({
+      cfg,
+      accountId,
+      input,
+    }),
+};
+
+export async function requestSiderPairing(): Promise<SiderPairingSession> {
+  const url = resolveSiderApiUrl(SIDER_PAIR_REQUEST_API_PATH)
+  const response = await fetch(url, {
+    method: "POST",
+    headers: {
+      "User-Agent": SIDER_USER_AGENT,
+    },
+  });
+  if (!response.ok) {
+    throw new Error(
+      `selfclaw pairing request failed (${url} ${response.status} ${response.statusText})${await parseErrorDetail(response)}`,
+    );
+  }
+  const parsed = parsePairRequestResponse(await readJsonResponse(response));
+  return {
+    pairingCode: parsed.pairing_code,
+    pairingToken: parsed.pairing_token,
+    expiresAt: parsed.expires_at,
+    pollIntervalMs:
+      (parsed.poll_interval && parsed.poll_interval > 0
+        ? parsed.poll_interval * 1000
+        : DEFAULT_POLL_INTERVAL_MS),
+  };
+}
+
+export async function readSiderPairingStatus(
+  pairingToken: string,
+): Promise<SiderPairStatusResponse | { status: "expired" }> {
+  const url = resolveSiderApiUrl(SIDER_PAIR_STATUS_API_PATH);
+  let response: Response;
+  try {
+    response = await fetch(url, {
+      method: "GET",
+      headers: {
+        Authorization: formatAuthorizationHeader(pairingToken),
+        "User-Agent": SIDER_USER_AGENT,
+      },
+    });
+  } catch (error) {
+    if (isRetryableFetchError(error)) {
+      throw new SiderPairingTransientError(describeUnknownError(error));
+    }
+    throw error;
+  }
+  if (response.status === 410) {
+    return { status: "expired" };
+  }
+  if ([502, 503, 504].includes(response.status)) {
+    throw new SiderPairingTransientError(
+      `server returned ${response.status} ${response.statusText}${await parseErrorDetail(response)}`,
+    );
+  }
+  if (!response.ok) {
+    throw new Error(
+      `selfclaw pairing status failed (${url} ${response.status} ${response.statusText})${await parseErrorDetail(response)}`,
+    );
+  }
+  return parsePairStatusResponse(await readJsonResponse(response));
+}
+
+export async function waitForSiderPairing(params: {
+  pairing: SiderPairingSession;
+  onPending?: (state: { remainingMs: number; pollIntervalMs: number }) => void | Promise<void>;
+  onRetryableError?: (message: string) => void | Promise<void>;
+}): Promise<SiderPairingResult> {
+  const expiresAtMs = params.pairing.expiresAt * 1000;
+
+  while (true) {
+    let status: SiderPairStatusResponse | { status: "expired" };
+    try {
+      status = await readSiderPairingStatus(params.pairing.pairingToken);
+    } catch (error) {
+      const remainingMs = Math.max(0, expiresAtMs - Date.now());
+      if (error instanceof SiderPairingTransientError && remainingMs > 0) {
+        const retryAfterMs = Math.min(params.pairing.pollIntervalMs, remainingMs);
+        await params.onRetryableError?.(
+          formatSiderPairingRetryMessage({
+            pairingCode: params.pairing.pairingCode,
+            remainingMs,
+            retryAfterMs,
+            detail: error.message,
+          }),
+        );
+        await sleep(retryAfterMs);
+        continue;
+      }
+      throw error;
+    }
+    if (status.status === "paired") {
+      return {
+        clawId: status.claw_id,
+        token: status.token,
+      };
+    }
+
+    const remainingMs = Math.max(0, expiresAtMs - Date.now());
+    if (status.status === "expired" || remainingMs <= 0) {
+      throw new SiderPairingExpiredError();
+    }
+
+    await params.onPending?.({
+      remainingMs,
+      pollIntervalMs: params.pairing.pollIntervalMs,
+    });
+    await sleep(Math.min(params.pairing.pollIntervalMs, remainingMs));
+  }
+}
+
+export function formatSiderPairingInstructions(params: {
+  pairingCode: string;
+  leadLine?: string;
+}): string {
+  return [
+    params.leadLine?.trim() || "Plugin installed. One more step to connect:",
+    "",
+    "PAIRING CODE",
+    `  ${formatHighlightedPairingCode(params.pairingCode)}`,
+    "",
+    "CHROME EXTENSION",
+    `  ${formatSiderExtensionInstallLink()}`,
+    "",
+    "1. Install the Sider Chrome extension from the link above",
+    "2. Click the Sider icon in your browser toolbar to open the side panel",
+    "3. In the right sidebar, find and click the Claw icon (the paw-shaped icon, 2nd from top)",
+    `4. Enter the pairing code "${params.pairingCode}" and click Connect`,
+    "",
+    "I'm waiting for the connection...",
+  ].join("\n");
+}
+
+export function getSiderSetupChannelId(): string {
+  return SIDER_CHANNEL_ID;
+}

package/src/user-agent.ts

@@ -0,0 +1,17 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+function readPluginVersion(): string {
+  try {
+    const dir = path.dirname(fileURLToPath(import.meta.url));
+    const pkgPath = path.resolve(dir, "..", "package.json");
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8")) as { version?: string };
+    return pkg.version ?? "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+export const SIDER_PLUGIN_VERSION = readPluginVersion();
+export const SIDER_USER_AGENT = `openclaw-sider/${SIDER_PLUGIN_VERSION}`;