@openclaw/gateway-client 0.0.0 → 2026.7.2-beta.4

package/dist/protocol-client-Cj1WAoMt.d.mts

@@ -0,0 +1,180 @@
+import { ErrorShape, EventFrame, HelloOk } from "@openclaw/gateway-protocol";
+
+//#region packages/gateway-client/src/protocol-client.d.ts
+type GatewayProtocolSocket = {
+  isOpen: () => boolean;
+  send: (data: string) => void;
+  close: (code?: number, reason?: string) => void;
+};
+type GatewayProtocolSocketHandlers = {
+  open: () => void;
+  message: (data: string) => void;
+  close: (code: number, reason: string) => void;
+  error: (error: Error) => void;
+};
+type GatewayProtocolRequestOptions = {
+  timeoutMs?: number | null;
+  expectFinal?: boolean;
+  onSent?: () => void;
+  onAccepted?: (payload: unknown) => void;
+  signal?: AbortSignal;
+};
+type GatewayProtocolConnectContext<TPlan> = {
+  generation: number;
+  nonce: string | null;
+  plan: TPlan;
+};
+type GatewayProtocolCloseContext = {
+  code: number;
+  reason: string;
+  generation: number;
+  socketOpened: boolean;
+  helloReceived: boolean;
+  connectRequestSent: boolean;
+  connectFailure?: {
+    error: Error;
+    reconnectDelayMs?: number;
+  };
+};
+type GatewayProtocolConnectDecision = {
+  closeCode: number;
+  closeReason: string;
+  reconnectDelayMs?: number;
+  stop?: boolean;
+  error?: Error;
+};
+type GatewayProtocolCloseDecision = {
+  retry: boolean;
+  notify: boolean;
+  reconnectDelayMs?: number;
+  pendingError?: Error;
+};
+type GatewayProtocolTiming<TPlan> = {
+  phase: "socket-open" | "challenge" | "fallback" | "device-identity-ready" | "connect-plan-ready" | "request-sent" | "hello" | "failed";
+  generation: number;
+  durationMs: number;
+  phaseDurationMs: number;
+  hasChallenge: boolean;
+  usedFallback: boolean;
+  plan?: TPlan;
+  detail?: unknown;
+};
+type GatewayProtocolRequestTiming = {
+  id: string;
+  method: string;
+  ok: boolean;
+  durationMs: number;
+  startedAtMs: number;
+  endedAtMs: number;
+  errorCode?: string;
+};
+type GatewayProtocolClientOptions<TPlan> = {
+  createSocket: (handlers: GatewayProtocolSocketHandlers) => GatewayProtocolSocket;
+  createRequestId: () => string;
+  createRequestError?: (error: Partial<ErrorShape>) => GatewayProtocolRequestError;
+  createRequestTimeoutError?: (method: string, timeoutMs: number) => Error;
+  createRequestAbortError?: (method: string) => Error;
+  buildConnectPlan: (params: {
+    nonce: string | null;
+    generation: number;
+  }) => TPlan | Promise<TPlan>;
+  buildConnectParams: (plan: TPlan) => unknown;
+  onConnectPlanError?: (error: Error) => GatewayProtocolConnectDecision;
+  onConnectHello?: (hello: HelloOk, context: GatewayProtocolConnectContext<TPlan>) => void;
+  onHello?: (hello: HelloOk) => void;
+  onConnectFailure?: (error: GatewayProtocolRequestError, context: GatewayProtocolConnectContext<TPlan>) => GatewayProtocolConnectDecision;
+  resolveClose: (context: GatewayProtocolCloseContext) => GatewayProtocolCloseDecision;
+  onClose?: (context: GatewayProtocolCloseContext, decision: GatewayProtocolCloseDecision) => void;
+  notifyStoppedClose?: boolean;
+  onConnectError?: (error: Error) => void;
+  onSocketFactoryError?: (error: Error) => void;
+  onParseError?: (error: unknown) => void;
+  onEvent?: (event: EventFrame) => void;
+  onGap?: (info: {
+    expected: number;
+    received: number;
+  }) => void;
+  onActivity?: () => void;
+  onTiming?: (timing: GatewayProtocolTiming<TPlan>) => void;
+  onRequestTiming?: (timing: GatewayProtocolRequestTiming) => void;
+  onCallbackError?: (label: string, error: unknown) => void;
+  handshake: {
+    mode: "fallback";
+    timeoutMs: number;
+  } | {
+    mode: "require-challenge";
+    timeoutMs: number;
+    timeoutMessage?: (elapsedMs: number) => string;
+  };
+  reconnect: {
+    initialMs: number;
+    multiplier: number;
+    maxMs: number;
+  };
+  requestTimeoutMs?: number;
+  nowMs?: () => number;
+  rethrowSocketFactoryError?: (error: Error) => boolean;
+};
+declare class GatewayProtocolRequestError extends Error {
+  readonly code: string;
+  readonly gatewayCode: string;
+  readonly details?: unknown;
+  readonly retryable: boolean;
+  readonly retryAfterMs?: number;
+  constructor(error: Partial<ErrorShape>);
+}
+/**
+ * Browser-safe gateway wire client. Environment adapters own transport and auth
+ * policy; this class owns the single socket/handshake/reconnect/frame state machine.
+ */
+declare class GatewayProtocolClient<TPlan> {
+  private readonly opts;
+  private socket;
+  private readonly pending;
+  private listeners;
+  private stopped;
+  private generation;
+  private lastSeq;
+  private connectNonce;
+  private connectSent;
+  private connectRequestSent;
+  private handshakeTimer;
+  private readonly reconnectSupervisor;
+  private socketOpened;
+  private helloReceived;
+  private connectFailure;
+  private connectTiming;
+  private stoppedSocket?;
+  constructor(opts: GatewayProtocolClientOptions<TPlan>);
+  get connected(): boolean;
+  get hasPendingRequests(): boolean;
+  get connecting(): boolean;
+  get hasUnboundedPendingRequests(): boolean;
+  start(): void;
+  stop(): void;
+  request<T = unknown>(method: string, params?: unknown, options?: GatewayProtocolRequestOptions): Promise<T>;
+  addEventListener(listener: (event: EventFrame) => void): () => void;
+  closeSocket(code?: number, reason?: string): void;
+  resetReconnectBackoff(initialMs: number): void;
+  recordTiming(phase: GatewayProtocolTiming<TPlan>["phase"], generation: number, plan?: TPlan, detail?: unknown): void;
+  private connect;
+  private handleOpen;
+  private armHandshakeTimer;
+  private sendConnect;
+  private handleConnectPlanError;
+  private sendConnectPlan;
+  private handleMessage;
+  private handleResponse;
+  private handleClose;
+  private handleSocketError;
+  private flushRequests;
+  private finishRequestTiming;
+  private scheduleReconnect;
+  private closeContext;
+  private isActive;
+  private nowMs;
+  private clearHandshakeTimer;
+  private invoke;
+}
+//#endregion
+export { GatewayProtocolRequestTiming as a, GatewayProtocolTiming as c, GatewayProtocolRequestOptions as i, GatewayProtocolCloseContext as n, GatewayProtocolSocket as o, GatewayProtocolRequestError as r, GatewayProtocolSocketHandlers as s, GatewayProtocolClient as t };

