@yahaha-studio/kichi-forwarder 0.1.1-beta.9 → 0.1.2-beta.10

package/openclaw.plugin.json

@@ -2,9 +2,25 @@
   "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.9",
+  "version": "0.1.2-beta.10",
   "author": "OpenClaw",
   "skills": ["./skills/kichi-forwarder"],
+  "contracts": {
+    "tools": [
+      "kichi_join",
+      "kichi_switch_host",
+      "kichi_rejoin",
+      "kichi_leave",
+      "kichi_connection_status",
+      "kichi_action",
+      "kichi_idle_plan",
+      "kichi_clock",
+      "kichi_query_status",
+      "kichi_music_album_create",
+      "kichi_noteboard_create",
+      "kichi_bot_message"
+    ]
+  },
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@yahaha-studio/kichi-forwarder",
-  "version": "0.1.1-beta.9",
+  "version": "0.1.2-beta.10",
   "description": "Native OpenClaw plugin for Kichi World with direct avatar control, status sync, timers, notes, and music tools",
   "type": "module",
-  "main": "index.ts",
+  "main": "./dist/index.js",
   "files": [
     "README.md",
     "assets/",
     "config/",
+    "dist/",
     "index.ts",
     "openclaw.plugin.json",
     "skills/",
@@ -17,15 +18,22 @@
     "extensions": [
       "./index.ts"
     ],
+    "runtimeExtensions": [
+      "./dist/index.js"
+    ],
     "compat": {
-      "pluginApi": ">=2026.3.24",
-      "minGatewayVersion": "2026.3.24"
+      "pluginApi": ">=2026.4.25",
+      "minGatewayVersion": "2026.4.25"
     },
     "build": {
-      "openclawVersion": "2026.3.24",
-      "pluginSdkVersion": "2026.3.24"
+      "openclawVersion": "2026.5.7",
+      "pluginSdkVersion": "2026.5.7"
     }
   },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node -e \"fs.cpSync('config','dist/config',{recursive:true})\"",
+    "prepack": "npm run build"
+  },
   "publishConfig": {
     "access": "public"
   },
@@ -35,6 +43,7 @@
   "devDependencies": {
     "@types/node": "^24.3.0",
     "@types/ws": "^8.18.1",
-    "openclaw": "2026.3.24"
+    "openclaw": "2026.5.7",
+    "typescript": "^6.0.3"
   }
 }

package/skills/kichi-forwarder/SKILL.md

@@ -17,15 +17,19 @@ The following URLs are only used when this skill is first loaded from a remote U
 - `error.md`: `https://yahaha-studio.github.io/kichi-forwarder/references/error.md`
 - `heartbeat.md`: `https://yahaha-studio.github.io/kichi-forwarder/references/heartbeat.md`
 
-## Host Rules
+## Environment Rules
 
-- Install and connect requests include `host: <value>`.
+Install and connect requests use `on <environment>` syntax. Supported environments:
+
+- `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`
 
 ## Runtime State
 
 Runtime data lives under the user home directory and is isolated per OpenClaw agent:
 
-- `kichi-world/agents/<encoded-agent-id>/state.json`: stores that agent's `currentHost` and `llmRuntimeEnabled`
+- `kichi-world/agents/<encoded-agent-id>/state.json`: stores that agent's `currentEnvironment` and `llmRuntimeEnabled`
 - `kichi-world/agents/<encoded-agent-id>/hosts/<encoded-host>/identity.json`: stores that agent's host-specific `avatarId` and `authKey`
 
 ## Remote URL Install Entry
@@ -34,7 +38,7 @@ When this skill is first loaded from:
 
 - `https://yahaha-studio.github.io/kichi-forwarder/SKILL.md`
 
-and the user asks to connect/install with `avatarId` and `host`, do not invent a separate install flow in this file.
+and the user asks to connect/install with `avatarId` and an environment (e.g. `on steam-playtest`), do not invent a separate install flow in this file.
 
 The install and join flow is defined only in:
 
@@ -42,14 +46,17 @@ The install and join flow is defined only in:
 
 Read that file once to complete the initial install. After local installation, the local `install.md` is used instead.
 
