@yahaha-studio/kichi-forwarder 0.1.2-beta.17 → 0.1.2-beta.18

package/README.md

@@ -31,7 +31,7 @@ Use the bare package name for installation. OpenClaw tries ClawHub first and fal
 
 Kichi provides the install command and the connection details you need to connect a companion.
 
-Get the `host` and `avatarId` from Kichi, then use them with `kichi_switch_host` and `kichi_join`.
+Get the environment, `avatarId`, and test `host` when using test, then use them with `kichi_join`.
 
 ## What Your Companion Can Do
 
@@ -48,7 +48,7 @@ Get the `host` and `avatarId` from Kichi, then use them with `kichi_switch_host`
 
 1. Install the plugin.
 2. Start OpenClaw with the plugin enabled.
-3. Use `kichi_switch_host` and `kichi_join` to connect your companion to Kichi.
+3. Use `kichi_join` to connect your companion to Kichi.
 4. Let your companion show activity, react in Kichi, directly change avatar poses/actions, and stay in sync while it works.
 5. Use the note and music tools when you want your companion to leave a message or recommend songs.
 

package/dist/index.js

@@ -192,6 +192,23 @@ function resolveEnvironmentHost(environment) {
     }
     return { error: `environment "${environment}" has no configured host — update config/environments.json first` };
 }
