@nextclaw/remote 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NextClaw contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,7 @@
+# @nextclaw/remote
+
+Remote access runtime for NextClaw.
+
+This package contains the device registration flow, websocket relay connector,
+remote request bridge, service-mode runtime module, and the CLI command facade
+used by `nextclaw`.

package/dist/index.d.ts

@@ -0,0 +1,207 @@
+import { Config } from '@nextclaw/core';
+import { Command } from 'commander';
+
+type RemoteConnectCommandOptions = {
+    apiBase?: string;
+    localOrigin?: string;
+    name?: string;
+    once?: boolean;
+};
+type RemoteEnableCommandOptions = {
+    apiBase?: string;
+    name?: string;
+};
+type RemoteStatusCommandOptions = {
+    json?: boolean;
+};
+type RemoteDoctorCommandOptions = {
+    json?: boolean;
+};
+type RemoteRuntimeState = {
+    enabled: boolean;
+    mode: "service" | "foreground";
+    state: "disabled" | "connecting" | "connected" | "disconnected" | "error";
+    deviceId?: string;
+    deviceName?: string;
+    platformBase?: string;
+    localOrigin?: string;
+    lastConnectedAt?: string | null;
+    lastError?: string | null;
+    updatedAt: string;
+};
+type RemoteStatusSnapshot = {
+    configuredEnabled: boolean;
+    runtime: RemoteRuntimeState | null;
+};
+type RemoteLogger = {
+    info: (message: string) => void;
+    warn: (message: string) => void;
+    error: (message: string) => void;
+};
+type RemoteServiceStateView = {
+    pid: number;
+    uiPort?: number;
+};
+type RegisteredRemoteDevice = {
+    id: string;
+    deviceInstallId: string;
+    displayName: string;
+    platform: string;
+    appVersion: string;
+    localOrigin: string;
+    status: "online" | "offline";
+    lastSeenAt: string;
+    createdAt: string;
+    updatedAt: string;
+};
+type RemoteStatusWriter = {
+    write: (next: Omit<RemoteRuntimeState, "mode" | "updatedAt">) => void;
+};
+type RemoteConnectorRunOptions = RemoteConnectCommandOptions & {
+    signal?: AbortSignal;
+    mode?: "foreground" | "service";
+    autoReconnect?: boolean;
+    statusStore?: RemoteStatusWriter;
+};
+type RemoteRunContext = {
+    config: Config;
+    platformBase: string;
+    token: string;
+    localOrigin: string;
+    displayName: string;
+    deviceInstallId: string;
+    autoReconnect: boolean;
+};
+type RemotePlatformClientDeps = {
+    loadConfig: () => Config;
+    getDataDir: () => string;
+    getPackageVersion: () => string;
+    resolvePlatformBase: (rawApiBase: string) => string;
+    readManagedServiceState?: () => RemoteServiceStateView | null;
+    isProcessRunning?: (pid: number) => boolean;
+};
+
+type RemoteCommandRuntime = {
+    enable: (opts?: RemoteEnableCommandOptions) => Promise<void>;
+    disable: () => Promise<void>;
+    status: (opts?: RemoteStatusCommandOptions) => Promise<void>;
+    doctor: (opts?: RemoteDoctorCommandOptions) => Promise<void>;
+    connect: (opts?: RemoteConnectCommandOptions) => Promise<void>;
+};
+declare function registerRemoteCommands(program: Command, runtime: RemoteCommandRuntime): void;
+
+type RemoteConfigChange = {
+    changed: boolean;
+    config: Config;
+};
+type RemoteCommandDriver = {
+    connect: (opts?: RemoteConnectCommandOptions) => Promise<void>;
+    enableConfig: (opts?: RemoteEnableCommandOptions) => RemoteConfigChange;
+    disableConfig: () => RemoteConfigChange;
+    status: (opts?: RemoteStatusCommandOptions) => Promise<void>;
+    doctor: (opts?: RemoteDoctorCommandOptions) => Promise<void>;
+};
+declare class RemoteRuntimeActions {
+    private readonly deps;
+    constructor(deps: {
+        appName: string;
+        initAuto: (source: string) => Promise<void>;
+        remoteCommands: RemoteCommandDriver;
+        restartBackgroundService: (reason: string) => Promise<boolean>;
+        hasRunningManagedService: () => boolean;
+    });
+    connect(opts?: RemoteConnectCommandOptions): Promise<void>;
+    enable(opts?: RemoteEnableCommandOptions): Promise<void>;
+    disable(): Promise<void>;
+    status(opts?: RemoteStatusCommandOptions): Promise<void>;
+    doctor(opts?: RemoteDoctorCommandOptions): Promise<void>;
+}
+
+declare function normalizeOptionalString(value: unknown): string | undefined;
+declare function delay(ms: number, signal?: AbortSignal): Promise<void>;
+declare function redactWsUrl(url: string): string;
+declare class RemotePlatformClient {
+    private readonly deps;
+    constructor(deps: RemotePlatformClientDeps);
+    private get remoteDir();
+    private get devicePath();
+    resolveRunContext(opts: RemoteConnectorRunOptions): RemoteRunContext;
+    registerDevice(params: {
+        platformBase: string;
+        token: string;
+        deviceInstallId: string;
+        displayName: string;
+        localOrigin: string;
+    }): Promise<RegisteredRemoteDevice>;
+    private ensureDeviceInstallId;
+    private resolvePlatformAccess;
+    private resolveLocalOrigin;
+    private resolveDisplayName;
+}
+
+type RelayRequestFrame = {
+    type: "request";
+    requestId: string;
+    method: string;
+    path: string;
+    headers: Array<[string, string]>;
+    bodyBase64?: string;
+};
+declare class RemoteRelayBridge {
+    private readonly localOrigin;
+    constructor(localOrigin: string);
+    ensureLocalUiHealthy(): Promise<void>;
+    forward(frame: RelayRequestFrame, socket: WebSocket): Promise<void>;
+    private createForwardHeaders;
+    private requestBridgeCookie;
+    private sendStreamingResponse;
+}
+
+declare class RemoteConnector {
+    private readonly deps;
+    constructor(deps: {
+        platformClient: RemotePlatformClient;
+        relayBridgeFactory?: (localOrigin: string) => RemoteRelayBridge;
+        logger?: RemoteLogger;
+    });
+    private get logger();
+    private connectOnce;
+    private handleSocketMessage;
+    private parseRelayFrame;
+    private ensureDevice;
+    private writeRemoteState;
+    private runCycle;
+    run(opts?: RemoteConnectorRunOptions): Promise<void>;
+}
+
+declare function buildConfiguredRemoteState(config: Config): RemoteRuntimeState;
+declare function resolveRemoteStatusSnapshot(params: {
+    config: Config;
+    currentRemoteState?: RemoteRuntimeState | null;
+    fallbackDeviceName?: string;
+}): RemoteStatusSnapshot;
+declare class RemoteStatusStore implements RemoteStatusWriter {
+    private readonly mode;
+    private readonly deps;
+    constructor(mode: RemoteRuntimeState["mode"], deps: {
+        writeRemoteState: (next: RemoteRuntimeState) => void;
+    });
+    write(next: Omit<RemoteRuntimeState, "mode" | "updatedAt">): void;
+}
+
+declare class RemoteServiceModule {
+    private readonly deps;
+    private abortController;
+    private runTask;
+    constructor(deps: {
+        config: Config;
+        localOrigin: string;
+        statusStore: RemoteStatusWriter;
+        createConnector: (logger: RemoteLogger) => RemoteConnector;
+        logger?: RemoteLogger;
+    });
+    start(): Promise<void> | null;
+    stop(): Promise<void>;
+}
+
+export { type RegisteredRemoteDevice, type RelayRequestFrame, type RemoteConnectCommandOptions, RemoteConnector, type RemoteConnectorRunOptions, type RemoteDoctorCommandOptions, type RemoteEnableCommandOptions, type RemoteLogger, RemotePlatformClient, type RemotePlatformClientDeps, RemoteRelayBridge, type RemoteRunContext, RemoteRuntimeActions, type RemoteRuntimeState, RemoteServiceModule, type RemoteServiceStateView, type RemoteStatusCommandOptions, type RemoteStatusSnapshot, RemoteStatusStore, type RemoteStatusWriter, buildConfiguredRemoteState, delay, normalizeOptionalString, redactWsUrl, registerRemoteCommands, resolveRemoteStatusSnapshot };

