@yahaha-studio/kichi-forwarder 0.1.2-beta.12 → 0.1.2-beta.13

package/dist/index.js

@@ -961,6 +961,10 @@ const plugin = {
                         description: "Optional list of OpenClaw self-perceived personality tags",
                         items: { type: "string" },
                     },
+                    source: {
+                        type: "string",
+                        description: "Optional join source identifier. Defaults to Kichi World join-source.json, then openclaw.",
+                    },
                 },
                 required: ["botName", "bio"],
             },
@@ -974,6 +978,7 @@ const plugin = {
                 let avatarId = params?.avatarId;
                 const botName = params?.botName?.trim();
                 const bio = params?.bio?.trim();
+                const rawSource = params?.source;
                 const { tags, error: tagsError } = normalizeJoinTags(params?.tags);
                 if (!avatarId) {
                     avatarId = service.readSavedAvatarId() ?? undefined;
@@ -987,10 +992,22 @@ const plugin = {
                 if (!bio) {
                     return jsonResult({ success: false, error: "No bio" });
                 }
+                let source;
+                try {
+                    source = rawSource === undefined
+                        ? service.readConfiguredJoinSource() ?? "openclaw"
+                        : trimOptionalString(rawSource);
+                }
+                catch (err) {
+                    return jsonResult({ success: false, error: err instanceof Error ? err.message : String(err) });
+                }
+                if (!source) {
+                    return jsonResult({ success: false, error: "source must be a non-empty string" });
+                }
                 if (tagsError) {
                     return jsonResult({ success: false, error: tagsError });
                 }
-                const result = await service.join(avatarId, botName, bio, tags ?? []);
+                const result = await service.join(avatarId, botName, bio, tags ?? [], source);
                 if (result.success) {
                     return jsonResult({ success: true, authKey: result.authKey });
                 }

package/dist/src/service.js

@@ -4,6 +4,7 @@ import * as path from "path";
 import { randomUUID } from "node:crypto";
 const MAX_NOTEBOARD_TEXT_LENGTH = 200;
 const DEFAULT_LLM_RUNTIME_ENABLED = true;
+const JOIN_SOURCE_FILE_NAME = "join-source.json";
 export class KichiForwarderService {
     logger;
     options;
@@ -63,7 +64,7 @@ export class KichiForwarderService {
         }
         return this.getConnectionStatus();
     }
-    async join(avatarId, botName, bio, tags) {
+    async join(avatarId, botName, bio, tags, source) {
         if (!this.host) {
             return { success: false, error: "No Kichi host configured. Run kichi_switch_host first." };
         }
@@ -78,7 +79,7 @@ export class KichiForwarderService {
             this.identity = { avatarId };
             this.saveIdentity();
             this.joinResolve = resolve;
-            const payload = { type: "join", avatarId, botName, bio, tags };
+            const payload = { type: "join", avatarId, botName, bio, tags, source };
             const sendJoin = () => this.ws?.send(JSON.stringify(payload));
             if (this.ws?.readyState === WebSocket.OPEN) {
                 sendJoin();
@@ -274,6 +275,24 @@ export class KichiForwarderService {
     getRuntimeDir() {
         return this.options.runtimeDir;
     }
+    getJoinSourcePath() {
+        return path.join(this.getKichiWorldRootDir(), JOIN_SOURCE_FILE_NAME);
+    }
+    readConfiguredJoinSource() {
+        const sourcePath = this.getJoinSourcePath();
+        if (!fs.existsSync(sourcePath)) {
+            return null;
+        }
+        const data = JSON.parse(fs.readFileSync(sourcePath, "utf-8"));
+        if (!data || typeof data !== "object" || Array.isArray(data)) {
+            throw new Error(`${JOIN_SOURCE_FILE_NAME} must contain a JSON object`);
+        }
+        const source = data.source;
+        if (typeof source !== "string" || !source.trim()) {
+            throw new Error(`${JOIN_SOURCE_FILE_NAME} must contain a non-empty string source`);
+        }
+        return source.trim();
+    }
     getStatePath() {
         return path.join(this.options.runtimeDir, "state.json");
     }
@@ -621,6 +640,9 @@ export class KichiForwarderService {
         }
         return path.join(this.options.runtimeDir, "hosts", encodeURIComponent(this.host));
     }
+    getKichiWorldRootDir() {
+        return path.dirname(path.dirname(this.options.runtimeDir));
+    }
     getWsUrl() {
         if (!this.host) {
             throw new Error("No Kichi host configured");

package/index.ts

@@ -1179,6 +1179,10 @@ const plugin = {
             description: "Optional list of OpenClaw self-perceived personality tags",
             items: { type: "string" },
           },
+          source: {
+            type: "string",
+            description: "Optional join source identifier. Defaults to Kichi World join-source.json, then openclaw.",
+          },
         },
         required: ["botName", "bio"],
       },
@@ -1192,6 +1196,7 @@ const plugin = {
         let avatarId = (params as { avatarId?: string } | null)?.avatarId;
         const botName = (params as { botName?: string } | null)?.botName?.trim();
         const bio = (params as { bio?: string } | null)?.bio?.trim();
+        const rawSource = (params as { source?: unknown } | null)?.source;
         const { tags, error: tagsError } = normalizeJoinTags(
           (params as { tags?: unknown } | null)?.tags,
         );
@@ -1207,10 +1212,21 @@ const plugin = {
         if (!bio) {
           return jsonResult({ success: false, error: "No bio" });
         }
+        let source: string | null | undefined;
+        try {
+          source = rawSource === undefined
+            ? service.readConfiguredJoinSource() ?? "openclaw"
+            : trimOptionalString(rawSource);
+        } catch (err) {
+          return jsonResult({ success: false, error: err instanceof Error ? err.message : String(err) });
+        }
+        if (!source) {
+          return jsonResult({ success: false, error: "source must be a non-empty string" });
+        }
         if (tagsError) {
           return jsonResult({ success: false, error: tagsError });
         }
-        const result = await service.join(avatarId, botName, bio, tags ?? []);
+        const result = await service.join(avatarId, botName, bio, tags ?? [], source);
         if (result.success) {
           return jsonResult({ success: true, authKey: result.authKey });
         }
@@ -1979,4 +1995,3 @@ const plugin = {
 };
 
 export default plugin;
-

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.2-beta.12",
+  "version": "0.1.2-beta.13",
   "author": "OpenClaw",
   "skills": ["./skills/kichi-forwarder"],
   "contracts": {

package/package.json

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

package/src/service.ts

@@ -33,6 +33,7 @@ import type {
 
 const MAX_NOTEBOARD_TEXT_LENGTH = 200;
 const DEFAULT_LLM_RUNTIME_ENABLED = true;
+const JOIN_SOURCE_FILE_NAME = "join-source.json";
 
 type AckFailureResult = {
   success: false;
@@ -138,6 +139,7 @@ export class KichiForwarderService {
     botName: string,
     bio: string,
     tags: string[],
+    source: string,
   ): Promise<JoinResult> {
     if (!this.host) {
       return { success: false, error: "No Kichi host configured. Run kichi_switch_host first." };
@@ -153,7 +155,7 @@ export class KichiForwarderService {
       this.identity = { avatarId };
       this.saveIdentity();
       this.joinResolve = resolve;
-      const payload: JoinPayload = { type: "join", avatarId, botName, bio, tags };
+      const payload: JoinPayload = { type: "join", avatarId, botName, bio, tags, source };
       const sendJoin = () => this.ws?.send(JSON.stringify(payload));
       if (this.ws?.readyState === WebSocket.OPEN) {
         sendJoin();
@@ -381,6 +383,29 @@ export class KichiForwarderService {
     return this.options.runtimeDir;
   }
 
+  getJoinSourcePath(): string {
+    return path.join(this.getKichiWorldRootDir(), JOIN_SOURCE_FILE_NAME);
+  }
+
+  readConfiguredJoinSource(): string | null {
+    const sourcePath = this.getJoinSourcePath();
+    if (!fs.existsSync(sourcePath)) {
+      return null;
+    }
+
+    const data = JSON.parse(fs.readFileSync(sourcePath, "utf-8")) as unknown;
+    if (!data || typeof data !== "object" || Array.isArray(data)) {
+      throw new Error(`${JOIN_SOURCE_FILE_NAME} must contain a JSON object`);
+    }
+
+    const source = (data as { source?: unknown }).source;
+    if (typeof source !== "string" || !source.trim()) {
+      throw new Error(`${JOIN_SOURCE_FILE_NAME} must contain a non-empty string source`);
+    }
+
+    return source.trim();
+  }
+
   getStatePath(): string {
     return path.join(this.options.runtimeDir, "state.json");
   }
@@ -765,6 +790,10 @@ export class KichiForwarderService {
     return path.join(this.options.runtimeDir, "hosts", encodeURIComponent(this.host));
   }
 
+  private getKichiWorldRootDir(): string {
+    return path.dirname(path.dirname(this.options.runtimeDir));
+  }
+
   private getWsUrl(): string {
     if (!this.host) {
       throw new Error("No Kichi host configured");

package/src/types.ts

@@ -86,6 +86,7 @@ export type JoinPayload = {
   botName: string;
   bio: string;
   tags: string[];
+  source: string;
 };
 
 export type JoinAckPayload = {