package/dist/readiness-CPiKyi1s.d.mts

@@ -0,0 +1,201 @@
+import { i as GatewayProtocolRequestOptions, r as GatewayProtocolRequestError } from "./protocol-client-Cj1WAoMt.mjs";
+import { ErrorShape, EventFrame, HelloOk } from "@openclaw/gateway-protocol/frame-guards";
+import { GatewayClientMode, GatewayClientName } from "@openclaw/gateway-protocol/client-info";
+
+//#region packages/gateway-client/src/client.d.ts
+type DeviceIdentity = {
+  deviceId: string;
+  privateKeyPem: string;
+  publicKeyPem: string;
+};
+type DeviceAuthTokenRecord = {
+  token?: string;
+  scopes?: string[];
+};
+type GatewayClientHostDeps = {
+  loadOrCreateDeviceIdentity?: () => DeviceIdentity | undefined;
+  signDevicePayload?: (privateKeyPem: string, payload: string) => string;
+  publicKeyRawBase64UrlFromPem?: (publicKeyPem: string) => string;
+  loadDeviceAuthToken?: (params: {
+    deviceId: string;
+    role: string;
+    env?: NodeJS.ProcessEnv;
+  }) => DeviceAuthTokenRecord | null;
+  storeDeviceAuthToken?: (params: {
+    deviceId: string;
+    role: string;
+    token: string;
+    scopes: string[];
+    env?: NodeJS.ProcessEnv;
+  }) => void;
+  clearDeviceAuthToken?: (params: {
+    deviceId: string;
+    role: string;
+    env?: NodeJS.ProcessEnv;
+  }) => void;
+  beforeConnect?: () => void;
+  registerGatewayLoopbackBypass?: (url: string) => (() => void) | undefined;
+  logDebug?: (message: string) => void;
+  logError?: (message: string) => void;
+  redactForLog?: (message: string) => string;
+  normalizeTlsFingerprint?: (fingerprint: string | undefined) => string;
+};
+type GatewayClientRequestOptions = GatewayProtocolRequestOptions;
+type GatewayReconnectPausedInfo = {
+  code: number;
+  reason: string;
+  detailCode: string | null;
+};
+type GatewayClientCloseInfo = {
+  phase: "pre-hello" | "post-hello";
+  socketOpened: boolean;
+  transportValidated: boolean;
+  transientPreHelloCleanClose: boolean;
+};
+declare class GatewayClientRequestError extends GatewayProtocolRequestError {
+  constructor(error: Partial<ErrorShape>);
+}
+declare function isGatewayConnectAssemblyError(value: unknown): value is Error;
+type GatewayClientOptions = {
+  url?: string;
+  origin?: string;
+  connectChallengeTimeoutMs?: number;
+  /**
+   * Server-side pre-auth handshake budget. Config-derived local clients use
+   * this to keep the connect-challenge watchdog aligned with the gateway.
+   */
+  preauthHandshakeTimeoutMs?: number;
+  tickWatchMinIntervalMs?: number;
+  tickWatchTimeoutMs?: number;
+  requestTimeoutMs?: number;
+  token?: string;
+  bootstrapToken?: string;
+  deviceToken?: string;
+  password?: string;
+  approvalRuntimeToken?: string;
+  agentRuntimeIdentityToken?: string;
+  instanceId?: string;
+  clientName?: GatewayClientName;
+  clientDisplayName?: string;
+  clientVersion?: string;
+  platform?: string;
+  deviceFamily?: string;
+  mode?: GatewayClientMode;
+  role?: string;
+  scopes?: string[];
+  caps?: string[];
+  commands?: string[];
+  permissions?: Record<string, boolean>;
+  pathEnv?: string;
+  env?: NodeJS.ProcessEnv;
+  deviceIdentity?: DeviceIdentity | null;
+  hostDeps?: GatewayClientHostDeps;
+  minProtocol?: number;
+  maxProtocol?: number;
+  tlsFingerprint?: string;
+  onEvent?: (evt: EventFrame) => void;
+  onHelloOk?: (hello: HelloOk) => void;
+  onConnectError?: (err: Error) => void;
+  onReconnectPaused?: (info: GatewayReconnectPausedInfo) => void;
+  onClose?: (code: number, reason: string, info?: GatewayClientCloseInfo) => void;
+  onGap?: (info: {
+    expected: number;
+    received: number;
+  }) => void;
+};
+type GatewayClientConnectionMetadata = {
+  clientName?: GatewayClientName;
+  hasDeviceIdentity: boolean;
+  mode?: GatewayClientMode;
+  preauthHandshakeTimeoutMs?: number;
+};
+declare class GatewayClient {
+  private readonly protocol;
+  private ws;
+  private opts;
+  private deps;
+  private stopped;
+  private pendingDeviceTokenRetry;
+  private deviceTokenRetryBudgetUsed;
+  private approvalRuntimeTokenCompatibilityDisabled;
+  private approvalRuntimeTokenRetryBudgetUsed;
+  private lastTick;
+  private tickIntervalMs;
+  private tickTimer;
+  private readonly requestTimeoutMs;
+  private pendingStop;
+  private transportValidated;
+  private suppressedTransientPreHelloCleanCloses;
+  constructor(opts: GatewayClientOptions);
+  getConnectionMetadata(): GatewayClientConnectionMetadata;
+  updateNodeManifest(manifest: {
+    caps: string[];
+    commands: string[];
+  }): void;
+  start(): void;
+  private createSocket;
+  stop(): void;
+  stopAndWait(opts?: {
+    timeoutMs?: number;
+  }): Promise<void>;
+  private beginStop;
+  private createPendingStop;
+  private resolvePendingStop;
+  private logDebug;
+  private logError;
+  private assembleConnectParams;
+  private buildDeviceConnectParams;
+  private handleConnectHello;
+  private handleConnectRequestFailure;
+  private resolveClose;
+  private closeInfo;
+  private clearStaleDeviceTokenForClose;
+  private notifyConnectError;
+  private notifyReconnectPaused;
+  private shouldRetryWithoutApprovalRuntimeToken;
+  private shouldFailClosedForUnsupportedAgentRuntimeIdentity;
+  private isTrustedDeviceRetryEndpoint;
+  private selectConnectAuth;
+  private startTickWatch;
+  private validateTlsFingerprint;
+  request<T = Record<string, unknown>>(method: string, params?: unknown, opts?: GatewayClientRequestOptions): Promise<T>;
+}
+//#endregion
+//#region packages/gateway-client/src/event-loop-ready.d.ts
+/** Readiness probe outcome with timing data for diagnosing event-loop stalls. */
+type EventLoopReadyResult = {
+  ready: boolean;
+  elapsedMs: number;
+  maxDriftMs: number;
+  checks: number;
+  aborted: boolean;
+};
+/** Controls how aggressively the client waits for low-drift timer checks before starting IO. */
+type EventLoopReadyOptions = {
+  maxWaitMs?: number;
+  intervalMs?: number;
+  driftThresholdMs?: number;
+  consecutiveReadyChecks?: number;
+  signal?: AbortSignal;
+};
+/** Waits until timer drift stays low for consecutive checks, or aborts/times out. */
+declare function waitForEventLoopReady(options?: EventLoopReadyOptions): Promise<EventLoopReadyResult>;
+//#endregion
+//#region packages/gateway-client/src/readiness.d.ts
+type GatewayClientStartable = {
+  start(): void;
+};
+/** Injectable readiness waiter used by tests and alternate event-loop probes. */
+type EventLoopReadyWaiter = (options?: EventLoopReadyOptions) => Promise<EventLoopReadyResult>;
+/** Timeout and abort controls for delaying client start until the loop can process IO. */
+type GatewayClientStartReadinessOptions = {
+  timeoutMs?: number;
+  clientOptions?: Pick<GatewayClientOptions, "connectChallengeTimeoutMs" | "env" | "preauthHandshakeTimeoutMs">;
+  signal?: AbortSignal;
+};
+/** Starts a gateway client only after the supplied readiness probe succeeds. */
+declare function startGatewayClientWithReadinessWait(waitForReady: EventLoopReadyWaiter, client: GatewayClientStartable, options?: GatewayClientStartReadinessOptions): Promise<EventLoopReadyResult>;
+/** Starts a gateway client after the default event-loop readiness probe succeeds. */
+declare function startGatewayClientWhenEventLoopReady(client: GatewayClientStartable, options?: GatewayClientStartReadinessOptions): Promise<EventLoopReadyResult>;
+//#endregion
+export { GatewayClientRequestOptions as _, startGatewayClientWithReadinessWait as a, waitForEventLoopReady as c, GatewayClient as d, GatewayClientCloseInfo as f, GatewayClientRequestError as g, GatewayClientOptions as h, startGatewayClientWhenEventLoopReady as i, DeviceAuthTokenRecord as l, GatewayClientHostDeps as m, GatewayClientStartReadinessOptions as n, EventLoopReadyOptions as o, GatewayClientConnectionMetadata as p, GatewayClientStartable as r, EventLoopReadyResult as s, EventLoopReadyWaiter as t, DeviceIdentity as u, GatewayReconnectPausedInfo as v, isGatewayConnectAssemblyError as y };

