@yahaha-studio/kichi-forwarder 0.0.1-alpha.40 → 0.0.1-alpha.41

package/index.ts

@@ -602,7 +602,18 @@ const plugin = {
           return { success: false, error: tagsError };
         }
         const result = await service?.join(avatarId, botName, bio, tags ?? []);
-        return result ? { success: true, authKey: result } : { success: false, error: "Failed" };
+        if (!result) {
+          return { success: false, error: "Kichi service is not initialized" };
+        }
+        if (result.success) {
+          return { success: true, authKey: result.authKey };
+        }
+        return {
+          success: false,
+          error: result.error,
+          ...(result.errorCode ? { errorCode: result.errorCode } : {}),
+          ...(result.errorMessage ? { errorMessage: result.errorMessage } : {}),
+        };
       },
     });
 
@@ -631,7 +642,18 @@ const plugin = {
       parameters: { type: "object", properties: {} },
       execute: async () => {
         const result = await service?.leave();
-        return result ? { success: true } : { success: false, error: "Failed or not connected" };
+        if (!result) {
+          return { success: false, error: "Kichi service is not initialized" };
+        }
+        if (result.success) {
+          return { success: true };
+        }
+        return {
+          success: false,
+          error: result.error,
+          ...(result.errorCode ? { errorCode: result.errorCode } : {}),
+          ...(result.errorMessage ? { errorMessage: result.errorMessage } : {}),
+        };
       },
     });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yahaha-studio/kichi-forwarder",
-  "version": "0.0.1-alpha.40",
+  "version": "0.0.1-alpha.41",
   "description": "Forward OpenClaw agent events to external WebSocket server for visualization",
   "type": "module",
   "main": "index.ts",

package/src/service.ts