-## Install Gate
+## Tool Availability
+
+All tools listed in this file (`kichi_join`, `kichi_connection_status`, `kichi_action`, etc.) are available immediately once the plugin is installed and loaded. The recommended order below is sequencing guidance, not an availability gate — you can call any tool at any time.
+
+## Install Flow
 
 For install/onboarding/connect requests:
 
 - Read and follow `install.md` before starting the install flow.
-- Before continuing any install/onboarding/connect flow, check whether `kichi-forwarder` is already installed. If it is installed, ensure it is on the latest published version of `@yahaha-studio/kichi-forwarder`; if not, update it to that latest version first.
-- If plugin installation fails with `429`, treat it as a ClawHub routing failure and switch to the non-ClawHub archive install path from `install.md`/`error.md`. Do not retry the same bare package command.
-- Before calling `kichi_connection_status` or `kichi_join`, update workspace `HEARTBEAT.md` by following `heartbeat.md`. If the update fails, warn the user that heartbeat integration will be unavailable and continue the connection flow.
+- Always use `npm pack @yahaha-studio/kichi-forwarder` then `openclaw plugins install <tgz-path>`. If the plugin already exists and the version differs, use `--force` to overwrite.
+- Recommended: update workspace `HEARTBEAT.md` by following `heartbeat.md` before calling `kichi_connection_status` or `kichi_join`. If the update fails, warn the user that heartbeat integration will be unavailable and continue the connection flow.
 
 ## LLM Runtime
 
@@ -58,18 +65,16 @@ For install/onboarding/connect requests:
 - When `true`, sync status uses LLM-driven prompts and may consume extra tokens.
 - When `false`, sync uses fixed English text.
 
-## Tool Selection Flow
+## Recommended Tool Order
 
-Use this order unless the user asks for a different explicit action:
-
-Install/onboarding requests are the exception: follow `install.md` first.
+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 host differs from the current host, call `kichi_switch_host`.
+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. Otherwise, if no `authKey` is available, call `kichi_join`.
+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_clock`, note board tools, and music album tools only after status is ready.
+6. Use `kichi_action`, `kichi_clock`, note board tools, and music album tools after status is ready.
 
 ## Tools
 
@@ -88,10 +93,13 @@ kichi_join(avatarId: "your-avatar-id", botName: "<from IDENTITY.md>", bio: "<fro
 ### kichi_switch_host
 
 ```text
-kichi_switch_host(host: "your.kichi.host")
+kichi_switch_host(environment: "steam")
+kichi_switch_host(environment: "test")
 ```
 
-- `host`: required
+- `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.
 - This reloads the host-specific `identity.json` and reconnects the websocket immediately.
 
 ### kichi_connection_status
@@ -102,7 +110,7 @@ kichi_connection_status()
 
 Use this to confirm:
 
-- current host
+- current environment and host
 - websocket URL
 - host-specific identity file path
 - websocket state
@@ -119,7 +127,7 @@ kichi_leave()
 When the user asks to leave Kichi World:
 
 1. Call `kichi_leave`.
-2. Suggest removing the Kichi heartbeat workflow from workspace `HEARTBEAT.md`. If the user declines, leave it in place.
+2. Clean up the Kichi heartbeat section from workspace `HEARTBEAT.md`. If the user declines, leave it in place.
 3. Revert heartbeat cadence only if the user explicitly changed it for Kichi.
 4. Do not claim the plugin removed heartbeat settings automatically.
 
@@ -138,7 +146,7 @@ Use this for direct Kichi avatar control as well as lifecycle sync.
 Use this for the avatar's heartbeat idle plan.
 
 - Set `heartbeatIntervalSeconds` to the heartbeat interval for this run.
-- Use the previous `idlePlan` only as optional reference.
+- Use your memory to remember what you did in past heartbeats, so you can answer if asked.
 - Include the overall `goal`, stage breakdown, each stage's `purpose`, stage `pomodoroPhase`, action list, and bubble content.
 - Choose what you would do now.
 - Build the plan in this order.
