@clawling/clawchat-plugin-openclaw 2026.10.9-1 → 2026.10.9-2

package/dist/src/connect-check.js

@@ -1,4 +1,5 @@
 import { ClawlingApiError } from "./api-types.js";
+import { readConnectFailureGuidance } from "./connect-failure.js";
 import { AGENTS_CONNECT_PLATFORM, RECONNECT_GUIDE_URL } from "./onboarding-context.js";
 /**
  * Non-consuming pre-check of a connect code. Records the "checked" funnel
@@ -29,8 +30,14 @@ export async function preCheckConnectCode(client, input, log) {
         };
     }
     catch (err) {
+        // Still a degrade, never a gate: `/connect` re-evaluates the code and
+        // surfaces the same guidance on the error it throws. The guidance is only
+        // logged here so a rate-limit or dead code is visible early.
         const kind = err instanceof ClawlingApiError ? err.kind : "error";
-        log(`Connect-code pre-check unavailable (${kind}); continuing without it.`);
+        const guidance = err instanceof ClawlingApiError ? readConnectFailureGuidance(err.meta?.data) : {};
+        const action = guidance.nextAction ? `; next_action: ${guidance.nextAction}` : "";
+        const hint = guidance.hint ? `. ${guidance.hint}` : "";
+        log(`Connect-code pre-check unavailable (${kind}${action})${hint}; continuing without it.`);
         return null;
     }
 }

package/dist/src/connect-failure.js

@@ -0,0 +1,78 @@
+/** Default wait for `wait_retry` when the server omits / garbles the delay. */
+export const WAIT_RETRY_DEFAULT_SECONDS = 60;
+/** Upper bound on any `wait_retry` wait, whatever the server asks for. */
+export const WAIT_RETRY_MAX_SECONDS = 120;
+function readNonBlankString(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed ? trimmed : undefined;
+}
+export function readConnectFailureGuidance(data) {
+    if (!data || typeof data !== "object" || Array.isArray(data))
+        return {};
+    const record = data;
+    const out = {};
+    const hint = readNonBlankString(record.hint);
+    if (hint)
+        out.hint = hint;
+    const nextAction = readNonBlankString(record.next_action);
+    if (nextAction)
+        out.nextAction = nextAction;
+    const retryAfter = record.retry_after_seconds;
+    if (typeof retryAfter === "number" && Number.isFinite(retryAfter)) {
+        out.retryAfterSeconds = retryAfter;
+    }
+    return out;
+}
+/** Delay before the single `wait_retry` retry: server value, capped, with a default. */
+export function waitRetryDelayMs(retryAfterSeconds) {
+    const seconds = typeof retryAfterSeconds === "number" && Number.isFinite(retryAfterSeconds) && retryAfterSeconds > 0
+        ? Math.min(retryAfterSeconds, WAIT_RETRY_MAX_SECONDS)
+        : WAIT_RETRY_DEFAULT_SECONDS;
+    return Math.round(seconds * 1000);
+}
+/**
+ * Error thrown by the invite-code login when `/v1/agents/connect` fails.
+ * The message keeps the historical `agents/connect failed (<kind>): <msg>`
+ * prefix; when the server sent guidance it is appended so an agent reading
+ * the CLI / chat-command output knows what to do next.
+ */
+export class ConnectFailedError extends Error {
+    kind;
+    code;
+    status;
+    hint;
+    nextAction;
+    retryAfterSeconds;
+    constructor(kind, serverMessage, meta = {}) {
+        super(formatConnectFailureMessage(kind, serverMessage, meta));
+        this.name = "ConnectFailedError";
+        this.kind = kind;
+        if (meta.code !== undefined)
+            this.code = meta.code;
+        if (meta.status !== undefined)
+            this.status = meta.status;
+        if (meta.hint !== undefined)
+            this.hint = meta.hint;
+        if (meta.nextAction !== undefined)
+            this.nextAction = meta.nextAction;
+        if (meta.retryAfterSeconds !== undefined)
+            this.retryAfterSeconds = meta.retryAfterSeconds;
+    }
+}
+function formatConnectFailureMessage(kind, serverMessage, guidance) {
+    let text = `agents/connect failed (${kind}): ${serverMessage}`;
+    if (guidance.nextAction)
+        text += ` (next_action: ${guidance.nextAction})`;
+    if (guidance.hint)
+        text += `. ${guidance.hint}`;
+    return text;
+}
+export function connectFailedError(err) {
+    return new ConnectFailedError(err.kind, err.message, {
+        ...(err.meta?.code !== undefined ? { code: err.meta.code } : {}),
+        ...(err.meta?.status !== undefined ? { status: err.meta.status } : {}),
+        ...readConnectFailureGuidance(err.meta?.data),
+    });
+}

