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

package/index.ts

@@ -411,9 +411,66 @@ function notifyMessageReceived(
   service.sendHookNotify("message_received", `"${trimmed}"`);
 }
 
+function trimOptionalString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function readExtraStringField(source: unknown, key: string): string | undefined {
+  if (!isPlainObject(source)) {
+    return undefined;
+  }
+  return trimOptionalString(source[key]);
+}
+
+function resolveBeforeDispatchLocator(
+  event: { sessionKey?: string },
+  ctx: { sessionKey?: string },
+): {
+  ctxAgentId?: string;
+  sessionKey?: string;
+} {
+  const ctxAgentId = readExtraStringField(ctx, "ctxAgentId");
+  const sessionKey = trimOptionalString(ctx.sessionKey) ?? trimOptionalString(event.sessionKey);
+  return {
+    ...(ctxAgentId ? { ctxAgentId } : {}),
+    ...(sessionKey ? { sessionKey } : {}),
+  };
+}
+
+function resolveAgentHookLocator(ctx: {
+  agentId?: string;
+  sessionKey?: string;
+}): {
+  agentId?: string;
+  ctxAgentId?: string;
+  sessionKey?: string;
+} {
+  const agentId = trimOptionalString(ctx.agentId);
+  const ctxAgentId = readExtraStringField(ctx, "ctxAgentId");
+  const sessionKey = trimOptionalString(ctx.sessionKey);
+  return {
+    ...(agentId ? { agentId } : {}),
+    ...(ctxAgentId ? { ctxAgentId } : {}),
+    ...(sessionKey ? { sessionKey } : {}),
+  };
+}
+
+function resolveToolLocator(ctx: OpenClawPluginToolContext): {
+  agentId?: string;
+  sessionKey?: string;
+} {
+  const agentId = trimOptionalString(ctx.agentId);
+  const sessionKey = trimOptionalString(ctx.sessionKey);
+  return {
+    ...(agentId ? { agentId } : {}),
+    ...(sessionKey ? { sessionKey } : {}),
+  };
+}
+
 function registerPluginHooks(api: OpenClawPluginApi, runtimeManager: KichiRuntimeManager): void {
   api.on("before_dispatch", (event, ctx) => {
-    const service = runtimeManager.getRuntime(ctx);
+    const locator = resolveBeforeDispatchLocator(event, ctx);
+    const service = runtimeManager.getRuntime(locator);
     if (!service) {
       return;
     }
@@ -428,7 +485,8 @@ function registerPluginHooks(api: OpenClawPluginApi, runtimeManager: KichiRuntim
   });
 
   api.on("before_prompt_build", (_event, ctx) => {
-    const service = runtimeManager.getRuntime(ctx);
+    const locator = resolveAgentHookLocator(ctx);
+    const service = runtimeManager.getRuntime(locator);
     if (!service?.hasValidIdentity() || !service.isConnected()) {
       return;
     }
@@ -445,7 +503,8 @@ function registerPluginHooks(api: OpenClawPluginApi, runtimeManager: KichiRuntim
   });
 
   api.on("before_tool_call", (_event, ctx) => {
-    const service = runtimeManager.getRuntime(ctx);
+    const locator = resolveAgentHookLocator(ctx);
+    const service = runtimeManager.getRuntime(locator);
     if (!service) {
       return;
     }
@@ -455,7 +514,8 @@ function registerPluginHooks(api: OpenClawPluginApi, runtimeManager: KichiRuntim
   });
 
   api.on("agent_end", (event, ctx) => {
-    const service = runtimeManager.getRuntime(ctx);
+    const locator = resolveAgentHookLocator(ctx);
+    const service = runtimeManager.getRuntime(locator);
     const preview = getLastAssistantPreview(event.messages, MAX_AGENT_END_PREVIEW_WIDTH);
     api.logger.debug(
       `[kichi:${service?.getAgentId() ?? "unknown"}] agent_end fired (trigger=${ctx.trigger ?? "unknown"}, success=${event.success}, durationMs=${event.durationMs ?? 0}, error=${event.error ?? ""}, preview=${preview || "(empty)"})`,
@@ -944,7 +1004,7 @@ function createAgentScopedTool(
   factory: (service: KichiForwarderService, ctx: OpenClawPluginToolContext) => AnyAgentTool,
 ) {
   return (ctx: OpenClawPluginToolContext) => {
-    const service = runtimeManager.getRuntime(ctx, { createIfMissing: true });
+    const service = runtimeManager.getRuntime(resolveToolLocator(ctx));
     if (!service) {
       throw new Error("Failed to resolve agent-scoped Kichi runtime");
     }
@@ -952,13 +1012,30 @@ function createAgentScopedTool(
   };
 }
 
+const GLOBAL_RUNTIME_MANAGER_KEY = "__kichi_forwarder_runtime_manager__";
+
+type GlobalRuntimeManagerState = typeof globalThis & {
+  [GLOBAL_RUNTIME_MANAGER_KEY]?: KichiRuntimeManager;
+};
+
+function getRuntimeManager(logger: OpenClawPluginApi["logger"]): KichiRuntimeManager {
+  const globalState = globalThis as GlobalRuntimeManagerState;
+  const existing = globalState[GLOBAL_RUNTIME_MANAGER_KEY];
+  if (existing) {
+    return existing;
+  }
+  const runtimeManager = new KichiRuntimeManager(logger);
+  globalState[GLOBAL_RUNTIME_MANAGER_KEY] = runtimeManager;
+  return runtimeManager;
+}
+
 const plugin = {
   id: "kichi-forwarder",
   name: "Kichi Forwarder",
   configSchema: { parse },
 
   register(api: OpenClawPluginApi) {
-    const runtimeManager = new KichiRuntimeManager(api.logger);
+    const runtimeManager = getRuntimeManager(api.logger);
     registerPluginHooks(api, runtimeManager);
     const musicTitleEnum = getMusicTitleEnum();
 
@@ -966,10 +1043,14 @@ const plugin = {
       id: "kichi-forwarder",
       start: (ctx) => {
         parse(ctx.config.plugins?.entries?.["kichi-forwarder"]?.config);
-        runtimeManager.startPersistedRuntimes();
+        runtimeManager.initializeStartupRuntimes();
       },
       stop: () => {
         runtimeManager.stopAll();
+        const globalState = globalThis as GlobalRuntimeManagerState;
+        if (globalState[GLOBAL_RUNTIME_MANAGER_KEY] === runtimeManager) {
+          delete globalState[GLOBAL_RUNTIME_MANAGER_KEY];
+        }
       },
     });
 
@@ -1031,7 +1112,14 @@ const plugin = {
       },
     })));
 
-    api.registerTool(createAgentScopedTool(runtimeManager, (service) => ({
+    api.registerTool((ctx: OpenClawPluginToolContext) => {
+      const locator = resolveToolLocator(ctx);
+      const agentId = runtimeManager.resolveRuntimeAgentId(locator);
+      if (!agentId) {
+        throw new Error("Failed to resolve agent-scoped Kichi runtime");
+      }
+      const service = runtimeManager.getRuntime(locator) ?? runtimeManager.createRuntimeForAgent(agentId);
+      return ({
       name: "kichi_switch_host",
       description:
         "Switch Kichi runtime host and reconnect immediately without restarting the gateway.",
@@ -1058,7 +1146,8 @@ const plugin = {
           status,
         };
       },
-    })));
+      });
+    });
 
     api.registerTool(createAgentScopedTool(runtimeManager, (service) => ({
       name: "kichi_rejoin",

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "kichi-forwarder",
   "name": "Kichi Forwarder",
   "description": "Native OpenClaw plugin for Kichi World with direct avatar control, status sync, timers, notes, and music tools",
-  "version": "0.1.1-beta.1",
+  "version": "0.1.1-beta.2",
   "author": "OpenClaw",
   "skills": ["./skills/kichi-forwarder"],
   "configSchema": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yahaha-studio/kichi-forwarder",
-  "version": "0.1.1-beta.1",
+  "version": "0.1.1-beta.2",
   "description": "Native OpenClaw plugin for Kichi World with direct avatar control, status sync, timers, notes, and music tools",
   "type": "module",
   "main": "index.ts",

package/src/runtime-manager.ts

@@ -2,7 +2,6 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import type { Logger } from "openclaw/plugin-sdk";
-import { resolveAgentIdFromSessionKey } from "openclaw/plugin-sdk/routing";
 import { KichiForwarderService } from "./service.js";
 
 const OPENCLAW_HOME_DIR = path.join(os.homedir(), ".openclaw");
@@ -15,37 +14,43 @@ const LEGACY_MIGRATION_AGENT_ID = "main";
 
 type AgentLocator = {
   agentId?: string;
+  ctxAgentId?: string;
   sessionKey?: string;
 };
 
-type GetRuntimeOptions = {
-  createIfMissing?: boolean;
-};
-
 export class KichiRuntimeManager {
   private services = new Map<string, KichiForwarderService>();
 
   constructor(private logger: Logger) {}
 
-  getRuntime(locator: AgentLocator, options: GetRuntimeOptions = {}): KichiForwarderService | null {
+  getRuntime(locator: AgentLocator): KichiForwarderService | null {
     const agentId = this.resolveAgentId(locator);
     if (!agentId) {
       return null;
     }
 
-    const existing = this.services.get(agentId);
-    if (existing) {
-      return existing;
+    return this.services.get(agentId) ?? null;
+  }
+
+  resolveRuntimeAgentId(locator: AgentLocator): string | null {
+    return this.resolveAgentId(locator);
+  }
+
+  createRuntimeForAgent(agentId: string): KichiForwarderService {
+    const normalizedAgentId = this.normalizeAgentId(agentId);
+    if (!normalizedAgentId) {
+      throw new Error("Cannot create Kichi runtime without a valid agentId");
     }
 
-    if (!options.createIfMissing && !this.hasPersistedRuntime(agentId)) {
-      return null;
+    const existing = this.services.get(normalizedAgentId);
+    if (existing) {
+      return existing;
     }
 
-    return this.createRuntime(agentId);
+    return this.createRuntime(normalizedAgentId);
   }
 
-  startPersistedRuntimes(): void {
+  initializeStartupRuntimes(): void {
     this.migrateRuntimeStorage();
 
     const rootDir = CANONICAL_AGENT_ROOT_DIR;
@@ -80,24 +85,36 @@ export class KichiRuntimeManager {
   }
 
   private resolveAgentId(locator: AgentLocator): string | null {
-    if (typeof locator.agentId === "string" && locator.agentId.trim()) {
-      return locator.agentId.trim();
+    const directAgentId = this.normalizeAgentId(locator.ctxAgentId) ?? this.normalizeAgentId(locator.agentId);
+    const sessionAgentId =
+      typeof locator.sessionKey === "string" && locator.sessionKey.trim()
+        ? this.parseAgentIdFromSessionKey(locator.sessionKey)
+        : null;
+
+    if (sessionAgentId) {
+      if (directAgentId && directAgentId !== sessionAgentId) {
+        this.logger.error(
+          `[kichi] runtime scope mismatch: directAgentId=${directAgentId} sessionAgentId=${sessionAgentId} sessionKey=${locator.sessionKey}`,
+        );
+      }
+      this.logger.debug(`[kichi] resolved agent runtime from sessionKey: ${sessionAgentId}`);
+      return sessionAgentId;
     }
 
-    if (typeof locator.sessionKey !== "string" || !locator.sessionKey.trim()) {
-      return null;
-    }
+    return directAgentId;
+  }
 
-    try {
-      const agentId = resolveAgentIdFromSessionKey(locator.sessionKey);
-      return typeof agentId === "string" && agentId.trim() ? agentId.trim() : null;
-    } catch {
-      return null;
-    }
+  private normalizeAgentId(value: unknown): string | null {
+    return typeof value === "string" && value.trim() ? value.trim() : null;
   }
 
-  private hasPersistedRuntime(agentId: string): boolean {
-    return fs.existsSync(path.join(this.getRuntimeDir(agentId), "state.json"));
+  private parseAgentIdFromSessionKey(sessionKey: string): string | null {
+    const trimmed = sessionKey.trim();
+    const match = /^agent:([^:]+):/i.exec(trimmed);
+    if (!match) {
+      return null;
+    }
+    return this.normalizeAgentId(match[1]);
   }
 
   private migrateRuntimeStorage(): void {

package/src/service.ts

@@ -54,10 +54,13 @@ type KichiForwarderServiceOptions = {
   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;
@@ -81,7 +84,7 @@ export class KichiForwarderService {
     this.identity = this.host ? this.loadIdentity() : null;
     this.stopped = false;
     if (this.host) {
-      this.connect();
+      this.connect("startup");
       return;
     }
     this.log("debug", "host is not configured yet; waiting for kichi_switch_host");
@@ -104,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();
   }
@@ -118,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;
@@ -129,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);
@@ -344,12 +355,18 @@ 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.",
     };
   }
 
@@ -409,12 +426,18 @@ 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;
@@ -431,15 +454,16 @@ 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 {
@@ -454,6 +478,7 @@ export class KichiForwarderService {
           this.log("warn", `join failed: ${failure.error}`);
           this.joinResolve?.(failure);
           this.joinResolve = null;
+          this.clearJoinTimeout();
           return;
         }
 
@@ -464,6 +489,7 @@ export class KichiForwarderService {
         }
         this.joinResolve?.({ success: true, authKey: joinAck.authKey });
         this.joinResolve = null;
+        this.clearJoinTimeout();
       } else if (msg.type === "rejoin_failed" || msg.type === "auth_error") {
         this.log("warn", `auth failed: ${msg.reason || "unknown"}`);
         this.clearAuthKey();
@@ -712,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;
@@ -723,6 +765,7 @@ export class KichiForwarderService {
     if (!this.joinResolve) return;
     this.joinResolve({ success: false, error: reason });
     this.joinResolve = null;
+    this.clearJoinTimeout();
   }
 
   private logPrefix(): string {