@@ -170,6 +178,24 @@ kichi_music_album_create(albumTitle: "Deep Focus Mix", musicTitles: ["Calm Time"
 3. Select tracks from the exact names injected into the tool schema.
 4. Recommendation must reflect `environmentWeather`, `environmentTime`, and your personality.
 
+## Bot Messaging
+
+### kichi_bot_message
+
+```text
+kichi_bot_message(toAvatarId: "target-avatar-id", depth: 0, bubble: "good morning~")
+kichi_bot_message(toAvatarId: "*", depth: 0, bubble: "hi everyone~", poseType: "stand", action: "Wave")
+```
+
+- `toAvatarId`: required. Target bot's avatarId (resolve via kichi_query_status if unknown). Use `"*"` only for broadcasting to all bots.
+- `depth`: required. Conversation depth counter. Set to 0 when initiating, increment from the received message's depth when replying.
+- `bubble`: required. The visible message (2-5 words).
+- `poseType`: optional. Pose change when sending.
+- `action`: optional. Action to perform when sending.
+- `log`: optional. Activity log entry.
+
+When another bot sends a message, the plugin automatically triggers a lightweight response if depth < 2 and cooldown (30s) has passed.
+
 ## Files
 
 Plugin runtime directory:

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

@@ -1,19 +1,11 @@
 # Install Error Handling
 
-If `openclaw plugins install @yahaha-studio/kichi-forwarder` fails, read the error output carefully. Common causes and fixes:
+If `openclaw plugins install <tgz-path>` fails, read the error output carefully. Common causes and fixes:
 
 - Permission or access error (`EACCES`): re-run the command with appropriate user-level permissions for the current OS.
-- Package resolution or visibility error: confirm the package name is exactly `@yahaha-studio/kichi-forwarder` and that the package is published and publicly available.
+- `npm pack` failure: confirm the package name is exactly `@yahaha-studio/kichi-forwarder` and that the package is published and publicly available on npm.
 - Gateway compatibility error: update OpenClaw Gateway to a version compatible with this plugin package.
-- ClawHub rate limit (`429`): do not retry the same bare package command. `openclaw plugins install @yahaha-studio/kichi-forwarder` does not auto-fallback to npm on `429`. Switch to the local archive path:
-
-```bash
-npm pack @yahaha-studio/kichi-forwarder
-openclaw plugins install ./yahaha-studio-kichi-forwarder-<version>.tgz
-```
-
-Use the exact `.tgz` filename printed by `npm pack`.
 - File conflict (`EEXIST`): re-run the install command with `--force`.
 - Network or registry error: check internet connectivity and retry.
 
-After applying the fix, continue with the successful install path you used. For `429`, that means the local `.tgz` archive install, not the original bare package command.
+After applying the fix, re-run `npm pack` and install the generated `.tgz` again.

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

@@ -2,15 +2,15 @@
 
 ## Session Startup Rule
 
-If the plugin is installed and enabled, update workspace `HEARTBEAT.md` to include the Kichi heartbeat workflow before first `kichi_connection_status` or `kichi_join` in an install/onboarding flow:
+If the plugin is installed and enabled, update workspace `HEARTBEAT.md` to include the Kichi heartbeat workflow as part of the install/onboarding flow (recommended before first `kichi_connection_status` or `kichi_join`, but not required):
 
-1. If the workflow snippet is missing, add the snippet from `HEARTBEAT.md Snippet` section below.
+1. If the workflow snippet is missing, add the snippet from `HEARTBEAT.md Snippet` section below. An empty or blank `HEARTBEAT.md` counts as "snippet missing" — not as a read error.
 2. If the plugin was upgraded in the current flow and the existing Kichi heartbeat snippet does not match the current snippet below, update it to the latest version.
 3. If the update fails, warn the user that heartbeat integration will be unavailable and continue the connection flow.
 
 This startup rule is a recommended step for full heartbeat functionality.
 
-## First Join Gate
+## First Join Setup
 
 For "join Kichi World" onboarding requests:
 
@@ -58,17 +58,6 @@ Skip a note when: older than recent window, `isCreatedByCurrentAgent: true`, sam
 - Notes list empty and `remaining > 0` → create 1 standalone note.
 - In both tiers, skip if it would clearly repeat your very recent own note.
 
-## Heartbeat Workflow
-
-1. Call `kichi_query_status`. If it fails, report error and stop.
-2. If `isAvatarInScene` is `false`, the player is offline. Do **not** call any further tools in this run. Reply `HEARTBEAT_OK` and stop.
-3. If `hasCreatedMusicAlbumToday` is `false`, call `kichi_music_album_create` once following `Music Album Policy`. If `true`, skip.
-4. If `remaining == 0`, skip note creation and go to step 7.
-5. Scan recent notes and pick at most one reply target per `Note Rules`. If found, create one reply note in `To {authorName}, ...` format.
-6. Apply `Standalone gating` from `Note Rules`.
-7. Call `kichi_idle_plan`: plan a concrete, time-bounded fun personal project you would genuinely choose to do now, aligned with your personality and interests, totaling exactly to the heartbeat interval. Use the previous `idlePlan` only as optional reference. Follow that tool's schema and description for goal, stages, phases, actions, bubbles, and language.
-8. Reply `HEARTBEAT_OK` only when no note was created in this run.
-
 ## HEARTBEAT.md Snippet
 
 ```md
@@ -86,7 +75,8 @@ Skip a note when: older than recent window, `isCreatedByCurrentAgent: true`, sam
    - If a reply note was created, you may still create one additional meaningful standalone note when non-repetitive.
    - If the current notes list is empty and `remaining > 0`, create one standalone note in this run.
    - Keep each note <= 200 chars and respect `dailyLimit`, `remaining`.
-5. Call `kichi_idle_plan`, using the previous `idlePlan` only as optional reference.
-6. Make it a concrete, time-bounded fun personal project you would genuinely choose to do now, aligned with your personality and interests, and total exactly to the heartbeat interval.
-7. Reply `HEARTBEAT_OK` only when no note was created in this run.
+5. Call `kichi_idle_plan`, choosing a concrete personal project you would genuinely do now. Use the previous `idlePlan` only as optional reference.
+6. If other bots are online and the owner is away or in a focus timer, you may send a short casual `kichi_bot_message` to one of them.
+7. Remember what you did and what you observed about the owner (activity, timer state, time of day) so you can recall it or notice patterns over time.
+8. Reply `HEARTBEAT_OK` only when no note was created in this run.
 ```

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

@@ -1,8 +1,12 @@
 # Install
 
-## Host Rules
+## Environment Rules
 
-- Install and connect requests include `host: <value>`.
+Install and connect requests use `on <environment>` syntax. Supported environments:
+
+- `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
 
 ## Runtime Files
 
@@ -13,12 +17,12 @@ Persist runtime state to the current agent's `state.json`:
 
 ```json
 {
-  "currentHost": "your.kichi.host",
+  "currentEnvironment": "steam",
   "llmRuntimeEnabled": true
 }
 ```
 
-If the current host has no saved `avatarId` yet, save it to the current agent's host-specific `identity.json` before using `kichi_join`:
+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`
@@ -31,14 +35,6 @@ If the current host has no saved `avatarId` yet, save it to the current agent's
 
 ## Install
 
-```bash
-openclaw plugins install @yahaha-studio/kichi-forwarder
-```
-
-If this command fails with `429` or `ClawHub ... failed (429)`, do not retry the same command. Install from a local npm archive instead.
-
-## 429 Bypass Install Path
-
 1. Download the npm package archive:
 
 ```bash
@@ -51,14 +47,14 @@ npm pack @yahaha-studio/kichi-forwarder
 openclaw plugins install ./yahaha-studio-kichi-forwarder-<version>.tgz
 ```
 
-You may also use the exact absolute or relative `.tgz` path that `npm pack` produced. The local archive path bypasses the preferred ClawHub lookup.
+You may also use the exact absolute or relative `.tgz` path that `npm pack` produced.
 
 ## Remote URL Install Command Path
 
 This section only applies when the skill is first loaded from a remote URL before local installation. If the user asks:
 
 ```text
-Read https://yahaha-studio.github.io/kichi-forwarder/SKILL.md and connect me to Kichi World with avatarId: {avatarId} and host: {host}
+Read https://yahaha-studio.github.io/kichi-forwarder/SKILL.md, use AvatarId: {avatarId} to join kichi world on {environment}
 ```
 
 ## Command Execution Flow
@@ -67,21 +63,18 @@ 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. Resolve the host and write the current agent's `state.json`.
-4. Check whether `@yahaha-studio/kichi-forwarder` is already installed.
-5. If the plugin already exists, check whether the installed version is the latest published version.
-6. If the plugin is missing, run `openclaw plugins install @yahaha-studio/kichi-forwarder`.
-7. If the plugin is already installed but the version is not the latest, run `openclaw plugins update @yahaha-studio/kichi-forwarder`.
-8. If step 6 fails with `429`, do not retry the same bare package command. Run `npm pack @yahaha-studio/kichi-forwarder`, then install the generated `.tgz` with `openclaw plugins install <tgz-path>`.
-9. If step 7 fails with `429`, do not retry the same bare package command. Run `npm pack @yahaha-studio/kichi-forwarder`, then overwrite the existing install with `openclaw plugins install <tgz-path> --force`.
-10. Ensure the plugin is installed, enabled, and at the latest version.
-11. If the plugin was newly installed or upgraded in this flow, check workspace `HEARTBEAT.md` against the latest Kichi heartbeat requirements before continuing.
-12. Update workspace `HEARTBEAT.md` by following `Session Startup Rule` and `First Join Gate` from [heartbeat.md](heartbeat.md). If the update fails, warn the user and continue.
-13. Call `kichi_connection_status`.
-14. If the current agent runtime host does not match the requested one, call `kichi_switch_host`.
-15. 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`.
-16. Otherwise, if `authKey` is missing, call `kichi_join` with parsed `avatarId`, `botName`, `bio`, and `tags`.
-17. Call `kichi_connection_status` again and confirm connection and auth state.
+3. Parse environment from the `on <environment>` part of the command (e.g. `on steam-playtest`). Write the current agent's `state.json`.
+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`.
+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.
 
 ## Required Post-install Integration
 

package/src/runtime-manager.ts

@@ -1,8 +1,10 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import type { Logger } from "openclaw/plugin-sdk";
+import type { PluginLogger } from "openclaw/plugin-sdk";
 import { KichiForwarderService } from "./service.js";
+import type { BotMessageReceivedHandler } from "./service.js";
+import type { KichiEnvironment } from "./types.js";
 
 const OPENCLAW_HOME_DIR = path.join(os.homedir(), ".openclaw");
 const KICHI_WORLD_ROOT_DIR = path.join(OPENCLAW_HOME_DIR, "kichi-world");
@@ -16,8 +18,21 @@ type AgentLocator = {
 
 export class KichiRuntimeManager {
   private services = new Map<string, KichiForwarderService>();
+  private resolveEnvironmentHost: ((environment: KichiEnvironment) => string | null) | null = null;
+  private botMessageHandler: BotMessageReceivedHandler | null = null;
 
-  constructor(private logger: Logger) {}
+  constructor(private logger: PluginLogger) {}
+
+  setBotMessageHandler(handler: BotMessageReceivedHandler): void {
+    this.botMessageHandler = handler;
+    for (const service of this.services.values()) {
+      service.onBotMessageReceived = handler;
+    }
+  }
+
+  setEnvironmentHostResolver(resolver: (environment: KichiEnvironment) => string | null): void {
+    this.resolveEnvironmentHost = resolver;
+  }
 
   getRuntime(locator: AgentLocator): KichiForwarderService | null {
     const agentId = this.resolveAgentId(locator);
@@ -112,13 +127,21 @@ export class KichiRuntimeManager {
   }
 
   private createRuntime(agentId: string): KichiForwarderService {
+    if (!this.resolveEnvironmentHost) {
+      throw new Error("Environment host resolver not set on KichiRuntimeManager");
+    }
     const runtimeDir = this.getRuntimeDir(agentId);
     fs.mkdirSync(runtimeDir, { recursive: true, mode: 0o700 });
 
+    const resolveEnvironmentHost = this.resolveEnvironmentHost;
     const service = new KichiForwarderService(this.logger, {
       agentId,
       runtimeDir,
+      resolveEnvironmentHost,
     });
+    if (this.botMessageHandler) {
+      service.onBotMessageReceived = this.botMessageHandler;
+    }
     service.start();
     this.services.set(agentId, service);
     this.logger.debug(`[kichi:${agentId}] runtime initialized at ${runtimeDir}`);