package/dist/src/login.runtime.js

@@ -8,10 +8,14 @@ import { CHANNEL_ID, mergeOpenclawClawchatRuntimePluginActivation, mergeOpenclaw
 import { getClawChatStore } from "./storage.js";
 import { buildOnboardingContext, RECONNECT_GUIDE_URL } from "./onboarding-context.js";
 import { boundCodeNewIdentityMessage, preCheckConnectCode, unpairableMessage } from "./connect-check.js";
+import { connectFailedError, readConnectFailureGuidance, waitRetryDelayMs } from "./connect-failure.js";
 // Re-exported: `src/login.runtime.test.ts` and `src/commands.ts` import these
 // from here, so the historical import path keeps working after the move.
 import { AGENTS_CONNECT_PLATFORM, AGENTS_CONNECT_TYPE, AGENT_NOT_FOUND_CODE, } from "./onboarding-context.js";
 export { AGENTS_CONNECT_PLATFORM, AGENTS_CONNECT_TYPE, AGENT_NOT_FOUND_CODE };
+function defaultSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
 /**
  * Thrown when redeeming an invite code would silently replace a live activation.
  *
@@ -284,8 +288,31 @@ export async function runOpenclawClawlingLogin(params) {
     // A brand-new identity is precisely "do not replay" — the replay is the only
     // thing that would bind this code to the incumbent agent.
     const existingUserId = newAccount ? "" : storedUserId;
+    // Rate-limit (`next_action: wait_retry`) budget: one wait-and-retry per
+    // activation, shared across both requests below.
+    let waitRetryUsed = false;
+    const sleep = params.sleep ?? defaultSleep;
+    const redeem = async (body) => {
+        try {
+            return await apiClient.agentsConnect(body);
+        }
+        catch (err) {
+            if (!(err instanceof ClawlingApiError) || waitRetryUsed)
+                throw err;
+            const guidance = readConnectFailureGuidance(err.meta?.data);
+            // Only wait_retry is retried: a rate-limited request did not consume the
+            // code. Every other next_action (and any unknown one) is final.
+            if (guidance.nextAction !== "wait_retry")
+                throw err;
+            waitRetryUsed = true;
+            const delayMs = waitRetryDelayMs(guidance.retryAfterSeconds);
+            runtime.log(`Connect code redeem rate limited — retrying once in ${Math.round(delayMs / 1000)}s …`);
+            await sleep(delayMs);
+            return await apiClient.agentsConnect(body);
+        }
+    };
     try {
-        result = await apiClient.agentsConnect({
+        result = await redeem({
             code: inviteCode,
             platform: AGENTS_CONNECT_PLATFORM,
             type: AGENTS_CONNECT_TYPE,
@@ -306,7 +333,7 @@ export async function runOpenclawClawlingLogin(params) {
             if (existingUserId && err.meta?.code === AGENT_NOT_FOUND_CODE) {
                 runtime.log(`Stored userId ${existingUserId} no longer exists on this server — retrying as a fresh pairing …`);
                 try {
-                    result = await apiClient.agentsConnect({
+                    result = await redeem({
                         code: inviteCode,
                         platform: AGENTS_CONNECT_PLATFORM,
                         type: AGENTS_CONNECT_TYPE,
@@ -315,13 +342,13 @@ export async function runOpenclawClawlingLogin(params) {
                 }
                 catch (retryErr) {
                     if (retryErr instanceof ClawlingApiError) {
-                        throw new Error(`agents/connect failed (${retryErr.kind}): ${retryErr.message}`);
+                        throw connectFailedError(retryErr);
                     }
                     throw retryErr;
                 }
             }
             else {
-                throw new Error(`agents/connect failed (${err.kind}): ${err.message}`);
+                throw connectFailedError(err);
             }
         }
         else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawling/clawchat-plugin-openclaw",
-  "version": "2026.10.9-1",
+  "version": "2026.10.9-2",
   "description": "OpenClaw ClawChat channel plugin",
   "license": "MIT",
   "author": "CLAWLING PTE. LTD.",

package/src/connect-check.ts

@@ -1,5 +1,6 @@
 import { ClawlingApiError } from "./api-types.ts";
 import type { OpenclawClawlingApiClient } from "./api-client.ts";
+import { readConnectFailureGuidance } from "./connect-failure.ts";
 import { AGENTS_CONNECT_PLATFORM, RECONNECT_GUIDE_URL } from "./onboarding-context.ts";
 
 export interface ConnectPreCheck {
@@ -41,8 +42,14 @@ export async function preCheckConnectCode(
       userIdStatus: typeof res.user_id_status === "string" ? res.user_id_status : "",
     };
   } catch (err) {
+    // Still a degrade, never a gate: `/connect` re-evaluates the code and
+    // surfaces the same guidance on the error it throws. The guidance is only
+    // logged here so a rate-limit or dead code is visible early.
     const kind = err instanceof ClawlingApiError ? err.kind : "error";
-    log(`Connect-code pre-check unavailable (${kind}); continuing without it.`);
+    const guidance = err instanceof ClawlingApiError ? readConnectFailureGuidance(err.meta?.data) : {};
+    const action = guidance.nextAction ? `; next_action: ${guidance.nextAction}` : "";
+    const hint = guidance.hint ? `. ${guidance.hint}` : "";
+    log(`Connect-code pre-check unavailable (${kind}${action})${hint}; continuing without it.`);
     return null;
   }
 }

package/src/connect-failure.ts

@@ -0,0 +1,109 @@
+import type { ClawlingApiError, ClawlingApiErrorKind } from "./api-types.ts";
+
+/**
+ * Machine-readable guidance the backend attaches to the error envelope's
+ * `data` on a failed `POST /v1/agents/connect` (and `/connect/check`). Every
+ * field is optional: older servers send none of them, and then the plugin
+ * behaves exactly as before.
+ *
+ * Known `next_action` values (closed enum on the server; any other value is
+ * surfaced verbatim and never retried):
+ * - `ask_owner_new_code` — the code is dead (unknown / expired); never retry.
+ * - `wait_retry`         — rate limited; the code was NOT consumed. Wait
+ *                          `retry_after_seconds`, then retry once.
+ * - `reconnect`          — redeemed from another device; the owner must send
+ *                          a reconnect prompt.
+ * - `stop`               — an unchanged retry fails the same way.
+ */
+export type ConnectNextAction = "ask_owner_new_code" | "wait_retry" | "reconnect" | "stop";
+
+export interface ConnectFailureGuidance {
+  hint?: string;
+  /** A `ConnectNextAction`, or an unknown value passed through verbatim. */
+  nextAction?: ConnectNextAction | (string & {});
+  retryAfterSeconds?: number;
+}
+
+/** Default wait for `wait_retry` when the server omits / garbles the delay. */
+export const WAIT_RETRY_DEFAULT_SECONDS = 60;
+/** Upper bound on any `wait_retry` wait, whatever the server asks for. */
+export const WAIT_RETRY_MAX_SECONDS = 120;
+
+function readNonBlankString(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+export function readConnectFailureGuidance(data: unknown): ConnectFailureGuidance {
+  if (!data || typeof data !== "object" || Array.isArray(data)) return {};
+  const record = data as Record<string, unknown>;
+  const out: ConnectFailureGuidance = {};
+  const hint = readNonBlankString(record.hint);
+  if (hint) out.hint = hint;
+  const nextAction = readNonBlankString(record.next_action);
+  if (nextAction) out.nextAction = nextAction;
+  const retryAfter = record.retry_after_seconds;
+  if (typeof retryAfter === "number" && Number.isFinite(retryAfter)) {
+    out.retryAfterSeconds = retryAfter;
+  }
+  return out;
+}
+
+/** Delay before the single `wait_retry` retry: server value, capped, with a default. */
+export function waitRetryDelayMs(retryAfterSeconds: number | undefined): number {
+  const seconds =
+    typeof retryAfterSeconds === "number" && Number.isFinite(retryAfterSeconds) && retryAfterSeconds > 0
+      ? Math.min(retryAfterSeconds, WAIT_RETRY_MAX_SECONDS)
+      : WAIT_RETRY_DEFAULT_SECONDS;
+  return Math.round(seconds * 1000);
+}
+
+/**
+ * Error thrown by the invite-code login when `/v1/agents/connect` fails.
+ * The message keeps the historical `agents/connect failed (<kind>): <msg>`
+ * prefix; when the server sent guidance it is appended so an agent reading
+ * the CLI / chat-command output knows what to do next.
+ */
+export class ConnectFailedError extends Error {
+  readonly kind: ClawlingApiErrorKind;
+  readonly code?: number;
+  readonly status?: number;
+  readonly hint?: string;
+  readonly nextAction?: ConnectFailureGuidance["nextAction"];
+  readonly retryAfterSeconds?: number;
+
+  constructor(
+    kind: ClawlingApiErrorKind,
+    serverMessage: string,
+    meta: { code?: number; status?: number } & ConnectFailureGuidance = {},
+  ) {
+    super(formatConnectFailureMessage(kind, serverMessage, meta));
+    this.name = "ConnectFailedError";
+    this.kind = kind;
+    if (meta.code !== undefined) this.code = meta.code;
+    if (meta.status !== undefined) this.status = meta.status;
+    if (meta.hint !== undefined) this.hint = meta.hint;
+    if (meta.nextAction !== undefined) this.nextAction = meta.nextAction;
+    if (meta.retryAfterSeconds !== undefined) this.retryAfterSeconds = meta.retryAfterSeconds;
+  }
+}
+
+function formatConnectFailureMessage(
+  kind: ClawlingApiErrorKind,
+  serverMessage: string,
+  guidance: ConnectFailureGuidance,
+): string {
+  let text = `agents/connect failed (${kind}): ${serverMessage}`;
+  if (guidance.nextAction) text += ` (next_action: ${guidance.nextAction})`;
+  if (guidance.hint) text += `. ${guidance.hint}`;
+  return text;
+}
+
+export function connectFailedError(err: ClawlingApiError): ConnectFailedError {
+  return new ConnectFailedError(err.kind, err.message, {
+    ...(err.meta?.code !== undefined ? { code: err.meta.code } : {}),
+    ...(err.meta?.status !== undefined ? { status: err.meta.status } : {}),
+    ...readConnectFailureGuidance(err.meta?.data),
+  });
+}

package/src/login.runtime.ts

@@ -16,6 +16,7 @@ import {
 import { getClawChatStore, type ClawChatStore } from "./storage.ts";
 import { buildOnboardingContext, RECONNECT_GUIDE_URL } from "./onboarding-context.ts";
 import { boundCodeNewIdentityMessage, preCheckConnectCode, unpairableMessage } from "./connect-check.ts";
+import { connectFailedError, readConnectFailureGuidance, waitRetryDelayMs } from "./connect-failure.ts";
 // Re-exported: `src/login.runtime.test.ts` and `src/commands.ts` import these
 // from here, so the historical import path keeps working after the move.
 import {
@@ -68,6 +69,15 @@ export interface LoginParams {
    * `promptActivationIntentFromStdin`; overridden by tests.
    */
   readActivationIntent?: () => Promise<ActivationIntent | null>;
+  /**
+   * Wait used before the single `next_action: wait_retry` retry of
+   * `/v1/agents/connect`. Defaults to a `setTimeout`; overridden by tests.
+   */
+  sleep?: (ms: number) => Promise<void>;
+}
+
+function defaultSleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
 /** The two outcomes available once an identity is already stored. */
@@ -396,8 +406,30 @@ export async function runOpenclawClawlingLogin(params: LoginParams): Promise<voi
   // A brand-new identity is precisely "do not replay" — the replay is the only
   // thing that would bind this code to the incumbent agent.
   const existingUserId = newAccount ? "" : storedUserId;
+  // Rate-limit (`next_action: wait_retry`) budget: one wait-and-retry per
+  // activation, shared across both requests below.
+  let waitRetryUsed = false;
+  const sleep = params.sleep ?? defaultSleep;
+  const redeem = async (body: Parameters<typeof apiClient.agentsConnect>[0]) => {
+    try {
+      return await apiClient.agentsConnect(body);
+    } catch (err) {
+      if (!(err instanceof ClawlingApiError) || waitRetryUsed) throw err;
+      const guidance = readConnectFailureGuidance(err.meta?.data);
+      // Only wait_retry is retried: a rate-limited request did not consume the
+      // code. Every other next_action (and any unknown one) is final.
+      if (guidance.nextAction !== "wait_retry") throw err;
+      waitRetryUsed = true;
+      const delayMs = waitRetryDelayMs(guidance.retryAfterSeconds);
+      runtime.log(
+        `Connect code redeem rate limited — retrying once in ${Math.round(delayMs / 1000)}s …`,
+      );
+      await sleep(delayMs);
+      return await apiClient.agentsConnect(body);
+    }
+  };
   try {
-    result = await apiClient.agentsConnect({
+    result = await redeem({
       code: inviteCode,
       platform: AGENTS_CONNECT_PLATFORM,
       type: AGENTS_CONNECT_TYPE,
@@ -419,7 +451,7 @@ export async function runOpenclawClawlingLogin(params: LoginParams): Promise<voi
           `Stored userId ${existingUserId} no longer exists on this server — retrying as a fresh pairing …`,
         );
         try {
-          result = await apiClient.agentsConnect({
+          result = await redeem({
             code: inviteCode,
             platform: AGENTS_CONNECT_PLATFORM,
             type: AGENTS_CONNECT_TYPE,
@@ -427,12 +459,12 @@ export async function runOpenclawClawlingLogin(params: LoginParams): Promise<voi
           });
         } catch (retryErr) {
           if (retryErr instanceof ClawlingApiError) {
-            throw new Error(`agents/connect failed (${retryErr.kind}): ${retryErr.message}`);
+            throw connectFailedError(retryErr);
           }
           throw retryErr;
         }
       } else {
-        throw new Error(`agents/connect failed (${err.kind}): ${err.message}`);
+        throw connectFailedError(err);
       }
     } else {
       throw err;