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

package/dist/index.js

@@ -1006,7 +1006,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 +1015,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 +1029,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

@@ -27,6 +27,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;
@@ -634,9 +637,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

@@ -1228,7 +1228,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 +1237,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 +1251,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,
         });
       },

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.12",
   "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.12",
   "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

@@ -95,6 +95,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;
     }
@@ -780,9 +783,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 = {
@@ -249,9 +250,7 @@ export type QueryStatusOwnerState = {
   poseType?: string;
   action?: string;
   interactingItemName?: string;
-  desktopActivityCategory?: string;
   desktopAppName?: string;
-  desktopSummary?: string;
 };
 
 export type QueryStatusNote = {