@@ -11,11 +11,13 @@ import type {
   CreateMusicAlbumPayload,
   HookNotifyPayload,
   HookNotifyType,
+  JoinAckPayload,
   JoinPayload,
   KichiConnectionStatus,
   CreateNotesBoardNotePayload,
   KichiForwarderConfig,
   KichiIdentity,
+  LeaveAckPayload,
   PoseType,
   QueryStatusPayload,
   QueryStatusResultPayload,
@@ -26,12 +28,32 @@ const IDENTITY_DIR = path.join(os.homedir(), ".openclaw", "kichi-world");
 const IDENTITY_PATH = path.join(IDENTITY_DIR, "identity.json");
 const MAX_NOTEBOARD_TEXT_LENGTH = 200;
 
+type AckFailureResult = {
+  success: false;
+  error: string;
+  errorCode?: string;
+  errorMessage?: string;
+};
+
+export type JoinResult =
+  | {
+      success: true;
+      authKey: string;
+    }
+  | AckFailureResult;
+
+export type LeaveResult =
+  | {
+      success: true;
+    }
+  | AckFailureResult;
+
 export class KichiForwarderService {
   private ws: WebSocket | null = null;
   private stopped = false;
   private reconnectTimeout: NodeJS.Timeout | null = null;
   private identity: KichiIdentity | null = null;
-  private joinResolve: ((authKey: string) => void) | null = null;
+  private joinResolve: ((result: JoinResult) => void) | null = null;
   private pendingRequests = new Map<
     string,
     {
@@ -64,7 +86,7 @@ export class KichiForwarderService {
     botName: string,
     bio: string,
     tags: string[],
-  ): Promise<string | null> {
+  ): Promise<JoinResult> {
     return new Promise((resolve) => {
       this.identity = { avatarId };
       this.joinResolve = resolve;
@@ -75,7 +97,12 @@ export class KichiForwarderService {
       } else {
         this.ws?.once("open", sendJoin);
       }
-      setTimeout(() => { if (this.joinResolve) { this.joinResolve = null; resolve(null); } }, 10000);
+      setTimeout(() => {
+        if (this.joinResolve) {
+          this.joinResolve = null;
+          resolve({ success: false, error: "Timed out waiting for join_ack" });
+        }
+      }, 10000);
     });
   }
 
@@ -102,27 +129,64 @@ export class KichiForwarderService {
   }
 
   private handleMessage(data: string): void {
+    this.logger.debug(`[kichi ws recv] ${data}`);
     try {
       const msg = JSON.parse(data);
       this.tryResolvePendingRequest(msg);
-      if (msg.type === "join_ack" && msg.authKey && this.identity) {
-        this.identity.authKey = msg.authKey;
-        this.saveIdentity();
-        this.logger.info(`Joined as ${this.identity.avatarId}`);
-        this.joinResolve?.(msg.authKey);
+      if (msg.type === "join_ack") {
+        const joinAck = msg as JoinAckPayload;
+        if (joinAck.success === false || !joinAck.authKey) {
+          const failure = this.buildAckFailure(joinAck, "Join failed");
+          this.logger.warn(`Join failed: ${failure.error}`);
+          this.joinResolve?.(failure);
+          this.joinResolve = null;
+          return;
+        }
+
+        if (this.identity) {
+          this.identity.authKey = joinAck.authKey;
+          this.saveIdentity();
+          this.logger.info(`Joined as ${this.identity.avatarId}`);
+        }
+        this.joinResolve?.({ success: true, authKey: joinAck.authKey });
         this.joinResolve = null;
       } else if (msg.type === "rejoin_failed" || msg.type === "auth_error") {
         // AuthKey invalid/expired, clear it
         this.logger.warn(`Auth failed: ${msg.reason || "unknown"}`);
         this.clearAuthKey();
       } else if (msg.type === "leave_ack") {
-        this.logger.info("Left Kichi world");
+        const leaveAck = msg as LeaveAckPayload;
+        if (leaveAck.success === false) {
+          const failure = this.buildAckFailure(leaveAck, "Leave failed");
+          this.logger.warn(`Leave failed: ${failure.error}`);
+        } else {
+          this.logger.info("Left Kichi world");
+        }
       }
     } catch (e) {
       this.logger.warn(`Failed to parse message: ${e}`);
     }
   }
 
+  private buildAckFailure(
+    msg: { errorCode?: unknown; errorMessage?: unknown },
+    fallbackError: string,
+  ): AckFailureResult {
+    const errorCode =
+      typeof msg.errorCode === "string" && msg.errorCode.trim().length > 0 ? msg.errorCode : undefined;
+    const errorMessage =
+      typeof msg.errorMessage === "string" && msg.errorMessage.trim().length > 0
+        ? msg.errorMessage
+        : undefined;
+
+    return {
+      success: false,
+      error: errorMessage ?? (errorCode ? `${fallbackError} (${errorCode})` : fallbackError),
+      errorCode,
+      errorMessage,
+    };
+  }
+
   private tryResolvePendingRequest(msg: { type?: unknown; requestId?: unknown }): void {
     const requestId = typeof msg.requestId === "string" ? msg.requestId : "";
     if (!requestId) {
@@ -448,16 +512,24 @@ export class KichiForwarderService {
     return "closed";
   }
 
-  async leave(): Promise<boolean> {
-    if (!this.identity?.avatarId || !this.identity?.authKey || this.ws?.readyState !== WebSocket.OPEN) return false;
+  async leave(): Promise<LeaveResult> {
+    if (!this.identity?.avatarId || !this.identity?.authKey || this.ws?.readyState !== WebSocket.OPEN) {
+      return { success: false, error: "Failed or not connected" };
+    }
+
     return new Promise((resolve) => {
       const handler = (data: WebSocket.Data) => {
         try {
           const msg = JSON.parse(data.toString());
           if (msg.type === "leave_ack") {
             this.ws?.off("message", handler);
+            const leaveAck = msg as LeaveAckPayload;
+            if (leaveAck.success === false) {
+              resolve(this.buildAckFailure(leaveAck, "Leave failed"));
+              return;
+            }
             this.clearAuthKey();
-            resolve(true);
+            resolve({ success: true });
           }
         } catch (e) {
           this.logger.warn(`Failed to parse leave response: ${e}`);
@@ -467,7 +539,10 @@ export class KichiForwarderService {
       this.ws!.send(
         JSON.stringify({ type: "leave", avatarId: this.identity!.avatarId, authKey: this.identity!.authKey }),
       );
-      setTimeout(() => { this.ws?.off("message", handler); resolve(false); }, 10000);
+      setTimeout(() => {
+        this.ws?.off("message", handler);
+        resolve({ success: false, error: "Timed out waiting for leave_ack" });
+      }, 10000);
     });
   }
 }

package/src/types.ts

@@ -69,7 +69,17 @@ export type JoinPayload = {
 
 export type JoinAckPayload = {
   type: "join_ack";
-  authKey: string;
+  authKey?: string;
+  success?: boolean;
+  errorCode?: string;
+  errorMessage?: string;
+};
+
+export type LeaveAckPayload = {
+  type: "leave_ack";
+  success?: boolean;
+  errorCode?: string;
+  errorMessage?: string;
 };
 
 export type LeavePayload = {