@yahaha-studio/kichi-forwarder 0.1.0-beta.9 → 0.1.1-beta.2

package/src/service.ts

@@ -1,6 +1,5 @@
 import WebSocket from "ws";
 import * as fs from "fs";
-import os from "node:os";
 import * as path from "path";
 import { randomUUID } from "node:crypto";
 import type { Logger } from "openclaw/plugin-sdk";
@@ -27,9 +26,6 @@ import type {
   StatusPayload,
 } from "./types.js";
 
-const KICHI_WORLD_DIR = path.join(os.homedir(), ".openclaw", "kichi-world");
-const HOSTS_DIR = path.join(KICHI_WORLD_DIR, "hosts");
-const STATE_PATH = path.join(KICHI_WORLD_DIR, "state.json");
 const MAX_NOTEBOARD_TEXT_LENGTH = 200;
 const DEFAULT_LLM_RUNTIME_ENABLED = true;
 
@@ -53,10 +49,18 @@ export type LeaveResult =
     }
   | AckFailureResult;
 
+type KichiForwarderServiceOptions = {
+  agentId: string;
+  runtimeDir: string;
+};
+
+type ConnectReason = "startup" | "switch_host" | "reconnect";
+
 export class KichiForwarderService {
   private ws: WebSocket | null = null;
   private stopped = false;
   private reconnectTimeout: NodeJS.Timeout | null = null;
+  private joinTimeout: NodeJS.Timeout | null = null;
   private identity: KichiIdentity | null = null;
   private host: string | null = null;
   private joinResolve: ((result: JoinResult) => void) | null = null;
@@ -70,20 +74,23 @@ export class KichiForwarderService {
     }
   >();
 
-  constructor(private logger: Logger) {}
+  constructor(
+    private logger: Logger,
+    private options: KichiForwarderServiceOptions,
+  ) {}
 
-  async start(): Promise<void> {
+  start(): void {
     this.host = this.loadCurrentHost();
     this.identity = this.host ? this.loadIdentity() : null;
     this.stopped = false;
     if (this.host) {
-      this.connect();
+      this.connect("startup");
       return;
     }
-    this.logger.info("Kichi host is not configured yet; waiting for kichi_switch_host");
+    this.log("debug", "host is not configured yet; waiting for kichi_switch_host");
   }
 
-  async stop(): Promise<void> {
+  stop(): void {
     this.stopped = true;
     this.clearReconnectTimeout();
     this.rejectPendingRequests("Kichi websocket stopped");
@@ -100,7 +107,7 @@ export class KichiForwarderService {
     this.failPendingJoin(`Kichi websocket switched to ${host}`);
     this.closeSocket();
     if (!this.stopped) {
-      this.connect();
+      this.connect("switch_host");
     }
     return this.getConnectionStatus();
   }
@@ -114,7 +121,14 @@ export class KichiForwarderService {
     if (!this.host) {
       return { success: false, error: "No Kichi host configured. Run kichi_switch_host first." };
     }
+    if (this.ws?.readyState !== WebSocket.OPEN && this.ws?.readyState !== WebSocket.CONNECTING) {
+      return {
+        success: false,
+        error: "Kichi websocket is not connected. Restart the gateway to reconnect before joining.",
+      };
+    }
     return new Promise((resolve) => {
+      this.failPendingJoin("Kichi join superseded by a new join request");
       this.identity = { avatarId };
       this.saveIdentity();
       this.joinResolve = resolve;
@@ -125,9 +139,10 @@ export class KichiForwarderService {
       } else {
         this.ws?.once("open", sendJoin);
       }
-      setTimeout(() => {
+      this.joinTimeout = setTimeout(() => {
         if (this.joinResolve) {
           this.joinResolve = null;
+          this.clearJoinTimeout();
           resolve({ success: false, error: "Timed out waiting for join_ack" });
         }
       }, 10000);
@@ -270,10 +285,26 @@ export class KichiForwarderService {
 
   hasValidIdentity(): boolean { return !!this.identity?.avatarId && !!this.identity?.authKey; }
 
+  isLlmRuntimeEnabled(): boolean {
+    return this.readStateFile()?.llmRuntimeEnabled ?? DEFAULT_LLM_RUNTIME_ENABLED;
+  }
+
   getCurrentHost(): string {
     return this.host ?? "";
   }
 
+  getAgentId(): string {
+    return this.options.agentId;
+  }
+
+  getRuntimeDir(): string {
+    return this.options.runtimeDir;
+  }
+
+  getStatePath(): string {
+    return path.join(this.options.runtimeDir, "state.json");
+  }
+
   getIdentityPath(): string {
     if (!this.host) {
       return "";
@@ -324,18 +355,27 @@ export class KichiForwarderService {
       };
     }
 
-    this.clearReconnectTimeout();
-    this.connect();
+    if (this.reconnectTimeout) {
+      return {
+        accepted: true,
+        mode: "reconnecting",
+        message: "WebSocket reconnect is already scheduled. Rejoin will be sent automatically on open.",
+      };
+    }
+
     return {
-      accepted: true,
-      mode: "reconnecting",
-      message: "Reconnect started. Rejoin will be sent automatically on open.",
+      accepted: false,
+      mode: "unavailable",
+      message: "WebSocket is not connected. Restart the gateway or wait for the scheduled reconnect.",
     };
   }
 
   getConnectionStatus(): KichiConnectionStatus {
     const host = this.host ?? undefined;
     return {
+      agentId: this.options.agentId,
+      runtimeDir: this.getRuntimeDir(),
+      statePath: this.getStatePath(),
       ...(host ? {
         host,
         wsUrl: this.getWsUrl(),
@@ -372,7 +412,7 @@ export class KichiForwarderService {
             resolve({ success: true });
           }
         } catch (e) {
-          this.logger.warn(`Failed to parse leave response: ${e}`);
+          this.log("warn", `failed to parse leave response: ${e}`);
         }
       };
       this.ws!.on("message", handler);
@@ -386,16 +426,22 @@ export class KichiForwarderService {
     });
   }
 
-  private connect(): void {
+  private connect(reason: ConnectReason): void {
     if (this.stopped || !this.host) return;
+    if (this.ws?.readyState === WebSocket.CONNECTING || this.ws?.readyState === WebSocket.OPEN) {
+      this.log("debug", `skipped websocket connect (${reason}) because socket is already ${this.getWebsocketState()}`);
+      return;
+    }
 
+    this.clearReconnectTimeout();
     const wsUrl = this.getWsUrl();
     const ws = new WebSocket(wsUrl);
     this.ws = ws;
+    this.log("debug", `opening websocket (${reason}) to ${wsUrl}`);
 
     ws.on("open", () => {
       if (this.ws !== ws) return;
-      this.logger.info(`Connected to ${wsUrl} (${this.host})`);
+      this.log("info", `connected to ${wsUrl} (${this.host})`);
       this.sendRejoinPayload();
     });
 
@@ -408,19 +454,20 @@ export class KichiForwarderService {
       if (this.ws !== ws) return;
       this.ws = null;
       this.rejectPendingRequests("Kichi websocket closed");
+      this.failPendingJoin("Kichi websocket closed");
       if (!this.stopped) {
-        this.reconnectTimeout = setTimeout(() => {
-          this.reconnectTimeout = null;
-          this.connect();
-        }, 2000);
+        this.scheduleReconnect();
       }
     });
 
-    ws.on("error", () => {});
+    ws.on("error", (error) => {
+      if (this.ws !== ws) return;
+      this.log("warn", `websocket error: ${error instanceof Error ? error.message : String(error)}`);
+    });
   }
 
   private handleMessage(data: string): void {
-    this.logger.debug(`[kichi ws recv] ${data}`);
+    this.log("debug", `ws recv ${data}`);
     try {
       const msg = JSON.parse(data);
       this.tryResolvePendingRequest(msg);
@@ -428,33 +475,35 @@ export class KichiForwarderService {
         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.log("warn", `join failed: ${failure.error}`);
           this.joinResolve?.(failure);
           this.joinResolve = null;
+          this.clearJoinTimeout();
           return;
         }
 
         if (this.identity) {
           this.identity.authKey = joinAck.authKey;
           this.saveIdentity();
-          this.logger.info(`Joined as ${this.identity.avatarId}`);
+          this.log("info", `joined as ${this.identity.avatarId}`);
         }
         this.joinResolve?.({ success: true, authKey: joinAck.authKey });
         this.joinResolve = null;
+        this.clearJoinTimeout();
       } else if (msg.type === "rejoin_failed" || msg.type === "auth_error") {
-        this.logger.warn(`Auth failed: ${msg.reason || "unknown"}`);
+        this.log("warn", `auth failed: ${msg.reason || "unknown"}`);
         this.clearAuthKey();
       } else if (msg.type === "leave_ack") {
         const leaveAck = msg as LeaveAckPayload;
         if (leaveAck.success === false) {
           const failure = this.buildAckFailure(leaveAck, "Leave failed");
-          this.logger.warn(`Leave failed: ${failure.error}`);
+          this.log("warn", `leave failed: ${failure.error}`);
         } else {
-          this.logger.info("Left Kichi world");
+          this.log("info", "left Kichi world");
         }
       }
     } catch (e) {
-      this.logger.warn(`Failed to parse message: ${e}`);
+      this.log("warn", `failed to parse message: ${e}`);
     }
   }
 
@@ -571,7 +620,7 @@ export class KichiForwarderService {
       }
       return null;
     } catch (e) {
-      this.logger.warn(`Failed to load identity: ${e}`);
+      this.log("warn", `failed to load identity: ${e}`);
       return null;
     }
   }
@@ -584,7 +633,7 @@ export class KichiForwarderService {
       if (!fs.existsSync(identityDir)) fs.mkdirSync(identityDir, { recursive: true, mode: 0o700 });
       fs.writeFileSync(identityPath, JSON.stringify(this.identity, null, 2), { mode: 0o600 });
     } catch (e) {
-      this.logger.error(`Failed to save identity: ${e}`);
+      this.log("error", `failed to save identity: ${e}`);
     }
   }
 
@@ -592,7 +641,7 @@ export class KichiForwarderService {
     if (!this.identity) return;
     this.identity.authKey = undefined;
     this.saveIdentity();
-    this.logger.info("AuthKey cleared");
+    this.log("info", "authKey cleared");
   }
 
   private sendRejoinPayload(): boolean {
@@ -603,7 +652,7 @@ export class KichiForwarderService {
     this.ws.send(
       JSON.stringify({ type: "rejoin", avatarId: this.identity.avatarId, authKey: this.identity.authKey }),
     );
-    this.logger.debug(`Sent rejoin for ${this.identity.avatarId}`);
+    this.log("debug", `sent rejoin for ${this.identity.avatarId}`);
     return true;
   }
 
@@ -628,7 +677,7 @@ export class KichiForwarderService {
     if (!this.host) {
       throw new Error("No Kichi host configured");
     }
-    return path.join(HOSTS_DIR, encodeURIComponent(this.host));
+    return path.join(this.options.runtimeDir, "hosts", encodeURIComponent(this.host));
   }
 
   private getWsUrl(): string {
@@ -647,14 +696,15 @@ export class KichiForwarderService {
 
   private loadCurrentHost(): string | null {
     try {
-      if (!fs.existsSync(STATE_PATH)) {
+      const statePath = this.getStatePath();
+      if (!fs.existsSync(statePath)) {
         return null;
       }
-      const data = JSON.parse(fs.readFileSync(STATE_PATH, "utf-8")) as { currentHost?: unknown };
+      const data = JSON.parse(fs.readFileSync(statePath, "utf-8")) as { currentHost?: unknown };
       if (typeof data.currentHost === "string" && data.currentHost.trim()) {
         return data.currentHost;
       }
-      throw new Error(`Invalid currentHost value in ${STATE_PATH}`);
+      throw new Error(`Invalid currentHost value in ${statePath}`);
     } catch (error) {
       throw new Error(`Failed to load current host: ${error}`);
     }
@@ -666,17 +716,18 @@ export class KichiForwarderService {
       currentHost: host,
       llmRuntimeEnabled: previousState?.llmRuntimeEnabled ?? DEFAULT_LLM_RUNTIME_ENABLED,
     };
-    fs.mkdirSync(KICHI_WORLD_DIR, { recursive: true, mode: 0o700 });
-    fs.writeFileSync(STATE_PATH, JSON.stringify(nextState, null, 2), { mode: 0o600 });
+    fs.mkdirSync(this.options.runtimeDir, { recursive: true, mode: 0o700 });
+    fs.writeFileSync(this.getStatePath(), JSON.stringify(nextState, null, 2), { mode: 0o600 });
   }
 
   private readStateFile(): Partial<KichiState> | null {
-    if (!fs.existsSync(STATE_PATH)) {
+    const statePath = this.getStatePath();
+    if (!fs.existsSync(statePath)) {
       return null;
     }
-    const data = JSON.parse(fs.readFileSync(STATE_PATH, "utf-8")) as unknown;
+    const data = JSON.parse(fs.readFileSync(statePath, "utf-8")) as unknown;
     if (!data || typeof data !== "object") {
-      throw new Error(`Invalid state payload in ${STATE_PATH}`);
+      throw new Error(`Invalid state payload in ${statePath}`);
     }
     return data as Partial<KichiState>;
   }
@@ -687,6 +738,22 @@ export class KichiForwarderService {
     this.reconnectTimeout = null;
   }
 
+  private clearJoinTimeout(): void {
+    if (!this.joinTimeout) return;
+    clearTimeout(this.joinTimeout);
+    this.joinTimeout = null;
+  }
+
+  private scheduleReconnect(): void {
+    if (this.reconnectTimeout || this.stopped) {
+      return;
+    }
+    this.reconnectTimeout = setTimeout(() => {
+      this.reconnectTimeout = null;
+      this.connect("reconnect");
+    }, 2000);
+  }
+
   private closeSocket(): void {
     const socket = this.ws;
     this.ws = null;
@@ -698,5 +765,28 @@ export class KichiForwarderService {
     if (!this.joinResolve) return;
     this.joinResolve({ success: false, error: reason });
     this.joinResolve = null;
+    this.clearJoinTimeout();
+  }
+
+  private logPrefix(): string {
+    return `[kichi:${this.options.agentId}]`;
+  }
+
+  private log(level: "debug" | "info" | "warn" | "error", message: string): void {
+    const formatted = `${this.logPrefix()} ${message}`;
+    switch (level) {
+      case "debug":
+        this.logger.debug(formatted);
+        return;
+      case "info":
+        this.logger.info(formatted);
+        return;
+      case "warn":
+        this.logger.warn(formatted);
+        return;
+      case "error":
+        this.logger.error(formatted);
+        return;
+    }
   }
 }

package/src/types.ts

@@ -47,6 +47,9 @@ export type KichiIdentity = {
 };
 
 export type KichiConnectionStatus = {
+  agentId?: string;
+  runtimeDir?: string;
+  statePath?: string;
   host?: string;
   wsUrl?: string;
   identityPath?: string;