@yahaha-studio/kichi-forwarder 0.1.2-beta.11 → 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 });
                 }
@@ -1006,7 +1023,7 @@ const plugin = {
         api.registerTool((ctx) => ({
             name: "kichi_switch_host",
             label: "kichi_switch_host",
-            description: "Switch Kichi runtime environment and reconnect immediately without restarting the gateway. Host is resolved from config/environments.json.",
+            description: "Switch Kichi runtime environment and reconnect immediately without restarting the gateway. For steam/steam-playtest the host is resolved automatically. For test, pass the host explicitly.",
             parameters: {
                 type: "object",
                 properties: {
@@ -1015,6 +1032,10 @@ const plugin = {
                         enum: VALID_ENVIRONMENTS,
                         description: "Target environment: steam, steam-playtest, or test",
                     },
+                    host: {
+                        type: "string",
+                        description: "Test node host (required for test environment, ignored otherwise)",
+                    },
                 },
                 required: ["environment"],
             },
@@ -1025,19 +1046,31 @@ const plugin = {
                     return jsonResult({ success: false, error: "Failed to resolve agent-scoped Kichi runtime" });
                 }
                 const service = runtimeManager.getRuntime(locator) ?? runtimeManager.createRuntimeForAgent(agentId);
-                const environment = params?.environment;
+                const p = params;
+                const environment = p?.environment;
                 if (!isKichiEnvironment(environment)) {
                     return jsonResult({ success: false, error: `environment must be one of: ${VALID_ENVIRONMENTS.join(", ")}` });
                 }
-                const resolved = resolveEnvironmentHost(environment);
-                if (resolved.error) {
-                    return jsonResult({ success: false, error: resolved.error });
+                let targetHost;
+                if (environment === "test") {
+                    const testHost = typeof p?.host === "string" ? p.host.trim() : "";
+                    if (!testHost) {
+                        return jsonResult({ success: false, error: "host is required for the test environment" });
+                    }
+                    targetHost = testHost;
+                }
+                else {
+                    const resolved = resolveEnvironmentHost(environment);
+                    if (resolved.error) {
+                        return jsonResult({ success: false, error: resolved.error });
+                    }
+                    targetHost = resolved.host;
                 }
-                const status = await service.switchHost(resolved.host, environment);
+                const status = await service.switchHost(targetHost, environment);
                 return jsonResult({
                     success: true,
                     environment,
-                    host: resolved.host,
+                    host: targetHost,
                     status,
                 });
             },

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;
@@ -27,6 +28,9 @@ export class KichiForwarderService {
         this.environment = state?.currentEnvironment ?? null;
         if (this.environment) {
             this.host = this.options.resolveEnvironmentHost(this.environment);
+            if (!this.host && this.environment === "test" && state?.testHost) {
+                this.host = state.testHost;
+            }
         }
         else {
             this.host = null;
@@ -60,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." };
         }
@@ -75,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();
@@ -271,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");
     }
@@ -618,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");
@@ -634,9 +659,11 @@ export class KichiForwarderService {
     }
     persistCurrentHost(host, environment) {
         const previousState = this.readStateFile();
+        const testHost = environment === "test" ? host : (previousState?.testHost ?? undefined);
         const nextState = {
             ...(environment ? { currentEnvironment: environment } : {}),
             llmRuntimeEnabled: previousState?.llmRuntimeEnabled ?? DEFAULT_LLM_RUNTIME_ENABLED,
+            ...(testHost ? { testHost } : {}),
         };
         fs.mkdirSync(this.options.runtimeDir, { recursive: true, mode: 0o700 });
         fs.writeFileSync(this.getStatePath(), JSON.stringify(nextState, null, 2), { mode: 0o600 });

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 });
         }
@@ -1228,7 +1244,7 @@ const plugin = {
       name: "kichi_switch_host",
       label: "kichi_switch_host",
       description:
-        "Switch Kichi runtime environment and reconnect immediately without restarting the gateway. Host is resolved from config/environments.json.",
+        "Switch Kichi runtime environment and reconnect immediately without restarting the gateway. For steam/steam-playtest the host is resolved automatically. For test, pass the host explicitly.",
       parameters: {
         type: "object",
         properties: {
@@ -1237,6 +1253,10 @@ const plugin = {
             enum: VALID_ENVIRONMENTS,
             description: "Target environment: steam, steam-playtest, or test",
           },
+          host: {
+            type: "string",
+            description: "Test node host (required for test environment, ignored otherwise)",
+          },
         },
         required: ["environment"],
       },
@@ -1247,21 +1267,32 @@ const plugin = {
           return jsonResult({ success: false, error: "Failed to resolve agent-scoped Kichi runtime" });
         }
         const service = runtimeManager.getRuntime(locator) ?? runtimeManager.createRuntimeForAgent(agentId);
-        const environment = (params as { environment?: unknown } | null)?.environment;
+        const p = params as { environment?: unknown; host?: unknown } | null;
+        const environment = p?.environment;
         if (!isKichiEnvironment(environment)) {
           return jsonResult({ success: false, error: `environment must be one of: ${VALID_ENVIRONMENTS.join(", ")}` });
         }
 
-        const resolved = resolveEnvironmentHost(environment);
-        if (resolved.error) {
-          return jsonResult({ success: false, error: resolved.error });
+        let targetHost: string;
+        if (environment === "test") {
+          const testHost = typeof p?.host === "string" ? p.host.trim() : "";
+          if (!testHost) {
+            return jsonResult({ success: false, error: "host is required for the test environment" });
+          }
+          targetHost = testHost;
+        } else {
+          const resolved = resolveEnvironmentHost(environment);
+          if (resolved.error) {
+            return jsonResult({ success: false, error: resolved.error });
+          }
+          targetHost = resolved.host!;
         }
 
-        const status = await service.switchHost(resolved.host!, environment);
+        const status = await service.switchHost(targetHost, environment);
         return jsonResult({
           success: true,
           environment,
-          host: resolved.host,
+          host: targetHost,
           status,
         });
       },
@@ -1964,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.11",
+  "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.11",
+  "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/skills/kichi-forwarder/SKILL.md

@@ -23,7 +23,7 @@ Install and connect requests use `on <environment>` syntax. Supported environmen
 
 - `steam`: connects to `focus-wss.yahaha.com`
 - `steam-playtest`: connects to `focus-steam-playtest-wss-int.yahaha.com`
-- `test`: no fixed host — ask the user for the current test node host, write it to the plugin's `config/environments.json`, then call `kichi_switch_host`
+- `test`: no fixed host — ask the user for the current test node host, then call `kichi_switch_host` with both the environment and host. The host is persisted in `state.json` and reused on restart
 
 ## Runtime State
 
@@ -94,12 +94,12 @@ kichi_join(avatarId: "your-avatar-id", botName: "<from IDENTITY.md>", bio: "<fro
 
 ```text
 kichi_switch_host(environment: "steam")
-kichi_switch_host(environment: "test")
+kichi_switch_host(environment: "test", host: "192.168.1.100")
 ```
 
 - `environment`: required. One of `steam`, `steam-playtest`, `test`.
-- Host is resolved from `config/environments.json`. If the environment has no configured host (null), the call fails.
-- For `test` environment: ask the user for the test node host, write it to the plugin's `config/environments.json`, then call this tool.
+- `host`: required for `test` environment, ignored otherwise. The test host is persisted in `state.json` and reused on restart.
+- For `steam` and `steam-playtest`, the host is resolved automatically from the bundled config.
 - This reloads the host-specific `identity.json` and reconnects the websocket immediately.
 
 ### kichi_connection_status

package/skills/kichi-forwarder/references/install.md

@@ -6,7 +6,7 @@ Install and connect requests use `on <environment>` syntax. Supported environmen
 
 - `steam`: connects to `focus-wss.yahaha.com`
 - `steam-playtest`: connects to `focus-steam-playtest-wss-int.yahaha.com`
-- `test`: no fixed host — ask the user for the current test node host, write it to the plugin's `config/environments.json`, then connect
+- `test`: no fixed host — ask the user for the current test node host, then call `kichi_switch_host` with both the environment and host
 
 ## Runtime Files
 
@@ -18,7 +18,8 @@ Persist runtime state to the current agent's `state.json`:
 ```json
 {
   "currentEnvironment": "steam",
-  "llmRuntimeEnabled": true
+  "llmRuntimeEnabled": true,
+  "testHost": "192.168.1.100"
 }
 ```
 
@@ -68,19 +69,21 @@ When the user asks with one of the commands above, execute in this fixed order:
 5. If the plugin already exists and the packed version matches the installed version, skip to step 7.
 6. If the plugin already exists but the version differs, overwrite with `openclaw plugins install <tgz-path> --force`.
 7. Ensure the plugin is installed, enabled, and at the latest version.
-8. If the plugin was newly installed or upgraded in this flow, check workspace `HEARTBEAT.md` against the latest Kichi heartbeat requirements before continuing. An empty or blank `HEARTBEAT.md` means the snippet is missing — treat it the same as "snippet not found", not as a read failure.
-9. Update workspace `HEARTBEAT.md` by following `Session Startup Rule` and `First Join Setup` from [heartbeat.md](heartbeat.md). If the update fails, warn the user and continue.
-10. Call `kichi_connection_status`.
-11. If the current agent runtime environment does not match the requested one, call `kichi_switch_host` with the target environment (and host for test).
-12. If the current host is still connected with a different `avatarId`, call `kichi_leave` first, then call `kichi_join` with parsed `avatarId`, `botName`, `bio`, and `tags`.
-13. Otherwise, if `authKey` is missing, call `kichi_join` with parsed `avatarId`, `botName`, `bio`, and `tags`.
-14. Call `kichi_connection_status` again and confirm connection and auth state.
+8. Run `openclaw --version`. If the version is **5.7 or later**, ensure `openclaw.json` has `plugins.entries.kichi-forwarder.hooks.allowConversationAccess` set to `true`. If missing, add it. On older versions, skip this step.
+9. If the plugin was newly installed or upgraded in this flow, check workspace `HEARTBEAT.md` against the latest Kichi heartbeat requirements before continuing. An empty or blank `HEARTBEAT.md` means the snippet is missing — treat it the same as "snippet not found", not as a read failure.
+10. Update workspace `HEARTBEAT.md` by following `Session Startup Rule` and `First Join Setup` from [heartbeat.md](heartbeat.md). If the update fails, warn the user and continue.
+11. Call `kichi_connection_status`.
+12. If the current agent runtime environment does not match the requested one, call `kichi_switch_host` with the target environment (and host for test).
+13. If the current host is still connected with a different `avatarId`, call `kichi_leave` first, then call `kichi_join` with parsed `avatarId`, `botName`, `bio`, and `tags`.
+14. Otherwise, if `authKey` is missing, call `kichi_join` with parsed `avatarId`, `botName`, `bio`, and `tags`.
+15. Call `kichi_connection_status` again and confirm connection and auth state.
 
 ## Required Post-install Integration
 
 Use this completion checklist:
 
 - [ ] plugin installed, enabled, and at latest version
+- [ ] `openclaw.json` has `plugins.entries.kichi-forwarder.hooks.allowConversationAccess: true` (OpenClaw >= 5.7 only)
 - [ ] `HEARTBEAT.md` updated with the Kichi heartbeat workflow snippet from [heartbeat.md](heartbeat.md)
 - [ ] `kichi_connection_status` verified the final connected/auth state
 

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;
@@ -95,6 +96,9 @@ export class KichiForwarderService {
     this.environment = (state?.currentEnvironment as KichiEnvironment) ?? null;
     if (this.environment) {
       this.host = this.options.resolveEnvironmentHost(this.environment);
+      if (!this.host && this.environment === "test" && state?.testHost) {
+        this.host = state.testHost as string;
+      }
     } else {
       this.host = null;
     }
@@ -135,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." };
@@ -150,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();
@@ -378,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");
   }
@@ -762,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");
@@ -780,9 +812,11 @@ export class KichiForwarderService {
 
   private persistCurrentHost(host: string, environment?: KichiEnvironment): void {
     const previousState = this.readStateFile();
+    const testHost = environment === "test" ? host : (previousState?.testHost ?? undefined);
     const nextState: KichiState = {
       ...(environment ? { currentEnvironment: environment } : {}),
       llmRuntimeEnabled: previousState?.llmRuntimeEnabled ?? DEFAULT_LLM_RUNTIME_ENABLED,
+      ...(testHost ? { testHost } : {}),
     };
     fs.mkdirSync(this.options.runtimeDir, { recursive: true, mode: 0o700 });
     fs.writeFileSync(this.getStatePath(), JSON.stringify(nextState, null, 2), { mode: 0o600 });

package/src/types.ts

@@ -44,6 +44,7 @@ export type KichiEnvironmentsConfig = Record<KichiEnvironment, string | null>;
 export type KichiState = {
   currentEnvironment?: KichiEnvironment;
   llmRuntimeEnabled: boolean;
+  testHost?: string;
 };
 
 export type KichiIdentity = {
@@ -85,6 +86,7 @@ export type JoinPayload = {
   botName: string;
   bio: string;
   tags: string[];
+  source: string;
 };
 
 export type JoinAckPayload = {
@@ -249,9 +251,7 @@ export type QueryStatusOwnerState = {
   poseType?: string;
   action?: string;
   interactingItemName?: string;
-  desktopActivityCategory?: string;
   desktopAppName?: string;
-  desktopSummary?: string;
 };
 
 export type QueryStatusNote = {