package/dist/index.js

@@ -0,0 +1,658 @@
+// src/register-remote-commands.ts
+function registerRemoteCommands(program, runtime) {
+  const remote = program.command("remote").description("Manage remote access");
+  remote.command("enable").description("Enable service-managed remote access").option("--api-base <url>", "Platform API base (supports /v1 suffix)").option("--name <name>", "Device display name").action(async (opts) => runtime.enable(opts));
+  remote.command("disable").description("Disable service-managed remote access").action(async () => runtime.disable());
+  remote.command("status").description("Show remote access status").option("--json", "Print JSON").action(async (opts) => runtime.status(opts));
+  remote.command("doctor").description("Run remote access diagnostics").option("--json", "Print JSON").action(async (opts) => runtime.doctor(opts));
+  remote.command("connect").description("Foreground debug mode: register this machine and keep the connector online").option("--api-base <url>", "Platform API base (supports /v1 suffix)").option("--local-origin <url>", "Local NextClaw UI origin (default: active service or http://127.0.0.1:18791)").option("--name <name>", "Device display name").option("--once", "Connect once without auto-reconnect", false).action(async (opts) => runtime.connect(opts));
+}
+
+// src/remote-runtime-actions.ts
+var RemoteRuntimeActions = class {
+  constructor(deps) {
+    this.deps = deps;
+  }
+  async connect(opts = {}) {
+    await this.deps.remoteCommands.connect(opts);
+  }
+  async enable(opts = {}) {
+    await this.deps.initAuto("remote enable");
+    const result = this.deps.remoteCommands.enableConfig(opts);
+    console.log("\u2713 Remote access enabled");
+    if (result.config.remote.deviceName.trim()) {
+      console.log(`Device: ${result.config.remote.deviceName.trim()}`);
+    }
+    if (result.config.remote.platformApiBase.trim()) {
+      console.log(`Platform: ${result.config.remote.platformApiBase.trim()}`);
+    }
+    if (this.deps.hasRunningManagedService()) {
+      await this.deps.restartBackgroundService("remote configuration updated");
+      console.log("\u2713 Applied remote settings to running background service");
+      return;
+    }
+    console.log(`Tip: Run "${this.deps.appName} start" to bring the managed remote connector online.`);
+  }
+  async disable() {
+    const result = this.deps.remoteCommands.disableConfig();
+    console.log(result.changed ? "\u2713 Remote access disabled" : "Remote access was already disabled");
+    if (this.deps.hasRunningManagedService()) {
+      await this.deps.restartBackgroundService("remote access disabled");
+      console.log("\u2713 Running background service restarted without remote access");
+    }
+  }
+  async status(opts = {}) {
+    await this.deps.remoteCommands.status(opts);
+  }
+  async doctor(opts = {}) {
+    await this.deps.remoteCommands.doctor(opts);
+  }
+};
+
+// src/remote-platform-client.ts
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { dirname, join } from "path";
+import { hostname, platform as readPlatform } from "os";
+function ensureDir(path) {
+  mkdirSync(path, { recursive: true });
+}
+function readJsonFile(path) {
+  if (!existsSync(path)) {
+    return null;
+  }
+  try {
+    return JSON.parse(readFileSync(path, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+function writeJsonFile(path, value) {
+  ensureDir(dirname(path));
+  writeFileSync(path, `${JSON.stringify(value, null, 2)}
+`, "utf-8");
+}
+function maskToken(value) {
+  if (value.length <= 12) {
+    return "<redacted>";
+  }
+  return `${value.slice(0, 6)}...${value.slice(-4)}`;
+}
+function normalizeOptionalString(value) {
+  if (typeof value !== "string") {
+    return void 0;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : void 0;
+}
+function delay(ms, signal) {
+  return new Promise((resolveDelay, rejectDelay) => {
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolveDelay();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      rejectDelay(new Error("Remote connector aborted."));
+    };
+    if (signal) {
+      signal.addEventListener("abort", onAbort, { once: true });
+    }
+  });
+}
+function redactWsUrl(url) {
+  try {
+    const parsed = new URL(url);
+    const token = parsed.searchParams.get("token");
+    if (token) {
+      parsed.searchParams.set("token", maskToken(token));
+    }
+    return parsed.toString();
+  } catch {
+    return url;
+  }
+}
+var RemotePlatformClient = class {
+  constructor(deps) {
+    this.deps = deps;
+  }
+  get remoteDir() {
+    return join(this.deps.getDataDir(), "remote");
+  }
+  get devicePath() {
+    return join(this.remoteDir, "device.json");
+  }
+  resolveRunContext(opts) {
+    const { platformBase, token, config } = this.resolvePlatformAccess(opts);
+    return {
+      config,
+      platformBase,
+      token,
+      localOrigin: this.resolveLocalOrigin(config, opts),
+      displayName: this.resolveDisplayName(config, opts),
+      deviceInstallId: this.ensureDeviceInstallId(),
+      autoReconnect: opts.once ? false : opts.autoReconnect ?? config.remote.autoReconnect
+    };
+  }
+  async registerDevice(params) {
+    const response = await fetch(`${params.platformBase}/platform/remote/devices/register`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        authorization: `Bearer ${params.token}`
+      },
+      body: JSON.stringify({
+        deviceInstallId: params.deviceInstallId,
+        displayName: params.displayName,
+        platform: readPlatform(),
+        appVersion: this.deps.getPackageVersion(),
+        localOrigin: params.localOrigin
+      })
+    });
+    const payload = await response.json();
+    if (!response.ok || !payload.ok || !payload.data?.device) {
+      throw new Error(payload.error?.message ?? `Failed to register remote device (${response.status}).`);
+    }
+    return payload.data.device;
+  }
+  ensureDeviceInstallId() {
+    const existing = readJsonFile(this.devicePath);
+    if (existing?.deviceInstallId?.trim()) {
+      return existing.deviceInstallId.trim();
+    }
+    const deviceInstallId = crypto.randomUUID();
+    ensureDir(this.remoteDir);
+    writeJsonFile(this.devicePath, { deviceInstallId });
+    return deviceInstallId;
+  }
+  resolvePlatformAccess(opts) {
+    const config = this.deps.loadConfig();
+    const providers = config.providers;
+    const nextclawProvider = providers.nextclaw;
+    const token = typeof nextclawProvider?.apiKey === "string" ? nextclawProvider.apiKey.trim() : "";
+    if (!token) {
+      throw new Error('NextClaw platform token is missing. Run "nextclaw login" first.');
+    }
+    const configuredApiBase = normalizeOptionalString(config.remote.platformApiBase) ?? (typeof nextclawProvider?.apiBase === "string" ? nextclawProvider.apiBase.trim() : "");
+    const rawApiBase = normalizeOptionalString(opts.apiBase) ?? configuredApiBase;
+    if (!rawApiBase) {
+      throw new Error("Platform API base is missing. Pass --api-base, run nextclaw login, or set remote.platformApiBase.");
+    }
+    const platformBase = this.deps.resolvePlatformBase(rawApiBase);
+    return { platformBase, token, config };
+  }
+  resolveLocalOrigin(config, opts) {
+    const explicitOrigin = normalizeOptionalString(opts.localOrigin);
+    if (explicitOrigin) {
+      return explicitOrigin.replace(/\/$/, "");
+    }
+    const state = this.deps.readManagedServiceState?.();
+    if (state && this.deps.isProcessRunning?.(state.pid) && Number.isFinite(state.uiPort)) {
+      return `http://127.0.0.1:${state.uiPort}`;
+    }
+    const configuredPort = typeof config.ui?.port === "number" && Number.isFinite(config.ui.port) ? config.ui.port : 18791;
+    return `http://127.0.0.1:${configuredPort}`;
+  }
+  resolveDisplayName(config, opts) {
+    return normalizeOptionalString(opts.name) ?? normalizeOptionalString(config.remote.deviceName) ?? hostname();
+  }
+};
+
+// src/remote-relay-bridge.ts
+import { ensureUiBridgeSecret } from "@nextclaw/server";
+function encodeBase64(bytes) {
+  return Buffer.from(bytes).toString("base64");
+}
+function decodeBase64(base64) {
+  if (!base64) {
+    return new Uint8Array();
+  }
+  return new Uint8Array(Buffer.from(base64, "base64"));
+}
+var RemoteRelayBridge = class {
+  constructor(localOrigin) {
+    this.localOrigin = localOrigin;
+  }
+  async ensureLocalUiHealthy() {
+    const response = await fetch(`${this.localOrigin}/api/health`);
+    if (!response.ok) {
+      throw new Error(`Local UI is not healthy at ${this.localOrigin}. Start NextClaw first.`);
+    }
+  }
+  async forward(frame, socket) {
+    const bridgeCookie = await this.requestBridgeCookie();
+    const url = new URL(frame.path, this.localOrigin);
+    const headers = this.createForwardHeaders(frame.headers, bridgeCookie);
+    const response = await fetch(url, {
+      method: frame.method,
+      headers,
+      body: frame.method === "GET" || frame.method === "HEAD" ? void 0 : decodeBase64(frame.bodyBase64)
+    });
+    const responseHeaders = Array.from(response.headers.entries()).filter(([key]) => {
+      const lower = key.toLowerCase();
+      return !["content-length", "connection", "transfer-encoding", "set-cookie"].includes(lower);
+    });
+    const contentType = response.headers.get("content-type")?.toLowerCase() ?? "";
+    if (response.body && contentType.startsWith("text/event-stream")) {
+      await this.sendStreamingResponse({ frame, response, responseHeaders, socket });
+      return;
+    }
+    const responseBody = response.body ? new Uint8Array(await response.arrayBuffer()) : new Uint8Array();
+    socket.send(JSON.stringify({
+      type: "response",
+      requestId: frame.requestId,
+      status: response.status,
+      headers: responseHeaders,
+      bodyBase64: encodeBase64(responseBody)
+    }));
+  }
+  createForwardHeaders(headersList, bridgeCookie) {
+    const headers = new Headers();
+    for (const [key, value] of headersList) {
+      const lower = key.toLowerCase();
+      if ([
+        "host",
+        "connection",
+        "content-length",
+        "cookie",
+        "x-forwarded-for",
+        "x-forwarded-proto",
+        "cf-connecting-ip"
+      ].includes(lower)) {
+        continue;
+      }
+      headers.set(key, value);
+    }
+    if (bridgeCookie) {
+      headers.set("cookie", bridgeCookie);
+    }
+    return headers;
+  }
+  async requestBridgeCookie() {
+    const response = await fetch(`${this.localOrigin}/api/auth/bridge`, {
+      method: "POST",
+      headers: {
+        "x-nextclaw-ui-bridge-secret": ensureUiBridgeSecret()
+      }
+    });
+    const payload = await response.json();
+    if (!response.ok || !payload.ok) {
+      throw new Error(payload.error?.message ?? `Failed to request local auth bridge (${response.status}).`);
+    }
+    return typeof payload.data?.cookie === "string" && payload.data.cookie.trim().length > 0 ? payload.data.cookie.trim() : null;
+  }
+  async sendStreamingResponse(params) {
+    params.socket.send(JSON.stringify({
+      type: "response.start",
+      requestId: params.frame.requestId,
+      status: params.response.status,
+      headers: params.responseHeaders
+    }));
+    const reader = params.response.body?.getReader();
+    if (!reader) {
+      params.socket.send(JSON.stringify({
+        type: "response.end",
+        requestId: params.frame.requestId
+      }));
+      return;
+    }
+    try {
+      while (true) {
+        const { value, done } = await reader.read();
+        if (done) {
+          break;
+        }
+        if (value && value.length > 0) {
+          params.socket.send(JSON.stringify({
+            type: "response.chunk",
+            requestId: params.frame.requestId,
+            bodyBase64: encodeBase64(value)
+          }));
+        }
+      }
+    } finally {
+      reader.releaseLock();
+    }
+    params.socket.send(JSON.stringify({
+      type: "response.end",
+      requestId: params.frame.requestId
+    }));
+  }
+};
+
+// src/remote-connector.ts
+var RemoteConnector = class {
+  constructor(deps) {
+    this.deps = deps;
+  }
+  get logger() {
+    return this.deps.logger ?? console;
+  }
+  async connectOnce(params) {
+    return await new Promise((resolve, reject) => {
+      const socket = new WebSocket(params.wsUrl);
+      let settled = false;
+      let aborted = false;
+      const pingTimer = setInterval(() => {
+        if (socket.readyState === WebSocket.OPEN) {
+          socket.send(JSON.stringify({ type: "ping", at: (/* @__PURE__ */ new Date()).toISOString() }));
+        }
+      }, 15e3);
+      const cleanup = () => {
+        clearInterval(pingTimer);
+        params.signal?.removeEventListener("abort", onAbort);
+      };
+      const finishResolve = (value) => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        cleanup();
+        resolve(value);
+      };
+      const finishReject = (error) => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        cleanup();
+        reject(error);
+      };
+      const onAbort = () => {
+        aborted = true;
+        try {
+          socket.close(1e3, "Remote connector aborted");
+        } catch {
+          finishResolve("aborted");
+        }
+      };
+      if (params.signal) {
+        if (params.signal.aborted) {
+          onAbort();
+        } else {
+          params.signal.addEventListener("abort", onAbort, { once: true });
+        }
+      }
+      socket.addEventListener("open", () => {
+        params.statusStore?.write({
+          enabled: true,
+          state: "connected",
+          deviceId: params.deviceId,
+          deviceName: params.displayName,
+          platformBase: params.platformBase,
+          localOrigin: params.localOrigin,
+          lastConnectedAt: (/* @__PURE__ */ new Date()).toISOString(),
+          lastError: null
+        });
+        this.logger.info(`\u2713 Remote connector connected: ${redactWsUrl(params.wsUrl)}`);
+      });
+      socket.addEventListener("message", (event) => {
+        this.handleSocketMessage({ data: event.data, relayBridge: params.relayBridge, socket });
+      });
+      socket.addEventListener("close", () => {
+        finishResolve(aborted ? "aborted" : "closed");
+      });
+      socket.addEventListener("error", () => {
+        if (aborted) {
+          finishResolve("aborted");
+          return;
+        }
+        finishReject(new Error("Remote connector websocket failed."));
+      });
+    });
+  }
+  handleSocketMessage(params) {
+    void (async () => {
+      const frame = this.parseRelayFrame(params.data);
+      if (!frame) {
+        return;
+      }
+      try {
+        await params.relayBridge.forward(frame, params.socket);
+      } catch (error) {
+        params.socket.send(JSON.stringify({
+          type: "response.error",
+          requestId: frame.requestId,
+          message: error instanceof Error ? error.message : String(error)
+        }));
+      }
+    })();
+  }
+  parseRelayFrame(data) {
+    try {
+      const frame = JSON.parse(String(data ?? ""));
+      return frame.type === "request" ? frame : null;
+    } catch {
+      return null;
+    }
+  }
+  async ensureDevice(params) {
+    if (params.device) {
+      return params.device;
+    }
+    const device = await this.deps.platformClient.registerDevice({
+      platformBase: params.context.platformBase,
+      token: params.context.token,
+      deviceInstallId: params.context.deviceInstallId,
+      displayName: params.context.displayName,
+      localOrigin: params.context.localOrigin
+    });
+    this.logger.info(`\u2713 Remote device registered: ${device.displayName} (${device.id})`);
+    this.logger.info(`\u2713 Local origin: ${params.context.localOrigin}`);
+    this.logger.info(`\u2713 Platform: ${params.context.platformBase}`);
+    return device;
+  }
+  writeRemoteState(statusStore, next) {
+    statusStore?.write(next);
+  }
+  async runCycle(params) {
+    try {
+      this.writeRemoteState(params.opts.statusStore, {
+        enabled: true,
+        state: "connecting",
+        deviceId: params.device?.id,
+        deviceName: params.context.displayName,
+        platformBase: params.context.platformBase,
+        localOrigin: params.context.localOrigin,
+        lastError: null
+      });
+      const device = await this.ensureDevice({ device: params.device, context: params.context });
+      const wsUrl = `${params.context.platformBase.replace(/^http/i, "ws")}/platform/remote/connect?deviceId=${encodeURIComponent(device.id)}&token=${encodeURIComponent(params.context.token)}`;
+      const outcome = await this.connectOnce({
+        wsUrl,
+        relayBridge: params.relayBridge,
+        signal: params.opts.signal,
+        statusStore: params.opts.statusStore,
+        displayName: params.context.displayName,
+        deviceId: device.id,
+        platformBase: params.context.platformBase,
+        localOrigin: params.context.localOrigin
+      });
+      if (outcome !== "aborted") {
+        this.writeRemoteState(params.opts.statusStore, {
+          enabled: true,
+          state: "disconnected",
+          deviceId: device.id,
+          deviceName: params.context.displayName,
+          platformBase: params.context.platformBase,
+          localOrigin: params.context.localOrigin,
+          lastError: null
+        });
+      }
+      return { device, aborted: outcome === "aborted" };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      this.writeRemoteState(params.opts.statusStore, {
+        enabled: true,
+        state: "error",
+        deviceId: params.device?.id,
+        deviceName: params.context.displayName,
+        platformBase: params.context.platformBase,
+        localOrigin: params.context.localOrigin,
+        lastError: message
+      });
+      this.logger.error(`Remote connector error: ${message}`);
+      return { device: params.device, aborted: false };
+    }
+  }
+  async run(opts = {}) {
+    const context = this.deps.platformClient.resolveRunContext(opts);
+    const relayBridge = (this.deps.relayBridgeFactory ?? ((localOrigin) => new RemoteRelayBridge(localOrigin)))(
+      context.localOrigin
+    );
+    await relayBridge.ensureLocalUiHealthy();
+    let device = null;
+    while (!opts.signal?.aborted) {
+      const cycle = await this.runCycle({ device, context, relayBridge, opts });
+      device = cycle.device;
+      if (cycle.aborted || !context.autoReconnect || opts.signal?.aborted) {
+        break;
+      }
+      this.logger.warn("Remote connector disconnected. Reconnecting in 3s...");
+      try {
+        await delay(3e3, opts.signal);
+      } catch {
+        break;
+      }
+    }
+    this.writeRemoteState(opts.statusStore, {
+      enabled: opts.mode === "service" ? true : Boolean(context.config.remote.enabled),
+      state: opts.signal?.aborted ? "disconnected" : "disabled",
+      deviceId: device?.id,
+      deviceName: context.displayName,
+      platformBase: context.platformBase,
+      localOrigin: context.localOrigin,
+      lastError: null
+    });
+  }
+};
+
+// src/remote-status-store.ts
+import { hostname as hostname2 } from "os";
+function normalizeOptionalString2(value) {
+  if (typeof value !== "string") {
+    return void 0;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : void 0;
+}
+function buildConfiguredRemoteState(config) {
+  const remote = config.remote;
+  return {
+    enabled: Boolean(remote.enabled),
+    mode: "service",
+    state: remote.enabled ? "disconnected" : "disabled",
+    ...normalizeOptionalString2(remote.deviceName) ? { deviceName: normalizeOptionalString2(remote.deviceName) } : {},
+    ...normalizeOptionalString2(remote.platformApiBase) ? { platformBase: normalizeOptionalString2(remote.platformApiBase) } : {},
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function resolveRemoteStatusSnapshot(params) {
+  if (params.currentRemoteState) {
+    return {
+      configuredEnabled: Boolean(params.config.remote.enabled),
+      runtime: params.currentRemoteState
+    };
+  }
+  if (params.config.remote.enabled) {
+    return {
+      configuredEnabled: true,
+      runtime: {
+        ...buildConfiguredRemoteState(params.config),
+        deviceName: normalizeOptionalString2(params.config.remote.deviceName) ?? normalizeOptionalString2(params.fallbackDeviceName) ?? hostname2()
+      }
+    };
+  }
+  return {
+    configuredEnabled: false,
+    runtime: null
+  };
+}
+var RemoteStatusStore = class {
+  constructor(mode, deps) {
+    this.mode = mode;
+    this.deps = deps;
+  }
+  write(next) {
+    this.deps.writeRemoteState({
+      ...next,
+      mode: this.mode,
+      updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+    });
+  }
+};
+
+// src/remote-service-module.ts
+var RemoteServiceModule = class {
+  constructor(deps) {
+    this.deps = deps;
+  }
+  abortController = null;
+  runTask = null;
+  start() {
+    if (!this.deps.config.remote.enabled) {
+      this.deps.statusStore.write({
+        enabled: false,
+        state: "disabled",
+        deviceName: void 0,
+        deviceId: void 0,
+        platformBase: void 0,
+        localOrigin: this.deps.localOrigin,
+        lastError: null,
+        lastConnectedAt: null
+      });
+      return null;
+    }
+    const logger = this.deps.logger ?? {
+      info: (message) => console.log(`[remote] ${message}`),
+      warn: (message) => console.warn(`[remote] ${message}`),
+      error: (message) => console.error(`[remote] ${message}`)
+    };
+    this.abortController = new AbortController();
+    const connector = this.deps.createConnector(logger);
+    this.runTask = connector.run({
+      mode: "service",
+      signal: this.abortController.signal,
+      autoReconnect: this.deps.config.remote.autoReconnect,
+      localOrigin: this.deps.localOrigin,
+      statusStore: this.deps.statusStore
+    });
+    void this.runTask.catch((error) => {
+      const message = error instanceof Error ? error.message : String(error);
+      this.deps.statusStore.write({
+        enabled: true,
+        state: "error",
+        deviceName: this.deps.config.remote.deviceName || void 0,
+        deviceId: void 0,
+        platformBase: this.deps.config.remote.platformApiBase || void 0,
+        localOrigin: this.deps.localOrigin,
+        lastError: message
+      });
+      logger.error(message);
+    });
+    return this.runTask;
+  }
+  async stop() {
+    this.abortController?.abort();
+    try {
+      await this.runTask;
+    } catch {
+    } finally {
+      this.abortController = null;
+      this.runTask = null;
+    }
+  }
+};
+export {
+  RemoteConnector,
+  RemotePlatformClient,
+  RemoteRelayBridge,
+  RemoteRuntimeActions,
+  RemoteServiceModule,
+  RemoteStatusStore,
+  buildConfiguredRemoteState,
+  delay,
+  normalizeOptionalString,
+  redactWsUrl,
+  registerRemoteCommands,
+  resolveRemoteStatusSnapshot
+};

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@nextclaw/remote",
+  "version": "0.1.1",
+  "private": false,
+  "description": "Remote access runtime for NextClaw device registration, relay bridging, and service-managed connectivity.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Peiiii/nextclaw.git",
+    "directory": "packages/nextclaw-remote"
+  },
+  "homepage": "https://github.com/Peiiii/nextclaw/tree/master/packages/nextclaw-remote",
+  "keywords": [
+    "nextclaw",
+    "remote",
+    "relay",
+    "cli"
+  ],
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "commander": "^12.1.0",
+    "@nextclaw/core": "0.9.5",
+    "@nextclaw/server": "0.10.5"
+  },
+  "devDependencies": {
+    "@types/node": "^20.17.6",
+    "prettier": "^3.3.3",
+    "tsup": "^8.3.5",
+    "typescript": "^5.6.3"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --out-dir dist",
+    "lint": "eslint .",
+    "tsc": "tsc -p tsconfig.json"
+  }
+}