package/dist/readiness-CrWxd4TI.mjs

@@ -0,0 +1,105 @@
+import { resolveConnectChallengeTimeoutMs, resolveFiniteTimeoutDelayMs } from "./timeouts.mjs";
+//#region packages/gateway-client/src/event-loop-ready.ts
+const DEFAULT_MAX_WAIT_MS = 1e4;
+const DEFAULT_INTERVAL_MS = 1;
+const DEFAULT_DRIFT_THRESHOLD_MS = 200;
+const DEFAULT_CONSECUTIVE_READY_CHECKS = 2;
+function resolvePositiveInteger(value, fallback) {
+	return Number.isFinite(value) && value !== void 0 ? Math.max(1, Math.floor(value)) : fallback;
+}
+/** Waits until timer drift stays low for consecutive checks, or aborts/times out. */
+async function waitForEventLoopReady(options = {}) {
+	const maxWaitMs = resolveFiniteTimeoutDelayMs(options.maxWaitMs, DEFAULT_MAX_WAIT_MS, { minMs: 0 });
+	const intervalMs = resolveFiniteTimeoutDelayMs(options.intervalMs, DEFAULT_INTERVAL_MS);
+	const driftThresholdMs = resolvePositiveInteger(options.driftThresholdMs, DEFAULT_DRIFT_THRESHOLD_MS);
+	const consecutiveReadyChecks = resolvePositiveInteger(options.consecutiveReadyChecks, DEFAULT_CONSECUTIVE_READY_CHECKS);
+	const signal = options.signal;
+	const startedAt = Date.now();
+	let readyChecks = 0;
+	let checks = 0;
+	let maxDriftMs = 0;
+	return await new Promise((resolve) => {
+		let settled = false;
+		let timer = null;
+		const clearTimer = () => {
+			if (timer) {
+				clearTimeout(timer);
+				timer = null;
+			}
+		};
+		const finish = (ready, aborted = false) => {
+			if (settled) return;
+			settled = true;
+			clearTimer();
+			signal?.removeEventListener("abort", onAbort);
+			resolve({
+				ready,
+				elapsedMs: Math.max(0, Date.now() - startedAt),
+				maxDriftMs,
+				checks,
+				aborted
+			});
+		};
+		const onAbort = () => {
+			finish(false, true);
+		};
+		if (signal?.aborted) {
+			finish(false, true);
+			return;
+		}
+		signal?.addEventListener("abort", onAbort, { once: true });
+		const scheduleNext = () => {
+			if (signal?.aborted) {
+				finish(false, true);
+				return;
+			}
+			const elapsedMs = Math.max(0, Date.now() - startedAt);
+			const remainingMs = maxWaitMs - elapsedMs;
+			if (remainingMs <= 0) {
+				finish(false);
+				return;
+			}
+			const delayMs = Math.min(intervalMs, remainingMs);
+			const scheduledAt = Date.now();
+			timer = setTimeout(() => {
+				timer = null;
+				checks += 1;
+				const driftMs = Math.max(0, Date.now() - scheduledAt - delayMs);
+				maxDriftMs = Math.max(maxDriftMs, driftMs);
+				if (driftMs > driftThresholdMs) readyChecks = 0;
+				else readyChecks += 1;
+				if (readyChecks >= consecutiveReadyChecks) {
+					finish(true);
+					return;
+				}
+				scheduleNext();
+			}, delayMs);
+		};
+		scheduleNext();
+	});
+}
+//#endregion
+//#region packages/gateway-client/src/readiness.ts
+function resolveGatewayClientStartReadinessTimeoutMs(options = {}) {
+	if (typeof options.timeoutMs === "number" && Number.isFinite(options.timeoutMs)) return options.timeoutMs;
+	const clientOptions = options.clientOptions ?? {};
+	return resolveConnectChallengeTimeoutMs(clientOptions.connectChallengeTimeoutMs, {
+		env: clientOptions.env,
+		configuredTimeoutMs: clientOptions.preauthHandshakeTimeoutMs
+	});
+}
+/** Starts a gateway client only after the supplied readiness probe succeeds. */
+async function startGatewayClientWithReadinessWait(waitForReady, client, options = {}) {
+	const readiness = await waitForReady({
+		maxWaitMs: resolveGatewayClientStartReadinessTimeoutMs(options),
+		signal: options.signal
+	});
+	if (readiness.ready && !readiness.aborted && options.signal?.aborted !== true) client.start();
+	return readiness;
+}
+/** Starts a gateway client after the default event-loop readiness probe succeeds. */
+async function startGatewayClientWhenEventLoopReady(client, options = {}) {
+	return startGatewayClientWithReadinessWait(waitForEventLoopReady, client, options);
+}
+//#endregion
+export { startGatewayClientWithReadinessWait as n, waitForEventLoopReady as r, startGatewayClientWhenEventLoopReady as t };

package/dist/readiness.d.mts

@@ -0,0 +1,2 @@
+import { a as startGatewayClientWithReadinessWait, i as startGatewayClientWhenEventLoopReady, n as GatewayClientStartReadinessOptions, r as GatewayClientStartable, t as EventLoopReadyWaiter } from "./readiness-CPiKyi1s.mjs";
+export { EventLoopReadyWaiter, GatewayClientStartReadinessOptions, GatewayClientStartable, startGatewayClientWhenEventLoopReady, startGatewayClientWithReadinessWait };

package/dist/readiness.mjs

@@ -0,0 +1,3 @@
+import "./timeouts.mjs";
+import { n as startGatewayClientWithReadinessWait, t as startGatewayClientWhenEventLoopReady } from "./readiness-CrWxd4TI.mjs";
+export { startGatewayClientWhenEventLoopReady, startGatewayClientWithReadinessWait };