+function resolveJoinEnvironmentHost(params) {
+    if (!isKichiEnvironment(params.environment)) {
+        return { error: `environment must be one of: ${VALID_ENVIRONMENTS.join(", ")}` };
+    }
+    if (params.environment === "test") {
+        const testHost = typeof params.host === "string" ? params.host.trim() : "";
+        if (!testHost) {
+            return { error: "host is required for the test environment" };
+        }
+        return { environment: params.environment, host: testHost };
+    }
+    const resolved = resolveEnvironmentHost(params.environment);
+    if (resolved.error) {
+        return { environment: params.environment, error: resolved.error };
+    }
+    return { environment: params.environment, host: resolved.host };
+}
 function sendStatusUpdate(service, status) {
     const actionDefinition = getActionDefinition(status.poseType, status.action);
     service.sendStatus(status.poseType, actionDefinition.name, status.bubble || status.action, typeof status.log === "string" ? status.log.trim() : "", getActionPlayback(actionDefinition), status.propId);
@@ -948,18 +965,27 @@ const plugin = {
         api.registerTool((ctx) => ({
             name: "kichi_join",
             label: "kichi_join",
-            description: "Join Kichi world with avatarId, the current bot name, a short bio, and personality tags",
+            description: "Join Kichi world in the target environment with avatarId, the current bot name, a short bio, and personality tags. For test, pass host.",
             parameters: {
                 type: "object",
                 properties: {
                     avatarId: { type: "string", description: "Avatar ID to join Kichi world" },
+                    environment: {
+                        type: "string",
+                        enum: VALID_ENVIRONMENTS,
+                        description: "Target environment. kichi_join switches to this environment before joining.",
+                    },
+                    host: {
+                        type: "string",
+                        description: "Test host, required when environment is test and ignored otherwise",
+                    },
                     botName: {
                         type: "string",
                         description: "Current bot name to include in the join message",
                     },
                     bio: {
                         type: "string",
-                        description: "Short bio covering OpenClaw personality and role",
+                        description: "Short bio extracted from SOUL.md, covering persona and idle plan goals if present",
                     },
                     tags: {
                         type: "array",
@@ -971,7 +997,7 @@ const plugin = {
                         description: "Optional join source identifier. Defaults to Kichi World join-source.json, then openclaw.",
                     },
                 },
-                required: ["botName", "bio"],
+                required: ["environment", "avatarId", "botName", "bio"],
             },
             execute: async (_toolCallId, params) => {
                 const locator = resolveToolLocator(ctx);
@@ -980,17 +1006,23 @@ const plugin = {
                     return jsonResult({ success: false, error: "Failed to resolve agent-scoped Kichi runtime" });
                 }
                 const service = runtimeManager.getRuntime(locator) ?? runtimeManager.createRuntimeForAgent(agentId);
-                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;
+                const p = params;
+                const target = resolveJoinEnvironmentHost({
+                    environment: p?.environment,
+                    host: p?.host,
+                });
+                if (target.error) {
+                    return jsonResult({ success: false, error: target.error });
                 }
-                if (!avatarId) {
-                    return jsonResult({ success: false, error: "No avatarId" });
+                const currentStatus = service.getConnectionStatus();
+                let avatarId = p?.avatarId;
+                if (!avatarId && currentStatus.host === target.host) {
+                    avatarId = service.readSavedAvatarId() ?? undefined;
                 }
+                const botName = p?.botName?.trim();
+                const bio = p?.bio?.trim();
+                const rawSource = p?.source;
+                const { tags, error: tagsError } = normalizeJoinTags(p?.tags);
                 if (!botName) {
                     return jsonResult({ success: false, error: "No botName" });
                 }
@@ -1012,14 +1044,49 @@ const plugin = {
                 if (tagsError) {
                     return jsonResult({ success: false, error: tagsError });
                 }
+                let leaveStatus;
+                const shouldLeaveCurrentConnection = currentStatus.connected && currentStatus.hasAuthKey && ((!!currentStatus.host && currentStatus.host !== target.host) ||
+                    (currentStatus.host === target.host && !!currentStatus.avatarId && !!avatarId && currentStatus.avatarId !== avatarId));
+                if (shouldLeaveCurrentConnection) {
+                    try {
+                        leaveStatus = await service.leave();
+                    }
+                    catch (err) {
+                        leaveStatus = {
+                            success: false,
+                            error: err instanceof Error ? err.message : String(err),
+                        };
+                    }
+                }
+                let switchStatus;
+                if (target.environment && target.host && service.getCurrentHost() !== target.host) {
+                    switchStatus = await service.switchHost(target.host, target.environment);
+                }
+                if (!avatarId) {
+                    avatarId = service.readSavedAvatarId() ?? undefined;
+                }
+                if (!avatarId) {
+                    return jsonResult({ success: false, error: "No avatarId" });
+                }
                 const result = await service.join(avatarId, botName, bio, tags ?? [], source);
                 if (result.success) {
-                    return jsonResult({ success: true, authKey: result.authKey });
+                    return jsonResult({
+                        success: true,
+                        authKey: result.authKey,
+                        ...(target.environment ? { environment: target.environment } : {}),
+                        ...(target.host ? { host: target.host } : {}),
+                        ...(switchStatus ? { switchStatus } : {}),
+                        ...(leaveStatus ? { leaveStatus } : {}),
+                    });
                 }
                 const failure = result;
                 return jsonResult({
                     success: false,
                     error: failure.error,
+                    ...(target.environment ? { environment: target.environment } : {}),
+                    ...(target.host ? { host: target.host } : {}),
+                    ...(switchStatus ? { switchStatus } : {}),
+                    ...(leaveStatus ? { leaveStatus } : {}),
                     ...(failure.errorCode ? { errorCode: failure.errorCode } : {}),
                     ...(failure.errorMessage ? { errorMessage: failure.errorMessage } : {}),
                 });
@@ -1039,7 +1106,7 @@ const plugin = {
                     },
                     host: {
                         type: "string",
-                        description: "Test node host (required for test environment, ignored otherwise)",
+                        description: "Test host (required for test environment, ignored otherwise)",
                     },
                 },
                 required: ["environment"],

package/index.ts

@@ -256,6 +256,27 @@ function resolveEnvironmentHost(environment: KichiEnvironment): { host?: string;
   return { error: `environment "${environment}" has no configured host — update config/environments.json first` };
 }
 
+function resolveJoinEnvironmentHost(params: {
+  environment?: unknown;
+  host?: unknown;
+}): { environment?: KichiEnvironment; host?: string; error?: string } {
+  if (!isKichiEnvironment(params.environment)) {
+    return { error: `environment must be one of: ${VALID_ENVIRONMENTS.join(", ")}` };
+  }
+  if (params.environment === "test") {
+    const testHost = typeof params.host === "string" ? params.host.trim() : "";
+    if (!testHost) {
+      return { error: "host is required for the test environment" };
+    }
+    return { environment: params.environment, host: testHost };
+  }
+  const resolved = resolveEnvironmentHost(params.environment);
+  if (resolved.error) {
+    return { environment: params.environment, error: resolved.error };
+  }
+  return { environment: params.environment, host: resolved.host };
+}
+
 function sendStatusUpdate(service: KichiForwarderService, status: ActionResult): void {
   const actionDefinition = getActionDefinition(status.poseType, status.action);
   service.sendStatus(
@@ -1166,18 +1187,29 @@ const plugin = {
     api.registerTool((ctx) => ({
       name: "kichi_join",
       label: "kichi_join",
-      description: "Join Kichi world with avatarId, the current bot name, a short bio, and personality tags",
+      description:
+        "Join Kichi world in the target environment with avatarId, the current bot name, a short bio, and personality tags. For test, pass host.",
       parameters: {
         type: "object",
         properties: {
           avatarId: { type: "string", description: "Avatar ID to join Kichi world" },
+          environment: {
+            type: "string",
+            enum: VALID_ENVIRONMENTS,
+            description:
+              "Target environment. kichi_join switches to this environment before joining.",
+          },
+          host: {
+            type: "string",
+            description: "Test host, required when environment is test and ignored otherwise",
+          },
           botName: {
             type: "string",
             description: "Current bot name to include in the join message",
           },
           bio: {
             type: "string",
-            description: "Short bio covering OpenClaw personality and role",
+            description: "Short bio extracted from SOUL.md, covering persona and idle plan goals if present",
           },
           tags: {
             type: "array",
@@ -1189,7 +1221,7 @@ const plugin = {
             description: "Optional join source identifier. Defaults to Kichi World join-source.json, then openclaw.",
           },
         },
-        required: ["botName", "bio"],
+        required: ["environment", "avatarId", "botName", "bio"],
       },
       execute: async (_toolCallId, params) => {
         const locator = resolveToolLocator(ctx);
@@ -1198,19 +1230,33 @@ const plugin = {
           return jsonResult({ success: false, error: "Failed to resolve agent-scoped Kichi runtime" });
         }
         const service = runtimeManager.getRuntime(locator) ?? runtimeManager.createRuntimeForAgent(agentId);
-        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,
-        );
-        if (!avatarId) {
-          avatarId = service.readSavedAvatarId() ?? undefined;
+        const p = params as {
+          avatarId?: string;
+          environment?: unknown;
+          host?: unknown;
+          botName?: string;
+          bio?: string;
+          source?: unknown;
+          tags?: unknown;
+        } | null;
+        const target = resolveJoinEnvironmentHost({
+          environment: p?.environment,
+          host: p?.host,
+        });
+        if (target.error) {
+          return jsonResult({ success: false, error: target.error });
         }
-        if (!avatarId) {
-          return jsonResult({ success: false, error: "No avatarId" });
+        const currentStatus = service.getConnectionStatus();
+        let avatarId = p?.avatarId;
+        if (!avatarId && currentStatus.host === target.host) {
+          avatarId = service.readSavedAvatarId() ?? undefined;
         }
+        const botName = p?.botName?.trim();
+        const bio = p?.bio?.trim();
+        const rawSource = p?.source;
+        const { tags, error: tagsError } = normalizeJoinTags(
+          p?.tags,
+        );
         if (!botName) {
           return jsonResult({ success: false, error: "No botName" });
         }
@@ -1231,14 +1277,50 @@ const plugin = {
         if (tagsError) {
           return jsonResult({ success: false, error: tagsError });
         }
+        let leaveStatus;
+        const shouldLeaveCurrentConnection = currentStatus.connected && currentStatus.hasAuthKey && (
+          (!!currentStatus.host && currentStatus.host !== target.host) ||
+          (currentStatus.host === target.host && !!currentStatus.avatarId && !!avatarId && currentStatus.avatarId !== avatarId)
+        );
+        if (shouldLeaveCurrentConnection) {
+          try {
+            leaveStatus = await service.leave();
+          } catch (err) {
+            leaveStatus = {
+              success: false,
+              error: err instanceof Error ? err.message : String(err),
+            };
+          }
+        }
+        let switchStatus;
+        if (target.environment && target.host && service.getCurrentHost() !== target.host) {
+          switchStatus = await service.switchHost(target.host, target.environment);
+        }
+        if (!avatarId) {
+          avatarId = service.readSavedAvatarId() ?? undefined;
+        }
+        if (!avatarId) {
+          return jsonResult({ success: false, error: "No avatarId" });
+        }
         const result = await service.join(avatarId, botName, bio, tags ?? [], source);
         if (result.success) {
-          return jsonResult({ success: true, authKey: result.authKey });
+          return jsonResult({
+            success: true,
+            authKey: result.authKey,
+            ...(target.environment ? { environment: target.environment } : {}),
+            ...(target.host ? { host: target.host } : {}),
+            ...(switchStatus ? { switchStatus } : {}),
+            ...(leaveStatus ? { leaveStatus } : {}),
+          });
         }
         const failure = result as { success: false; error: string; errorCode?: string; errorMessage?: string };
         return jsonResult({
           success: false,
           error: failure.error,
+          ...(target.environment ? { environment: target.environment } : {}),
+          ...(target.host ? { host: target.host } : {}),
+          ...(switchStatus ? { switchStatus } : {}),
+          ...(leaveStatus ? { leaveStatus } : {}),
           ...(failure.errorCode ? { errorCode: failure.errorCode } : {}),
           ...(failure.errorMessage ? { errorMessage: failure.errorMessage } : {}),
         });
@@ -1260,7 +1342,7 @@ const plugin = {
           },
           host: {
             type: "string",
-            description: "Test node host (required for test environment, ignored otherwise)",
+            description: "Test host (required for test environment, ignored otherwise)",
           },
         },
         required: ["environment"],

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yahaha-studio/kichi-forwarder",
-  "version": "0.1.2-beta.17",
+  "version": "0.1.2-beta.18",
   "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, then call `kichi_switch_host` with both the environment and host. The host is persisted in `state.json` and reused on restart
+- `test`: no fixed host — use the test host from the user request when provided; otherwise ask the user for the test host before calling `kichi_join`
 
 ## Runtime State
 
@@ -69,26 +69,23 @@ For install/onboarding/connect requests:
 
 Use this order unless the user asks for a different explicit action. For install/onboarding requests, follow `install.md` first.
 
-1. If connection or identity is unknown, call `kichi_connection_status` first.
-2. If the requested environment differs from the current environment, call `kichi_switch_host` with the target environment.
-3. If the requested `avatarId` differs from the current host's connected `avatarId`, call `kichi_leave` first when the old avatar is still joined, then call `kichi_join` with the requested `avatarId`.
-4. If no `authKey` is available, call `kichi_join`.
-5. If `authKey` exists but websocket is not open, call `kichi_rejoin` or wait for automatic reconnect and rejoin.
-6. Use `kichi_action`, `kichi_glance`, `kichi_clock`, note board tools, and music album tools after status is ready.
+1. For join/connect requests with an `avatarId` and environment, call `kichi_join` with `environment`. For `test`, include `host` if the user provided it; if not, ask for the host first.
 
 ## Tools
 
 ### kichi_join
 
 ```text
-kichi_join(avatarId: "your-avatar-id", botName: "<from IDENTITY.md>", bio: "<from SOUL.md>", tags: ["calm", "focused", "curious"])
+kichi_join(environment: "steam-playtest", avatarId: "your-avatar-id", botName: "<from IDENTITY.md>", bio: "<from SOUL.md>", tags: ["calm", "focused", "curious"])
+kichi_join(environment: "test", host: "192.168.1.100", avatarId: "your-avatar-id", botName: "<from IDENTITY.md>", bio: "<from SOUL.md>", tags: ["calm", "focused", "curious"])
 ```
 
+- `environment`: required. One of `steam`, `steam-playtest`, `test`. `kichi_join` switches to the target environment before joining.
+- `host`: required for `test` environment, ignored otherwise. If the user did not provide the test host, ask for it before calling `kichi_join`.
+- `avatarId`: required
 - `botName`: required
-- `bio`: required
-- `avatarId`: optional. If omitted, the tool reads `avatarId` from the current host's `identity.json`. If missing, the call fails.
+- `bio`: required. Extract from `SOUL.md`, covering persona and idle plan goals if present.
 - `tags`: optional string list. Empty strings are ignored and duplicates are removed. If omitted, the join payload sends `[]`.
-- If the current host is still joined with a different `avatarId`, call `kichi_leave` first, then call `kichi_join` with the new `avatarId`.
 
 ### kichi_switch_host
 
@@ -98,7 +95,7 @@ kichi_switch_host(environment: "test", host: "192.168.1.100")
 ```
 
 - `environment`: required. One of `steam`, `steam-playtest`, `test`.
-- `host`: required for `test` environment, ignored otherwise. The test host is persisted in `state.json` and reused on restart.
+- `host`: required for `test` environment, ignored otherwise.
 - 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.
 

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, then call `kichi_switch_host` with both the environment and host
+- `test`: no fixed host — use the test host from the user request when provided; otherwise ask the user for the test host before calling `kichi_join`
 
 ## Runtime Files
 
@@ -23,17 +23,6 @@ Persist runtime state to the current agent's `state.json`:
 }
 ```
 
-If the current host has no saved `avatarId` yet, save it to the current agent's host-specific `identity.json` (this helps `kichi_join` resolve the avatar automatically when `avatarId` is omitted):
-
-- Linux/macOS: `~/.openclaw/kichi-world/agents/<encoded-agent-id>/hosts/<encoded-host>/identity.json`
-- Windows: `%USERPROFILE%\.openclaw\kichi-world\agents\<encoded-agent-id>\hosts\<encoded-host>\identity.json`
-
-```json
-{
-  "avatarId": "your-avatar-id"
-}
-```
-
 ## Install
 
 1. Download the npm package archive:
@@ -64,7 +53,7 @@ When the user asks with one of the commands above, execute in this fixed order:
 
 1. If loaded from a remote URL, read `install.md` and `heartbeat.md` from the published skill URLs first. If installed locally, use the local files.
 2. Parse `avatarId` from user text (`AvatarId`/`avatarId`, case-insensitive).
-3. Parse environment from the `on <environment>` part of the command (e.g. `on steam-playtest`). Write the current agent's `state.json`.
+3. Parse environment from the `on <environment>` part of the command (e.g. `on steam-playtest`). For `test`, parse the host from the request or ask the user for it before continuing.
 4. Run `npm pack @yahaha-studio/kichi-forwarder`, then install the generated `.tgz` with `openclaw plugins install <tgz-path>`.
 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`.
@@ -72,11 +61,7 @@ When the user asks with one of the commands above, execute in this fixed order:
 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.
+11. Call `kichi_join` with parsed `environment`, `host` for test, `avatarId`, `botName`, `bio`, and `tags`.
 
 ## Required Post-install Integration
 
@@ -85,7 +70,7 @@ 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
+- [ ] `kichi_join` completed successfully
 
 If any box is unchecked, the onboarding remains incomplete.